> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statebase.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Async-ready, lightweight client for StateBase.

The StateBase Python SDK is the recommended way to integrate with our infrastructure. It is designed to be lightweight with minimal dependencies.

## Installation

```bash theme={null}
pip install statebase
```

## Initialization

```python theme={null}
from statebase import StateBase

# Initialize with your API Key (resolves user ownership automatically)
sb = StateBase(api_key="sb_live_...")
```

## Sessions

### Create or Resume

```python theme={null}
session = sb.sessions.create(
    agent_id="my-agent",
    initial_state={"status": "initializing"}
)
```

### Get Context (Consolidated)

The `get_context` call is optimized for agent prompts. It fetches State, Memories, and Turns in a single low-latency call.

```python theme={null}
context = sb.sessions.get_context(
    session_id=session.id,
    query="What does the user like?",
    memory_limit=5,
    turn_limit=10
)

# context['state'] -> dict
# context['memories'] -> list of dicts with scores
# context['recent_turns'] -> list of turns
```

### Update State

```python theme={null}
sb.sessions.update_state(
    session_id=session.id,
    state={"status": "completed", "user_ready": True},
    reasoning="User confirmed onboarding"
)
```

## Memory

### Manual Injection

```python theme={null}
sb.memory.add(
    content="User is allergic to peanuts.",
    type="fact",
    session_id=session.id,
    tags=["medical", "preferences"]
)
```

### Semantic Search

```python theme={null}
results = sb.memory.search(
    query="dietary restrictions",
    limit=3,
    threshold=0.8
)
```

## Clean Up

Always close the client if you are not using a context manager.

```python theme={null}
sb.close()
```