xqo-sqlite 3.0.0__tar.gz

xqo_sqlite-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dudikkocak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xqo_sqlite-3.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: xqo-sqlite
+Version: 3.0.0
+Summary: SQLite event store for xqo
+Author: dudikkocak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudikkocak/xqo
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xqo<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-sqlite
+
+The `sqlite` event store for [xqo](https://github.com/dudikkocak/xqo): one SQLite file with indexed events, so task
+pages, deletes and history reads don't scan the log.
+
+```bash
+pip install xqo-sqlite
+```
+
+```json
+"storage": {"backend": "sqlite"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `path` | `events.db` | relative to the data dir's `logs/` folder |
+| `busy_timeout_ms` | `5000` | how long a second writer waits instead of failing |
+
+WAL mode (readers never block the writer), `synchronous=NORMAL` (a crash loses at most the last commits, never the
+file), and a quick integrity check when it opens. `xqo backup` writes a consistent copy with SQLite's online
+backup API. `XQO_STORAGE=sqlite` picks it for one run. Switching backends starts an empty store: events are not
+copied between stores.

xqo_sqlite-3.0.0/README.md

@@ -0,0 +1,22 @@
+# xqo-sqlite
+
+The `sqlite` event store for [xqo](https://github.com/dudikkocak/xqo): one SQLite file with indexed events, so task
+pages, deletes and history reads don't scan the log.
+
+```bash
+pip install xqo-sqlite
+```
+
+```json
+"storage": {"backend": "sqlite"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `path` | `events.db` | relative to the data dir's `logs/` folder |
+| `busy_timeout_ms` | `5000` | how long a second writer waits instead of failing |
+
+WAL mode (readers never block the writer), `synchronous=NORMAL` (a crash loses at most the last commits, never the
+file), and a quick integrity check when it opens. `xqo backup` writes a consistent copy with SQLite's online
+backup API. `XQO_STORAGE=sqlite` picks it for one run. Switching backends starts an empty store: events are not
+copied between stores.

xqo_sqlite-3.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xqo-sqlite"
+version = "3.0.0"
+description = "SQLite event store for xqo"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "dudikkocak"}]
+dependencies = [
+  "xqo>=3.0,<4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-timeout>=2.3"]
+
+[project.urls]
+Homepage = "https://github.com/dudikkocak/xqo"
+
+[project.entry-points."xqo.plugins"]
+sqlite = "xqo_sqlite:SqlitePlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

xqo_sqlite-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xqo_sqlite-3.0.0/src/xqo_sqlite/__init__.py

@@ -0,0 +1,134 @@
+"""xqo-sqlite: the "sqlite" event store for xqo.
+
+    pip install xqo-sqlite
+    "storage": {"backend": "sqlite"}                                  # logs/events.db
+    "storage": {"backend": "sqlite", "path": "events.db", "busy_timeout_ms": 5000}
+
+One SQLite file with indexed events: task pages, deletes and history reads don't scan the log. One server process
+per data dir, like every xqo store. `xqo backup` writes a consistent copy through SQLite's online backup API.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Iterable, Iterator
+
+from xqo.api import SEED_KINDS, EventStore, Plugin, register_store, store_path
+
+__version__ = "3.0.0"
+KEYS = {"backend", "path", "busy_timeout_ms"}
+
+
+class SqliteStore(EventStore):
+    """One SQLite file with indexed events: reads of one task tree, kinds and recent events don't scan the log.
+    WAL mode (readers never block the writer), busy_timeout (a second writer waits instead of failing),
+    synchronous=NORMAL (a crash loses at most the last commits, never the file), a quick_check when it opens."""
+    backend = "sqlite"
+    SCHEMA = """
+    CREATE TABLE IF NOT EXISTS events (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts TEXT, kind TEXT, task_id TEXT, root_id TEXT, data TEXT NOT NULL);
+    CREATE INDEX IF NOT EXISTS events_root ON events(root_id);
+    CREATE INDEX IF NOT EXISTS events_task ON events(task_id);
+    CREATE INDEX IF NOT EXISTS events_kind ON events(kind);
+    """
+
+    def __init__(self, path: str | Path, busy_timeout_ms: int = 5000):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        try:
+            self.db = sqlite3.connect(str(self.path), timeout=busy_timeout_ms / 1000, check_same_thread=False,
+                                      isolation_level=None)
+            self.db.execute(f"PRAGMA busy_timeout={int(busy_timeout_ms)}")
+            self.db.execute("PRAGMA journal_mode=WAL")
+            self.db.execute("PRAGMA synchronous=NORMAL")
+            ok = self.db.execute("PRAGMA quick_check").fetchone()[0]
+            if ok != "ok":
+                raise ValueError(f"storage: {self.path} failed its integrity check ({ok}). Restore a backup, or "
+                                 f"recover the readable rows: sqlite3 {self.path} \".recover\" | sqlite3 fixed.db")
+            self.db.executescript(self.SCHEMA)
+        except sqlite3.DatabaseError as e:
+            raise ValueError(f"storage: can't open {self.path}: {e}") from None
+
+    def _rows(self, sql: str, args: tuple = ()) -> list[dict]:
+        with self._lock:
+            rows = self.db.execute(sql, args).fetchall()
+        return [json.loads(r[0]) for r in rows]
+
+    def append(self, d: dict) -> None:
+        with self._lock:
+            self.db.execute("INSERT INTO events(ts, kind, task_id, root_id, data) VALUES (?, ?, ?, ?, ?)",
+                            (d.get("ts"), d.get("kind"), d.get("task_id"), d.get("root_task_id"), json.dumps(d)))
+
+    def recent(self, limit: int) -> list[dict]:
+        return self._rows("SELECT data FROM (SELECT seq, data FROM events ORDER BY seq DESC LIMIT ?) ORDER BY seq",
+                          (int(limit),))
+
+    def seeds(self) -> list[dict]:
+        marks = ",".join("?" * len(SEED_KINDS))
+        return self._rows(f"SELECT data FROM events WHERE kind IN ({marks}) ORDER BY seq", SEED_KINDS)
+
+    def tree(self, root_id: str) -> list[dict]:
+        return self._rows("SELECT data FROM events WHERE root_id = ? OR task_id = ? ORDER BY seq", (root_id, root_id))
+
+    def by_kind_prefix(self, prefix: str) -> list[dict]:
+        esc = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        return self._rows("SELECT data FROM events WHERE kind LIKE ? ESCAPE '\\' ORDER BY seq", (esc + "%",))
+
+    def purge(self, root_id: str, ids: set[str], keep_kinds: Iterable[str]) -> int:
+        keep = tuple(keep_kinds) or ("",)
+        tids = tuple(ids) or ("",)
+        with self._lock:
+            cur = self.db.execute(
+                f"DELETE FROM events WHERE kind NOT IN ({','.join('?' * len(keep))}) AND "
+                f"(root_id = ? OR task_id = ? OR task_id IN ({','.join('?' * len(tids))}))",
+                (*keep, root_id, root_id, *tids))
+            return cur.rowcount
+
+    def iter_all(self) -> Iterator[dict]:
+        yield from self._rows("SELECT data FROM events ORDER BY seq")
+
+    def count(self) -> int:
+        with self._lock:
+            return self.db.execute("SELECT COUNT(*) FROM events").fetchone()[0]
+
+    def backup_files(self, scratch: Path) -> dict[str, Path]:
+        """A consistent copy through SQLite's online backup API (never a raw copy of a live database)."""
+        scratch.mkdir(parents=True, exist_ok=True)
+        dst = scratch / self.path.name
+        dst.unlink(missing_ok=True)
+        out = sqlite3.connect(str(dst))
+        try:
+            with self._lock:
+                self.db.backup(out)
+        finally:
+            out.close()
+        return {self.path.name: dst}
+
+    def describe(self) -> dict:
+        return {"backend": self.backend, "path": str(self.path), "events": self.count()}
+
+    def close(self) -> None:
+        with self._lock:
+            self.db.close()
+
+
+
+def _factory(cfg: dict, logs: Path) -> SqliteStore:
+    unknown = set(cfg) - KEYS
+    if unknown:
+        raise ValueError(f"storage: unknown setting(s) {', '.join(sorted(unknown))} for sqlite; "
+                         f"known: {', '.join(sorted(KEYS))}")
+    return SqliteStore(store_path(cfg, logs, "events.db"), int(cfg.get("busy_timeout_ms", 5000)))
+
+
+class SqlitePlugin(Plugin):
+    name = "sqlite"
+    description = "SQLite storage backend for the event log"
+
+    @classmethod
+    def register(cls) -> None:
+        register_store("sqlite", _factory)

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: xqo-sqlite
+Version: 3.0.0
+Summary: SQLite event store for xqo
+Author: dudikkocak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudikkocak/xqo
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xqo<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-sqlite
+
+The `sqlite` event store for [xqo](https://github.com/dudikkocak/xqo): one SQLite file with indexed events, so task
+pages, deletes and history reads don't scan the log.
+
+```bash
+pip install xqo-sqlite
+```
+
+```json
+"storage": {"backend": "sqlite"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `path` | `events.db` | relative to the data dir's `logs/` folder |
+| `busy_timeout_ms` | `5000` | how long a second writer waits instead of failing |
+
+WAL mode (readers never block the writer), `synchronous=NORMAL` (a crash loses at most the last commits, never the
+file), and a quick integrity check when it opens. `xqo backup` writes a consistent copy with SQLite's online
+backup API. `XQO_STORAGE=sqlite` picks it for one run. Switching backends starts an empty store: events are not
+copied between stores.

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/xqo_sqlite/__init__.py
+src/xqo_sqlite.egg-info/PKG-INFO
+src/xqo_sqlite.egg-info/SOURCES.txt
+src/xqo_sqlite.egg-info/dependency_links.txt
+src/xqo_sqlite.egg-info/entry_points.txt
+src/xqo_sqlite.egg-info/requires.txt
+src/xqo_sqlite.egg-info/top_level.txt
+tests/test_sqlite.py

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xqo.plugins]
+sqlite = xqo_sqlite:SqlitePlugin

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/requires.txt

@@ -0,0 +1,5 @@
+xqo<4,>=3.0
+
+[dev]
+pytest>=8
+pytest-timeout>=2.3

xqo_sqlite-3.0.0/src/xqo_sqlite.egg-info/top_level.txt

@@ -0,0 +1 @@
+xqo_sqlite

xqo_sqlite-3.0.0/tests/test_sqlite.py

@@ -0,0 +1,58 @@
+"""xqo-sqlite: the storage contract, restarts, backups, config checks and how xqo finds it."""
+import json
+
+import pytest
+
+from xqo.config import build
+from xqo.store import open_store
+from xqo.testing import check_event_store, check_restart_keeps_tasks, event
+from xqo_sqlite import SqliteStore
+
+
+def test_contract(tmp_path):
+    check_event_store(SqliteStore(tmp_path / "events.db"))
+
+
+def test_all_tasks_survive_a_restart(tmp_path):
+    again = check_restart_keeps_tasks(tmp_path, {"backend": "sqlite"})
+    assert again.store.backend == "sqlite" and again.store.path == tmp_path / "logs" / "events.db"
+
+
+def test_found_as_a_plugin_and_not_missing(tmp_path):
+    cfg = tmp_path / "agents.json"
+    cfg.write_text(json.dumps({"agents": [{"name": "planner", "skills": ["planning"]}],
+                               "storage": {"backend": "sqlite"}}))
+    bus = build(cfg, tmp_path / "a", str(tmp_path / "logs" / "events.jsonl"), mock=True, departments="none")
+    st = bus.plugins.states["sqlite"]
+    assert st.state != "missing" and st.source == "xqo_sqlite:SqlitePlugin"
+    assert bus.store.backend == "sqlite"
+
+
+def test_file_and_backup_copy(tmp_path):
+    build_dir = tmp_path / "logs"
+    from xqo_sqlite import SqlitePlugin
+    SqlitePlugin.register()
+    s = open_store({"backend": "sqlite"}, build_dir / "events.jsonl")
+    assert s.path == build_dir / "events.db"
+    s.append(event("task", "r1"))
+    files = s.backup_files(tmp_path / "scratch")
+    copy = SqliteStore(files["events.db"])
+    assert [d["kind"] for d in copy.iter_all()] == ["task"]
+
+
+def test_bad_config_and_bad_file_stop_startup(tmp_path):
+    from xqo_sqlite import SqlitePlugin
+    SqlitePlugin.register()
+    with pytest.raises(ValueError, match="unknown setting.*for sqlite"):
+        open_store({"backend": "sqlite", "table": "x"}, tmp_path / "events.jsonl")
+    bad = tmp_path / "bad.db"
+    bad.write_bytes(b"this is not a database" * 100)
+    with pytest.raises(ValueError, match="storage: can't open"):
+        SqliteStore(bad)
+
+
+def test_env_picks_sqlite(tmp_path, monkeypatch):
+    from xqo_sqlite import SqlitePlugin
+    SqlitePlugin.register()
+    monkeypatch.setenv("XQO_STORAGE", "sqlite")
+    assert open_store({"backend": "jsonl"}, tmp_path / "events.jsonl").backend == "sqlite"