Metadata-Version: 2.4
Name: agent-framework-persql
Version: 0.1.0
Summary: Microsoft Agent Framework conversation history backed by PerSQL — durable message history in an isolated SQLite database per agent.
Project-URL: Homepage, https://persql.com
Project-URL: Documentation, https://docs.persql.com
Project-URL: Console, https://console.persql.com
Project-URL: Issues, https://persql.com/support
Author-email: PerSQL <support@persql.com>
License: MIT
License-File: LICENSE
Keywords: agent-framework,agents,history,memory,persistence,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: agent-framework-core<2,>=1.8
Requires-Dist: persql>=0.4
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# agent-framework-persql

[Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/) conversation history backed by [PerSQL](https://persql.com) — durable message history in an isolated SQLite database per agent, provisioned instantly.

```
pip install agent-framework-persql
```

## Usage

```python
import os
from persql import PerSQL
from agent_framework_persql import PerSQLHistoryProvider

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
provider = PerSQLHistoryProvider(client.database("acme/agent-state"))

agent = chat_client.as_agent(instructions="...", context_providers=[provider])
session = agent.create_session(session_id="user-42")
await agent.run("hi", session=session)
```

Or let the provider own the client:

```python
with PerSQLHistoryProvider.from_token(os.environ["PERSQL_TOKEN"], "acme/agent-state") as provider:
    ...
```

`AsyncPerSQL` databases are awaited natively; sync databases run via
`asyncio.to_thread`.

## What it stores

One `agent_framework_messages` row per message (`Message.to_dict()` as
JSON), appended in run order and replayed with `Message.from_dict()`.
Pass `messages_table=` to rename the table. The standard
`HistoryProvider` flags (`load_messages`, `store_inputs`,
`store_outputs`, `store_context_messages`, `store_context_from`) and
`skip_excluded` work as in the built-in providers, so the same class
covers primary memory, audit-only, and evaluation storage.

`provider.clear(session_id)` deletes one session's history.

## Limits

- A `None` session_id maps to one shared `"default"` history — the same
  behavior as the framework's `FileHistoryProvider`. Pass session ids
  for per-user isolation.
- Message payloads are JSON; binary content should be referenced by
  URI, not embedded.
- Requires `agent-framework-core >= 1.8, < 2` — the package subclasses
  `HistoryProvider`, so a framework major version can change the
  contract.

## Local mode for tests

```python
from persql import PerSQL
provider = PerSQLHistoryProvider(PerSQL(local=":memory:").database("test/db"))
```

Runs against in-process SQLite — no network, no token.
