cortexdb-cli 0.2.0__py3-none-any.whl

cortexdb_cli/commands/entities.py

@@ -0,0 +1,174 @@
+"""cortexdb entities — entity-level views over /v1/facts.
+
+The v1 surface doesn't expose a dedicated /v1/entities route. Entities are
+the distinct subjects of facts, so `entities list` and `entities get` are
+both implemented on top of /v1/facts:
+
+    entities list   →  GET /v1/facts          (group by subject)
+    entities get ID →  GET /v1/facts?subject= (one entity's facts)
+    entities link   →  POST /v1/experience    (sentence the LLM extractor
+                                              promotes to a fact triple)
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+from datetime import datetime, timezone
+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_entities,
+    print_entity_detail,
+    print_json,
+    print_success,
+    spinner,
+)
+
+
+@click.group("entities")
+def entities_group() -> None:
+    """Entities — distinct subjects across the Facts layer."""
+
+
+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
+
+
+@entities_group.command("list")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--limit", "-l", default=200, show_default=True, help="Max facts to fold")
+@click.pass_context
+@handle_errors
+def entities_list(ctx: click.Context, scope: str | None, limit: int) -> None:
+    """List entities (distinct fact subjects)."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading entities..."):
+                resp = client.get("/v1/facts", params={"scope": s, "limit": limit})
+        else:
+            resp = client.get("/v1/facts", params={"scope": s, "limit": limit})
+        resp.raise_for_status()
+
+    data = resp.json()
+    facts = data.get("items", data) if isinstance(data, dict) else data
+
+    grouped: dict[str, dict[str, Any]] = defaultdict(
+        lambda: {"subject": "", "predicates": set(), "fact_count": 0}
+    )
+    for f in facts:
+        raw = f.get("subject") or f.get("entity_id") or ""
+        # v1 returns subject as {type, id}; legacy paths return a string.
+        subj = raw.get("id") if isinstance(raw, dict) else raw
+        if not subj:
+            continue
+        bucket = grouped[subj]
+        bucket["subject"] = subj
+        bucket["predicates"].add(f.get("predicate", ""))
+        bucket["fact_count"] += 1
+
+    entities = [
+        {
+            "id": subj,
+            "subject": v["subject"],
+            "predicates": sorted(p for p in v["predicates"] if p),
+            "fact_count": v["fact_count"],
+        }
+        for subj, v in grouped.items()
+    ]
+    entities.sort(key=lambda e: e["fact_count"], reverse=True)
+    print_entities(entities, cfg)
+
+
+@entities_group.command("get")
+@click.argument("entity_id")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.pass_context
+@handle_errors
+def entities_get(ctx: click.Context, entity_id: str, scope: str | None) -> None:
+    """Show every fact about an entity."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading entity..."):
+                resp = client.get(
+                    "/v1/facts", params={"scope": s, "subject": entity_id, "limit": 500}
+                )
+        else:
+            resp = client.get(
+                "/v1/facts", params={"scope": s, "subject": entity_id, "limit": 500}
+            )
+        resp.raise_for_status()
+    data = resp.json()
+    facts = data.get("items", data) if isinstance(data, dict) else data
+    print_entity_detail({"id": entity_id, "facts": facts}, cfg)
+
+
+@entities_group.command("link")
+@click.option("--source", "-s", required=True, help="Source entity id")
+@click.option("--target", "-t", required=True, help="Target entity id")
+@click.option("--relationship", "-r", required=True, help="Relationship label (predicate)")
+@click.option("--fact", "-f", default="", help="Plain-English sentence the LLM will extract from")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.pass_context
+@handle_errors
+def entities_link(
+    ctx: click.Context,
+    source: str,
+    target: str,
+    relationship: str,
+    fact: str,
+    scope: str | None,
+) -> None:
+    """Link two entities by recording a sentence for the LLM extractor.
+
+    The v1 entity graph is derived — you can't insert a triple directly.
+    Instead we write an experience whose text the extractor promotes to a
+    fact triple on the next pipeline tick.
+
+        cortexdb entities link -s acme -t cortexdb -r uses
+    """
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    sentence = fact or f"{source} {relationship} {target}."
+
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+    idem = "cli-link:" + hashlib.sha256(
+        f"{s}|{source}|{relationship}|{target}".encode("utf-8")
+    ).hexdigest()[:16]
+
+    body = {
+        "scope": s,
+        "modality": "observation",
+        "content": {"kind": "message", "role": "system", "text": sentence},
+        "context": {
+            "observed_at": now,
+            "labels": [f"link:{relationship}", f"subject:{source}", f"object:{target}"],
+        },
+        "idempotency_key": idem,
+    }
+
+    with get_client(cfg) as client:
+        resp = client.post("/v1/experience", json=body)
+        resp.raise_for_status()
+        if is_json_mode(cfg):
+            print_json(resp.json())
+        else:
+            print_success(
+                f"Recorded: {source} —[{relationship}]→ {target}. "
+                "The fact extractor will promote this to a triple on the next tick.",
+                cfg,
+            )

cortexdb_cli/commands/episodes.py

@@ -0,0 +1,131 @@
+"""cortexdb episodes — GET /v1/episodes + GET /v1/events/{id} + delete via /v1/forget."""
+
+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,
+    is_json_mode,
+    print_episodes,
+    print_json,
+    print_success,
+    spinner,
+)
+
+
+@click.group("episodes")
+def episodes_group() -> None:
+    """Episodes — segmented narrative summaries built from raw 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
+
+
+@episodes_group.command("list")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--limit", "-l", default=20, show_default=True, help="Max results")
+@click.option(
+    "--view",
+    type=click.Choice(["local", "holistic", "descend"]),
+    default="local",
+    show_default=True,
+    help="local = this scope only; holistic = ancestors; descend = descendants.",
+)
+@click.pass_context
+@handle_errors
+def episodes_list(
+    ctx: click.Context, scope: str | None, limit: int, view: str
+) -> None:
+    """List episodes."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    params = {"scope": s, "view": view, "limit": limit}
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading episodes..."):
+                resp = client.get("/v1/episodes", params=params)
+        else:
+            resp = client.get("/v1/episodes", params=params)
+        resp.raise_for_status()
+        print_episodes(resp.json(), cfg)
+
+
+@episodes_group.command("get")
+@click.argument("event_id")
+@click.pass_context
+@handle_errors
+def episodes_get(ctx: click.Context, event_id: str) -> None:
+    """Get a specific event by id (GET /v1/events/{id})."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get(f"/v1/events/{event_id}")
+        resp.raise_for_status()
+        data = resp.json()
+        if is_json_mode(cfg):
+            print_json(data)
+        else:
+            from rich.panel import Panel
+            from cortexdb_cli.output import escape
+
+            content = data.get("content", {})
+            text = ""
+            if isinstance(content, dict):
+                text = content.get("text") or content.get("summary") or str(content)
+            modality = data.get("modality", "")
+            actor = data.get("observed_actor") or data.get("actor", "")
+            console.print(
+                Panel(
+                    f"{escape(str(text))}\n\n"
+                    f"[dim]Modality: {escape(modality)}  Actor: {escape(actor)}[/dim]",
+                    title=f"[header]Event {escape(event_id[:16])}[/header]",
+                    border_style="cyan",
+                    padding=(1, 2),
+                )
+            )
+
+
+@episodes_group.command("delete")
+@click.argument("event_id")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--reason", "-r", required=True, help="Audit trail note.")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+@handle_errors
+def episodes_delete(
+    ctx: click.Context,
+    event_id: str,
+    scope: str | None,
+    reason: str,
+    yes: bool,
+) -> None:
+    """Delete an event via /v1/forget (selector.memory_ids)."""
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    if not yes and not is_json_mode(cfg):
+        click.confirm(f"Forget event {event_id} in scope {s}?", abort=True)
+
+    body = {
+        "scope": s,
+        "selector": {"memory_ids": [event_id]},
+        "cascade": "derived_only",
+        "audit_note": reason,
+    }
+
+    with get_client(cfg) as client:
+        resp = client.post("/v1/forget", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+        if is_json_mode(cfg):
+            print_json(data)
+        else:
+            print_success(f"Forgot event {event_id}", cfg)

cortexdb_cli/commands/experience.py

@@ -0,0 +1,238 @@
+"""cortexdb experience — POST /v1/experience.
+
+`remember` is kept as a hidden alias so existing scripts and muscle memory
+keep working, but `experience` is the canonical command — it matches the
+v1 endpoint name and the SDK method.
+
+The command is a Click group so we can hang `bulk` under it for
+`POST /v1/experience/bulk`. When you call `cortexdb experience "text"`
+the group's default invocation stores a single envelope; with no args
+it shows help.
+"""
+
+from __future__ import annotations
+
+import hashlib
+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, print_remember, spinner
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _idem(content: str, scope: str) -> str:
+    h = hashlib.sha256(f"{scope}|{content}".encode("utf-8")).hexdigest()[:16]
+    return f"cli:{h}"
+
+
+def _store(
+    cfg: dict[str, Any],
+    content: str | None,
+    scope: str | None,
+    source: str | None,
+    tags: str | None,
+    modality: str,
+    role: str,
+    wait: str | None,
+) -> None:
+    """Shared implementation of `experience [text]` and the `remember` alias."""
+    if content == "-" or (content is None and not sys.stdin.isatty()):
+        content = sys.stdin.read().strip()
+    if not content:
+        raise click.UsageError(
+            "No content provided. Pass text as an argument or pipe from stdin."
+        )
+
+    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."
+        )
+
+    labels: list[str] = []
+    if tags:
+        labels = [t.strip() for t in tags.split(",") if t.strip()]
+    if source:
+        labels.append(f"source:{source}")
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "modality": modality,
+        "content": {"kind": "message", "role": role, "text": content},
+        "context": {"observed_at": _now_iso()},
+        "idempotency_key": _idem(content, target_scope),
+    }
+    if labels:
+        body["context"]["labels"] = labels
+
+    params = {"wait": wait} if wait else None
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Storing memory..."):
+                resp = client.post("/v1/experience", json=body, params=params)
+        else:
+            resp = client.post("/v1/experience", json=body, params=params)
+        resp.raise_for_status()
+        print_remember(resp.json(), cfg)
+
+
+@click.group("experience", invoke_without_command=True)
+@click.argument("content", required=False)
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--source", "-s", help="Source label, e.g. slack, github")
+@click.option("--tags", "-t", help="Comma-separated labels")
+@click.option(
+    "--modality",
+    type=click.Choice(["conversation", "document", "observation", "feedback"]),
+    default="conversation",
+    show_default=True,
+)
+@click.option(
+    "--role",
+    type=click.Choice(["user", "assistant", "system", "tool"]),
+    default="user",
+    show_default=True,
+)
+@click.option(
+    "--wait",
+    type=click.Choice(["captured", "indexed", "consolidated"]),
+    default=None,
+    help="Block until the requested lifecycle stage.",
+)
+@click.pass_context
+@handle_errors
+def experience_cmd(
+    ctx: click.Context,
+    content: str | None,
+    scope: str | None,
+    source: str | None,
+    tags: str | None,
+    modality: str,
+    role: str,
+    wait: str | None,
+) -> None:
+    """Store a memory.
+
+    \b
+        cortexdb experience "Deploy succeeded at 14:32 UTC"
+        echo "Important fact"  | cortexdb experience -
+        cat envelopes.jsonl    | cortexdb experience bulk -
+    """
+    if ctx.invoked_subcommand is None:
+        # `cortexdb experience "text"` — the common single-envelope path.
+        if content is None and sys.stdin.isatty():
+            click.echo(ctx.get_help())
+            return
+        _store(ctx.obj, content, scope, source, tags, modality, role, wait)
+
+
+@experience_cmd.command("bulk")
+@click.argument("file", type=click.Path(exists=True), required=False)
+@click.option("--scope", "-S", help="Scope path applied when an envelope omits it.")
+@click.option(
+    "--ordering",
+    type=click.Choice(["independent", "strict_temporal"]),
+    default="independent",
+    show_default=True,
+    help="strict_temporal — fail the batch if observed_at is non-monotonic per actor.",
+)
+@click.pass_context
+@handle_errors
+def experience_bulk(
+    ctx: click.Context, file: str | None, scope: str | None, ordering: str
+) -> None:
+    """POST /v1/experience/bulk — submit a JSONL file of pre-built envelopes.
+
+    Each line must be a fully-formed experience envelope. Use
+    `cortexdb import` for plain-text or CSV ingestion where the CLI
+    wraps each row in an envelope for you.
+
+        cortexdb experience bulk events.jsonl
+    """
+    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."
+        )
+
+    if file == "-" or (file is None and not sys.stdin.isatty()):
+        raw = sys.stdin.read()
+    elif file:
+        raw = Path(file).read_text(encoding="utf-8")
+    else:
+        raise click.UsageError("Provide a JSONL file or pipe from stdin.")
+
+    items: list[dict[str, Any]] = []
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        env = json.loads(line)
+        env.setdefault("scope", target_scope)
+        items.append(env)
+    if not items:
+        raise click.UsageError("No envelopes in input.")
+
+    body = {"items": items, "ordering": ordering}
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner(f"Submitting {len(items)} envelopes..."):
+                resp = client.post("/v1/experience/bulk", json=body)
+        else:
+            resp = client.post("/v1/experience/bulk", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+        if is_json_mode(cfg):
+            print_json(data)
+        else:
+            accepted = data.get("accepted") or data.get("count") or len(items)
+            console.print(f"[success]Accepted {accepted} envelopes[/success]")
+
+
+# Hidden alias — keep `cortexdb remember "..."` working for muscle memory.
+@click.command("remember", hidden=True)
+@click.argument("content", required=False)
+@click.option("--scope", "-S")
+@click.option("--source", "-s")
+@click.option("--tags", "-t")
+@click.option(
+    "--modality",
+    type=click.Choice(["conversation", "document", "observation", "feedback"]),
+    default="conversation",
+)
+@click.option(
+    "--role",
+    type=click.Choice(["user", "assistant", "system", "tool"]),
+    default="user",
+)
+@click.option(
+    "--wait",
+    type=click.Choice(["captured", "indexed", "consolidated"]),
+    default=None,
+)
+@click.pass_context
+@handle_errors
+def remember_alias(
+    ctx: click.Context,
+    content: str | None,
+    scope: str | None,
+    source: str | None,
+    tags: str | None,
+    modality: str,
+    role: str,
+    wait: str | None,
+) -> None:
+    """Alias for `experience`. Hidden — prefer `cortexdb experience`."""
+    _store(ctx.obj, content, scope, source, tags, modality, role, wait)

cortexdb_cli/commands/export_cmd.py

@@ -0,0 +1,65 @@
+"""cortexdb export — POST /v1/export."""
+
+from __future__ import annotations
+
+import json
+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, spinner
+
+
+@click.command("export")
+@click.option("--output", "-o", type=click.Path(), help="Write JSON to this path")
+@click.option("--scope", "-S", help="Scope path to export (defaults to your default scope)")
+@click.option(
+    "--include",
+    multiple=True,
+    type=click.Choice(["events", "episodes", "facts", "beliefs", "understanding"]),
+    help="Layer(s) to include (repeatable). Defaults to events + facts.",
+)
+@click.pass_context
+@handle_errors
+def export_cmd(
+    ctx: click.Context,
+    output: str | None,
+    scope: str | None,
+    include: tuple[str, ...],
+) -> None:
+    """Export memories to JSON.
+
+    \b
+        cortexdb export                              # stdout
+        cortexdb export -o backup.json
+        cortexdb export --include facts --include beliefs
+    """
+    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}
+    if include:
+        body["include"] = list(include)
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Exporting..."):
+                resp = client.post("/v1/export", json=body)
+        else:
+            resp = client.post("/v1/export", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+
+    if output:
+        Path(output).write_text(json.dumps(data, indent=2), encoding="utf-8")
+        if not is_json_mode(cfg):
+            console.print(f"[success]Exported to {output}[/success]")
+    else:
+        print_json(data)