xqo-postgres 3.0.0__tar.gz

xqo_postgres-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_postgres-3.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: xqo-postgres
+Version: 3.0.0
+Summary: Postgres 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
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-postgres
+
+The `postgres` event store for [xqo](https://github.com/dudikkocak/xqo): for several machines or a hosted dashboard
+that share one database. A single local HQ is better served by `xqo-sqlite`.
+
+```bash
+pip install xqo-postgres                   # brings psycopg 3
+export XQO_PG_DSN="postgresql://xqo:secret@db.example:5432/xqo"
+```
+
+```json
+"storage": {"backend": "postgres", "dsn_env": "XQO_PG_DSN", "table": "xqo_events"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `dsn_env` | `XQO_PG_DSN` | the environment variable that holds the connection string (never put it in agents.json) |
+| `table` | `xqo_events` | lowercase letters, digits and `_`; created with its indexes on first start |
+
+Back it up with `pg_dump`: `xqo backup` leaves database contents to Postgres's own tools. The tests need a
+database: `XQO_TEST_PG_DSN=postgresql://... pytest`.

xqo_postgres-3.0.0/README.md

@@ -0,0 +1,21 @@
+# xqo-postgres
+
+The `postgres` event store for [xqo](https://github.com/dudikkocak/xqo): for several machines or a hosted dashboard
+that share one database. A single local HQ is better served by `xqo-sqlite`.
+
+```bash
+pip install xqo-postgres                   # brings psycopg 3
+export XQO_PG_DSN="postgresql://xqo:secret@db.example:5432/xqo"
+```
+
+```json
+"storage": {"backend": "postgres", "dsn_env": "XQO_PG_DSN", "table": "xqo_events"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `dsn_env` | `XQO_PG_DSN` | the environment variable that holds the connection string (never put it in agents.json) |
+| `table` | `xqo_events` | lowercase letters, digits and `_`; created with its indexes on first start |
+
+Back it up with `pg_dump`: `xqo backup` leaves database contents to Postgres's own tools. The tests need a
+database: `XQO_TEST_PG_DSN=postgresql://... pytest`.

xqo_postgres-3.0.0/pyproject.toml

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

xqo_postgres-3.0.0/setup.cfg

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

xqo_postgres-3.0.0/src/xqo_postgres/__init__.py

@@ -0,0 +1,116 @@
+"""xqo-postgres: the "postgres" event store for xqo.
+
+    pip install xqo-postgres                       # psycopg 3
+    export XQO_PG_DSN="postgresql://xqo:secret@db.example:5432/xqo"
+    "storage": {"backend": "postgres", "dsn_env": "XQO_PG_DSN", "table": "xqo_events"}
+
+Use it when several machines or a hosted dashboard need one shared database; a single local HQ is better served by
+xqo-sqlite. Back it up with pg_dump (xqo backup leaves database contents to Postgres's own tools).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+from pathlib import Path
+from typing import Iterable, Iterator
+
+from xqo.api import SEED_KINDS, EventStore, Plugin, register_store
+
+__version__ = "3.0.0"
+KEYS = {"backend", "dsn_env", "table"}
+
+TABLE = re.compile(r"^[a-z_][a-z0-9_]{0,62}$")
+
+
+class PostgresStore(EventStore):
+    backend = "postgres"
+
+    def __init__(self, dsn: str, table: str = "xqo_events"):
+        try:
+            import psycopg
+        except ImportError:
+            raise ValueError("storage: the postgres backend needs psycopg: pip install xqo-postgres") from None
+        if not TABLE.match(table):
+            raise ValueError("storage.table: lowercase letters, digits and _ only")
+        self.table = table
+        self._lock = threading.Lock()
+        try:
+            self.db = psycopg.connect(dsn, autocommit=True, connect_timeout=10)
+            self.db.execute(f"""
+                CREATE TABLE IF NOT EXISTS {table} (
+                    seq BIGSERIAL PRIMARY KEY, ts TEXT, kind TEXT, task_id TEXT, root_id TEXT, data JSONB NOT NULL);
+                CREATE INDEX IF NOT EXISTS {table}_root ON {table}(root_id);
+                CREATE INDEX IF NOT EXISTS {table}_task ON {table}(task_id);
+                CREATE INDEX IF NOT EXISTS {table}_kind ON {table}(kind);""")
+        except psycopg.Error as e:
+            raise ValueError(f"storage: can't use Postgres: {str(e).strip().splitlines()[0]}") from None
+
+    def _rows(self, sql: str, args: tuple = ()) -> list[dict]:
+        with self._lock:
+            rows = self.db.execute(sql, args).fetchall()
+        return [r[0] if isinstance(r[0], dict) else json.loads(r[0]) for r in rows]
+
+    def append(self, d: dict) -> None:
+        with self._lock:
+            self.db.execute(f"INSERT INTO {self.table}(ts, kind, task_id, root_id, data) VALUES (%s, %s, %s, %s, %s)",
+                            (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(f"SELECT data FROM (SELECT seq, data FROM {self.table} ORDER BY seq DESC LIMIT %s) r "
+                          "ORDER BY seq", (int(limit),))
+
+    def seeds(self) -> list[dict]:
+        return self._rows(f"SELECT data FROM {self.table} WHERE kind = ANY(%s) ORDER BY seq", (list(SEED_KINDS),))
+
+    def tree(self, root_id: str) -> list[dict]:
+        return self._rows(f"SELECT data FROM {self.table} WHERE root_id = %s OR task_id = %s ORDER BY seq",
+                          (root_id, root_id))
+
+    def by_kind_prefix(self, prefix: str) -> list[dict]:
+        esc = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        return self._rows(f"SELECT data FROM {self.table} WHERE kind LIKE %s ORDER BY seq", (esc + "%",))
+
+    def purge(self, root_id: str, ids: set[str], keep_kinds: Iterable[str]) -> int:
+        with self._lock:
+            cur = self.db.execute(
+                f"DELETE FROM {self.table} WHERE NOT (kind = ANY(%s)) AND "
+                "(root_id = %s OR task_id = %s OR task_id = ANY(%s))",
+                (list(keep_kinds), root_id, root_id, list(ids)))
+            return cur.rowcount
+
+    def iter_all(self) -> Iterator[dict]:
+        yield from self._rows(f"SELECT data FROM {self.table} ORDER BY seq")
+
+    def count(self) -> int:
+        with self._lock:
+            return self.db.execute(f"SELECT COUNT(*) FROM {self.table}").fetchone()[0]
+
+    def describe(self) -> dict:
+        return {"backend": self.backend, "table": self.table, "events": self.count()}
+
+    def close(self) -> None:
+        with self._lock:
+            self.db.close()
+
+
+def _factory(cfg: dict, logs: Path) -> PostgresStore:
+    unknown = set(cfg) - KEYS
+    if unknown:
+        raise ValueError(f"storage: unknown setting(s) {', '.join(sorted(unknown))} for postgres; "
+                         f"known: {', '.join(sorted(KEYS))}")
+    env = cfg.get("dsn_env") or "XQO_PG_DSN"
+    dsn = os.getenv(env)
+    if not dsn:
+        raise ValueError(f"storage: set the environment variable {env} to the Postgres DSN (storage.dsn_env)")
+    return PostgresStore(dsn, str(cfg.get("table") or "xqo_events"))
+
+
+class PostgresPlugin(Plugin):
+    name = "postgres"
+    description = "Postgres storage backend for the event log"
+
+    @classmethod
+    def register(cls) -> None:
+        register_store("postgres", _factory)

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

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: xqo-postgres
+Version: 3.0.0
+Summary: Postgres 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
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-postgres
+
+The `postgres` event store for [xqo](https://github.com/dudikkocak/xqo): for several machines or a hosted dashboard
+that share one database. A single local HQ is better served by `xqo-sqlite`.
+
+```bash
+pip install xqo-postgres                   # brings psycopg 3
+export XQO_PG_DSN="postgresql://xqo:secret@db.example:5432/xqo"
+```
+
+```json
+"storage": {"backend": "postgres", "dsn_env": "XQO_PG_DSN", "table": "xqo_events"}
+```
+
+| Key | Default | |
+|---|---|---|
+| `dsn_env` | `XQO_PG_DSN` | the environment variable that holds the connection string (never put it in agents.json) |
+| `table` | `xqo_events` | lowercase letters, digits and `_`; created with its indexes on first start |
+
+Back it up with `pg_dump`: `xqo backup` leaves database contents to Postgres's own tools. The tests need a
+database: `XQO_TEST_PG_DSN=postgresql://... pytest`.

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[xqo.plugins]
+postgres = xqo_postgres:PostgresPlugin

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

@@ -0,0 +1,6 @@
+xqo<4,>=3.0
+psycopg[binary]>=3.1
+
+[dev]
+pytest>=8
+pytest-timeout>=2.3

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

@@ -0,0 +1 @@
+xqo_postgres

xqo_postgres-3.0.0/tests/test_postgres.py

@@ -0,0 +1,47 @@
+"""xqo-postgres: the storage contract and restarts against a real database (XQO_TEST_PG_DSN), plus config checks."""
+import json
+import os
+import uuid
+
+import pytest
+
+from xqo.config import build
+from xqo.store import open_store
+from xqo.testing import check_event_store, check_restart_keeps_tasks
+from xqo_postgres import PostgresPlugin, PostgresStore
+
+PG_DSN = os.getenv("XQO_TEST_PG_DSN")  # e.g. postgresql://xqo@/xqo_test?host=/tmp&port=55432
+needs_pg = pytest.mark.skipif(not PG_DSN, reason="set XQO_TEST_PG_DSN to test against Postgres")
+
+
+@needs_pg
+def test_contract():
+    check_event_store(PostgresStore(PG_DSN, "t_" + uuid.uuid4().hex[:12]))
+
+
+@needs_pg
+def test_all_tasks_survive_a_restart(tmp_path, monkeypatch):
+    monkeypatch.setenv("XQO_PG_DSN", PG_DSN)
+    table = "b_" + uuid.uuid4().hex[:12]
+    again = check_restart_keeps_tasks(tmp_path, {"backend": "postgres", "table": table})
+    assert again.store.describe()["table"] == table
+    assert not (tmp_path / "logs" / "events.jsonl").exists()
+
+
+def test_found_as_a_plugin_and_needs_its_dsn(tmp_path, monkeypatch):
+    monkeypatch.delenv("XQO_PG_DSN", raising=False)
+    cfg = tmp_path / "agents.json"
+    cfg.write_text(json.dumps({"agents": [{"name": "planner", "skills": ["planning"]}],
+                               "storage": {"backend": "postgres"}}))
+    with pytest.raises(ValueError, match="XQO_PG_DSN"):
+        build(cfg, tmp_path / "a", str(tmp_path / "l" / "e.jsonl"), mock=True, departments="none")
+
+
+def test_bad_config_stops_startup(tmp_path):
+    PostgresPlugin.register()
+    with pytest.raises(ValueError, match="dsn_env"):
+        open_store({"backend": "postgres", "dsn": "postgresql://x"}, tmp_path / "events.jsonl")
+    with pytest.raises(ValueError, match="unknown setting.*for postgres"):
+        open_store({"backend": "postgres", "path": "x"}, tmp_path / "events.jsonl")
+    with pytest.raises(ValueError, match="lowercase"):
+        PostgresStore("postgresql://unused", "Bad-Name")