cortexdb-cli 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

cortexdb_cli/__init__.py

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

cortexdb_cli/commands/admin.py

@@ -95,7 +95,7 @@ def admin_layers(ctx: click.Context) -> None:
 
 # -- retention (unified WAL) -------------------------------------------------
 #
-# The operator surface over the D1 retention plane. Every write here is
+# The operator surface over the retention plane. Every write here is
 # irreversible in effect - an applied sweep removes expired captured events,
 # everything about them under an `erase` rule, their raw data under a
 # `keep_learned` one - so reporting is the default on both mutating commands

cortexdb_cli/commands/admin_access.py

@@ -151,7 +151,11 @@ def tenant_settings(ctx, root, mode, readiness_ticket, clear_readiness):
 def tenant_binding(ctx, root, from_tenant, apply_):
     """Bind a root's records and tombstones to the tenant it names (POST /v1/admin/access/tenant-binding).
 
-    A DRY RUN unless --apply; running it again is safe.
+    A DRY RUN unless --apply; running it again is safe. The dry run says how
+    the operator plane decides the real run (operator_plane: whether it
+    registers the root, is in-band, the tenant's mode): when it says
+    break_glass_required, pass --break-glass REASON --break-glass-ticket
+    TICKET with --apply.
     """
     cfg = ctx.obj
     scope = root_or_die(cfg, root)
@@ -169,6 +173,15 @@ def tenant_binding(ctx, root, from_tenant, apply_):
                       + (", root registered" if d.get("root_registered") else ""))
         if d.get("consistency_token"):
             console.print(f"[dim]  consistency token: {escape(str(d['consistency_token']))}[/dim]")
+        plane = d.get("operator_plane")
+        if isinstance(plane, dict):
+            # 0.14.1 (p6a C): how the operator plane decides the run.
+            console.print(f"  operator plane: mode {escape(str(plane.get('mode')))}"
+                          + (", the run registers the root" if plane.get("registers_root") else "")
+                          + (", an in-band path for the operator key" if plane.get("in_band") else ""))
+            if plane.get("break_glass_required"):
+                console.print("[warning]  The real run needs break-glass: add --break-glass REASON "
+                              "--break-glass-ticket TICKET to --apply (else 403 BREAK_GLASS_REQUIRED).[/warning]")
         if d.get("dry_run"):
             console.print("[dim]Nothing was changed. Run again with --apply.[/dim]")
 

cortexdb_cli/commands/beliefs.py

@@ -5,12 +5,20 @@ from __future__ import annotations
 import click
 
 from cortexdb_cli.client import get_client
-from cortexdb_cli.common import api_options, at_least_option
+from cortexdb_cli.common import (
+    api_options,
+    at_least_option,
+    derived_by_option,
+    include_option,
+    include_param,
+)
 from cortexdb_cli.errors import handle_errors
 from cortexdb_cli.output import (
     console,
+    derivation_summary,
     escape,
     is_json_mode,
+    note_unreported_derivation,
     print_json,
     spinner,
 )
@@ -40,15 +48,30 @@ def _scope_or_die(cfg: dict, scope: str | None) -> str:
 @beliefs_group.command("list")
 @click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
 @click.option("--limit", "-l", default=50, show_default=True)
+@include_option
 @at_least_option
 @api_options
 @click.pass_context
 @handle_errors
-def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: str | None) -> None:
-    """List active beliefs in a scope."""
+def beliefs_list(
+    ctx: click.Context,
+    scope: str | None,
+    limit: int,
+    include: tuple[str, ...],
+    at_least: str | None,
+) -> None:
+    """List active beliefs in a scope.
+
+    With --include derivation each belief also says how it was made,
+    computed from its supporting facts (the latest one's; unsynced when any
+    of them is). A belief with no fact support, a declared one, has no stamp.
+    """
     cfg = ctx.obj
     s = _scope_or_die(cfg, scope)
     params: dict[str, str | int] = {"scope": s, "limit": limit}
+    included = include_param(include)
+    if included:
+        params["include"] = included
     if at_least:
         params["at_least"] = at_least
     with get_client(cfg) as client:
@@ -79,19 +102,26 @@ def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: st
     table.add_column("Object", style="bold")
     table.add_column("Conf", justify="right", width=6)
     table.add_column("Support", justify="right", width=8)
+    if included:
+        table.add_column("Why", style="dim", max_width=48)
     for b in items:
         # v1 beliefs carry their triple under `claim` ({subject, predicate,
         # object}, each term {type, value|id}); the columns used to read
         # top-level `predicate`/`object`, which no belief has.
         claim = b.get("claim") if isinstance(b.get("claim"), dict) else b
-        table.add_row(
+        row = [
             escape(str(b.get("belief_id") or b.get("id", ""))[:16]),
             escape(_term(claim.get("predicate"))),
             escape(_term(claim.get("object"))),
             f"{(b.get('confidence') or 0):.0%}",
             str(b.get("support_count") or len(b.get("supports") or [])),
-        )
+        ]
+        if included:
+            row.append(escape(derivation_summary(b.get("derivation"))))
+        table.add_row(*row)
     console.print(table)
+    if included:
+        note_unreported_derivation(items)
     if isinstance(data, dict) and data.get("rollups"):
         console.print(
             f"[dim]{len(data['rollups'])} rollup(s) on this page; "
@@ -108,19 +138,30 @@ def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: st
     help="Return the belief only if it lies at or under this scope (?scope=; else 404). It "
     "routes the read on a cluster, and a break-glass read of a private region must name it.",
 )
+@include_option
 @api_options
 @click.pass_context
 @handle_errors
-def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
+def beliefs_why(
+    ctx: click.Context, belief_id: str, scope: str | None, include: tuple[str, ...]
+) -> None:
     """Show the facts + events that ground a belief.
 
+    \b
         cortexdb beliefs why belief_01HX...
         cortexdb beliefs why belief_01HX... --scope org:acme/team:eng
+        cortexdb beliefs why belief_01HX... --include derivation
+
+    With --include derivation the belief also carries its derivation, and
+    the terminal says it on one line under the answer.
     """
     cfg = ctx.obj
     params = {"belief_id": belief_id}
     if scope:
         params["scope"] = scope
+    included = include_param(include)
+    if included:
+        params["include"] = included
     with get_client(cfg) as client:
         if not is_json_mode(cfg):
             with spinner("Tracing provenance..."):
@@ -128,7 +169,13 @@ def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
         else:
             resp = client.get("/v1/beliefs/why", params=params)
         resp.raise_for_status()
-        print_json(resp.json())
+        data = resp.json()
+        print_json(data)
+    if included and not is_json_mode(cfg):
+        belief = data.get("belief") if isinstance(data, dict) else None
+        if isinstance(belief, dict):
+            console.print(f"[dim]why: {escape(derivation_summary(belief.get('derivation')))}[/dim]")
+            note_unreported_derivation([belief])
 
 
 @beliefs_group.command("create")
@@ -165,6 +212,10 @@ def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
     "key is 409 IDEMPOTENCY_CONFLICT).",
 )
 @click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@derived_by_option(
+    "A declared belief carries it in its record (below apply format 10 the server answers 503 "
+    "FORMAT_UPGRADE_PENDING), and include=derivation reads it back."
+)
 @api_options
 @click.pass_context
 @handle_errors
@@ -179,16 +230,20 @@ def beliefs_create(
     provenance: tuple[str, ...],
     idempotency_key: str | None,
     scope: str | None,
+    derived_by: dict[str, str] | None,
 ) -> None:
     """Declare a belief directly (POST /v1/beliefs).
 
     \b
         cortexdb beliefs create "Acme is on the enterprise plan" \\
             --confidence 0.9 --support evt_01HX... --subject Acme --predicate plan
+        cortexdb beliefs create "Bob reads at level B2" --confidence 0.8 \\
+            --subject Bob --predicate level --derived-by acme-level@1.1.0
 
     Declaring a newer belief over the same (subject, predicate) closes the
     previous one. Pass --idempotency-key to retry safely after an outcome
-    you did not learn (WAL_OUTCOME_UNKNOWN, a lost connection).
+    you did not learn (WAL_OUTCOME_UNKNOWN, a lost connection); the same key
+    with another --derived-by stamp, or none, is 409 IDEMPOTENCY_CONFLICT.
     """
     cfg = ctx.obj
     s = _scope_or_die(cfg, scope)
@@ -210,6 +265,8 @@ def beliefs_create(
         if not idempotency_key.strip() or len(idempotency_key.encode("utf-8")) > 256:
             raise click.UsageError("--idempotency-key is 1 to 256 bytes, not blank")
         body["idempotency_key"] = idempotency_key
+    if derived_by:
+        body["derived_by"] = derived_by
     with get_client(cfg) as client:
         resp = client.post("/v1/beliefs", json=body)
         resp.raise_for_status()