cortexdb-cli 0.2.0__py3-none-any.whl

cortexdb_cli/commands/facts.py

@@ -0,0 +1,171 @@
+"""cortexdb facts — GET /v1/facts + GET /v1/facts/timeline."""
+
+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 (
+    console,
+    escape,
+    is_json_mode,
+    print_json,
+    spinner,
+)
+
+
+def _render_subject(s: Any) -> str:
+    """Subjects are `{type, id}` or `{id}` or a bare string."""
+    if isinstance(s, dict):
+        return s.get("id") or s.get("value") or str(s)
+    return str(s) if s is not None else ""
+
+
+def _render_object(o: Any) -> str:
+    """Objects are `{type, datatype, value}` or `{type, id}` or a bare string."""
+    if isinstance(o, dict):
+        return str(o.get("value") or o.get("id") or o)
+    return str(o) if o is not None else ""
+
+
+@click.group("facts")
+def facts_group() -> None:
+    """Facts — typed subject/predicate/object triples derived from events."""
+
+
+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
+
+
+@facts_group.command("list")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--subject", help="Filter by subject")
+@click.option("--predicate", help="Filter by predicate")
+@click.option("--limit", "-l", default=50, show_default=True)
+@click.pass_context
+@handle_errors
+def facts_list(
+    ctx: click.Context,
+    scope: str | None,
+    subject: str | None,
+    predicate: str | None,
+    limit: int,
+) -> None:
+    """List facts in a scope."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    params: dict[str, str | int] = {"scope": s, "limit": limit}
+    if subject:
+        params["subject"] = subject
+    if predicate:
+        params["predicate"] = predicate
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading facts..."):
+                resp = client.get("/v1/facts", params=params)
+        else:
+            resp = client.get("/v1/facts", 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 facts in this scope yet.[/dim]")
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Facts[/header]", border_style="blue")
+    table.add_column("Subject", style="bold", max_width=24)
+    table.add_column("Predicate", style="magenta", max_width=20)
+    table.add_column("Object", max_width=40)
+    table.add_column("Conf", justify="right", width=6)
+    table.add_column("Valid from", style="dim", width=20)
+    for f in items:
+        table.add_row(
+            escape(_render_subject(f.get("subject"))),
+            escape(str(f.get("predicate", ""))),
+            escape(_render_object(f.get("object"))),
+            f"{(f.get('confidence') or 0):.0%}",
+            escape(str(f.get("valid_from") or f.get("observed_at", "")))[:20],
+        )
+    console.print(table)
+
+
+@facts_group.command("timeline")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--subject", required=True, help="Subject to trace")
+@click.option("--predicate", help="Limit timeline to one predicate")
+@click.option("--as-of", help="Bi-temporal: only show facts known as of this timestamp")
+@click.pass_context
+@handle_errors
+def facts_timeline(
+    ctx: click.Context,
+    scope: str | None,
+    subject: str,
+    predicate: str | None,
+    as_of: str | None,
+) -> None:
+    """Show the full bi-temporal lineage of a fact.
+
+        cortexdb facts timeline --subject "opp_xyz" --predicate stage
+    """
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    params: dict[str, str] = {"scope": s, "subject": subject}
+    if predicate:
+        params["predicate"] = predicate
+    if as_of:
+        params["as_of"] = as_of
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading timeline..."):
+                resp = client.get("/v1/facts/timeline", params=params)
+        else:
+            resp = client.get("/v1/facts/timeline", 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 fact history for this subject.[/dim]")
+        return
+
+    from rich.table import Table
+
+    table = Table(
+        title=f"[header]Timeline[/header] [dim]{escape(subject)}[/dim]",
+        border_style="cyan",
+    )
+    table.add_column("Predicate", style="magenta")
+    table.add_column("Object")
+    table.add_column("Valid from", style="dim")
+    table.add_column("Valid to", style="dim")
+    table.add_column("Recorded at", style="dim")
+    for f in items:
+        table.add_row(
+            escape(str(f.get("predicate", ""))),
+            escape(_render_object(f.get("object"))),
+            escape(str(f.get("valid_from", ""))[:20]),
+            escape(str(f.get("valid_to") or "")[:20]),
+            escape(str(f.get("recorded_at", ""))[:20]),
+        )
+    console.print(table)

cortexdb_cli/commands/forget.py

@@ -0,0 +1,86 @@
+"""cortexdb forget — POST /v1/forget."""
+
+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_forget, spinner
+
+
+@click.command("forget")
+@click.option("--memory-id", "-i", multiple=True, help="Event id(s) to forget. Repeatable.")
+@click.option("--query", "-q", help='Free-text predicate, e.g. "test data" or "deal_stage:lost"')
+@click.option("--subject", help="Forget everything where about_subject matches this value.")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--reason", "-r", required=True, help="Audit trail note — recorded against the forget.")
+@click.option(
+    "--cascade",
+    type=click.Choice(["none", "derived_only", "redact_events"]),
+    default="derived_only",
+    show_default=True,
+    help="How aggressively to propagate the forget across derived layers.",
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+@handle_errors
+def forget_cmd(
+    ctx: click.Context,
+    memory_id: tuple[str, ...],
+    query: str | None,
+    subject: str | None,
+    scope: str | None,
+    reason: str,
+    cascade: str,
+    yes: bool,
+) -> None:
+    """Delete memories with an audit trail.
+
+    \b
+        cortexdb forget --memory-id evt_01HX... --reason "user requested deletion"
+        cortexdb forget --query "test data"      --reason "cleaning up test fixtures"
+        cortexdb forget --subject "user:alice"   --reason "GDPR erasure" --cascade redact_events
+    """
+    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."
+        )
+
+    selector: dict[str, Any] = {}
+    if memory_id:
+        selector["memory_ids"] = list(memory_id)
+    if query:
+        selector["query"] = query
+    if subject:
+        selector["about_subject"] = subject
+    if not selector:
+        raise click.UsageError("Provide at least one of --memory-id, --query, or --subject.")
+
+    if not yes and not is_json_mode(cfg):
+        target = (
+            f"{len(memory_id)} memory id(s)"
+            if memory_id
+            else (f'query "{query}"' if query else f"subject {subject}")
+        )
+        click.confirm(f"Forget {target} in scope {target_scope}?", abort=True)
+
+    body = {
+        "scope": target_scope,
+        "selector": selector,
+        "cascade": cascade,
+        "audit_note": reason,
+    }
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Forgetting..."):
+                resp = client.post("/v1/forget", json=body)
+        else:
+            resp = client.post("/v1/forget", json=body)
+        resp.raise_for_status()
+        print_forget(resp.json(), cfg)

cortexdb_cli/commands/import_cmd.py

@@ -0,0 +1,198 @@
+"""cortexdb import — bulk-load memories via POST /v1/experience."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+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 console, is_json_mode, print_json
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _idem(content: str, scope: str, i: int) -> str:
+    h = hashlib.sha256(f"{scope}|{i}|{content}".encode("utf-8")).hexdigest()[:16]
+    return f"cli-import:{h}"
+
+
+def _envelope(content: str, scope: str, idem: str, extra_meta: dict[str, Any]) -> dict[str, Any]:
+    labels = []
+    role = extra_meta.get("role", "user")
+    if "source" in extra_meta:
+        labels.append(f"source:{extra_meta['source']}")
+    if "tags" in extra_meta:
+        for t in str(extra_meta["tags"]).split(","):
+            t = t.strip()
+            if t:
+                labels.append(t)
+    body: dict[str, Any] = {
+        "scope": scope,
+        "modality": "conversation",
+        "content": {"kind": "message", "role": role, "text": content},
+        "context": {"observed_at": extra_meta.get("observed_at", _now_iso())},
+        "idempotency_key": idem,
+    }
+    if labels:
+        body["context"]["labels"] = labels
+    return body
+
+
+@click.command("import")
+@click.argument("file", type=click.Path(exists=True), required=False)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "jsonl", "csv", "text"]),
+    help="File format. Auto-detected from extension if omitted.",
+)
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option(
+    "--single",
+    is_flag=True,
+    help="Treat a .txt input as one memory rather than one-per-line.",
+)
+@click.pass_context
+@handle_errors
+def import_cmd(
+    ctx: click.Context,
+    file: str | None,
+    fmt: str | None,
+    scope: str | None,
+    single: bool,
+) -> None:
+    """Import memories from a file.
+
+    \b
+        cortexdb import data.json
+        cortexdb import data.jsonl
+        cortexdb import notes.csv
+        cortexdb import notes.txt --single
+        cat data.json | cortexdb import -
+    """
+    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."
+        )
+
+    # Read input
+    if file == "-" or (file is None and not sys.stdin.isatty()):
+        raw = sys.stdin.read()
+        if not fmt:
+            fmt = "json"
+    elif file:
+        path = Path(file)
+        raw = path.read_text(encoding="utf-8")
+        if not fmt:
+            ext = path.suffix.lower()
+            fmt = {
+                ".json": "json",
+                ".jsonl": "jsonl",
+                ".ndjson": "jsonl",
+                ".csv": "csv",
+                ".txt": "text",
+                ".md": "text",
+            }.get(ext, "json")
+    else:
+        raise click.UsageError("Provide a file path or pipe from stdin.")
+
+    # Parse
+    memories: list[dict[str, Any]] = []
+    if fmt == "json":
+        data = json.loads(raw)
+        if isinstance(data, list):
+            memories = data
+        elif isinstance(data, dict) and "memories" in data:
+            memories = data["memories"]
+        else:
+            memories = [data]
+    elif fmt == "jsonl":
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            memories.append(json.loads(line))
+    elif fmt == "csv":
+        reader = csv.DictReader(io.StringIO(raw))
+        for row in reader:
+            if "content" in row:
+                memories.append(dict(row))
+    elif fmt == "text":
+        if single:
+            memories = [{"content": raw.strip()}]
+        else:
+            for line in raw.strip().splitlines():
+                line = line.strip()
+                if line:
+                    memories.append({"content": line})
+
+    if not memories:
+        raise click.UsageError("No memories found in input.")
+
+    # POST each one
+    stored = 0
+    errors = 0
+
+    with get_client(cfg) as client:
+        total = len(memories)
+        if not is_json_mode(cfg):
+            from rich.progress import (
+                Progress,
+                SpinnerColumn,
+                BarColumn,
+                TextColumn,
+            )
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                TextColumn("{task.completed}/{task.total}"),
+                console=console,
+            ) as progress:
+                task = progress.add_task("Importing...", total=total)
+                for i, mem in enumerate(memories):
+                    content = mem.get("content") or mem.get("text") or ""
+                    if not content:
+                        progress.advance(task)
+                        continue
+                    extra = {k: v for k, v in mem.items() if k not in ("content", "text")}
+                    body = _envelope(content, target_scope, _idem(content, target_scope, i), extra)
+                    resp = client.post("/v1/experience", json=body)
+                    if resp.status_code < 400:
+                        stored += 1
+                    else:
+                        errors += 1
+                    progress.advance(task)
+
+            console.print(f"\n[success]Imported {stored} memories[/success]", end="")
+            if errors:
+                console.print(f" [warning]({errors} errors)[/warning]")
+            else:
+                console.print()
+        else:
+            for i, mem in enumerate(memories):
+                content = mem.get("content") or mem.get("text") or ""
+                if not content:
+                    continue
+                extra = {k: v for k, v in mem.items() if k not in ("content", "text")}
+                body = _envelope(content, target_scope, _idem(content, target_scope, i), extra)
+                resp = client.post("/v1/experience", json=body)
+                if resp.status_code < 400:
+                    stored += 1
+                else:
+                    errors += 1
+            print_json({"imported": stored, "errors": errors})

cortexdb_cli/commands/init.py

@@ -0,0 +1,95 @@
+"""cortexdb init — anonymous signup + config persistence."""
+
+from __future__ import annotations
+
+import click
+import httpx
+
+from cortexdb_cli.client import DEFAULT_ENDPOINT, signup
+from cortexdb_cli.config import config_path, save_config
+from cortexdb_cli.output import console
+from cortexdb_cli.state import save_state, state_path
+
+
+@click.command("init")
+@click.option(
+    "--endpoint",
+    default=DEFAULT_ENDPOINT,
+    show_default=True,
+    help="CortexDB v1 API base URL.",
+)
+@click.option(
+    "--api-key",
+    default=None,
+    help="Existing PASETO bearer token. If set, skips anonymous signup.",
+)
+@click.option(
+    "--actor",
+    default=None,
+    help="X-Cortex-Actor value. Required when --api-key is set.",
+)
+@click.option(
+    "--scope",
+    default=None,
+    help="Default scope path. Defaults to the actor.",
+)
+def init_cmd(
+    endpoint: str,
+    api_key: str | None,
+    actor: str | None,
+    scope: str | None,
+) -> None:
+    """Set up CortexDB CLI.
+
+    \b
+    Without flags:      anonymous signup (free tier, 7-day token TTL).
+    With --api-key:     register an existing token + actor (e.g. from your IdP).
+    """
+    console.print("\n[header]CortexDB CLI setup[/header]\n")
+
+    if api_key:
+        if not actor:
+            raise click.UsageError("--actor is required when --api-key is supplied.")
+        # Pure config write — no signup call.
+        save_config("default", {"endpoint": endpoint})
+        save_state(
+            {
+                "token": api_key,
+                "user_id": actor,
+                "scope": scope or actor,
+                "source": "explicit",
+            }
+        )
+        console.print(f"[success]Saved token + actor to {state_path()}[/success]")
+        console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
+        return
+
+    # Anonymous signup path.
+    console.print(f"  Endpoint: [bold]{endpoint}[/bold]")
+    console.print("  No email, no card — free tier, 7-day token TTL.\n")
+
+    try:
+        resp = signup(endpoint)
+    except httpx.HTTPError as exc:
+        console.print(f"[error]Signup failed: {exc}[/error]")
+        raise SystemExit(2) from exc
+
+    state = {
+        "token": resp["token"],
+        "user_id": resp["user_id"],
+        "scope": resp.get("scope") or resp["user_id"],
+        "expires_at": resp.get("expires_at"),
+        "tier": resp.get("tier", "free"),
+        "source": "signup",
+    }
+    save_state(state)
+    save_config("default", {"endpoint": endpoint})
+
+    console.print(f"  [success]Token minted[/success]  (expires {resp.get('expires_at', '?')})")
+    console.print(f"  [success]Actor:[/success] {resp['user_id']}")
+    console.print(f"  [success]Default scope:[/success] {state['scope']}")
+    console.print(f"\n[dim]State written to {state_path()}[/dim]")
+    console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
+    console.print("Try it:\n")
+    console.print('  [bold]cortexdb remember "Q3 revenue: $2.4M"[/bold]')
+    console.print('  [bold]cortexdb recall   "Q3 revenue?"[/bold]\n')