orchid-storage-sqlite 1.1.0__py3-none-any.whl

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.
@@ -0,0 +1,111 @@
1
+ """SQLite storage plugin for the Orchid AI framework.
2
+
3
+ Provides SQLite-backed implementations of every framework
4
+ storage / persistence ABC:
5
+
6
+ - :class:`OrchidSQLiteChatStorage` — chat sessions + messages
7
+ (:class:`orchid_ai.persistence.base.OrchidChatStorage`).
8
+ - :class:`OrchidSQLiteConfigStorage` — agent configuration CRUD
9
+ (:class:`orchid_ai.config.storage.OrchidConfigStorage`).
10
+ - :class:`OrchidSQLiteMCPTokenStore` — per-server OAuth tokens
11
+ (:class:`orchid_ai.core.mcp.OrchidMCPTokenStore`).
12
+ - :class:`OrchidSQLiteMCPClientRegistrationStore` — RFC 7591 DCR
13
+ (:class:`orchid_ai.core.mcp.OrchidMCPClientRegistrationStore`).
14
+ - :class:`OrchidSQLiteMCPGatewayStateStore` — gateway clients,
15
+ auth codes and tokens (all three
16
+ :mod:`orchid_ai.core.mcp_gateway_state` ABCs).
17
+ - :class:`OrchidSQLiteIngestionManifest` — content-hash tracking for
18
+ idempotent indexing
19
+ (:class:`orchid_ai.core.ingestion_manifest.OrchidIngestionManifest`).
20
+ - :class:`SQLiteEventStorage` (+ four narrow stores) — events
21
+ signal/job/schedule/trigger persistence.
22
+ - :class:`SQLiteSignalQueue` — durable lease-based signal queue.
23
+ - :class:`SQLiteMigrationRunner` — migration tracking against a
24
+ ``_migrations`` table (migrations v001 + v002).
25
+ - A SQLite checkpointer factory wired into
26
+ :func:`orchid_ai.checkpointing.factory.build_checkpointer` via the
27
+ ``sqlite`` type string.
28
+ - A SQLite visibility fragment for
29
+ :func:`orchid_ai.events.visibility.build_run_filter_clause`.
30
+
31
+ Auto-registers the visibility fragment + checkpointer via
32
+ ``importlib.metadata`` entry points; storage classes are referenced
33
+ by dotted import path in the consumer's YAML.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import logging
39
+
40
+ __version__ = "1.1.0"
41
+
42
+ from .chat_storage import OrchidSQLiteChatStorage
43
+ from .config_storage import OrchidSQLiteConfigStorage
44
+ from .event_queue import SQLiteSignalQueue
45
+ from .event_storage import (
46
+ SQLiteEventStorage,
47
+ SQLiteJobStore,
48
+ SQLiteScheduleStore,
49
+ SQLiteSignalStore,
50
+ SQLiteTriggerStore,
51
+ )
52
+ from .ingestion_manifest import OrchidSQLiteIngestionManifest
53
+ from .mcp_client_registration_store import OrchidSQLiteMCPClientRegistrationStore
54
+ from .mcp_gateway_state_store import OrchidSQLiteMCPGatewayStateStore
55
+ from .mcp_token_store import OrchidSQLiteMCPTokenStore
56
+ from .migrations import SQLiteMigrationRunner
57
+ from .visibility import _build_sqlite_filter
58
+
59
+ __all__ = [
60
+ "OrchidSQLiteChatStorage",
61
+ "OrchidSQLiteConfigStorage",
62
+ "OrchidSQLiteIngestionManifest",
63
+ "OrchidSQLiteMCPClientRegistrationStore",
64
+ "OrchidSQLiteMCPGatewayStateStore",
65
+ "OrchidSQLiteMCPTokenStore",
66
+ "SQLiteEventStorage",
67
+ "SQLiteJobStore",
68
+ "SQLiteMigrationRunner",
69
+ "SQLiteScheduleStore",
70
+ "SQLiteSignalQueue",
71
+ "SQLiteSignalStore",
72
+ "SQLiteTriggerStore",
73
+ ]
74
+
75
+ logger = logging.getLogger(__name__)
76
+
77
+
78
+ async def _build_sqlite_checkpointer(dsn: str):
79
+ """Build an async SQLite checkpointer from a file path."""
80
+ import aiosqlite
81
+ from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
82
+
83
+ if not dsn:
84
+ raise ValueError("DSN is required for sqlite checkpointer (e.g. ~/.orchid/checkpoints.db)")
85
+ # ``AsyncSqliteSaver.from_conn_string`` is an async *context manager*,
86
+ # not a saver — construct the saver from a long-lived connection so
87
+ # it outlives this call; ``shutdown_checkpointer`` closes it.
88
+ conn = await aiosqlite.connect(dsn)
89
+ checkpointer = AsyncSqliteSaver(conn)
90
+ await checkpointer.setup()
91
+ logger.info("[orchid-storage-sqlite] Checkpointer ready")
92
+ return checkpointer
93
+
94
+
95
+ def _register() -> None:
96
+ """Entry-point callable — registers the sqlite visibility fragment and checkpointer."""
97
+ try:
98
+ from orchid_ai.events.visibility import register_visibility_fragment
99
+
100
+ register_visibility_fragment("sqlite", _build_sqlite_filter)
101
+ logger.debug("[orchid-storage-sqlite] Registered visibility fragment")
102
+ except ImportError:
103
+ logger.debug("[orchid-storage-sqlite] Skipping visibility fragment (not in this orchid-ai version)")
104
+
105
+ try:
106
+ from orchid_ai.checkpointing.factory import register_checkpointer
107
+
108
+ register_checkpointer("sqlite", _build_sqlite_checkpointer)
109
+ logger.debug("[orchid-storage-sqlite] Registered checkpointer")
110
+ except ImportError:
111
+ logger.debug("[orchid-storage-sqlite] Skipping checkpointer (not in this orchid-ai version)")
@@ -0,0 +1,257 @@
1
+ """
2
+ SQLite chat storage — ``OrchidChatStorage`` over a single aiosqlite file.
3
+
4
+ Data is stored in a single file (default: ``~/.orchid/chats.db``) or
5
+ ``:memory:`` for tests.
6
+
7
+ Configuration::
8
+
9
+ storage:
10
+ class: orchid_storage_sqlite.chat_storage.OrchidSQLiteChatStorage
11
+ dsn: ~/.orchid/chats.db
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import logging
18
+ import os
19
+ import uuid
20
+ from datetime import datetime
21
+
22
+ import aiosqlite
23
+ from orchid_ai.persistence.base import OrchidChatStorage
24
+ from orchid_ai.persistence.models import OrchidChatMessage, OrchidChatSession, utcnow
25
+
26
+ from .migrations import SQLiteMigrationRunner
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+
31
+ class OrchidSQLiteChatStorage(OrchidChatStorage):
32
+ """
33
+ Async SQLite storage for chat sessions and messages.
34
+
35
+ Constructor accepts the file path via ``dsn`` and an optional
36
+ ``extra_migrations_package`` (dotted import path) so integrators
37
+ can append their own migrations after this package's — see
38
+ :class:`orchid_ai.persistence.migrations.runner.OrchidMigrationRunner`.
39
+
40
+ Use ``:memory:`` for in-memory databases (tests). The default path
41
+ ``~/.orchid/chats.db`` is resolved at init time.
42
+ """
43
+
44
+ def __init__(self, *, dsn: str, extra_migrations_package: str | None = None):
45
+ self._db_path = os.path.expanduser(dsn)
46
+ self._conn: aiosqlite.Connection | None = None
47
+ self._migrator = SQLiteMigrationRunner(
48
+ extra_migrations_package=extra_migrations_package,
49
+ )
50
+
51
+ # ── Lifecycle ────────────────────────────────────────────
52
+
53
+ async def init_db(self) -> None:
54
+ if not self._is_memory_db(self._db_path):
55
+ os.makedirs(os.path.dirname(self._db_path) or ".", exist_ok=True)
56
+
57
+ self._conn = await aiosqlite.connect(self._db_path)
58
+ self._conn.row_factory = aiosqlite.Row
59
+ await self._conn.execute("PRAGMA journal_mode=WAL")
60
+ await self._conn.execute("PRAGMA foreign_keys=ON")
61
+ await self._migrator.run_up(self._conn)
62
+ logger.info("[OrchidChatStorage:sqlite] Initialised — %s", self._db_path)
63
+
64
+ @staticmethod
65
+ def _is_memory_db(path: str) -> bool:
66
+ """Detect in-memory SQLite databases.
67
+
68
+ Handles ``:memory:``, ``:memory:?cache=shared``, and
69
+ ``file::memory:`` URI variants.
70
+ """
71
+ return path == ":memory:" or path.startswith(":memory:?") or ":memory:" in path
72
+
73
+ async def close(self) -> None:
74
+ if self._conn:
75
+ await self._conn.close()
76
+
77
+ # ── Sessions ─────────────────────────────────────────────
78
+
79
+ async def create_chat(
80
+ self,
81
+ tenant_id: str,
82
+ user_id: str,
83
+ title: str = "",
84
+ ) -> OrchidChatSession:
85
+ now = utcnow()
86
+ now_iso = now.isoformat()
87
+ chat = OrchidChatSession(
88
+ id=str(uuid.uuid4()),
89
+ tenant_id=tenant_id,
90
+ user_id=user_id,
91
+ title=title or "New chat",
92
+ created_at=now,
93
+ updated_at=now,
94
+ )
95
+ await self._conn.execute(
96
+ "INSERT INTO chat_sessions (id, tenant_id, user_id, title, created_at, updated_at) "
97
+ "VALUES (?, ?, ?, ?, ?, ?)",
98
+ (chat.id, chat.tenant_id, chat.user_id, chat.title, now_iso, now_iso),
99
+ )
100
+ await self._conn.commit()
101
+ return chat
102
+
103
+ async def list_chats(
104
+ self,
105
+ tenant_id: str,
106
+ user_id: str,
107
+ ) -> list[OrchidChatSession]:
108
+ cursor = await self._conn.execute(
109
+ "SELECT * FROM chat_sessions WHERE tenant_id = ? AND user_id = ? ORDER BY updated_at DESC",
110
+ (tenant_id, user_id),
111
+ )
112
+ rows = await cursor.fetchall()
113
+ return [_row_to_session(r) for r in rows]
114
+
115
+ async def get_chat(self, chat_id: str) -> OrchidChatSession | None:
116
+ cursor = await self._conn.execute(
117
+ "SELECT * FROM chat_sessions WHERE id = ?",
118
+ (chat_id,),
119
+ )
120
+ row = await cursor.fetchone()
121
+ return _row_to_session(row) if row else None
122
+
123
+ async def delete_chat(self, chat_id: str) -> None:
124
+ await self._conn.execute("DELETE FROM chat_sessions WHERE id = ?", (chat_id,))
125
+ await self._conn.commit()
126
+
127
+ async def update_title(self, chat_id: str, title: str) -> None:
128
+ now_iso = utcnow().isoformat()
129
+ await self._conn.execute(
130
+ "UPDATE chat_sessions SET title = ?, updated_at = ? WHERE id = ?",
131
+ (title, now_iso, chat_id),
132
+ )
133
+ await self._conn.commit()
134
+
135
+ async def mark_shared(self, chat_id: str) -> None:
136
+ now_iso = utcnow().isoformat()
137
+ await self._conn.execute(
138
+ "UPDATE chat_sessions SET is_shared = 1, updated_at = ? WHERE id = ?",
139
+ (now_iso, chat_id),
140
+ )
141
+ await self._conn.commit()
142
+
143
+ # ── Messages ─────────────────────────────────────────────
144
+
145
+ async def add_message(
146
+ self,
147
+ chat_id: str,
148
+ role: str,
149
+ content: str,
150
+ agents_used: list[str] | None = None,
151
+ metadata: dict | None = None,
152
+ ) -> OrchidChatMessage:
153
+ now = utcnow()
154
+ now_iso = now.isoformat()
155
+ msg = OrchidChatMessage(
156
+ id=str(uuid.uuid4()),
157
+ chat_id=chat_id,
158
+ role=role,
159
+ content=content,
160
+ agents_used=agents_used or [],
161
+ created_at=now,
162
+ metadata=metadata or {},
163
+ )
164
+ await self._conn.execute(
165
+ "INSERT INTO chat_messages (id, chat_id, role, content, agents_used, created_at, metadata) "
166
+ "VALUES (?, ?, ?, ?, ?, ?, ?)",
167
+ (
168
+ msg.id,
169
+ msg.chat_id,
170
+ msg.role,
171
+ msg.content,
172
+ json.dumps(msg.agents_used),
173
+ now_iso,
174
+ json.dumps(msg.metadata),
175
+ ),
176
+ )
177
+ await self._conn.execute(
178
+ "UPDATE chat_sessions SET updated_at = ? WHERE id = ?",
179
+ (now_iso, chat_id),
180
+ )
181
+ await self._conn.commit()
182
+ return msg
183
+
184
+ async def get_messages(
185
+ self,
186
+ chat_id: str,
187
+ limit: int = 50,
188
+ offset: int = 0,
189
+ ) -> list[OrchidChatMessage]:
190
+ cursor = await self._conn.execute(
191
+ "SELECT * FROM chat_messages WHERE chat_id = ? ORDER BY created_at ASC LIMIT ? OFFSET ?",
192
+ (chat_id, limit, offset),
193
+ )
194
+ rows = await cursor.fetchall()
195
+ return [_row_to_message(r) for r in rows]
196
+
197
+ # ── Conversation summaries (running-summary memory) ──────
198
+
199
+ async def get_conversation_summary(self, chat_id: str) -> str | None:
200
+ cursor = await self._conn.execute(
201
+ "SELECT summary_text FROM conversation_summaries WHERE chat_id = ?",
202
+ (chat_id,),
203
+ )
204
+ row = await cursor.fetchone()
205
+ return row[0] if row else None
206
+
207
+ async def save_conversation_summary(self, chat_id: str, summary: str, turn_number: int) -> None:
208
+ now_iso = utcnow().isoformat()
209
+ await self._conn.execute(
210
+ "INSERT INTO conversation_summaries (chat_id, summary_text, turn_number, updated_at) "
211
+ "VALUES (?, ?, ?, ?) "
212
+ "ON CONFLICT(chat_id) DO UPDATE SET summary_text = ?, turn_number = ?, updated_at = ?",
213
+ (chat_id, summary, turn_number, now_iso, summary, turn_number, now_iso),
214
+ )
215
+ await self._conn.commit()
216
+
217
+
218
+ # ── Row mappers ──────────────────────────────────────────────
219
+
220
+
221
+ def _parse_dt(val: str | datetime) -> datetime:
222
+ if isinstance(val, datetime):
223
+ return val
224
+ try:
225
+ return datetime.fromisoformat(val)
226
+ except (ValueError, TypeError):
227
+ return utcnow()
228
+
229
+
230
+ def _row_to_session(row: aiosqlite.Row) -> OrchidChatSession:
231
+ return OrchidChatSession(
232
+ id=row["id"],
233
+ tenant_id=row["tenant_id"],
234
+ user_id=row["user_id"],
235
+ title=row["title"],
236
+ created_at=_parse_dt(row["created_at"]),
237
+ updated_at=_parse_dt(row["updated_at"]),
238
+ is_shared=bool(row["is_shared"]),
239
+ )
240
+
241
+
242
+ def _row_to_message(row: aiosqlite.Row) -> OrchidChatMessage:
243
+ agents_used = row["agents_used"]
244
+ if isinstance(agents_used, str):
245
+ agents_used = json.loads(agents_used)
246
+ meta = row["metadata"]
247
+ if isinstance(meta, str):
248
+ meta = json.loads(meta)
249
+ return OrchidChatMessage(
250
+ id=row["id"],
251
+ chat_id=row["chat_id"],
252
+ role=row["role"],
253
+ content=row["content"],
254
+ agents_used=agents_used,
255
+ created_at=_parse_dt(row["created_at"]),
256
+ metadata=meta,
257
+ )
@@ -0,0 +1,146 @@
1
+ """
2
+ SQLite config storage — ``OrchidConfigStorage`` over a single aiosqlite file.
3
+
4
+ Uses aiosqlite for async connection management. The ``agent_configs`` table
5
+ is created by this package's migration v001 when :meth:`init_db` runs.
6
+
7
+ Configuration::
8
+
9
+ config_storage:
10
+ enabled: true
11
+ class: orchid_storage_sqlite.config_storage.OrchidSQLiteConfigStorage
12
+ dsn: ~/.orchid/chats.db
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import logging
19
+ import os
20
+ from datetime import UTC, datetime
21
+
22
+ import aiosqlite
23
+ from orchid_ai.config.schema_agent import OrchidAgentConfig, _deep_merge
24
+ from orchid_ai.config.storage import OrchidConfigStorage
25
+
26
+ from .migrations import SQLiteMigrationRunner
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+
31
+ class OrchidSQLiteConfigStorage(OrchidConfigStorage):
32
+ """Async SQLite storage for agent configurations.
33
+
34
+ Reuses the same migration runner as the rest of this package — the
35
+ schema is applied once per database regardless of which storage
36
+ class initiates it. ``CREATE TABLE IF NOT EXISTS`` makes this safe
37
+ to call multiple times.
38
+ """
39
+
40
+ def __init__(self, *, dsn: str) -> None:
41
+ """Keyword-only constructor.
42
+
43
+ Parameters
44
+ ----------
45
+ dsn : str
46
+ SQLite database path (e.g. ``"~/.orchid/chats.db"`` or ``":memory:"``).
47
+ """
48
+ self._db_path = os.path.expanduser(dsn)
49
+ self._conn: aiosqlite.Connection | None = None
50
+ self._migrator = SQLiteMigrationRunner()
51
+
52
+ async def init_db(self) -> None:
53
+ if self._conn is not None:
54
+ return
55
+ if self._db_path != ":memory:":
56
+ os.makedirs(os.path.dirname(self._db_path) or ".", exist_ok=True)
57
+ self._conn = await aiosqlite.connect(self._db_path)
58
+ self._conn.row_factory = aiosqlite.Row
59
+ await self._conn.execute("PRAGMA journal_mode=WAL")
60
+ await self._conn.execute("PRAGMA foreign_keys=ON")
61
+ await self._migrator.run_up(self._conn)
62
+ logger.info("[OrchidConfigStorage:sqlite] Initialised — %s", self._db_path)
63
+
64
+ async def close(self) -> None:
65
+ if self._conn:
66
+ await self._conn.close()
67
+ self._conn = None
68
+
69
+ async def list_configs(self) -> list[dict]:
70
+ if self._conn is None:
71
+ return []
72
+ cursor = await self._conn.execute(
73
+ "SELECT name, config, created_at, updated_at FROM agent_configs ORDER BY updated_at DESC"
74
+ )
75
+ rows = await cursor.fetchall()
76
+ return [_row_to_config(r) for r in rows]
77
+
78
+ async def get_config(self, name: str) -> dict | None:
79
+ if self._conn is None:
80
+ return None
81
+ cursor = await self._conn.execute(
82
+ "SELECT name, config, created_at, updated_at FROM agent_configs WHERE name = ?",
83
+ (name,),
84
+ )
85
+ row = await cursor.fetchone()
86
+ return _row_to_config(row) if row else None
87
+
88
+ async def upsert_config(self, name: str, config: dict) -> dict:
89
+ if self._conn is None:
90
+ raise RuntimeError("SQLiteConfigStorage: not initialised. Call init_db() first.")
91
+ now = _now_iso()
92
+ config_json = json.dumps(config)
93
+ await self._conn.execute(
94
+ """INSERT INTO agent_configs (name, config, created_at, updated_at)
95
+ VALUES (?, ?, ?, ?)
96
+ ON CONFLICT(name) DO UPDATE SET
97
+ config = excluded.config,
98
+ updated_at = excluded.updated_at""",
99
+ (name, config_json, now, now),
100
+ )
101
+ await self._conn.commit()
102
+ return {"name": name, "config": config, "created_at": now, "updated_at": now}
103
+
104
+ async def patch_config(self, name: str, patch: dict) -> dict | None:
105
+ if self._conn is None:
106
+ raise RuntimeError("SQLiteConfigStorage: not initialised. Call init_db() first.")
107
+ cursor = await self._conn.execute(
108
+ "SELECT name, config, created_at, updated_at FROM agent_configs WHERE name = ?",
109
+ (name,),
110
+ )
111
+ row = await cursor.fetchone()
112
+ if row is None:
113
+ return None
114
+ existing = _row_to_config(row)
115
+ merged = _deep_merge(existing["config"], patch)
116
+ OrchidAgentConfig.model_validate(merged)
117
+ now = _now_iso()
118
+ config_json = json.dumps(merged)
119
+ await self._conn.execute(
120
+ "UPDATE agent_configs SET config = ?, updated_at = ? WHERE name = ?",
121
+ (config_json, now, name),
122
+ )
123
+ await self._conn.commit()
124
+ return {"name": name, "config": merged, "created_at": existing["created_at"], "updated_at": now}
125
+
126
+ async def delete_config(self, name: str) -> None:
127
+ if self._conn is None:
128
+ return
129
+ await self._conn.execute("DELETE FROM agent_configs WHERE name = ?", (name,))
130
+ await self._conn.commit()
131
+
132
+
133
+ def _now_iso() -> str:
134
+ return datetime.now(UTC).isoformat()
135
+
136
+
137
+ def _row_to_config(row: aiosqlite.Row) -> dict:
138
+ config = row["config"]
139
+ if isinstance(config, str):
140
+ config = json.loads(config)
141
+ return {
142
+ "name": row["name"],
143
+ "config": config,
144
+ "created_at": row["created_at"],
145
+ "updated_at": row["updated_at"],
146
+ }