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.
- orchid_storage_sqlite-1.1.0/.github/workflows/ci.yml +156 -0
- orchid_storage_sqlite-1.1.0/.gitignore +8 -0
- orchid_storage_sqlite-1.1.0/.pre-commit-config.yaml +11 -0
- orchid_storage_sqlite-1.1.0/AGENTS.md +141 -0
- orchid_storage_sqlite-1.1.0/CHANGELOG.md +21 -0
- orchid_storage_sqlite-1.1.0/LICENSE +21 -0
- orchid_storage_sqlite-1.1.0/PKG-INFO +145 -0
- orchid_storage_sqlite-1.1.0/README.md +118 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/__init__.py +111 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/chat_storage.py +257 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/config_storage.py +146 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/event_queue.py +355 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/event_storage.py +623 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/ingestion_manifest.py +120 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_client_registration_store.py +130 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_gateway_state_store.py +342 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/mcp_token_store.py +155 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/__init__.py +50 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/v001_initial_schema.py +359 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/migrations/v002_ingestion_manifest.py +48 -0
- orchid_storage_sqlite-1.1.0/orchid_storage_sqlite/visibility.py +45 -0
- orchid_storage_sqlite-1.1.0/pyproject.toml +74 -0
- orchid_storage_sqlite-1.1.0/tests/test_chat_storage.py +248 -0
- orchid_storage_sqlite-1.1.0/tests/test_checkpointer.py +41 -0
- orchid_storage_sqlite-1.1.0/tests/test_config_storage.py +83 -0
- orchid_storage_sqlite-1.1.0/tests/test_end_to_end_bloom.py +461 -0
- orchid_storage_sqlite-1.1.0/tests/test_entry_points.py +56 -0
- orchid_storage_sqlite-1.1.0/tests/test_event_queue.py +342 -0
- orchid_storage_sqlite-1.1.0/tests/test_event_storage.py +380 -0
- orchid_storage_sqlite-1.1.0/tests/test_ingestion_manifest.py +99 -0
- orchid_storage_sqlite-1.1.0/tests/test_jobstore_chat_binding_filter.py +201 -0
- orchid_storage_sqlite-1.1.0/tests/test_mcp_stores.py +443 -0
- orchid_storage_sqlite-1.1.0/tests/test_migration.py +105 -0
- 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,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
|