Metadata-Version: 2.4
Name: openai-agents-persql
Version: 0.1.0
Summary: OpenAI Agents SDK session memory backed by PerSQL — durable conversation 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: agents,memory,openai,persistence,session,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: openai-agents>=0.2
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

# openai-agents-persql

Session memory for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) backed by [PerSQL](https://persql.com) — durable conversation history in an isolated SQLite database per agent.

```
pip install openai-agents-persql
```

## Usage

```python
import os
from agents import Agent, Runner
from persql import PerSQL
from openai_agents_persql import PerSQLSession

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
session = PerSQLSession("user-42", client.database("acme/agent-state"))

agent = Agent(name="assistant", instructions="Be helpful.")
result = await Runner.run(agent, "hi", session=session)
result = await Runner.run(agent, "remember me?", session=session)  # history persists
```

Or let the session own its client:

```python
with PerSQLSession.from_token("user-42", os.environ["PERSQL_TOKEN"], "acme/agent-state") as session:
    result = Runner.run_sync(agent, "hi", session=session)
```

Async apps can pass an `AsyncPerSQLDatabase` instead — calls are awaited natively rather than dispatched to a thread:

```python
from persql import AsyncPerSQL

async with AsyncPerSQL(token=os.environ["PERSQL_TOKEN"]) as client:
    session = PerSQLSession("user-42", client.database("acme/agent-state"))
    result = await Runner.run(agent, "hi", session=session)
```

## Storage layout

Two tables, created lazily on first use — the same layout as the SDK's built-in `SQLiteSession`:

- `agent_sessions(session_id, created_at, updated_at)`
- `agent_messages(id, session_id, message_data, created_at)`

Items are stored as JSON text, so the history is queryable like any other data:

```sql
SELECT session_id, COUNT(*) AS items, MAX(created_at) AS last_active
FROM agent_messages GROUP BY session_id ORDER BY 2 DESC;
```

Table names are configurable via `sessions_table=` / `messages_table=`.

## Local tests, no network

The persql SDK's local mode runs the same session against in-process SQLite:

```python
session = PerSQLSession("test", PerSQL(local=":memory:").database("test/db"))
```

## Limits

- Each session operation is one HTTP round-trip to the database (reads and writes alike ride single `query`/`batch` calls) — the same trade-off as the SDK's SQLAlchemy session against a remote database.
- Rows are metered like any other PerSQL usage; see [pricing](https://persql.com/pricing).
- `PerSQLSession` implements the `Session` protocol (`get_items` / `add_items` / `pop_item` / `clear_session`). Compaction-aware extras (`run_compaction`) are not implemented.

## License

MIT © PerSQL
