agentic-coop-db 0.3.1__py3-none-any.whl

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"

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.
+"""

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"])

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)

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)

agentcoopdb/cli/key.py

@@ -0,0 +1,48 @@
+"""`agentic-coop-db key` — manage API keys."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from agentcoopdb import connect
+from agentcoopdb.cli.config import CLIConfig
+from agentcoopdb.cli.config import load as load_config
+
+key_app = typer.Typer(no_args_is_help=True)
+
+
+@key_app.command("create")
+def create(
+    pg_role: str = typer.Option(..., "--role", help="Postgres role to attach (e.g. dbuser, dbadmin, custom_role)"),
+    workspace: str = typer.Option("", "--workspace", help="Override the workspace id (defaults to caller's)"),
+    name: str = typer.Option("", "--name", help="Human label for the key"),
+) -> None:
+    """Mint a new API key. The caller must be a dbadmin key."""
+    cfg = _cfg()
+    db = connect(cfg.base_url, api_key=cfg.api_key)
+    body = {"pg_role": pg_role, "name": name}
+    if workspace:
+        body["workspace_id"] = workspace
+    res = db._post("/v1/auth/keys", body)  # noqa: SLF001 — intentional internal use
+    typer.echo(json.dumps(res, indent=2))
+    typer.echo("\nstore the token above NOW — it is shown exactly once")
+
+
+@key_app.command("rotate")
+def rotate() -> None:
+    """Rotate the calling key. The old key remains active for the configured overlap window."""
+    cfg = _cfg()
+    db = connect(cfg.base_url, api_key=cfg.api_key)
+    res = db.rotate_key()
+    typer.echo(json.dumps(res, indent=2))
+    typer.echo("\nstore the token above NOW — it is shown exactly once")
+
+
+def _cfg() -> CLIConfig:
+    cfg = load_config()
+    if cfg is None:
+        typer.echo("no config found — run `agentic-coop-db init` first", err=True)
+        raise typer.Exit(code=2)
+    return cfg

agentcoopdb/cli/main.py

@@ -0,0 +1,80 @@
+"""agentcoopdb — top-level CLI.
+
+Subcommands:
+
+    agentic-coop-db init       interactive onboarding wizard (start the stack, mint a key)
+    agentic-coop-db sql        run a one-shot SQL statement
+    agentic-coop-db me         show the calling key's workspace + role
+    agentic-coop-db key        manage API keys (create, rotate)
+    agentic-coop-db queue      inspect / flush the local offline retry queue
+    agentic-coop-db doctor     verify that everything is wired correctly
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from agentcoopdb import connect
+from agentcoopdb.cli import config as cli_config
+from agentcoopdb.cli.doctor import doctor as doctor_cmd
+from agentcoopdb.cli.init import init as init_cmd
+from agentcoopdb.cli.key import key_app
+from agentcoopdb.cli.queue import queue_app
+
+app = typer.Typer(
+    name="agentcoopdb",
+    help="Agentic Coop DB CLI — auth gateway client for shared PostgreSQL.",
+    no_args_is_help=True,
+)
+
+app.add_typer(key_app, name="key", help="Manage API keys.")
+app.add_typer(queue_app, name="queue", help="Inspect / flush the local offline retry queue.")
+app.command(name="init", help="Interactive onboarding wizard.")(init_cmd)
+app.command(name="doctor", help="Verify config, network, auth, db, and migrations.")(doctor_cmd)
+
+
+@app.command()
+def me() -> None:
+    """Print { workspace, role, server } for the configured key."""
+    cfg = _require_config()
+    db = connect(cfg.base_url, api_key=cfg.api_key)
+    typer.echo(json.dumps(db.me(), indent=2))
+
+
+@app.command()
+def sql(
+    statement: str = typer.Argument(..., help="The SQL statement (use $1, $2, ... for params)"),
+    param: list[str] = typer.Option([], "--param", "-p", help="Repeatable; positional values for $1, $2, ..."),
+) -> None:
+    """Run a one-shot SQL statement against the configured server."""
+    cfg = _require_config()
+    db = connect(cfg.base_url, api_key=cfg.api_key)
+    parsed_params: list[Any] = list(param)
+    res = db.execute(statement, parsed_params)
+    typer.echo(
+        json.dumps(
+            {
+                "command": res.command,
+                "columns": res.columns,
+                "rows": res.rows,
+                "rows_affected": res.rows_affected,
+                "duration_ms": res.duration_ms,
+            },
+            indent=2,
+        )
+    )
+
+
+def _require_config() -> cli_config.CLIConfig:
+    cfg = cli_config.load()
+    if cfg is None:
+        typer.echo("no config found — run `agentic-coop-db init` first", err=True)
+        raise typer.Exit(code=2)
+    return cfg
+
+
+if __name__ == "__main__":
+    app()

agentcoopdb/cli/queue.py

@@ -0,0 +1,58 @@
+"""`agentic-coop-db queue` — inspect / flush the local offline retry queue."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from agentcoopdb import connect
+from agentcoopdb.cli.config import config_dir
+from agentcoopdb.cli.config import load as load_config
+from agentcoopdb.queue import Queue, QueueItem
+
+queue_app = typer.Typer(no_args_is_help=True)
+
+
+def queue_path() -> Path:
+    return config_dir() / "queue.db"
+
+
+@queue_app.command("status")
+def status() -> None:
+    """Show the current depth + dead-letter count."""
+    q = Queue(queue_path())
+    typer.echo(f"pending:     {q.depth()}")
+    typer.echo(f"dead-letter: {q.dead_letter_count()}")
+    typer.echo(f"db:          {q.path}")
+
+
+@queue_app.command("flush")
+def flush() -> None:
+    """Drain the queue against the configured server."""
+    cfg = load_config()
+    if cfg is None:
+        typer.echo("no config found — run `agentic-coop-db init` first", err=True)
+        raise typer.Exit(code=2)
+    db = connect(cfg.base_url, api_key=cfg.api_key)
+    q = Queue(queue_path())
+
+    def send(item: QueueItem) -> None:
+        db.execute(item.sql, item.params, idempotency_key=item.idempotency_key)
+
+    sent, failed = q.flush(send)
+    typer.echo(f"sent={sent} failed={failed} remaining={q.depth()}")
+
+
+@queue_app.command("clear-dead")
+def clear_dead() -> None:
+    """Truncate the dead-letter table after manual review."""
+    import sqlite3
+
+    path = queue_path()
+    if not path.exists():
+        typer.echo("no queue db")
+        return
+    with sqlite3.connect(path) as c:
+        c.execute("DELETE FROM dead")
+    typer.echo("dead letters cleared")