cortexdb-cli 0.2.0__py3-none-any.whl

cortexdb_cli/commands/interactive.py

@@ -0,0 +1,254 @@
+"""cortexdb interactive REPL — chat with your memory.
+
+Wraps the same v1 endpoints the discrete commands hit, so anything you
+can do via subcommand you can do here, plus natural-language input routed
+through /v1/recall.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.output import console, print_recall, print_search, print_error
+
+
+BANNER = """
+[bold magenta]  ____          _            ____  ____  [/bold magenta]
+[bold magenta] / ___|___  _ __| |_ _____  _|  _ \\| __ ) [/bold magenta]
+[bold magenta]| |   / _ \\| '__| __/ _ \\ \\/ / | | |  _ \\ [/bold magenta]
+[bold magenta]| |__| (_) | |  | ||  __/>  <| |_| | |_) |[/bold magenta]
+[bold magenta] \\____\\___/|_|   \\__\\___/_/\\_\\____/|____/ [/bold magenta]
+
+[dim]Type a question to recall from memory.[/dim]
+[dim]Commands: /remember /recall /search /forget /health /usage /help /quit[/dim]
+"""
+
+HELP_TEXT = """
+[bold]Commands:[/bold]
+  [cyan]/remember TEXT[/cyan]     Store a new memory
+  [cyan]/recall QUERY[/cyan]      Recall a stratified context pack
+  [cyan]/search QUERY[/cyan]      Granular search — individual event hits
+  [cyan]/forget QUERY[/cyan]      Forget by query (prompts for reason)
+  [cyan]/health[/cyan]            Identity + reachability via /v1/auth/whoami
+  [cyan]/usage[/cyan]             Tier, caps, rate-limit headers
+  [cyan]/help[/cyan]              This help
+  [cyan]/quit[/cyan]              Exit
+
+[bold]Natural Language:[/bold]
+  Just type a question to recall from memory.
+  e.g., "what happened with the deploy?"
+"""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _idem(content: str, scope: str) -> str:
+    return "cli-repl:" + hashlib.sha256(
+        f"{scope}|{content}".encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def _experience_body(scope: str, text: str) -> dict[str, Any]:
+    return {
+        "scope": scope,
+        "modality": "conversation",
+        "content": {"kind": "message", "role": "user", "text": text},
+        "context": {"observed_at": _now_iso()},
+        "idempotency_key": _idem(text, scope),
+    }
+
+
+def repl(ctx: Any) -> None:
+    """Run the interactive REPL."""
+    try:
+        from prompt_toolkit import PromptSession
+        from prompt_toolkit.history import FileHistory
+        from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+        from prompt_toolkit.formatted_text import HTML
+    except ImportError:
+        console.print("[error]prompt-toolkit is required for interactive mode.[/error]")
+        console.print("Install it: [bold]pip install prompt-toolkit[/bold]")
+        return
+
+    from cortexdb_cli.config import history_path
+    from cortexdb_cli.output import (
+        print_health,
+        print_usage,
+        print_remember,
+        print_forget,
+        spinner,
+    )
+
+    cfg = ctx.obj
+    scope = cfg.get("scope") or cfg.get("actor")
+    if not scope:
+        console.print(
+            "[warning]No scope configured. Run [bold]cortexdb init[/bold] first.[/warning]"
+        )
+        return
+
+    console.print(BANNER)
+
+    session: PromptSession[str] = PromptSession(
+        history=FileHistory(str(history_path())),
+        auto_suggest=AutoSuggestFromHistory(),
+    )
+
+    with get_client(cfg) as client:
+        while True:
+            try:
+                text = session.prompt(
+                    HTML("<ansicyan><b>cortexdb</b></ansicyan><b>&gt;</b> "),
+                ).strip()
+            except (EOFError, KeyboardInterrupt):
+                console.print("\n[dim]Goodbye.[/dim]")
+                break
+
+            if not text:
+                continue
+
+            if text.lower() in ("/quit", "/exit", "/q"):
+                console.print("[dim]Goodbye.[/dim]")
+                break
+
+            elif text.lower() == "/help":
+                console.print(HELP_TEXT)
+
+            elif text.lower() == "/health":
+                try:
+                    with spinner("Checking..."):
+                        resp = client.get("/v1/auth/whoami")
+                    resp.raise_for_status()
+                    body = resp.json()
+                    body.setdefault("status", "ok")
+                    print_health(body, cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.lower() == "/usage":
+                try:
+                    with spinner("Loading usage..."):
+                        resp = client.get("/v1/auth/whoami")
+                    resp.raise_for_status()
+                    body = resp.json()
+                    for k in (
+                        "X-RateLimit-Limit",
+                        "X-RateLimit-Reset",
+                        "X-Cortex-Token-Expires-In",
+                        "X-Cortex-Token-Expires-At",
+                    ):
+                        if k in resp.headers:
+                            body[k] = resp.headers[k]
+                    print_usage(body, cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.lower().startswith("/remember "):
+                content = text[10:].strip()
+                if not content:
+                    console.print("[warning]Usage: /remember TEXT[/warning]")
+                    continue
+                try:
+                    with spinner("Storing..."):
+                        resp = client.post("/v1/experience", json=_experience_body(scope, content))
+                    resp.raise_for_status()
+                    print_remember(resp.json(), cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.lower().startswith("/recall "):
+                query = text[8:].strip()
+                if not query:
+                    console.print("[warning]Usage: /recall QUERY[/warning]")
+                    continue
+                try:
+                    with spinner("Recalling..."):
+                        resp = client.post(
+                            "/v1/recall",
+                            json={
+                                "scope": scope,
+                                "view": "holistic",
+                                "query": query,
+                                "diagnostics": "none",
+                            },
+                        )
+                    resp.raise_for_status()
+                    print_recall(resp.json(), cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.lower().startswith("/search "):
+                query = text[8:].strip()
+                if not query:
+                    console.print("[warning]Usage: /search QUERY[/warning]")
+                    continue
+                try:
+                    with spinner("Searching..."):
+                        resp = client.post(
+                            "/v1/recall",
+                            json={
+                                "scope": scope,
+                                "view": "granular",
+                                "query": query,
+                                "diagnostics": "none",
+                                "budgets": {"max_events": 10},
+                            },
+                        )
+                    resp.raise_for_status()
+                    print_search(resp.json(), cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.lower().startswith("/forget "):
+                query = text[8:].strip()
+                if not query:
+                    console.print("[warning]Usage: /forget QUERY[/warning]")
+                    continue
+                from prompt_toolkit import prompt as pt_prompt
+
+                reason = pt_prompt("Reason: ")
+                if not reason.strip():
+                    console.print("[warning]A reason is required.[/warning]")
+                    continue
+                try:
+                    with spinner("Forgetting..."):
+                        resp = client.post(
+                            "/v1/forget",
+                            json={
+                                "scope": scope,
+                                "selector": {"query": query},
+                                "cascade": "derived_only",
+                                "audit_note": reason.strip(),
+                            },
+                        )
+                    resp.raise_for_status()
+                    print_forget(resp.json(), cfg)
+                except Exception as e:
+                    print_error(str(e))
+
+            elif text.startswith("/"):
+                console.print(f"[warning]Unknown command: {text.split()[0]}[/warning]")
+                console.print("[dim]Type /help for available commands.[/dim]")
+
+            else:
+                # Natural language -> /v1/recall holistic
+                try:
+                    with spinner("Thinking..."):
+                        resp = client.post(
+                            "/v1/recall",
+                            json={
+                                "scope": scope,
+                                "view": "holistic",
+                                "query": text,
+                                "diagnostics": "none",
+                            },
+                        )
+                    resp.raise_for_status()
+                    print_recall(resp.json(), cfg)
+                except Exception as e:
+                    print_error(str(e))

cortexdb_cli/commands/policy.py

@@ -0,0 +1,99 @@
+"""cortexdb policy — /v1/policy/effective + /v1/policy/deployment."""
+
+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("policy")
+def policy_group() -> None:
+    """Policy introspection — what is this actor allowed to do, and where?"""
+
+
+@policy_group.command("effective")
+@click.option("--actor", "actor_arg", help="Actor to query (defaults to your actor).")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope).")
+@click.pass_context
+@handle_errors
+def policy_effective(
+    ctx: click.Context, actor_arg: str | None, scope: str | None
+) -> None:
+    """GET /v1/policy/effective — full allow/deny matrix.
+
+    Shows every capability and which policy tier (deployment / tenant /
+    scope / actor) decided each one. The authoritative answer to "what
+    can <actor> do at <scope> right now."
+
+        cortexdb policy effective --actor user:alice --scope org:acme/user:alice
+    """
+    cfg = ctx.obj
+    actor = actor_arg or cfg.get("actor")
+    target_scope = scope or cfg.get("scope") or actor
+    if not actor or not target_scope:
+        raise click.UsageError(
+            "Need both --actor and --scope (or run `cortexdb init` so defaults are set)."
+        )
+    params = {"actor": actor, "scope": target_scope}
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading policy..."):
+                resp = client.get("/v1/policy/effective", params=params)
+        else:
+            resp = client.get("/v1/policy/effective", params=params)
+        resp.raise_for_status()
+
+    data = resp.json()
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    caps = data.get("capabilities") or data.get("effective") or {}
+    if isinstance(caps, list):
+        # Server returned a flat allow list.
+        from rich.table import Table
+
+        table = Table(title="[header]Effective capabilities[/header]", border_style="cyan")
+        table.add_column("Capability", style="bold")
+        for c in caps:
+            table.add_row(escape(str(c)))
+        console.print(table)
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Effective policy[/header]", border_style="cyan")
+    table.add_column("Capability", style="bold")
+    table.add_column("Decision")
+    table.add_column("Decided by", style="dim")
+    for cap, detail in caps.items():
+        decision = detail.get("decision") if isinstance(detail, dict) else str(detail)
+        tier = detail.get("decided_by_tier", "") if isinstance(detail, dict) else ""
+        style = "green" if decision == "allow" else "red"
+        table.add_row(
+            escape(str(cap)),
+            f"[{style}]{escape(str(decision))}[/{style}]",
+            escape(str(tier)),
+        )
+    console.print(table)
+
+
+@policy_group.command("deployment")
+@click.pass_context
+@handle_errors
+def policy_deployment(ctx: click.Context) -> None:
+    """GET /v1/policy/deployment — show this deployment's preset + floor."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/policy/deployment")
+        resp.raise_for_status()
+        print_json(resp.json())

cortexdb_cli/commands/recall.py

@@ -0,0 +1,93 @@
+"""cortexdb recall — POST /v1/recall."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import is_json_mode, print_recall, spinner
+
+
+@click.command("recall")
+@click.argument("query")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option(
+    "--view",
+    type=click.Choice(["raw", "granular", "structured", "holistic", "descend"]),
+    default="holistic",
+    show_default=True,
+    help="Pack shape — 'holistic' merges layers; 'granular' returns single-scope events.",
+)
+@click.option(
+    "--include",
+    multiple=True,
+    type=click.Choice(["events", "episodes", "facts", "beliefs", "understanding"]),
+    help="Layers to fill (repeatable). Default: facts + beliefs + episodes.",
+)
+@click.option(
+    "--temporal",
+    default=None,
+    help='Natural-language time window, e.g. "last 30 days".',
+)
+@click.option(
+    "--max-tokens",
+    type=int,
+    default=None,
+    help="Budget for the returned context_block (string).",
+)
+@click.option(
+    "--diagnostics",
+    type=click.Choice(["none", "summary", "full"]),
+    default="none",
+    show_default=True,
+    help='"none" works on every tier. "summary"/"full" need the diagnostics.read capability.',
+)
+@click.pass_context
+@handle_errors
+def recall_cmd(
+    ctx: click.Context,
+    query: str,
+    scope: str | None,
+    view: str,
+    include: tuple[str, ...],
+    temporal: str | None,
+    max_tokens: int | None,
+    diagnostics: str,
+) -> None:
+    """Recall context from memory.
+
+    \b
+        cortexdb recall "what did we decide about Acme?"
+        cortexdb recall "renewal status" --temporal "last 30 days"
+    """
+    cfg = ctx.obj
+    target_scope = scope or cfg.get("scope") or cfg.get("actor")
+    if not target_scope:
+        raise click.UsageError(
+            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
+        )
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "view": view,
+        "query": query,
+        "diagnostics": diagnostics,
+    }
+    if include:
+        body["include"] = list(include)
+    if temporal:
+        body["temporal"] = {"natural": temporal}
+    if max_tokens is not None:
+        body["budgets"] = {"max_tokens": max_tokens}
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Recalling..."):
+                resp = client.post("/v1/recall", json=body)
+        else:
+            resp = client.post("/v1/recall", json=body)
+        resp.raise_for_status()
+        print_recall(resp.json(), cfg)

cortexdb_cli/commands/scopes.py

@@ -0,0 +1,98 @@
+"""cortexdb scopes — /v1/scopes* (list, register, delete, members)."""
+
+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("scopes")
+def scopes_group() -> None:
+    """Hierarchical scopes — list, register, members."""
+
+
+@scopes_group.command("list")
+@click.option("--prefix", help="Only show scopes under this prefix")
+@click.option("--limit", "-l", default=100, show_default=True)
+@click.pass_context
+@handle_errors
+def scopes_list(ctx: click.Context, prefix: str | None, limit: int) -> None:
+    """List scopes visible to the caller."""
+    cfg = ctx.obj
+    params: dict[str, str | int] = {"limit": limit}
+    if prefix:
+        params["prefix"] = prefix
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading scopes..."):
+                resp = client.get("/v1/scopes/list", params=params)
+        else:
+            resp = client.get("/v1/scopes/list", 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 scopes visible.[/dim]")
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Scopes[/header]", border_style="blue")
+    table.add_column("Path", style="bold")
+    table.add_column("Owner", style="cyan")
+    table.add_column("Members", justify="right", width=8)
+    for s in items:
+        members = s.get("member_count") or len(s.get("members") or [])
+        table.add_row(
+            escape(str(s.get("path") or s.get("scope", ""))),
+            escape(str(s.get("owner", ""))),
+            str(members),
+        )
+    console.print(table)
+
+
+@scopes_group.command("register")
+@click.argument("path")
+@click.option("--owner", help="Owner actor — defaults to your actor.")
+@click.pass_context
+@handle_errors
+def scopes_register(ctx: click.Context, path: str, owner: str | None) -> None:
+    """POST /v1/scopes — register a new scope path."""
+    cfg = ctx.obj
+    body: dict[str, str] = {"path": path}
+    if owner or cfg.get("actor"):
+        body["owner"] = owner or cfg["actor"]
+    with get_client(cfg) as client:
+        resp = client.post("/v1/scopes", json=body)
+        resp.raise_for_status()
+        if is_json_mode(cfg):
+            print_json(resp.json())
+        else:
+            console.print(f"[success]Registered[/success] {path}")
+
+
+@scopes_group.command("members")
+@click.argument("path")
+@click.pass_context
+@handle_errors
+def scopes_members(ctx: click.Context, path: str) -> None:
+    """GET /v1/scopes — list members of a scope."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/scopes", params={"path": path})
+        resp.raise_for_status()
+        print_json(resp.json())

cortexdb_cli/commands/search.py

@@ -0,0 +1,64 @@
+"""cortexdb search — POST /v1/recall (granular view) with optional filters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import is_json_mode, print_search, spinner
+
+
+@click.command("search")
+@click.argument("query")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--limit", "-l", default=10, show_default=True, help="Max results")
+@click.option("--temporal", "-t", help='Time window, e.g. "last 7 days"')
+@click.option(
+    "--diagnostics",
+    type=click.Choice(["none", "summary", "full"]),
+    default="none",
+    show_default=True,
+)
+@click.pass_context
+@handle_errors
+def search_cmd(
+    ctx: click.Context,
+    query: str,
+    scope: str | None,
+    limit: int,
+    temporal: str | None,
+    diagnostics: str,
+) -> None:
+    """Search memories — granular view, individual event hits.
+
+    Equivalent to `cortexdb recall --view granular`, optimised for
+    "show me the matching events" rather than "give me a context block."
+    """
+    cfg = ctx.obj
+    target_scope = scope or cfg.get("scope") or cfg.get("actor")
+    if not target_scope:
+        raise click.UsageError(
+            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
+        )
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "view": "granular",
+        "query": query,
+        "diagnostics": diagnostics,
+        "budgets": {"max_events": limit},
+    }
+    if temporal:
+        body["temporal"] = {"natural": temporal}
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Searching..."):
+                resp = client.post("/v1/recall", json=body)
+        else:
+            resp = client.post("/v1/recall", json=body)
+        resp.raise_for_status()
+        print_search(resp.json(), cfg)