Metadata-Version: 2.4
Name: strands-persql
Version: 0.1.0
Summary: AWS Strands Agents session persistence backed by PerSQL — durable sessions, agents, and messages 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,persistence,session,sqlite,strands,strands-agents
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: persql>=0.4
Requires-Dist: strands-agents<2,>=1.42
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# strands-persql

[AWS Strands Agents](https://strandsagents.com) session persistence backed by [PerSQL](https://persql.com) — durable sessions, agents, and messages in an isolated SQLite database per agent, provisioned instantly.

```
pip install strands-persql
```

## Usage

```python
import os
from strands import Agent
from persql import PerSQL
from strands_persql import PerSQLSessionManager

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

agent = Agent(session_manager=manager)
agent("hi")  # history and state persist across restarts
```

Or let the manager own the client:

```python
manager = PerSQLSessionManager.from_token("user-42", os.environ["PERSQL_TOKEN"], "acme/agent-state")
```

`PerSQLSessionRepository` is also exported for use with
`RepositorySessionManager` or your own manager.

## What it stores

The same data model as `FileSessionManager`, with tables instead of
directories — one row per session (`strands_sessions`), per agent
(`strands_agents`), and per message (`strands_messages`), each holding
the dataclass's JSON. Multi-agent (Graph/Swarm) state goes to
`strands_multi_agents`. Pass `table_prefix=` to change the `strands_`
prefix.

## Limits

- The repository contract is synchronous, so calls block on HTTP to
  your PerSQL database (or run in-process in local mode).
- `update_agent` / `update_message` are read-then-write (to preserve
  `created_at`), not atomic over HTTP. Keep one writer per session —
  the same assumption Strands' file and S3 managers make.
- Requires `strands-agents >= 1.42, < 2` — the package subclasses
  `SessionRepository`, so a framework major version can change the
  contract.

## Local mode for tests

```python
from persql import PerSQL
manager = PerSQLSessionManager("t", PerSQL(local=":memory:").database("test/db"))
```

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