cortexdb-cli 0.5.3__tar.gz → 0.6.0__tar.gz

{cortexdb_cli-0.5.3 → cortexdb_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-cli
-Version: 0.5.3
+Version: 0.6.0
 Summary: Command-line interface for CortexDB — the long-term memory layer for AI.
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://cortexdb.ai/docs

{cortexdb_cli-0.5.3 → cortexdb_cli-0.6.0}/cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB CLI - command-line interface for the v1 memory API."""
 
-__version__ = "0.5.3"
+__version__ = "0.6.0"

{cortexdb_cli-0.5.3 → cortexdb_cli-0.6.0}/cortexdb_cli/client.py

@@ -63,6 +63,14 @@ class CortexClient:
     ) -> httpx.Response:
         return self._http.post(path, json=json, params=params)
 
+    def put(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        return self._http.put(path, json=json, params=params)
+
     def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
         return self._http.delete(path, params=params)
 

{cortexdb_cli-0.5.3 → cortexdb_cli-0.6.0}/cortexdb_cli/commands/__init__.py

@@ -1 +1 @@
-"""CortexDB CLI command modules."""
+"""CortexDB CLI command modules."""

cortexdb_cli-0.6.0/cortexdb_cli/commands/admin.py

@@ -0,0 +1,612 @@
+"""cortexdb admin - health, usage, layer stats, retention, unified WAL."""
+
+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_health,
+    print_json,
+    print_ontology,
+    print_success,
+    print_usage,
+    spinner,
+)
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Diagnostics - reachability, identity, rate-limit, layer status."""
+
+
+@admin_group.command("health")
+@click.pass_context
+@handle_errors
+def admin_health(ctx: click.Context) -> None:
+    """Auth + reachability check (GET /v1/auth/whoami)."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Normalise into the shape print_health expects.
+        body.setdefault("status", "ok")
+        print_health(body, cfg)
+
+
+@admin_group.command("usage")
+@click.pass_context
+@handle_errors
+def admin_usage(ctx: click.Context) -> None:
+    """Tier, capabilities, rate-limit headroom, token expiry."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading usage..."):
+                resp = client.get("/v1/auth/whoami")
+        else:
+            resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Fold rate-limit + expiry response headers into the body so the
+        # output formatter can render them in one block.
+        for k in (
+            "X-RateLimit-Limit",
+            "X-RateLimit-Reset",
+            "X-RateLimit-Remaining",
+            "X-Cortex-Token-Expires-In",
+            "X-Cortex-Token-Expires-At",
+        ):
+            if k in resp.headers:
+                body[k] = resp.headers[k]
+        print_usage(body, cfg)
+
+
+@admin_group.command("layers")
+@click.pass_context
+@handle_errors
+def admin_layers(ctx: click.Context) -> None:
+    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
+
+    Stability: experimental - the endpoint is gated by the
+    `admin.layers.stats` capability and may not be present on the free tier.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading layer stats..."):
+                resp = client.get("/v1/admin/layers/stats")
+        else:
+            resp = client.get("/v1/admin/layers/stats")
+        resp.raise_for_status()
+        print_ontology(resp.json(), cfg)
+
+
+# -- retention (unified WAL) -------------------------------------------------
+#
+# The operator surface over the D1 retention plane. Every write here is
+# irreversible in effect - an applied sweep ERASES expired captured events
+# through the ordinary erasure plane - so reporting is the default on both
+# mutating commands and `--apply` is the only thing that sends
+# `dry_run: false`.
+
+
+def _parse_source_days(pairs: tuple[str, ...]) -> dict[str, int]:
+    """Parse repeated ``--source-days KEY=N`` options into the wire map.
+
+    Only the option's own grammar is checked here (KEY=VALUE, N a positive
+    integer). The ``source:`` prefix rule and the 1..=36500 ceiling belong to
+    the server's governance validator, which answers 422
+    INVALID_RETENTION_POLICY - duplicating them here would let the CLI and
+    the server disagree about what a valid rule is.
+    """
+    out: dict[str, int] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise click.UsageError(f"--source-days must be KEY=DAYS, got {pair!r}")
+        key, raw = pair.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise click.UsageError(f"--source-days needs a key, got {pair!r}")
+        try:
+            days = int(raw)
+        except ValueError:
+            raise click.UsageError(
+                f"--source-days value must be a whole number of days, got {raw!r}"
+            ) from None
+        if days < 1:
+            raise click.UsageError(
+                f"--source-days must be at least 1 day, got {days} for {key!r}"
+            )
+        if key in out:
+            raise click.UsageError(f"--source-days {key!r} given twice")
+        out[key] = days
+    return out
+
+
+def _print_retention_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/retention."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    config = Table(title="[header]Retention[/header]", border_style="cyan")
+    config.add_column("Setting", style="bold")
+    config.add_column("Value")
+    interval = data.get("sweep_interval_secs", 0)
+    if data.get("enabled"):
+        scheduled = "yes"
+    elif data.get("scheduler_disabled"):
+        scheduled = "[warning]no (CORTEX_SCHEDULER_DISABLE)[/warning]"
+    else:
+        scheduled = "no (operator-triggered only)"
+    config.add_row("scheduled", scheduled)
+    config.add_row("sweep interval", f"{interval}s" if interval else "-")
+    default_days = data.get("deployment_default_days")
+    config.add_row("deployment default", f"{default_days}d" if default_days else "keep")
+    config.add_row("max events/tick", str(data.get("max_events_per_tick", "")))
+    config.add_row("tick budget", str(data.get("tick_budget_secs", "")) + "s")
+    config.add_row(
+        "compact after sweep", "yes" if data.get("compact_after_sweep") else "no"
+    )
+    config.add_row("cursor", str(data.get("cursor", "")))
+    config.add_row("watermark", str(data.get("watermark", "")))
+    config.add_row(
+        "cursor trustworthy",
+        "yes" if data.get("fingerprint_ok") else "no (next applied tick rescans)",
+    )
+    config.add_row("running", "yes" if data.get("running") else "no")
+    if data.get("native_profile_blocked"):
+        config.add_row("native profile", "[warning]retention refused[/warning]")
+    console.print(config)
+
+    policies = data.get("policies") or []
+    if policies:
+        table = Table(title="[header]Policies[/header]", border_style="cyan")
+        table.add_column("Scope", style="bold")
+        table.add_column("Default", justify="right")
+        table.add_column("Per-source", style="dim")
+        for entry in policies:
+            policy = entry.get("policy") or {}
+            days = policy.get("default_retention_days")
+            per_source = policy.get("per_source_days") or {}
+            table.add_row(
+                escape(str(entry.get("scope", ""))),
+                f"{days}d" if days else "keep",
+                escape(", ".join(f"{k}={v}d" for k, v in sorted(per_source.items()))),
+            )
+        console.print(table)
+    else:
+        console.print("[dim]No per-scope retention rules stored.[/dim]")
+
+    last = data.get("last")
+    if isinstance(last, dict):
+        note = " [warning](dry run)[/warning]" if last.get("dry_run") else ""
+        console.print(
+            "[dim]Last tick:[/dim] "
+            f"scanned {last.get('scanned', 0)}, "
+            f"expired {last.get('expired', 0)}, "
+            f"erased {last.get('erased', 0)}, "
+            f"stopped {escape(str(last.get('stopped', '')))}" + note
+        )
+
+
+def _print_sweep_report(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/retention/sweep (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "erased" not in data:
+        # 202: the tick outlived the blocking-lane deadline and is still going.
+        poll = escape(str(data.get("poll", "/v1/admin/retention")))
+        console.print(
+            Panel(
+                f"Sweep still running; poll [bold]{poll}[/bold]",
+                title="[header]Retention sweep[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] captured row(s)",
+        f"expired [bold]{data.get('expired', 0)}[/bold], "
+        f"erased [bold]{data.get('erased', 0)}[/bold], "
+        f"kept forever [bold]{data.get('kept_forever', 0)}[/bold]",
+        f"cursor {data.get('cursor_before', 0)} -> {data.get('cursor_after', 0)} "
+        f"(watermark {data.get('watermark', 0)})",
+        f"stopped: {escape(str(data.get('stopped', '')))} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    held = data.get("held") or {}
+    if isinstance(held, dict) and any(held.values()):
+        lines.append(f"[dim]held: {escape(str(held))}[/dim]")
+    for error in data.get("errors") or []:
+        lines.append(f"[error]{escape(str(error))}[/error]")
+    title = "[header]Retention sweep" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+def _print_wal_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/wal."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Unified WAL[/header]", border_style="cyan")
+    table.add_column("Field", style="bold")
+    table.add_column("Value", justify="right")
+    for label, key in (
+        ("live rows", "live_count"),
+        ("next offset", "next_offset"),
+        ("head offset", "head_offset"),
+        ("captured head", "captured_head_offset"),
+        ("partitions", "partitions"),
+        ("retired markers", "retired_marker_count"),
+    ):
+        value = data.get(key)
+        table.add_row(label, "-" if value is None else str(value))
+    if data.get("native_profile_blocked"):
+        table.add_row("native profile", "[warning]mutations refused[/warning]")
+    console.print(table)
+
+    consumers = data.get("consumer_offsets") or {}
+    if consumers:
+        floors = Table(title="[header]Consumer floors[/header]", border_style="cyan")
+        floors.add_column("Consumer", style="bold")
+        floors.add_column("Offset", justify="right")
+        for name, offset in sorted(consumers.items()):
+            floors.add_row(escape(str(name)), str(offset))
+        console.print(floors)
+
+    verify = data.get("verify")
+    if isinstance(verify, dict):
+        ok = verify.get("ok")
+        if ok is None:
+            # Not a verdict: the self-check is bounded and a production-sized
+            # log is past that bound, so nothing was checked. Rendering this
+            # as a failure is how a healthy store gets restored from backup.
+            skipped = escape(
+                str(verify.get("skipped", "log exceeds the bounded self-check"))
+            )
+            console.print(f"[warning]Integrity check not run:[/warning] {skipped}")
+        elif ok:
+            console.print("[success]Integrity check passed.[/success]")
+        else:
+            reason = escape(str(verify.get("reason", "unknown")))
+            console.print(f"[error]Integrity check failed:[/error] {reason}")
+
+
+def _print_compaction(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/wal/compact (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "removed_tombstones" not in data:
+        poll = escape(str(data.get("poll", "/v1/admin/wal")))
+        console.print(
+            Panel(
+                f"Compaction still running; poll [bold]{poll}[/bold]",
+                title="[header]WAL compaction[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] row(s)",
+        f"removed {data.get('removed_tombstones', 0)} tombstone(s), "
+        f"{data.get('removed_orphaned_twins', 0)} orphaned twin(s)",
+        f"skipped {data.get('skipped_in_use', 0)} in use, "
+        f"{data.get('skipped_above_bound', 0)} above the bound",
+        f"live rows {data.get('live_count_before', 0)} -> "
+        f"{data.get('live_count_after', 0)}, "
+        f"{data.get('bytes_removed', 0)} byte(s) reclaimed",
+        f"ranges compacted: {data.get('ranges_compacted', 0)} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    if data.get("truncated_by_budget"):
+        lines.append("[warning]Budget reached - rerun to continue.[/warning]")
+    title = "[header]WAL compaction" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+@admin_group.group("retention")
+def retention_group() -> None:
+    """Unified-WAL retention - per-scope rules and the expiry sweep.
+
+    Requires trusted-operator access. Reporting needs `diagnostics.read`;
+    storing a rule or applying a sweep needs `admin.compact`.
+    """
+
+
+@retention_group.command("show")
+@click.pass_context
+@handle_errors
+def retention_show(ctx: click.Context) -> None:
+    """Config, stored rules, cursor and last tick (GET /v1/admin/retention).
+
+    503 NOT_AVAILABLE when this process runs no retention sweeper (legacy
+    WAL, no coordinator, or a configuration the sweeper refused).
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading retention status..."):
+                resp = client.get("/v1/admin/retention")
+        else:
+            resp = client.get("/v1/admin/retention")
+        resp.raise_for_status()
+        _print_retention_status(resp.json(), cfg)
+
+
+@retention_group.command("set")
+@click.option("--scope", "-S", required=True, help="Scope path the rule is keyed on.")
+@click.option(
+    "--days",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Expire captured events after this many days. Omit for an explicit KEEP.",
+)
+@click.option(
+    "--source-days",
+    "source_days",
+    multiple=True,
+    metavar="KEY=DAYS",
+    help="Per-source override, e.g. source:slack=30. Repeatable.",
+)
+@click.pass_context
+@handle_errors
+def retention_set(
+    ctx: click.Context,
+    scope: str,
+    days: int | None,
+    source_days: tuple[str, ...],
+) -> None:
+    """Store the retention rule for one scope (PUT /v1/admin/retention/policies).
+
+    Irreversible in effect: an applied sweep under this rule ERASES expired
+    events from the scope and every scope beneath it. Omitting `--days`
+    stores an explicit KEEP, which overrides the deployment default for the
+    subtree but never a shorter rule inherited from an ancestor scope.
+    Storing a rule always resets the durable sweep cursor.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"scope": scope, "default_retention_days": days}
+    per_source = _parse_source_days(source_days)
+    if per_source:
+        body["per_source_days"] = per_source
+    with get_client(cfg) as client:
+        resp = client.put("/v1/admin/retention/policies", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    policy = data.get("policy") or {}
+    stored = policy.get("default_retention_days")
+    reset = " (sweep cursor reset)" if data.get("cursor_reset") else ""
+    print_success(
+        f"Retention rule stored for {scope}: "
+        + (f"{stored} day(s)" if stored else "keep")
+        + reset
+    )
+
+
+@retention_group.command("delete")
+@click.option("--scope", "-S", required=True, help="Scope path whose rule to remove.")
+@click.pass_context
+@handle_errors
+def retention_delete(ctx: click.Context, scope: str) -> None:
+    """Remove one scope's rule (DELETE /v1/admin/retention/policies).
+
+    404 when a well-formed store held no rule for exactly this scope -
+    inheritance is resolution, not storage, so a descendant that expires by
+    an ancestor's rule has no rule of its own to delete. Resets the durable
+    sweep cursor, like `set`.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.delete("/v1/admin/retention/policies", params={"scope": scope})
+        resp.raise_for_status()
+    if is_json_mode(cfg):
+        print_json({"scope": scope, "deleted": True, "cursor_reset": True})
+        return
+    print_success(f"Retention rule removed for {scope} (sweep cursor reset)")
+
+
+@retention_group.command("sweep")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="ERASE expired events. Without it the tick only reports.",
+)
+@click.option("--scope", "-S", default=None, help="Confine the scan to this subtree.")
+@click.option(
+    "--older-than-secs",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Request-only TTL override for --scope. Never persisted.",
+)
+@click.option(
+    "--max-events",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Override the per-tick expiry budget.",
+)
+@click.option(
+    "--rescan",
+    is_flag=True,
+    default=False,
+    help="Ignore the durable cursor and scan from the start of the log.",
+)
+@click.pass_context
+@handle_errors
+def retention_sweep(
+    ctx: click.Context,
+    apply_: bool,
+    scope: str | None,
+    older_than_secs: int | None,
+    max_events: int | None,
+    rescan: bool,
+) -> None:
+    """Run one retention tick (POST /v1/admin/retention/sweep).
+
+    DRY RUN IS THE DEFAULT - the tick reports what would be erased and
+    writes nothing. `--apply` is what sends `dry_run: false`, which erases
+    expired captured events irreversibly and needs `admin.compact`.
+
+    Single-flight: a second concurrent tick is refused with 409
+    RETENTION_SWEEP_RUNNING rather than queued.
+    """
+    cfg = ctx.obj
+    if older_than_secs is not None and not scope:
+        raise click.UsageError("--older-than-secs requires --scope.")
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if scope:
+        body["scope"] = scope
+    if older_than_secs is not None:
+        body["older_than_secs"] = older_than_secs
+    if max_events is not None:
+        body["max_events"] = max_events
+    if rescan:
+        body["rescan"] = True
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Sweeping..."):
+                resp = client.post("/v1/admin/retention/sweep", json=body)
+        else:
+            resp = client.post("/v1/admin/retention/sweep", json=body)
+        resp.raise_for_status()
+        _print_sweep_report(resp.json(), cfg)
+
+
+@admin_group.group("wal")
+def wal_group() -> None:
+    """Unified write-ahead log - census and dead-row compaction.
+
+    Requires trusted-operator access. A legacy data dir is refused with 409
+    RETENTION_UNSUPPORTED_BACKEND naming the offline migrator.
+    """
+
+
+@wal_group.command("status")
+@click.option(
+    "--verify",
+    is_flag=True,
+    default=False,
+    help=(
+        "Also run the bounded row-level self-check (clamped server-side). "
+        "The check is bounded at 1M rows / 512 MiB, which a production-sized "
+        "log exceeds: it then reports 'not run', which is not a failure."
+    ),
+)
+@click.pass_context
+@handle_errors
+def wal_status(ctx: click.Context, verify: bool) -> None:
+    """Live rows, offsets, consumer floors, markers (GET /v1/admin/wal)."""
+    cfg = ctx.obj
+    params = {"verify": "true"} if verify else None
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading WAL census..."):
+                resp = client.get("/v1/admin/wal", params=params)
+        else:
+            resp = client.get("/v1/admin/wal", params=params)
+        resp.raise_for_status()
+        _print_wal_status(resp.json(), cfg)
+
+
+@wal_group.command("compact")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="Physically remove the dead rows. Without it the run only reports.",
+)
+@click.option(
+    "--max-rows",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Upper bound on dead rows removed in one sweep.",
+)
+@click.option(
+    "--below-offset",
+    type=click.IntRange(min=0),
+    default=None,
+    help="Exclusive offset bound. Defaults to the indexer watermark.",
+)
+@click.option(
+    "--compaction",
+    type=click.Choice(["none", "touched_ranges", "full"]),
+    default=None,
+    help="Physical reclamation mode. `full` is a whole-CF compaction.",
+)
+@click.pass_context
+@handle_errors
+def wal_compact(
+    ctx: click.Context,
+    apply_: bool,
+    max_rows: int | None,
+    below_offset: int | None,
+    compaction: str | None,
+) -> None:
+    """Reclaim already-dead WAL rows (POST /v1/admin/wal/compact).
+
+    Removes only rows that are ALREADY logically dead - redaction
+    tombstones and orphaned Derived twins. It never removes a live row and
+    never touches derived-artifact history.
+
+    DRY RUN IS THE DEFAULT; `--apply` is what sends `dry_run: false` and
+    needs `admin.compact`. Single-flight: 409 WAL_COMPACTION_RUNNING.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if max_rows is not None:
+        body["max_rows"] = max_rows
+    if below_offset is not None:
+        body["below_offset"] = below_offset
+    if compaction is not None:
+        body["compaction"] = compaction
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Compacting..."):
+                resp = client.post("/v1/admin/wal/compact", json=body)
+        else:
+            resp = client.post("/v1/admin/wal/compact", json=body)
+        resp.raise_for_status()
+        _print_compaction(resp.json(), cfg)