orchid-storage-sqlite 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. orchid_storage_sqlite-1.1.0/.github/workflows/ci.yml +156 -0
  2. orchid_storage_sqlite-1.1.0/.gitignore +8 -0
  3. orchid_storage_sqlite-1.1.0/.pre-commit-config.yaml +11 -0
  4. orchid_storage_sqlite-1.1.0/AGENTS.md +141 -0
  5. orchid_storage_sqlite-1.1.0/CHANGELOG.md +21 -0
  6. orchid_storage_sqlite-1.1.0/LICENSE +21 -0
  7. orchid_storage_sqlite-1.1.0/PKG-INFO +145 -0
  8. orchid_storage_sqlite-1.1.0/README.md +118 -0
  9. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/__init__.py +111 -0
  10. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/chat_storage.py +257 -0
  11. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/config_storage.py +146 -0
  12. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/event_queue.py +355 -0
  13. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/event_storage.py +623 -0
  14. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/ingestion_manifest.py +120 -0
  15. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_client_registration_store.py +130 -0
  16. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_gateway_state_store.py +342 -0
  17. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_token_store.py +155 -0
  18. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/__init__.py +50 -0
  19. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/v001_initial_schema.py +359 -0
  20. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/v002_ingestion_manifest.py +48 -0
  21. orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/visibility.py +45 -0
  22. orchid_storage_sqlite-1.1.0/pyproject.toml +74 -0
  23. orchid_storage_sqlite-1.1.0/tests/test_chat_storage.py +248 -0
  24. orchid_storage_sqlite-1.1.0/tests/test_checkpointer.py +41 -0
  25. orchid_storage_sqlite-1.1.0/tests/test_config_storage.py +83 -0
  26. orchid_storage_sqlite-1.1.0/tests/test_end_to_end_bloom.py +461 -0
  27. orchid_storage_sqlite-1.1.0/tests/test_entry_points.py +56 -0
  28. orchid_storage_sqlite-1.1.0/tests/test_event_queue.py +342 -0
  29. orchid_storage_sqlite-1.1.0/tests/test_event_storage.py +380 -0
  30. orchid_storage_sqlite-1.1.0/tests/test_ingestion_manifest.py +99 -0
  31. orchid_storage_sqlite-1.1.0/tests/test_jobstore_chat_binding_filter.py +201 -0
  32. orchid_storage_sqlite-1.1.0/tests/test_mcp_stores.py +443 -0
  33. orchid_storage_sqlite-1.1.0/tests/test_migration.py +105 -0
  34. orchid_storage_sqlite-1.1.0/tests/test_visibility.py +116 -0
@@ -0,0 +1,156 @@
1
+ # orchid-storage-sqlite — CI + Semantic Release + PyPI Publish
2
+
3
+ name: CI
4
+
5
+ on:
6
+ pull_request:
7
+ branches: [main]
8
+ push:
9
+ branches: [main]
10
+
11
+ jobs:
12
+ # ── Lint ────────────────────────────────────────────────────
13
+
14
+ ruff:
15
+ name: Ruff lint & format
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.13"
22
+ - run: pip install ruff
23
+ - run: ruff check orchid_storage_sqlite/
24
+ - run: ruff format --check orchid_storage_sqlite/
25
+
26
+ # ── Test ────────────────────────────────────────────────────
27
+
28
+ test:
29
+ name: Tests + coverage
30
+ runs-on: ubuntu-latest
31
+ needs: [ruff]
32
+ permissions:
33
+ contents: read
34
+ pull-requests: write
35
+ strategy:
36
+ matrix:
37
+ python-version: ['3.11', '3.12', '3.13']
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+ - uses: actions/setup-python@v5
41
+ with:
42
+ python-version: ${{ matrix.python-version }}
43
+ cache: pip
44
+ cache-dependency-path: pyproject.toml
45
+ - run: pip install -e ".[dev]" pytest-cov
46
+ - name: Run tests
47
+ run: |
48
+ pytest tests/ \
49
+ --cov=orchid_storage_sqlite \
50
+ --cov-report=term-missing \
51
+ --cov-report=xml:coverage.xml \
52
+ --junitxml=report.xml \
53
+ -x
54
+ - name: Upload coverage
55
+ if: always()
56
+ uses: actions/upload-artifact@v4
57
+ with:
58
+ name: coverage
59
+ path: coverage.xml
60
+ if-no-files-found: ignore
61
+ - name: Upload test report
62
+ if: always()
63
+ uses: actions/upload-artifact@v4
64
+ with:
65
+ name: test-report
66
+ path: report.xml
67
+ if-no-files-found: ignore
68
+ - name: Coverage summary
69
+ if: hashFiles('coverage.xml') != ''
70
+ uses: irongut/CodeCoverageSummary@v1.3.0
71
+ with:
72
+ filename: "**/coverage.xml"
73
+ format: markdown
74
+ output: both
75
+ badge: true
76
+ fail_below_min: false
77
+ thresholds: "50 75"
78
+ - name: Add coverage PR comment
79
+ if: github.event_name == 'pull_request' && hashFiles('code-coverage-results.md') != ''
80
+ uses: marocchino/sticky-pull-request-comment@v2
81
+ with:
82
+ header: coverage
83
+ path: code-coverage-results.md
84
+
85
+ # ── Build ───────────────────────────────────────────────────
86
+
87
+ build:
88
+ name: Build wheel
89
+ runs-on: ubuntu-latest
90
+ needs: [ruff, test]
91
+ steps:
92
+ - uses: actions/checkout@v4
93
+ - uses: actions/setup-python@v5
94
+ with:
95
+ python-version: "3.13"
96
+ - run: pip install build
97
+ - run: python -m build
98
+ - uses: actions/upload-artifact@v4
99
+ with:
100
+ name: dist
101
+ path: dist/
102
+ retention-days: 7
103
+
104
+ # ── Release + PyPI Publish (on main push) ───────────────────
105
+
106
+ release:
107
+ name: Release & publish
108
+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'
109
+ runs-on: ubuntu-latest
110
+ needs: [ruff, test, build]
111
+ permissions:
112
+ contents: write
113
+ id-token: write
114
+ steps:
115
+ - uses: actions/checkout@v4
116
+ with:
117
+ fetch-depth: 0
118
+ token: ${{ secrets.GITHUB_TOKEN }}
119
+ - uses: actions/setup-python@v5
120
+ with:
121
+ python-version: "3.13"
122
+ - run: pip install python-semantic-release build
123
+ - name: Configure git
124
+ run: |
125
+ git config user.name "github-actions[bot]"
126
+ git config user.email "github-actions[bot]@users.noreply.github.com"
127
+ - name: Bump version & tag
128
+ id: version
129
+ env:
130
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
131
+ run: |
132
+ before=$(python -c "import re,pathlib; c=pathlib.Path('orchid_storage_sqlite/__init__.py').read_text(); m=re.search(r'__version__\s*=\s*\"([^\"]+)\"', c); print(m.group(1))")
133
+ semantic-release version --push --tag --commit || true
134
+ after=$(python -c "import re,pathlib; c=pathlib.Path('orchid_storage_sqlite/__init__.py').read_text(); m=re.search(r'__version__\s*=\s*\"([^\"]+)\"', c); print(m.group(1))")
135
+ echo "before=$before"
136
+ echo "after=$after"
137
+ if [ "$before" = "$after" ]; then
138
+ echo "No version bump — skipping publish steps."
139
+ echo "released=false" >> "$GITHUB_OUTPUT"
140
+ else
141
+ echo "Bumped $before → $after."
142
+ echo "released=true" >> "$GITHUB_OUTPUT"
143
+ fi
144
+ - name: Build distribution
145
+ if: steps.version.outputs.released == 'true'
146
+ run: python -m build
147
+ - name: Publish GitHub Release
148
+ if: steps.version.outputs.released == 'true'
149
+ env:
150
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
151
+ run: semantic-release publish
152
+ - name: Publish to PyPI
153
+ if: steps.version.outputs.released == 'true'
154
+ uses: pypa/gh-action-pypi-publish@release/v1
155
+ with:
156
+ skip-existing: true
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ .env
5
+ .venv/
6
+ *.egg-info/
7
+ dist/
8
+ build/
@@ -0,0 +1,11 @@
1
+ # Pre-commit hooks — run automatically before each commit
2
+ # Install: pip install pre-commit && pre-commit install
3
+ # Manual: pre-commit run --all-files
4
+
5
+ repos:
6
+ - repo: https://github.com/astral-sh/ruff-pre-commit
7
+ rev: v0.16.0
8
+ hooks:
9
+ - id: ruff
10
+ args: [--fix, --exit-non-zero-on-fix]
11
+ - id: ruff-format
@@ -0,0 +1,141 @@
1
+ # orchid-storage-sqlite — AI Context
2
+
3
+ ## What This Package Is
4
+
5
+ `orchid-storage-sqlite` is the SQLite storage plugin for the Orchid AI
6
+ framework. It provides SQLite-backed implementations of the framework's
7
+ storage / persistence ABCs, plus the migrations that own every
8
+ framework table:
9
+
10
+ | Class | Implements | Module |
11
+ |-------|-----------|--------|
12
+ | `OrchidSQLiteChatStorage` | `OrchidChatStorage` | `chat_storage.py` |
13
+ | `OrchidSQLiteConfigStorage` | `OrchidConfigStorage` | `config_storage.py` |
14
+ | `OrchidSQLiteMCPTokenStore` | `OrchidMCPTokenStore` | `mcp_token_store.py` |
15
+ | `OrchidSQLiteMCPClientRegistrationStore` | `OrchidMCPClientRegistrationStore` | `mcp_client_registration_store.py` |
16
+ | `OrchidSQLiteMCPGatewayStateStore` | `OrchidMCPGatewayClientStore` + `OrchidMCPGatewayAuthCodeStore` + `OrchidMCPGatewayTokenStore` | `mcp_gateway_state_store.py` |
17
+ | `OrchidSQLiteIngestionManifest` | `OrchidIngestionManifest` | `ingestion_manifest.py` |
18
+ | `SQLiteEventStorage` (+ 4 narrow stores) | `OrchidSignalStore` / `OrchidJobStore` / `OrchidScheduleStore` / `OrchidTriggerStore` | `event_storage.py` |
19
+ | `SQLiteSignalQueue` | `OrchidSignalQueue` | `event_queue.py` |
20
+ | `SQLiteMigrationRunner` | `OrchidMigrationRunner` | `migrations/__init__.py` |
21
+ | `_build_sqlite_checkpointer` | LangGraph `BaseCheckpointSaver` | `__init__.py` |
22
+ | `_build_sqlite_filter` | `_Filter` (visibility fragment) | `visibility.py` |
23
+
24
+ Migration `v001_initial_schema` provisions every framework-owned table in
25
+ a single pass; `v002_ingestion_manifest` adds the indexing manifest.
26
+
27
+ ## Entry-Point Auto-Registration
28
+
29
+ The package registers two extension points via Python
30
+ `importlib.metadata` entry points:
31
+
32
+ ```toml
33
+ [project.entry-points."orchid.visibility_fragments"]
34
+ sqlite = "orchid_storage_sqlite:_register"
35
+
36
+ [project.entry-points."orchid.checkpointers"]
37
+ sqlite = "orchid_storage_sqlite:_register"
38
+ ```
39
+
40
+ Once installed, `build_run_filter_clause(auth, dialect="sqlite")` and
41
+ `build_checkpointer("sqlite", dsn=...)` resolve through the registry —
42
+ no manual `register_*` calls. The registry is populated by
43
+ `orchid_ai.plugins.lazy_init_plugins()` (called automatically by the
44
+ `Orchid` facade); direct factory calls outside an `Orchid` instance
45
+ need `lazy_init_plugins()` or a direct `_register()` call.
46
+
47
+ The storage classes themselves are **not** auto-registered — consumers
48
+ reference them by dotted class path in their YAML:
49
+
50
+ ```yaml
51
+ storage:
52
+ class: orchid_storage_sqlite.chat_storage.OrchidSQLiteChatStorage
53
+ dsn: ~/.orchid/chats.db
54
+
55
+ config_storage:
56
+ enabled: true
57
+ class: orchid_storage_sqlite.config_storage.OrchidSQLiteConfigStorage
58
+ dsn: ~/.orchid/chats.db
59
+ ```
60
+
61
+ All classes are also re-exported at package top level
62
+ (`orchid_storage_sqlite.OrchidSQLiteChatStorage`,
63
+ `orchid_storage_sqlite.SQLiteEventStorage`, …).
64
+
65
+ ## Key Files
66
+
67
+ | File | Purpose |
68
+ |------|---------|
69
+ | `chat_storage.py` | `OrchidSQLiteChatStorage` + row mappers |
70
+ | `config_storage.py` | `OrchidSQLiteConfigStorage` |
71
+ | `mcp_token_store.py` | `OrchidSQLiteMCPTokenStore` |
72
+ | `mcp_client_registration_store.py` | `OrchidSQLiteMCPClientRegistrationStore` |
73
+ | `mcp_gateway_state_store.py` | `OrchidSQLiteMCPGatewayStateStore` (all three gateway ABCs) |
74
+ | `ingestion_manifest.py` | `OrchidSQLiteIngestionManifest` |
75
+ | `event_storage.py` | `SQLiteEventStorage` facade + four narrow stores |
76
+ | `event_queue.py` | `SQLiteSignalQueue` + `_SQLiteDBTransaction` (ledger of leases/DLQ) |
77
+ | `visibility.py` | `_build_sqlite_filter` (named `:param` bind style) |
78
+ | `migrations/__init__.py` | `SQLiteMigrationRunner` (dialect + `_migrations` table) |
79
+ | `migrations/v001_initial_schema.py` | Initial schema (all framework tables) |
80
+ | `migrations/v002_ingestion_manifest.py` | Ingestion manifest table + index |
81
+ | `__init__.py` | Entry-point `_register()` callable + checkpointer factory |
82
+
83
+ ## Schema Ownership
84
+
85
+ All store classes share one database and one migration runner. The
86
+ first `init_db()` on a DSN applies the pending migrations; every later
87
+ call is a no-op (`CREATE TABLE IF NOT EXISTS`). Framework versions are
88
+ recorded bare (`"001"`, `"002"`); integrator extras from
89
+ `extra_migrations_package` run afterwards with the `ext:` prefix.
90
+
91
+ JSON columns (`agents_used`, `metadata`, `scopes`, `identity`, `spec`,
92
+ `config`, …) are stored as serialised `TEXT`. The owning store class
93
+ performs the `json.dumps` / `json.loads` boundary — callers always see
94
+ Python objects, never strings.
95
+
96
+ ## Testing
97
+
98
+ Tests use `:memory:` SQLite databases — no external services.
99
+
100
+ ```bash
101
+ cd orchid-storage-sqlite
102
+ pip install -e ".[dev]"
103
+ pytest tests/ -x
104
+ ruff check orchid_storage_sqlite/ tests/
105
+ ruff format orchid_storage_sqlite/ tests/
106
+ ```
107
+
108
+ ## Common Pitfalls
109
+
110
+ - **Single-writer engine.** Write-heavy flows (signal queue) serialise
111
+ through transactions; don't parallelise writes on one connection.
112
+ - **`:memory:` databases are per-connection.** Re-opening a store with
113
+ `dsn=":memory:"` creates a fresh empty database; use a file (or
114
+ `tmp_path`) when state must survive `init_db()`.
115
+ - **WAL + `foreign_keys=ON`** are set by every store's `init_db()`;
116
+ cascade deletes (chat messages, conversation summaries) depend on the
117
+ foreign-keys pragma.
118
+ - **`float()` on TEXT columns.** SQLite stores timestamps as `TEXT` in
119
+ some tables and `REAL` in others — row mappers defensively fall back
120
+ to `time.time()` when the value isn't numeric. Keep that behaviour.
121
+ - **Migration v001 is the single root schema.** New framework tables
122
+ belong in a new `vNNN_*.py` module (never edit an applied migration);
123
+ `discover_migrations` scans for `v*` modules exposing `VERSION`, `up`
124
+ and `down`.
125
+ - **Event queue leases are time-based.** `dequeue` bumps `attempt` and
126
+ sets `lease_until`; a crashed consumer's message becomes visible again
127
+ after the lease expires. `nack` schedules a retry; max-attempt rows
128
+ move to `signal_queue_dead_letter`.
129
+ - **`SQLiteEventStorage(conn=...)` does not own the connection.**
130
+ `close()` only closes connections opened from `dsn=`; shared-connection
131
+ callers close their own handle.
132
+ - **`:memory:` is per-connection.** Constructing `SQLiteEventStorage(dsn=":memory:")`
133
+ and `SQLiteSignalQueue(dsn=":memory:")` yields **two different empty
134
+ databases**; pass the same `conn=` to both (the dispatcher's
135
+ transactional outbox depends on it).
136
+ - **Visibility fragment uses named bind params** (`:tenant_key`,
137
+ `:user_id`). Callers pass `**fragment.params` to aiosqlite — do not
138
+ mix in positional `?` placeholders.
139
+ - **The checkpointer keeps a long-lived connection.** The registered
140
+ `sqlite` builder connects once and returns the saver; call
141
+ `shutdown_checkpointer(saver)` (or `saver.aclose()`) to release it.
@@ -0,0 +1,21 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [1.0.0] - TBD
6
+
7
+ ### Added
8
+
9
+ - `OrchidSQLiteChatStorage`, `OrchidSQLiteConfigStorage`,
10
+ `OrchidSQLiteMCPTokenStore`,
11
+ `OrchidSQLiteMCPClientRegistrationStore`,
12
+ `OrchidSQLiteMCPGatewayStateStore` and
13
+ `OrchidSQLiteIngestionManifest` extracted from `orchid-ai` core.
14
+ - `SQLiteEventStorage` (+ four narrow stores) and `SQLiteSignalQueue`
15
+ extracted from `orchid-ai` core.
16
+ - SQLite schema migrations v001 (all framework-owned tables) and v002
17
+ (ingestion manifest) with the `SQLiteMigrationRunner`.
18
+ - SQLite visibility fragment for `build_run_filter_clause`,
19
+ auto-registered via the `orchid.visibility_fragments` entry-point group.
20
+ - Async SQLite LangGraph checkpointer, auto-registered as the `sqlite`
21
+ type via the `orchid.checkpointers` entry-point group.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Francesco Marchesini
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,145 @@
1
+ Metadata-Version: 2.5
2
+ Name: orchid-storage-sqlite
3
+ Version: 1.1.0
4
+ Summary: SQLite storage backend plugin for the Orchid AI framework
5
+ Project-URL: Homepage, https://github.com/gadz82/orchid-storage-sqlite
6
+ Project-URL: Issues, https://github.com/gadz82/orchid-storage-sqlite/issues
7
+ License: MIT
8
+ License-File: LICENSE
9
+ Keywords: agents,ai,aiosqlite,sqlite,storage
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
17
+ Requires-Python: >=3.11
18
+ Requires-Dist: aiosqlite>=0.20.0
19
+ Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0
20
+ Requires-Dist: orchid-ai>=1.11.0
21
+ Provides-Extra: dev
22
+ Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
23
+ Requires-Dist: pytest-cov>=6.0; extra == 'dev'
24
+ Requires-Dist: pytest>=8.0; extra == 'dev'
25
+ Requires-Dist: ruff>=0.9.0; extra == 'dev'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # orchid-storage-sqlite
29
+
30
+ SQLite storage backend package for the [Orchid AI](https://github.com/gadz82/orchid) framework.
31
+
32
+ ## What it provides
33
+
34
+ SQLite implementations of the framework's storage / persistence ABCs:
35
+
36
+ - `OrchidSQLiteChatStorage` — chat sessions + messages + conversation summaries
37
+ - `OrchidSQLiteConfigStorage` — agent configuration CRUD
38
+ - `OrchidSQLiteMCPTokenStore` — per-user MCP OAuth tokens
39
+ - `OrchidSQLiteMCPClientRegistrationStore` — RFC 7591 dynamic-client registrations
40
+ - `OrchidSQLiteMCPGatewayStateStore` — inbound gateway clients / auth codes / tokens
41
+ - `OrchidSQLiteIngestionManifest` — content-hash tracking for idempotent indexing
42
+ - `SQLiteEventStorage` (+ four narrow stores) — Pollen + Bloom signal / job /
43
+ schedule / trigger persistence
44
+ - `SQLiteSignalQueue` — durable lease-based signal queue with dead-lettering
45
+ - `SQLiteMigrationRunner` + migrations v001 (all framework-owned tables) and
46
+ v002 (ingestion manifest)
47
+ - A SQLite visibility fragment for `build_run_filter_clause`
48
+ - An async SQLite LangGraph checkpointer (registered as the `sqlite` type)
49
+
50
+ The visibility fragment and checkpointer auto-register through
51
+ `importlib.metadata` entry points — no manual `register_*` calls.
52
+
53
+ ## Installation
54
+
55
+ ```bash
56
+ pip install orchid-storage-sqlite
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ Reference the classes you need in your `orchid.yml`:
62
+
63
+ ```yaml
64
+ storage:
65
+ class: orchid_storage_sqlite.chat_storage.OrchidSQLiteChatStorage
66
+ dsn: ~/.orchid/chats.db
67
+
68
+ config_storage:
69
+ enabled: true
70
+ class: orchid_storage_sqlite.config_storage.OrchidSQLiteConfigStorage
71
+ dsn: ~/.orchid/chats.db
72
+
73
+ checkpointer:
74
+ type: sqlite
75
+ dsn: ~/.orchid/checkpoints.db
76
+ ```
77
+
78
+ For MCP gateway / OAuth deployments, add:
79
+
80
+ ```yaml
81
+ mcp_token_store:
82
+ class: orchid_storage_sqlite.mcp_token_store.OrchidSQLiteMCPTokenStore
83
+ dsn: ~/.orchid/chats.db
84
+
85
+ mcp_client_registration_store:
86
+ class: orchid_storage_sqlite.mcp_client_registration_store.OrchidSQLiteMCPClientRegistrationStore
87
+ dsn: ~/.orchid/chats.db
88
+
89
+ mcp_gateway_state_store:
90
+ class: orchid_storage_sqlite.mcp_gateway_state_store.OrchidSQLiteMCPGatewayStateStore
91
+ dsn: ~/.orchid/chats.db
92
+ ```
93
+
94
+ For the events block (Pollen + Bloom):
95
+
96
+ ```yaml
97
+ events:
98
+ enabled: true
99
+ store:
100
+ class: orchid_storage_sqlite.event_storage.SQLiteEventStorage
101
+ extra_args:
102
+ dsn: ~/.orchid/chats.db
103
+ queue:
104
+ class: orchid_storage_sqlite.event_queue.SQLiteSignalQueue
105
+ ```
106
+
107
+ Or build any of them programmatically:
108
+
109
+ ```python
110
+ from orchid_storage_sqlite import OrchidSQLiteChatStorage, SQLiteSignalQueue, SQLiteEventStorage
111
+
112
+ storage = OrchidSQLiteChatStorage(dsn="~/.orchid/chats.db")
113
+ await storage.init_db()
114
+ ```
115
+
116
+ Use `:memory:` for tests and ephemeral runs.
117
+
118
+ ## Schema ownership
119
+
120
+ The single `v001_initial_schema` migration creates **all** framework
121
+ tables (chat, MCP, events, agent_configs, conversation_summaries) in one
122
+ pass; `v002_ingestion_manifest` adds the indexing manifest. All store
123
+ classes share the same migration runner, so it does not matter which
124
+ class triggers `init_db()` first; subsequent calls become no-ops thanks
125
+ to `CREATE TABLE IF NOT EXISTS`.
126
+
127
+ Integrators can append their own migrations on top of this package's by
128
+ setting `extra_migrations_package` (a dotted import path) on the storage
129
+ class — their migrations run after the framework's and are recorded with
130
+ an `ext:` prefix in the shared `_migrations` table.
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ cd orchid-storage-sqlite
136
+ pip install -e ".[dev]"
137
+ pytest tests/ -x
138
+ ruff check orchid_storage_sqlite/ tests/
139
+ ```
140
+
141
+ Tests use `:memory:` / `tmp_path` SQLite databases — no services required.
142
+
143
+ ## License
144
+
145
+ MIT
@@ -0,0 +1,118 @@
1
+ # orchid-storage-sqlite
2
+
3
+ SQLite storage backend package for the [Orchid AI](https://github.com/gadz82/orchid) framework.
4
+
5
+ ## What it provides
6
+
7
+ SQLite implementations of the framework's storage / persistence ABCs:
8
+
9
+ - `OrchidSQLiteChatStorage` — chat sessions + messages + conversation summaries
10
+ - `OrchidSQLiteConfigStorage` — agent configuration CRUD
11
+ - `OrchidSQLiteMCPTokenStore` — per-user MCP OAuth tokens
12
+ - `OrchidSQLiteMCPClientRegistrationStore` — RFC 7591 dynamic-client registrations
13
+ - `OrchidSQLiteMCPGatewayStateStore` — inbound gateway clients / auth codes / tokens
14
+ - `OrchidSQLiteIngestionManifest` — content-hash tracking for idempotent indexing
15
+ - `SQLiteEventStorage` (+ four narrow stores) — Pollen + Bloom signal / job /
16
+ schedule / trigger persistence
17
+ - `SQLiteSignalQueue` — durable lease-based signal queue with dead-lettering
18
+ - `SQLiteMigrationRunner` + migrations v001 (all framework-owned tables) and
19
+ v002 (ingestion manifest)
20
+ - A SQLite visibility fragment for `build_run_filter_clause`
21
+ - An async SQLite LangGraph checkpointer (registered as the `sqlite` type)
22
+
23
+ The visibility fragment and checkpointer auto-register through
24
+ `importlib.metadata` entry points — no manual `register_*` calls.
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install orchid-storage-sqlite
30
+ ```
31
+
32
+ ## Usage
33
+
34
+ Reference the classes you need in your `orchid.yml`:
35
+
36
+ ```yaml
37
+ storage:
38
+ class: orchid_storage_sqlite.chat_storage.OrchidSQLiteChatStorage
39
+ dsn: ~/.orchid/chats.db
40
+
41
+ config_storage:
42
+ enabled: true
43
+ class: orchid_storage_sqlite.config_storage.OrchidSQLiteConfigStorage
44
+ dsn: ~/.orchid/chats.db
45
+
46
+ checkpointer:
47
+ type: sqlite
48
+ dsn: ~/.orchid/checkpoints.db
49
+ ```
50
+
51
+ For MCP gateway / OAuth deployments, add:
52
+
53
+ ```yaml
54
+ mcp_token_store:
55
+ class: orchid_storage_sqlite.mcp_token_store.OrchidSQLiteMCPTokenStore
56
+ dsn: ~/.orchid/chats.db
57
+
58
+ mcp_client_registration_store:
59
+ class: orchid_storage_sqlite.mcp_client_registration_store.OrchidSQLiteMCPClientRegistrationStore
60
+ dsn: ~/.orchid/chats.db
61
+
62
+ mcp_gateway_state_store:
63
+ class: orchid_storage_sqlite.mcp_gateway_state_store.OrchidSQLiteMCPGatewayStateStore
64
+ dsn: ~/.orchid/chats.db
65
+ ```
66
+
67
+ For the events block (Pollen + Bloom):
68
+
69
+ ```yaml
70
+ events:
71
+ enabled: true
72
+ store:
73
+ class: orchid_storage_sqlite.event_storage.SQLiteEventStorage
74
+ extra_args:
75
+ dsn: ~/.orchid/chats.db
76
+ queue:
77
+ class: orchid_storage_sqlite.event_queue.SQLiteSignalQueue
78
+ ```
79
+
80
+ Or build any of them programmatically:
81
+
82
+ ```python
83
+ from orchid_storage_sqlite import OrchidSQLiteChatStorage, SQLiteSignalQueue, SQLiteEventStorage
84
+
85
+ storage = OrchidSQLiteChatStorage(dsn="~/.orchid/chats.db")
86
+ await storage.init_db()
87
+ ```
88
+
89
+ Use `:memory:` for tests and ephemeral runs.
90
+
91
+ ## Schema ownership
92
+
93
+ The single `v001_initial_schema` migration creates **all** framework
94
+ tables (chat, MCP, events, agent_configs, conversation_summaries) in one
95
+ pass; `v002_ingestion_manifest` adds the indexing manifest. All store
96
+ classes share the same migration runner, so it does not matter which
97
+ class triggers `init_db()` first; subsequent calls become no-ops thanks
98
+ to `CREATE TABLE IF NOT EXISTS`.
99
+
100
+ Integrators can append their own migrations on top of this package's by
101
+ setting `extra_migrations_package` (a dotted import path) on the storage
102
+ class — their migrations run after the framework's and are recorded with
103
+ an `ext:` prefix in the shared `_migrations` table.
104
+
105
+ ## Development
106
+
107
+ ```bash
108
+ cd orchid-storage-sqlite
109
+ pip install -e ".[dev]"
110
+ pytest tests/ -x
111
+ ruff check orchid_storage_sqlite/ tests/
112
+ ```
113
+
114
+ Tests use `:memory:` / `tmp_path` SQLite databases — no services required.
115
+
116
+ ## License
117
+
118
+ MIT