agentic-coop-db 0.3.1__tar.gz

agentic_coop_db-0.3.1/.gitignore

@@ -0,0 +1,55 @@
+# Build artifacts
+/bin/
+/dist/
+/build/
+*.exe
+*.test
+*.out
+coverage.*
+
+# Go workspace
+go.work
+go.work.sum
+vendor/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.venv/
+venv/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local secrets / state (never commit these)
+.env
+.env.local
+*.pem
+*.key
+*.crt
+secrets/
+
+# Local docker volumes
+deploy/data/
+deploy/postgres-data/
+
+# Agentic Coop DB local state (CLI config via platformdirs)
+.config/agentcoopdb/
+queue.db
+queue.db-journal
+
+# Test containers reaper state
+.testcontainers/

agentic_coop_db-0.3.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: agentic-coop-db
+Version: 0.3.1
+Summary: Auth gateway client for shared PostgreSQL — sends parameterised SQL over HTTPS.
+Project-URL: Homepage, https://github.com/fheinfling/agentic-coop-db
+Project-URL: Source, https://github.com/fheinfling/agentic-coop-db
+Project-URL: Issues, https://github.com/fheinfling/agentic-coop-db/issues
+Author: Franz Heinfling
+License: Apache-2.0
+Keywords: auth,gateway,pgvector,postgres,postgresql,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: requests>=2.32
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentcoopdb (Python client)
+
+A thin Python client for [Agentic Coop DB](https://github.com/fheinfling/agentic-coop-db), the
+auth gateway for shared PostgreSQL.
+
+```python
+from agentcoopdb import connect
+
+db = connect("https://db.example.com", api_key="acd_live_...")
+db.execute(
+    "INSERT INTO notes(id, body) VALUES ($1, $2)",
+    ["b9c3...", "hi"],
+)
+rows = db.select("SELECT * FROM notes WHERE owner = $1", ["alice"])
+```
+
+## Install
+
+```bash
+pip install agentic-coop-db
+```
+
+Or install directly from GitHub (the Python client lives in a subdirectory):
+
+```bash
+pip install "agentic-coop-db @ git+https://github.com/fheinfling/agentic-coop-db.git#subdirectory=clients/python"
+```
+
+## CLI
+
+```bash
+agentic-coop-db init                  # interactive onboarding wizard
+agentic-coop-db me
+agentic-coop-db sql "SELECT 1"
+agentic-coop-db queue flush
+agentic-coop-db doctor
+```
+
+See the [main repo](https://github.com/fheinfling/agentic-coop-db) for the full docs.

agentic_coop_db-0.3.1/README.md

@@ -0,0 +1,39 @@
+# agentcoopdb (Python client)
+
+A thin Python client for [Agentic Coop DB](https://github.com/fheinfling/agentic-coop-db), the
+auth gateway for shared PostgreSQL.
+
+```python
+from agentcoopdb import connect
+
+db = connect("https://db.example.com", api_key="acd_live_...")
+db.execute(
+    "INSERT INTO notes(id, body) VALUES ($1, $2)",
+    ["b9c3...", "hi"],
+)
+rows = db.select("SELECT * FROM notes WHERE owner = $1", ["alice"])
+```
+
+## Install
+
+```bash
+pip install agentic-coop-db
+```
+
+Or install directly from GitHub (the Python client lives in a subdirectory):
+
+```bash
+pip install "agentic-coop-db @ git+https://github.com/fheinfling/agentic-coop-db.git#subdirectory=clients/python"
+```
+
+## CLI
+
+```bash
+agentic-coop-db init                  # interactive onboarding wizard
+agentic-coop-db me
+agentic-coop-db sql "SELECT 1"
+agentic-coop-db queue flush
+agentic-coop-db doctor
+```
+
+See the [main repo](https://github.com/fheinfling/agentic-coop-db) for the full docs.

agentic_coop_db-0.3.1/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentic-coop-db"
+version = "0.3.1"
+description = "Auth gateway client for shared PostgreSQL — sends parameterised SQL over HTTPS."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Franz Heinfling" }
+]
+keywords = ["postgres", "postgresql", "auth", "gateway", "pgvector", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.32",
+    "typer>=0.12",
+    "platformdirs>=4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "types-requests",
+]
+
+[project.scripts]
+agentic-coop-db = "agentcoopdb.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/fheinfling/agentic-coop-db"
+Source = "https://github.com/fheinfling/agentic-coop-db"
+Issues = "https://github.com/fheinfling/agentic-coop-db/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentcoopdb"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+# typer.Option(...) / typer.Argument(...) MUST appear in argument
+# defaults — that's how Typer (and FastAPI) declare option metadata.
+# B008 ("Do not perform function call in argument defaults") is a
+# known false positive for these libraries; suppress only on the CLI
+# entrypoint module.
+[tool.ruff.lint.per-file-ignores]
+"src/agentcoopdb/cli/main.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

agentic_coop_db-0.3.1/src/agentcoopdb/__init__.py

@@ -0,0 +1,44 @@
+"""agentcoopdb — Python client for the Agentic Coop DB auth gateway.
+
+This package is intentionally tiny. The public surface is:
+
+    from agentcoopdb import connect
+    db = connect("https://db.example.com", api_key="acd_live_...")
+    db.execute(sql, params)
+    db.select(sql, params)
+    db.transaction()
+    db.vector_upsert(...)
+    db.vector_search(...)
+    db.rotate_key()
+    db.health()
+    db.me()
+
+Plus error classes (errors.py) and the offline retry queue (queue.py).
+"""
+
+from agentcoopdb.client import AgentCoopDBClient, connect
+from agentcoopdb.errors import (
+    AgentCoopDBError,
+    AuthError,
+    IdempotencyConflict,
+    NetworkError,
+    QueueFullError,
+    RateLimited,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "connect",
+    "AgentCoopDBClient",
+    "AgentCoopDBError",
+    "AuthError",
+    "ValidationError",
+    "IdempotencyConflict",
+    "RateLimited",
+    "ServerError",
+    "NetworkError",
+    "QueueFullError",
+]
+
+__version__ = "0.1.0"

agentic_coop_db-0.3.1/src/agentcoopdb/cli/__init__.py

@@ -0,0 +1,5 @@
+"""agentcoopdb CLI package.
+
+The entry point is `agentcoopdb.cli.main:app`. Each subcommand lives in its
+own module and is registered in main.py.
+"""

agentic_coop_db-0.3.1/src/agentcoopdb/cli/config.py

@@ -0,0 +1,66 @@
+"""Local user config for the CLI.
+
+The CLI persists a tiny TOML file under the platform config directory
+(e.g. ~/.config/agentcoopdb/config.toml on Linux, ~/Library/Application
+Support/agentcoopdb/config.toml on macOS) so that subsequent commands don't
+need --url / --api-key flags. The wizard (`agentic-coop-db init`) writes
+this file; `agentic-coop-db me` and friends read it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import platformdirs
+
+CONFIG_FILENAME = "config.toml"
+
+
+def config_dir() -> Path:
+    return Path(platformdirs.user_config_dir("agentcoopdb", appauthor=False, ensure_exists=True))
+
+
+def config_path() -> Path:
+    return config_dir() / CONFIG_FILENAME
+
+
+@dataclass
+class CLIConfig:
+    base_url: str
+    api_key: str
+
+    def write(self) -> Path:
+        path = config_path()
+        path.write_text(
+            f'base_url = "{self.base_url}"\napi_key  = "{self.api_key}"\n',
+            encoding="utf-8",
+        )
+        # Best-effort chmod — on Windows this raises and we don't care.
+        with contextlib.suppress(OSError):
+            os.chmod(path, 0o600)
+        return path
+
+
+def load() -> CLIConfig | None:
+    path = config_path()
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8")
+    data: dict[str, Any] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        k = k.strip()
+        v = v.strip().strip('"')
+        data[k] = v
+    if "base_url" not in data or "api_key" not in data:
+        return None
+    return CLIConfig(base_url=data["base_url"], api_key=data["api_key"])

agentic_coop_db-0.3.1/src/agentcoopdb/cli/doctor.py

@@ -0,0 +1,119 @@
+"""`agentic-coop-db doctor` — verify the local install end to end.
+
+Checks (in order):
+
+  1. Config file exists and is parseable
+  2. /healthz reachable
+  3. /readyz returns 200 (DB + migrations OK)
+  4. /v1/me succeeds (auth works)
+  5. SELECT 1 round trip
+  6. Idempotency replay probe — same key returns cached response
+  7. pgvector available (CREATE EXTENSION query)
+  8. Local queue path writable
+  9. Server vs SDK version skew
+
+Exits 0 on success, non-zero on the first failure.
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+
+from agentcoopdb import __version__ as sdk_version
+from agentcoopdb import connect
+from agentcoopdb.cli.config import config_dir
+from agentcoopdb.cli.config import load as load_config
+from agentcoopdb.errors import AgentCoopDBError
+from agentcoopdb.queue import Queue
+
+
+def doctor() -> None:
+    cfg = load_config()
+    if cfg is None:
+        _fail("config not found — run `agentic-coop-db init` first")
+
+    _ok("config", f"loaded from {Path(config_dir()) / 'config.toml'}")
+
+    db = connect(cfg.base_url, api_key=cfg.api_key, timeout=5.0)
+
+    try:
+        h = db.health()
+        _ok("/healthz", str(h.get("status", "?")))
+    except AgentCoopDBError as e:
+        _fail(f"/healthz failed: {e}")
+
+    try:
+        rz = db._get("/readyz")
+        _ok("/readyz", str(rz.get("status", "?")))
+    except AgentCoopDBError as e:
+        _fail(f"/readyz failed (DB or migrations unhealthy): {e}")
+
+    try:
+        info = db.me()
+        _ok("/v1/me", f"workspace={info.get('workspace_id')} role={info.get('role')}")
+    except AgentCoopDBError as e:
+        _fail(f"/v1/me failed: {e}")
+
+    try:
+        res = db.execute("SELECT 1")
+        if res.command != "SELECT" or res.rows_affected != 1:
+            _fail(f"SELECT 1 returned unexpected result: {res}")
+        _ok("SELECT 1", "round trip ok")
+    except AgentCoopDBError as e:
+        _fail(f"SELECT 1 failed: {e}")
+
+    # Idempotency replay probe — uses a temp uuid as the key and verifies
+    # the server's X-Idempotent-Replayed header to confirm a cached replay.
+    key = str(uuid.uuid4())
+    try:
+        db.execute("SELECT pg_sleep(0)", idempotency_key=key)
+        r2 = db.execute("SELECT pg_sleep(0)", idempotency_key=key)
+        if r2.replayed:
+            _ok("idempotency", "replay returned cached response (X-Idempotent-Replayed confirmed)")
+        else:
+            _fail("idempotency replay succeeded but X-Idempotent-Replayed header missing — caching may be broken")
+    except AgentCoopDBError as e:
+        _fail(f"idempotency probe failed: {e}")
+
+    try:
+        rows = db.select("SELECT extname FROM pg_extension WHERE extname = 'vector'")
+        if rows:
+            _ok("pgvector", "extension installed")
+        else:
+            _warn("pgvector", "extension not installed (run migration 0005)")
+    except AgentCoopDBError as e:
+        _warn("pgvector", f"could not query pg_extension: {e}")
+
+    try:
+        Queue(config_dir() / "queue.db").depth()
+        _ok("queue", "local sqlite path writable")
+    except Exception as e:
+        _warn("queue", f"could not open local queue: {e}")
+
+    server_version = info.get("server", {}).get("version", "unknown")
+    if server_version != sdk_version:
+        _warn(
+            "version skew",
+            f"sdk={sdk_version} server={server_version} — keep them in lockstep when possible",
+        )
+    else:
+        _ok("version", f"sdk={sdk_version} server={server_version}")
+
+    typer.echo("\nall checks passed")
+
+
+def _ok(name: str, detail: str = "") -> None:
+    typer.echo(f"  [OK]   {name}: {detail}")
+
+
+def _warn(name: str, detail: str) -> None:
+    typer.echo(f"  [WARN] {name}: {detail}")
+
+
+def _fail(msg: str) -> NoReturn:
+    typer.echo(f"  [FAIL] {msg}", err=True)
+    raise typer.Exit(code=1)

agentic_coop_db-0.3.1/src/agentcoopdb/cli/init.py

@@ -0,0 +1,177 @@
+"""`agentic-coop-db init` — interactive onboarding wizard.
+
+Goal: get a brand-new user from zero to a working CRUD round trip in
+under five minutes without reading any docs beyond the README.
+
+Decision tree:
+
+  1. Detect docker. If missing, link to install instructions.
+  2. Ask which profile they want: local / pi-lite / cloud / "I have a server".
+  3. For self-hosted profiles: run `make up-<profile>`, wait for /readyz,
+     mint an admin API key via scripts/gen-key.sh, capture it once.
+  4. For "existing server": prompt for URL + key, call /v1/me to validate.
+  5. Write ~/.agentic-coop-db/config.toml.
+  6. Run `agentic-coop-db doctor` and print a Python + curl snippet.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import typer
+
+from agentcoopdb import connect
+from agentcoopdb.cli import config as cli_config
+from agentcoopdb.errors import AgentCoopDBError
+
+
+def init() -> None:
+    """Run the wizard."""
+    typer.echo(_BANNER)
+
+    if not _have("docker"):
+        typer.echo(
+            "Docker is not on PATH. Install it from https://docs.docker.com/engine/install/ "
+            "and re-run `agentic-coop-db init`."
+        )
+        raise typer.Exit(code=2)
+
+    profile = typer.prompt(
+        "Which profile? [local / pi-lite / cloud / existing]",
+        default="local",
+    ).strip().lower()
+
+    if profile == "existing":
+        base_url = typer.prompt("Server base URL (e.g. https://db.example.com)").strip()
+        api_key = typer.prompt("API key (will not be echoed)", hide_input=True).strip()
+        _validate_and_save(base_url, api_key)
+        return
+
+    repo_root = _find_repo_root()
+    if repo_root is None:
+        typer.echo(
+            "Could not find an Agentic Coop DB checkout in the current or parent directories. "
+            "Either run this from inside the repo, or pick `existing` and point at a remote server."
+        )
+        raise typer.Exit(code=2)
+
+    target = {
+        "local": "up-local",
+        "pi-lite": "up-pi",
+        "cloud": "up-cloud",
+    }.get(profile)
+    if target is None:
+        typer.echo(f"unknown profile: {profile}")
+        raise typer.Exit(code=2)
+
+    typer.echo(f"\n→ make {target}")
+    res = subprocess.run(["make", target], cwd=repo_root)
+    if res.returncode != 0:
+        typer.echo("`make` failed — fix the error above and re-run `agentic-coop-db init`")
+        raise typer.Exit(code=res.returncode)
+
+    base_url = "http://localhost:8080"
+    typer.echo(f"\n→ waiting for {base_url}/readyz ...")
+    if not _wait_ready(base_url, timeout=120):
+        typer.echo("the server did not become ready within 120s — check `make logs`")
+        raise typer.Exit(code=1)
+
+    typer.echo("→ minting an admin API key via scripts/gen-key.sh ...")
+    key_proc = subprocess.run(
+        ["./scripts/gen-key.sh", "default", "dbadmin"],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+    )
+    if key_proc.returncode != 0:
+        typer.echo(key_proc.stderr)
+        raise typer.Exit(code=key_proc.returncode)
+    api_key = _extract_token(key_proc.stdout)
+    if not api_key:
+        typer.echo("could not parse the minted key from gen-key.sh output")
+        typer.echo(key_proc.stdout)
+        raise typer.Exit(code=1)
+
+    _validate_and_save(base_url, api_key)
+
+
+# ---- helpers -----------------------------------------------------------------
+
+def _validate_and_save(base_url: str, api_key: str) -> None:
+    db = connect(base_url, api_key=api_key, timeout=10.0)
+    try:
+        info = db.me()
+    except AgentCoopDBError as e:
+        typer.echo(f"could not authenticate against {base_url}: {e}")
+        raise typer.Exit(code=1) from e
+
+    cfg = cli_config.CLIConfig(base_url=base_url, api_key=api_key)
+    path = cfg.write()
+    typer.echo(f"\nconfig saved to {path}")
+    typer.echo(f"workspace: {info.get('workspace_id', '?')}")
+    typer.echo(f"role:      {info.get('role', '?')}")
+    typer.echo(f"server:    {info.get('server', {}).get('version', '?')}")
+    typer.echo("\nyou are ready. try this:\n")
+    typer.echo(f"    curl -H 'Authorization: Bearer {api_key}' {base_url}/v1/me")
+    typer.echo("    agentic-coop-db sql 'SELECT 1'")
+    typer.echo("\nor in Python:\n")
+    typer.echo("    from agentcoopdb import connect")
+    typer.echo(f"    db = connect('{base_url}', api_key='acd_...')")
+    typer.echo("    db.execute('SELECT 1')")
+
+
+def _have(cmd: str) -> bool:
+    return shutil.which(cmd) is not None
+
+
+def _find_repo_root() -> Path | None:
+    here = Path.cwd().resolve()
+    for candidate in [here, *here.parents]:
+        if (candidate / "Makefile").exists() and (candidate / "deploy").is_dir():
+            return candidate
+    return None
+
+
+def _wait_ready(base_url: str, timeout: int) -> bool:
+    import requests
+
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            r = requests.get(base_url + "/readyz", timeout=2.0)
+            if r.status_code == 200:
+                return True
+        except requests.RequestException:
+            pass
+        time.sleep(1)
+    return False
+
+
+def _extract_token(stdout: str) -> str | None:
+    for line in stdout.splitlines():
+        line = line.strip()
+        if line.startswith("acd_"):
+            return line
+    return None
+
+
+_BANNER = """\
+agentic-coop-db init — interactive onboarding wizard
+
+This wizard will:
+  1. Verify Docker is up
+  2. Start the stack with your chosen profile
+  3. Mint an admin API key
+  4. Save your config (run `agentic-coop-db doctor` to see the path)
+  5. Print a Python + curl snippet you can copy/paste
+
+Press Ctrl-C at any time to abort.
+"""
+
+if __name__ == "__main__":
+    init()
+    sys.exit(0)