cortexdb-cli 0.2.0__py3-none-any.whl

cortexdb_cli/commands/understanding.py

@@ -0,0 +1,141 @@
+"""cortexdb understanding — GET /v1/understanding* + POST /v1/understanding/synthesize."""
+
+from __future__ import annotations
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import (
+    console,
+    escape,
+    is_json_mode,
+    print_json,
+    spinner,
+)
+
+
+@click.group("understanding")
+def understanding_group() -> None:
+    """Understanding — LLM-synthesized concepts and themes across a scope."""
+
+
+def _scope_or_die(cfg: dict, scope: str | None) -> str:
+    s = scope or cfg.get("scope") or cfg.get("actor")
+    if not s:
+        raise click.UsageError(
+            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
+        )
+    return s
+
+
+@understanding_group.command("list")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--topic", help="Filter by topic name")
+@click.option("--limit", "-l", default=50, show_default=True)
+@click.pass_context
+@handle_errors
+def understanding_list(
+    ctx: click.Context, scope: str | None, topic: str | None, limit: int
+) -> None:
+    """List synthesized concepts."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    params: dict[str, str | int] = {"scope": s, "limit": limit}
+    if topic:
+        params["topic"] = topic
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading concepts..."):
+                resp = client.get("/v1/understanding", params=params)
+        else:
+            resp = client.get("/v1/understanding", params=params)
+        resp.raise_for_status()
+
+    data = resp.json()
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    items = data.get("items", data) if isinstance(data, dict) else data
+    if not items:
+        console.print(
+            "[dim]No concepts synthesised yet. Try [bold]cortexdb understanding synthesize[/bold] "
+            "to trigger a pass.[/dim]"
+        )
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Understanding[/header]", border_style="blue")
+    table.add_column("Concept", style="bold", max_width=24)
+    table.add_column("Topic", style="magenta", max_width=20)
+    table.add_column("Summary", max_width=60)
+    table.add_column("Conf", justify="right", width=6)
+    for c in items:
+        table.add_row(
+            escape(str(c.get("name") or c.get("concept_id", ""))[:24]),
+            escape(str(c.get("topic", ""))),
+            escape(str(c.get("summary", ""))[:120]),
+            f"{(c.get('confidence') or 0):.0%}",
+        )
+    console.print(table)
+    if isinstance(data, dict) and data.get("_partial"):
+        console.print(
+            "[dim]_partial: true — the synthesizer is still catching up on this scope.[/dim]"
+        )
+
+
+@understanding_group.command("coverage")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.pass_context
+@handle_errors
+def understanding_coverage(ctx: click.Context, scope: str | None) -> None:
+    """Per-topic synthesis coverage and confidence."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading coverage..."):
+                resp = client.get("/v1/understanding/coverage", params={"scope": s})
+        else:
+            resp = client.get("/v1/understanding/coverage", params={"scope": s})
+        resp.raise_for_status()
+        print_json(resp.json())
+
+
+@understanding_group.command("synthesize")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--topic", "topics", multiple=True, help="Restrict to topic(s); repeat for multiple.")
+@click.option("--force", is_flag=True, help="Force re-synthesis even if already current.")
+@click.pass_context
+@handle_errors
+def understanding_synthesize(
+    ctx: click.Context, scope: str | None, topics: tuple[str, ...], force: bool
+) -> None:
+    """Trigger an on-demand synthesis pass.
+
+    Calls an LLM (Claude Opus 4.6 by default) — counts against the
+    tenant's LLM quota. Capability `understanding.synthesize` required.
+    The free tier denies this; paid tiers allow it.
+
+        cortexdb understanding synthesize --topic sales_process
+    """
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    body: dict[str, object] = {"scope": s, "force": force}
+    if topics:
+        body["topics"] = list(topics)
+    with get_client(cfg) as client:
+        resp = client.post("/v1/understanding/synthesize", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+        if is_json_mode(cfg):
+            print_json(data)
+        else:
+            console.print(
+                f"[success]Synthesis scheduled[/success] — job [bold]{data.get('job_id', '?')}[/bold]"
+            )
+            stream = data.get("lifecycle_stream")
+            if stream:
+                console.print(f"[dim]Watch: {escape(stream)}[/dim]")

cortexdb_cli/config.py

@@ -0,0 +1,113 @@
+"""Configuration management for CortexDB CLI.
+
+Two files live under `~/.cortexdb/`:
+- `config.toml`  — human-editable: endpoint, profile names.
+- `state.json`   — machine-managed: PASETO token, actor, scope, expiry
+  (written by `cortexdb init`; never edited by hand).
+
+`load_config` merges everything together so commands see one dict:
+
+    endpoint   ← env CORTEXDB_URL > config.toml > default
+    api_key    ← env CORTEXDB_API_KEY > state.json[token] > config.toml
+    actor      ← env CORTEXDB_ACTOR > state.json[user_id] > config.toml
+    scope      ← env CORTEXDB_SCOPE > state.json[scope] > config.toml > actor
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+DEFAULT_ENDPOINT = "https://api-v1.cortexdb.ai"
+
+
+def config_dir() -> Path:
+    """Return the CortexDB config directory, creating it if needed."""
+    d = Path.home() / ".cortexdb"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def config_path() -> Path:
+    return config_dir() / "config.toml"
+
+
+def history_path() -> Path:
+    return config_dir() / "history"
+
+
+def load_config(profile: str = "default") -> dict[str, Any]:
+    """Load merged config: TOML file + state.json + env vars."""
+    cfg: dict[str, Any] = {}
+    path = config_path()
+    if path.exists():
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        if profile != "default" and profile in data.get("profiles", {}):
+            cfg = dict(data["profiles"][profile])
+        elif "default" in data:
+            cfg = dict(data["default"])
+        else:
+            cfg = {k: v for k, v in data.items() if k != "profiles"}
+
+    # Merge persisted signup state.
+    # Import here to avoid a circular import (state.py imports config_dir).
+    from cortexdb_cli.state import load_state
+
+    st = load_state()
+    if st.get("token") and not cfg.get("api_key"):
+        cfg["api_key"] = st["token"]
+    if st.get("user_id") and not cfg.get("actor"):
+        cfg["actor"] = st["user_id"]
+    if st.get("scope") and not cfg.get("scope"):
+        cfg["scope"] = st["scope"]
+    if st.get("expires_at") and not cfg.get("expires_at"):
+        cfg["expires_at"] = st["expires_at"]
+
+    # Env vars win.
+    if os.environ.get("CORTEXDB_API_KEY"):
+        cfg["api_key"] = os.environ["CORTEXDB_API_KEY"]
+    if os.environ.get("CORTEXDB_URL"):
+        cfg["endpoint"] = os.environ["CORTEXDB_URL"]
+    if os.environ.get("CORTEXDB_ENDPOINT"):
+        cfg["endpoint"] = os.environ["CORTEXDB_ENDPOINT"]
+    if os.environ.get("CORTEXDB_ACTOR"):
+        cfg["actor"] = os.environ["CORTEXDB_ACTOR"]
+    if os.environ.get("CORTEXDB_SCOPE"):
+        cfg["scope"] = os.environ["CORTEXDB_SCOPE"]
+
+    cfg.setdefault("endpoint", DEFAULT_ENDPOINT)
+    # Scope defaults to actor when not explicitly set.
+    if cfg.get("actor") and not cfg.get("scope"):
+        cfg["scope"] = cfg["actor"]
+    return cfg
+
+
+def save_config(profile: str, data: dict[str, Any]) -> None:
+    """Save the human-editable TOML config for a profile."""
+    path = config_path()
+    existing: dict[str, Any] = {}
+    if path.exists():
+        with open(path, "rb") as f:
+            existing = tomllib.load(f)
+
+    if profile == "default":
+        existing["default"] = data
+    else:
+        existing.setdefault("profiles", {})[profile] = data
+
+    with open(path, "wb") as f:
+        tomli_w.dump(existing, f)
+
+
+def get_value(cfg: dict[str, Any], key: str, default: Any = None) -> Any:
+    return cfg.get(key, default)

cortexdb_cli/errors.py

@@ -0,0 +1,96 @@
+"""Error handling for CortexDB CLI commands."""
+
+from __future__ import annotations
+
+import functools
+import sys
+from typing import Any, Callable
+
+import click
+import httpx
+
+from cortexdb_cli.output import err_console
+
+
+def escape_safe(s: Any) -> str:
+    """Rich-safe escape used in the error decorator (avoids circular imports)."""
+    from rich.markup import escape
+
+    return escape(str(s))
+
+
+def handle_errors(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator that catches common errors and prints friendly messages."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            body: dict[str, Any] = {}
+            try:
+                body = exc.response.json()
+            except Exception:
+                body = {}
+            code = body.get("error_code") or body.get("code") or ""
+            msg = body.get("message") or body.get("error") or exc.response.text[:200]
+
+            if status == 401:
+                if code in ("TOKEN_EXPIRED", "INVALID_TOKEN_SIGNATURE", "MISSING_TOKEN"):
+                    err_console.print(
+                        f"[error]Token rejected ({code}).[/error] "
+                        "Run [bold]cortexdb init[/bold] to mint a fresh one."
+                    )
+                elif code == "actor_mismatch":
+                    err_console.print(
+                        "[error]Actor mismatch.[/error] The X-Cortex-Actor header "
+                        "doesn't match the token's subject. Re-run "
+                        "[bold]cortexdb init[/bold] to re-bind."
+                    )
+                else:
+                    err_console.print(
+                        f"[error]Authentication failed:[/error] {msg}\n"
+                        "Run [bold]cortexdb init[/bold] to set up credentials."
+                    )
+            elif status == 403:
+                # The v1 surface always cites the missing capability.
+                details = body.get("details") or {}
+                cap = details.get("capability") or ""
+                tier = details.get("decided_by_tier") or ""
+                if cap:
+                    err_console.print(
+                        f"[error]Denied by {escape_safe(tier)}:[/error] "
+                        f"missing capability [bold]{escape_safe(cap)}[/bold]."
+                    )
+                    if cap == "diagnostics.read":
+                        err_console.print(
+                            "[dim]Hint: pass [bold]--diagnostics none[/bold] (free tier).[/dim]"
+                        )
+                else:
+                    err_console.print(f"[error]Forbidden:[/error] {msg}")
+            elif status == 429:
+                retry = exc.response.headers.get("Retry-After", "?")
+                err_console.print(f"[error]Rate limited.[/error] Retry after {retry}s.")
+            elif status == 402:
+                err_console.print(f"[warning]Feature not available on your tier.[/warning] {msg}")
+            else:
+                err_console.print(f"[error]API error (HTTP {status}, {code}):[/error] {msg}")
+            sys.exit(1)
+        except httpx.ConnectError:
+            err_console.print(
+                "[error]Cannot connect to CortexDB.[/error] "
+                "Check your endpoint and network."
+            )
+            sys.exit(2)
+        except httpx.TimeoutException:
+            err_console.print("[error]Request timed out.[/error]")
+            sys.exit(2)
+        except click.Abort:
+            err_console.print("\n[dim]Aborted.[/dim]")
+            sys.exit(130)
+        except KeyboardInterrupt:
+            err_console.print("\n[dim]Interrupted.[/dim]")
+            sys.exit(130)
+
+    return wrapper

cortexdb_cli/main.py

@@ -0,0 +1,140 @@
+"""CortexDB CLI — the v1 memory API at your fingertips.
+
+Usage:
+    cortexdb init                            anonymous signup; persist token + actor
+    cortexdb experience "..."                store a memory       (POST /v1/experience)
+    cortexdb experience bulk file.jsonl      bulk ingest          (POST /v1/experience/bulk)
+    cortexdb recall   "..."                  recall context pack  (POST /v1/recall)
+    cortexdb search   "..."                  granular event hits  (POST /v1/recall, granular)
+    cortexdb answer   "..."                  recall + LLM answer  (POST /v1/answer)
+    cortexdb forget   --memory-id ...        delete with audit    (POST /v1/forget)
+    cortexdb episodes {list,get,delete}
+    cortexdb entities {list,get,link}
+    cortexdb facts    {list,timeline}
+    cortexdb beliefs  {list,why,build}
+    cortexdb understanding {list,coverage,synthesize}
+    cortexdb scopes   {list,register,members}
+    cortexdb auth     {whoami,signup,tokens,revoke}
+    cortexdb policy   {effective,deployment}
+    cortexdb admin    {health,usage,layers}
+    cortexdb import   data.json
+    cortexdb export   -o backup.json
+    cortexdb config   {show,set}
+    cortexdb                                 interactive REPL
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from cortexdb_cli import __version__
+from cortexdb_cli.client import DEFAULT_ENDPOINT
+from cortexdb_cli.config import load_config
+
+try:
+    import rich_click
+
+    rich_click.rich_click.SHOW_ARGUMENTS = True
+    rich_click.rich_click.GROUP_ARGUMENTS_OPTIONS = True
+    rich_click.rich_click.STYLE_COMMANDS_TABLE_COLUMN_WIDTH_RATIO = (1, 2)
+    rich_click.rich_click.USE_MARKDOWN = True
+except ImportError:
+    pass
+
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(invoke_without_command=True, context_settings=CONTEXT_SETTINGS)
+@click.option("--api-key", envvar="CORTEXDB_API_KEY", help="PASETO bearer token (or env CORTEXDB_API_KEY)")
+@click.option("--endpoint", envvar="CORTEXDB_ENDPOINT", help="API base URL (default api-v1.cortexdb.ai)")
+@click.option("--actor", envvar="CORTEXDB_ACTOR", help="X-Cortex-Actor (or env CORTEXDB_ACTOR)")
+@click.option("--scope", envvar="CORTEXDB_SCOPE", help="Default scope path (or env CORTEXDB_SCOPE)")
+@click.option("--json", "json_output", is_flag=True, help="Output as JSON (auto-enabled when piped)")
+@click.option("--profile", "-p", default="default", help="Config profile")
+@click.version_option(version=__version__, prog_name="cortexdb")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    api_key: str | None,
+    endpoint: str | None,
+    actor: str | None,
+    scope: str | None,
+    json_output: bool,
+    profile: str,
+) -> None:
+    """CortexDB — long-term memory layer for AI systems.
+
+    Run without a command to enter the interactive REPL.
+    """
+    ctx.ensure_object(dict)
+
+    cfg = load_config(profile)
+    ctx.obj["api_key"] = api_key or cfg.get("api_key", "")
+    ctx.obj["endpoint"] = endpoint or cfg.get("endpoint") or DEFAULT_ENDPOINT
+    ctx.obj["actor"] = actor or cfg.get("actor", "")
+    ctx.obj["scope"] = scope or cfg.get("scope") or ctx.obj["actor"]
+    ctx.obj["expires_at"] = cfg.get("expires_at")
+    ctx.obj["json_output"] = json_output or not sys.stdout.isatty()
+    ctx.obj["profile"] = profile
+
+    # No subcommand → interactive REPL.
+    if ctx.invoked_subcommand is None:
+        if not sys.stdout.isatty():
+            click.echo(ctx.get_help())
+            return
+        from cortexdb_cli.commands.interactive import repl
+
+        repl(ctx)
+
+
+# --- Register commands ---
+
+from cortexdb_cli.commands.admin import admin_group
+from cortexdb_cli.commands.answer import answer_cmd
+from cortexdb_cli.commands.auth import auth_group
+from cortexdb_cli.commands.beliefs import beliefs_group
+from cortexdb_cli.commands.config_cmd import config_group
+from cortexdb_cli.commands.entities import entities_group
+from cortexdb_cli.commands.episodes import episodes_group
+from cortexdb_cli.commands.experience import experience_cmd, remember_alias
+from cortexdb_cli.commands.export_cmd import export_cmd
+from cortexdb_cli.commands.facts import facts_group
+from cortexdb_cli.commands.forget import forget_cmd
+from cortexdb_cli.commands.import_cmd import import_cmd
+from cortexdb_cli.commands.init import init_cmd
+from cortexdb_cli.commands.policy import policy_group
+from cortexdb_cli.commands.recall import recall_cmd
+from cortexdb_cli.commands.scopes import scopes_group
+from cortexdb_cli.commands.search import search_cmd
+from cortexdb_cli.commands.understanding import understanding_group
+
+cli.add_command(init_cmd)
+cli.add_command(experience_cmd)
+cli.add_command(remember_alias)  # hidden alias for muscle memory
+cli.add_command(recall_cmd)
+cli.add_command(search_cmd)
+cli.add_command(answer_cmd)
+cli.add_command(forget_cmd)
+cli.add_command(episodes_group)
+cli.add_command(entities_group)
+cli.add_command(facts_group)
+cli.add_command(beliefs_group)
+cli.add_command(understanding_group)
+cli.add_command(scopes_group)
+cli.add_command(auth_group)
+cli.add_command(policy_group)
+cli.add_command(admin_group)
+cli.add_command(import_cmd)
+cli.add_command(export_cmd)
+cli.add_command(config_group)
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()