Metadata-Version: 2.5
Name: pydantic-ai-persistence
Version: 0.1.0
Summary: Backend-agnostic persistence for PydanticAI — chat history + durable StepStore, over a small async KV interface
Project-URL: Homepage, https://github.com/skamalj/pydantic-ai-persistence
Project-URL: Repository, https://github.com/skamalj/pydantic-ai-persistence.git
Author-email: Kamal <skamalj@github.com>
Keywords: agent-memory,agent-state,chat-history,checkpoint,durable-execution,message-history,persistence,pydantic,pydantic-ai,pydantic-graph,pydanticai,step-store,storage
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: pydantic-ai-harness
Requires-Dist: pydantic-ai>=1.0
Provides-Extra: all
Requires-Dist: pydantic-ai-cosmosdb-persistence>=0.1.0; extra == 'all'
Requires-Dist: pydantic-ai-dynamodb-persistence>=0.1.0; extra == 'all'
Requires-Dist: pydantic-ai-firestore-persistence>=0.1.0; extra == 'all'
Provides-Extra: cosmosdb
Requires-Dist: pydantic-ai-cosmosdb-persistence>=0.1.0; extra == 'cosmosdb'
Provides-Extra: dynamodb
Requires-Dist: pydantic-ai-dynamodb-persistence>=0.1.0; extra == 'dynamodb'
Provides-Extra: firestore
Requires-Dist: pydantic-ai-firestore-persistence>=0.1.0; extra == 'firestore'
Description-Content-Type: text/markdown

# pydantic-ai-persistence

Backend-agnostic persistence for [PydanticAI](https://ai.pydantic.dev): **chat history** and **durable step persistence**, over one small async KV interface. Backends (DynamoDB, CosmosDB, Firestore) implement `AsyncKV` and get both stores.

PydanticAI has two persistence layers:
- **History** — you serialize `result.all_messages()` and store it yourself. `KVHistoryStore` does exactly that.
- **Step persistence** — PydanticAI's `StepStore` (append-only events, continuable snapshots, tool-effect ledger) for durable/resumable runs. `KVStepStore` implements the async `StepStore` protocol.

## Install

```bash
pip install pydantic-ai-persistence            # core (in-memory backend)
pip install "pydantic-ai-persistence[dynamodb]"  # + DynamoDB backend
```

## Core pieces

| Component | What it does |
|---|---|
| `AsyncKV` | tiny async interface a backend implements (`put`/`get`/`query`/`delete`) |
| `InMemoryAsyncKV` | in-memory backend for tests/dev |
| `KVHistoryStore` | `save(conversation_id, messages)` / `load(conversation_id)` |
| `KVStepStore` | implements PydanticAI's async `StepStore` over an `AsyncKV` |

## History

```python
from pydantic_ai import Agent
from pydantic_ai_persistence import KVHistoryStore, InMemoryAsyncKV

store = KVHistoryStore(InMemoryAsyncKV())

result = agent.run_sync("Hi, I'm Kamal")
await store.save("conv-1", result.all_messages())

prior = await store.load("conv-1")
result = agent.run_sync("What's my name?", message_history=prior)
```

## Step persistence

```python
from pydantic_ai import Agent
from pydantic_ai_harness.step_persistence import StepPersistence
from pydantic_ai_persistence import KVStepStore, InMemoryAsyncKV

step_store = KVStepStore(InMemoryAsyncKV(), max_snapshots_per_run=10)
agent = Agent("openai:gpt-4o", capabilities=[StepPersistence(store=step_store)])
```

`KVStepStore` records runs, append-only events, continuable snapshots (with pruning), and the tool-effect ledger — everything the `StepStore` protocol requires.

## Build your own backend
Implement `AsyncKV` (four async methods) and hand it to `KVStepStore` / `KVHistoryStore`. See `pydantic-ai-dynamodb-persistence` for an example.

> **Note:** `StepStore` is a beta/experimental PydanticAI harness feature; its API may still change.

## License

MIT
