Metadata-Version: 2.4
Name: google-adk-persql
Version: 0.1.0
Summary: Google ADK session service backed by PerSQL — durable sessions, events, and state 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: adk,agents,google-adk,memory,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: google-adk<3,>=2.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

# google-adk-persql

[Google ADK](https://google.github.io/adk-docs/) session service backed by [PerSQL](https://persql.com) — durable sessions, events, and state in an isolated SQLite database per agent, provisioned instantly.

```
pip install google-adk-persql
```

## Usage

```python
import os
from google.adk.runners import Runner
from persql import PerSQL
from google_adk_persql import PerSQLSessionService

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

runner = Runner(agent=agent, app_name="my-app", session_service=service)
```

Or let the service own the client:

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

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

## What it stores

The same four-table layout and state-scope semantics as ADK's built-in
`SqliteSessionService`:

- `adk_sessions` — one row per session, with session-scoped state.
- `adk_events` — one row per event, stored as opaque JSON so ADK event
  fields can evolve without schema migrations.
- `adk_app_states` / `adk_user_states` — `app:` and `user:` prefixed
  state keys, shared across sessions and merged into `session.state` on
  read. `temp:` keys are never persisted.

Pass `table_prefix=` to change the `adk_` prefix.

## Limits

- The stale-session check in `append_event` is read-then-write over
  HTTP, not a single database transaction — two writers racing the same
  session can both pass it. Keep one writer per session.
- Event payloads are JSON; binary artifacts should go through ADK's
  artifact service, not session state.
- Requires `google-adk >= 2.2, < 3` — the package subclasses
  `BaseSessionService`, so an ADK major version can change the contract.

## Local mode for tests

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

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