axio-context-sqlite 0.6.1__tar.gz → 0.6.2__tar.gz

{axio_context_sqlite-0.6.1 → axio_context_sqlite-0.6.2}/.gitignore

@@ -10,3 +10,5 @@ dist/
 build/
 _build/
 .DS_Store
+*.sqlite
+*.db

{axio_context_sqlite-0.6.1 → axio_context_sqlite-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axio-context-sqlite
-Version: 0.6.1
+Version: 0.6.2
 Summary: SQLite-backed context store for Axio
 Project-URL: Homepage, https://github.com/axio-agent/monorepo
 Project-URL: Repository, https://github.com/axio-agent/monorepo
@@ -27,6 +27,32 @@ pip install axio-context-sqlite
 
 ## Usage
 
+### `connect(db_path)`
+
+Open (or create) a SQLite database at `db_path` and initialise the schema.
+Returns an `aiosqlite.Connection`. The caller is responsible for closing it.
+
+```python
+async def main():
+    conn = await connect("~/.axio/chat.db")
+    # ... use the connection ...
+    await conn.close()
+```
+
+The helper enables WAL journal mode and a 5-second busy timeout so concurrent
+readers and a single writer can safely share the same database file.
+
+### `SQLiteContextStore(conn, session_id, project=None, db_name="axio_context")`
+
+Create a context store bound to one session.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `conn` | `aiosqlite.Connection` | — | Open database connection (from `connect()`) |
+| `session_id` | `str` | — | Unique identifier for this conversation session |
+| `project` | `str \| None` | `str(Path.cwd().resolve())` | Logical project scope used to group and list sessions. Defaults to the current working directory. |
+| `db_name` | `str` | `"axio_context"` | Prefix used for the database table names (`axio_context_messages`, `axio_context_tokens`). |
+
 Open a connection with `connect()`, then create a `SQLiteContextStore` bound to a
 session. The caller owns the connection and is responsible for closing it.
 
@@ -56,6 +82,22 @@ asyncio.run(main())
 conversation history across process restarts. Multiple sessions can coexist in
 the same database file, isolated by `session_id` and `project`.
 
+#### Storage and compression
+
+Message content is stored as serialized JSON. Payloads larger than 512 bytes
+are automatically compressed with gzip (compresslevel 6) and stored
+base64-encoded with a `gzip:` prefix. Smaller payloads are stored as-is with a
+`plain:` prefix. Decompression happens transparently on read — callers never
+see the encoded form.
+
+#### SQLite performance settings
+
+Every connection opened by `connect()` is configured with:
+
+- `PRAGMA journal_mode=WAL` — enables concurrent readers alongside one writer
+- `PRAGMA busy_timeout=5000` — waits up to 5 seconds before raising a lock error
+- `PRAGMA synchronous=NORMAL` — balances durability and write throughput
+
 ### Agent integration
 
 <!--
@@ -112,6 +154,16 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Token accounting
+
+`add_context_tokens(input_tokens, output_tokens)` atomically increments the
+stored token counts for the current session and project using a SQL UPSERT
+(`INSERT ... ON CONFLICT DO UPDATE SET ... = ... + excluded....`). This is safe
+to call concurrently from multiple coroutines without an application-level lock.
+
+`set_context_tokens()` replaces the counts unconditionally, and
+`get_context_tokens()` returns a `(input_tokens, output_tokens)` tuple.
+
 ### Forking
 
 `fork()` copies the current session's messages into a new session — useful for

{axio_context_sqlite-0.6.1 → axio_context_sqlite-0.6.2}/README.md

@@ -14,6 +14,32 @@ pip install axio-context-sqlite
 
 ## Usage
 
+### `connect(db_path)`
+
+Open (or create) a SQLite database at `db_path` and initialise the schema.
+Returns an `aiosqlite.Connection`. The caller is responsible for closing it.
+
+```python
+async def main():
+    conn = await connect("~/.axio/chat.db")
+    # ... use the connection ...
+    await conn.close()
+```
+
+The helper enables WAL journal mode and a 5-second busy timeout so concurrent
+readers and a single writer can safely share the same database file.
+
+### `SQLiteContextStore(conn, session_id, project=None, db_name="axio_context")`
+
+Create a context store bound to one session.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `conn` | `aiosqlite.Connection` | — | Open database connection (from `connect()`) |
+| `session_id` | `str` | — | Unique identifier for this conversation session |
+| `project` | `str \| None` | `str(Path.cwd().resolve())` | Logical project scope used to group and list sessions. Defaults to the current working directory. |
+| `db_name` | `str` | `"axio_context"` | Prefix used for the database table names (`axio_context_messages`, `axio_context_tokens`). |
+
 Open a connection with `connect()`, then create a `SQLiteContextStore` bound to a
 session. The caller owns the connection and is responsible for closing it.
 
@@ -43,6 +69,22 @@ asyncio.run(main())
 conversation history across process restarts. Multiple sessions can coexist in
 the same database file, isolated by `session_id` and `project`.
 
+#### Storage and compression
+
+Message content is stored as serialized JSON. Payloads larger than 512 bytes
+are automatically compressed with gzip (compresslevel 6) and stored
+base64-encoded with a `gzip:` prefix. Smaller payloads are stored as-is with a
+`plain:` prefix. Decompression happens transparently on read — callers never
+see the encoded form.
+
+#### SQLite performance settings
+
+Every connection opened by `connect()` is configured with:
+
+- `PRAGMA journal_mode=WAL` — enables concurrent readers alongside one writer
+- `PRAGMA busy_timeout=5000` — waits up to 5 seconds before raising a lock error
+- `PRAGMA synchronous=NORMAL` — balances durability and write throughput
+
 ### Agent integration
 
 <!--
@@ -99,6 +141,16 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Token accounting
+
+`add_context_tokens(input_tokens, output_tokens)` atomically increments the
+stored token counts for the current session and project using a SQL UPSERT
+(`INSERT ... ON CONFLICT DO UPDATE SET ... = ... + excluded....`). This is safe
+to call concurrently from multiple coroutines without an application-level lock.
+
+`set_context_tokens()` replaces the counts unconditionally, and
+`get_context_tokens()` returns a `(input_tokens, output_tokens)` tuple.
+
 ### Forking
 
 `fork()` copies the current session's messages into a new session — useful for

{axio_context_sqlite-0.6.1 → axio_context_sqlite-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axio-context-sqlite"
-version = "0.6.1"
+version = "0.6.2"
 description = "SQLite-backed context store for Axio"
 readme = "README.md"
 requires-python = ">=3.12"