brainpalace-cli 26.7.2__tar.gz → 26.7.4__tar.gz

{brainpalace_cli-26.7.2 → brainpalace_cli-26.7.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: brainpalace-cli
-Version: 26.7.2
-Summary: BrainPalace CLI - Command-line interface for managing AI agent memory and knowledge retrieval
+Version: 26.7.4
+Summary: BrainPalace CLI - Command-line interface for the typed-memory & retrieval engine for AI agents (code & docs today, more domains coming)
 License: MIT
 Keywords: brainpalace,rag,cli,ai-memory,llm-memory,semantic-search,ai-agent,claude-code,agent-memory
 Author: bxw91

{brainpalace_cli-26.7.2 → brainpalace_cli-26.7.4}/brainpalace_cli/cli.py

@@ -22,6 +22,7 @@ from .commands import (
     folders_group,
     hook_group,
     index_command,
+    ingest_command,
     init_command,
     inject_command,
     install_agent_command,
@@ -35,8 +36,10 @@ from .commands import (
     query_command,
     recall_command,
     records_group,
+    references_group,
     remember_command,
     reset_command,
+    rules_group,
     session_path_command,
     start_command,
     status_command,
@@ -49,6 +52,7 @@ from .commands import (
     verify_docs_command,
     whoami_command,
 )
+from .commands.entities import entities_group
 from .commands.graph import graph_group
 
 
@@ -137,6 +141,7 @@ cli.add_command(context_command, name="context")
 cli.add_command(submit_session_command, name="submit-session")
 cli.add_command(session_path_command, name="session-path")
 cli.add_command(index_command, name="index")
+cli.add_command(ingest_command, name="ingest")
 cli.add_command(inject_command, name="inject")
 cli.add_command(jobs_command, name="jobs")
 cli.add_command(reset_command, name="reset")
@@ -152,8 +157,11 @@ cli.add_command(install_agent_command, name="install-agent")
 cli.add_command(install_session_hooks_command, name="install-session-hooks")
 cli.add_command(backfill_command, name="backfill-sessions")
 cli.add_command(records_group, name="records")
+cli.add_command(references_group, name="references")
+cli.add_command(rules_group, name="rules")
 cli.add_command(extraction_group, name="extraction")
 cli.add_command(graph_group, name="graph")
+cli.add_command(entities_group, name="entities")
 
 # Register doc-sync maintenance commands (hidden; deterministic, never call an LLM)
 cli.add_command(sync_docs_command, name="sync-docs")

{brainpalace_cli-26.7.2 → brainpalace_cli-26.7.4}/brainpalace_cli/client/api_client.py

@@ -58,6 +58,9 @@ class IndexingStatus:
     migration: dict[str, Any] | None = None
     graph_index: dict[str, Any] | None = None
     features: dict[str, Any] | None = None
+    #: Programmatic text-ingest chunk count block ({"chunks": int}); separate
+    #: from folder-manifest-derived total_documents (spec Item 3).
+    text_ingest: dict[str, Any] | None = None
     #: Index-drift warnings (embedding provider/model or storage backend changed
     #: away from what the existing index was built with). Empty when consistent.
     index_warnings: list[str] = field(default_factory=list)
@@ -287,6 +290,7 @@ class DocServeClient:
             embedding_cache=data.get("embedding_cache"),
             graph_index=data.get("graph_index"),
             features=data.get("features"),
+            text_ingest=data.get("text_ingest"),
             index_warnings=data.get("index_warnings") or [],
         )
 
@@ -300,8 +304,11 @@ class DocServeClient:
         source_types: list[str] | None = None,
         languages: list[str] | None = None,
         file_paths: list[str] | None = None,
+        domains: list[str] | None = None,
+        metadata_filter: dict[str, str] | None = None,
         time_decay: bool = True,
         language: str | None = None,
+        include_sensitive: bool = False,
     ) -> QueryResponse:
         """
         Query indexed documents.
@@ -315,8 +322,15 @@ class DocServeClient:
             source_types: Filter by source types (doc, code, test).
             languages: Filter by programming languages.
             file_paths: Filter by file path patterns.
+            domains: Filter to chunks ingested under one of these domains
+                (reserved `domain` metadata key; OR across values).
+            metadata_filter: Filter to chunks whose metadata exact-matches
+                every key/value pair (AND across keys).
             language: BM25 query language override (ISO 639-1). Defaults to
                 the project bm25.language setting when None.
+            include_sensitive: Reveal rows marked sensitive (interactive CLI
+                only). Omitted from the request when False, so MCP/dashboard
+                callers — which never pass it — stay at default-deny.
 
         Returns:
             QueryResponse with matching results.
@@ -330,6 +344,8 @@ class DocServeClient:
         }
         if not time_decay:
             request_data["time_decay"] = False
+        if include_sensitive:
+            request_data["include_sensitive"] = True
         # Truthy (not ``is not None``) so an empty list means "no filter" — the
         # MCP QueryInput now defaults these to ``[]`` (avoids a nullable-union
         # JSON schema that some LLM clients mishandle). Empty == omit == default.
@@ -339,6 +355,10 @@ class DocServeClient:
             request_data["languages"] = languages
         if file_paths:
             request_data["file_paths"] = file_paths
+        if domains:
+            request_data["domains"] = domains
+        if metadata_filter:
+            request_data["metadata_filter"] = metadata_filter
         if language is not None:
             request_data["language"] = language
 
@@ -449,6 +469,9 @@ class DocServeClient:
         watch_mode: str | None = None,
         watch_debounce_seconds: int | None = None,
         rebuild_graph: bool = False,
+        domain: str | None = None,
+        authority: str | None = None,
+        force_authority: bool = False,
     ) -> IndexResponse:
         """
         Enqueue an indexing job for documents and optionally code from a folder.
@@ -474,6 +497,11 @@ class DocServeClient:
             watch_debounce_seconds: Per-folder debounce in seconds.
             rebuild_graph: Rebuild the graph index from existing chunks only
                 (no embedding); returns a completed response, not a queued job.
+            domain: Optional user-facing domain label for the folder (6.5).
+            authority: Binary provenance trust level: 'authoritative' or
+                'reference' (6.5). None lets the server resolve the default.
+            force_authority: Allow an external folder to be registered as
+                'authoritative' (6.5).
 
         Returns:
             IndexResponse with job ID and queue status.
@@ -490,7 +518,12 @@ class DocServeClient:
             "exclude_patterns": exclude_patterns,
             "force": force,
             "force_budget": force_budget,
+            "force_authority": force_authority,
         }
+        if domain is not None:
+            body["domain"] = domain
+        if authority is not None:
+            body["authority"] = authority
         if include_types is not None:
             body["include_types"] = include_types
         if injector_script is not None:
@@ -521,6 +554,225 @@ class DocServeClient:
             message=data.get("message"),
         )
 
+    def ingest_text(
+        self,
+        *,
+        items: list[dict[str, Any]],
+        sensitivity: str = "normal",
+        language: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Ingest free text with caller-supplied provenance (spec Item 3).
+
+        Args:
+            items: List of {text, metadata, domain, source, source_id} dicts.
+            sensitivity: Sensitivity mark applied to all items in this call.
+            language: Optional BM25 language override.
+
+        Returns:
+            Response dict with chunks_new, chunks_kept, chunks_deleted,
+            chunk_ids, source_ids.
+        """
+        body: dict[str, Any] = {"items": items, "sensitivity": sensitivity}
+        if language:
+            body["language"] = language
+        return self._request("POST", "/ingest/text", json=body)
+
+    def ingest_records(
+        self,
+        *,
+        items: list[dict[str, Any]],
+        sensitivity: str = "normal",
+    ) -> dict[str, Any]:
+        """Ingest caller-asserted typed records (POST /ingest/records).
+
+        Args:
+            items: List of {subject, metric, value, unit?, ts?, domain, source,
+                source_id, confidence?, properties?} dicts.
+            sensitivity: Sensitivity mark applied to all items in this call.
+
+        Returns:
+            Response dict with the number of records persisted.
+        """
+        return self._request(
+            "POST",
+            "/ingest/records",
+            json={"items": items, "sensitivity": sensitivity},
+        )
+
+    def ingest_references(
+        self,
+        *,
+        items: list[dict[str, Any]],
+        sensitivity: str = "normal",
+    ) -> dict[str, Any]:
+        """Ingest lazy-tier references (POST /ingest/references).
+
+        Args:
+            items: List of {pointer, summary, domain, source, source_id} dicts.
+            sensitivity: Sensitivity mark applied to all items in this call.
+
+        Returns:
+            Response dict with the number of references persisted.
+        """
+        return self._request(
+            "POST",
+            "/ingest/references",
+            json={"items": items, "sensitivity": sensitivity},
+        )
+
+    def references_list(self, domain: str | None = None) -> dict[str, Any]:
+        """List references, optionally filtered by domain (GET /references)."""
+        params = {"domain": domain} if domain else None
+        return self._request("GET", "/references", params=params)
+
+    def references_search(
+        self,
+        *,
+        query: str,
+        top_k: int = 5,
+        domain: str | None = None,
+        include_sensitive: bool = False,
+    ) -> dict[str, Any]:
+        """Semantic search over reference summaries (POST /references/search)."""
+        body: dict[str, Any] = {
+            "query": query,
+            "top_k": top_k,
+            "include_sensitive": include_sensitive,
+        }
+        if domain:
+            body["domain"] = domain
+        return self._request("POST", "/references/search", json=body)
+
+    def references_embed_missing(self) -> dict[str, Any]:
+        """Backfill embeddings for references lacking one
+        (POST /references/embed-missing)."""
+        return self._request("POST", "/references/embed-missing")
+
+    def ingest_sources(
+        self,
+        *,
+        domain: str | None = None,
+        source: str | None = None,
+        include_sensitive: bool = False,
+    ) -> dict[str, Any]:
+        """List distinct ingested source_ids (GET /ingest/sources).
+
+        Args:
+            domain: Optional domain filter.
+            source: Optional raw-source filter.
+            include_sensitive: Reveal sources whose chunks are marked sensitive.
+
+        Returns:
+            Response dict with `sources` (each: source_id, domain, source,
+            chunk_count, ingested_at) and `total`.
+        """
+        params: dict[str, Any] = {}
+        if domain:
+            params["domain"] = domain
+        if source:
+            params["source"] = source
+        if include_sensitive:
+            params["include_sensitive"] = True
+        return self._request("GET", "/ingest/sources", params=params or None)
+
+    def ingest_show(
+        self,
+        source_id: str,
+        *,
+        offset: int = 0,
+        limit: int = 50,
+        include_sensitive: bool = False,
+    ) -> dict[str, Any]:
+        """Show one source_id's ingested chunks, paginated
+        (GET /ingest/text/{source_id}).
+
+        Args:
+            source_id: Caller-supplied source id used at ingest time.
+            offset: Pagination offset.
+            limit: Page size.
+            include_sensitive: Reveal chunks marked sensitive.
+
+        Returns:
+            Response dict with source_id, total, offset, limit, and chunks
+            (each: chunk_id, text, metadata).
+        """
+        params: dict[str, Any] = {"offset": offset, "limit": limit}
+        if include_sensitive:
+            params["include_sensitive"] = True
+        return self._request("GET", f"/ingest/text/{source_id}", params=params)
+
+    def ingest_delete(self, source_id: str) -> dict[str, Any]:
+        """
+        Delete all ingested chunks for a source_id (un-ingest).
+
+        Args:
+            source_id: Caller-supplied source id used at ingest time.
+
+        Returns:
+            Response dict with chunks_deleted.
+        """
+        return self._request("DELETE", f"/ingest/text/{source_id}")
+
+    def ingest_forget(self, source_id: str) -> dict[str, Any]:
+        """
+        Full forget: delete a source_id across all three ingest tiers
+        (DELETE /ingest/source/{source_id}).
+
+        Args:
+            source_id: Caller-supplied source id used at ingest time.
+
+        Returns:
+            Response dict with chunks_deleted, records_deleted,
+            references_deleted.
+        """
+        return self._request("DELETE", f"/ingest/source/{source_id}")
+
+    # --- identity (G5): person / alias / link ---------------------------
+
+    def entities_person(self, person: dict[str, Any]) -> dict[str, Any]:
+        """Upsert a person (POST /entities/person)."""
+        return self._request("POST", "/entities/person", json=person)
+
+    def entities_alias(self, alias: dict[str, Any]) -> dict[str, Any]:
+        """Bind a surface to a person (POST /entities/alias)."""
+        return self._request("POST", "/entities/alias", json=alias)
+
+    def entities_link(self, link: dict[str, Any]) -> dict[str, Any]:
+        """Attach a ref to a person or record it unresolved
+        (POST /entities/link)."""
+        return self._request("POST", "/entities/link", json=link)
+
+    def entities_resolve(
+        self,
+        *,
+        surface: str,
+        scope: str | None = None,
+        at: str | None = None,
+        ref: str | None = None,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Ranked candidates + evidence (GET /entities/resolve). Never picks."""
+        params: dict[str, Any] = {"surface": surface}
+        if scope is not None:
+            params["scope"] = scope
+        if at is not None:
+            params["at"] = at
+        if ref is not None:
+            params["ref"] = ref
+        if session_id is not None:
+            params["session_id"] = session_id
+        return self._request("GET", "/entities/resolve", params=params)
+
+    def entities_unresolved(self) -> dict[str, Any]:
+        """The unresolved-link bucket (GET /entities/unresolved)."""
+        return self._request("GET", "/entities/unresolved")
+
+    def entities_backfill(self) -> dict[str, Any]:
+        """Re-score unresolved links against current aliases
+        (POST /entities/backfill)."""
+        return self._request("POST", "/entities/backfill")
+
     def estimate_index(
         self,
         folder_path: str,

{brainpalace_cli-26.7.2 → brainpalace_cli-26.7.4}/brainpalace_cli/commands/__init__.py

@@ -11,6 +11,7 @@ from .extraction import extraction_group
 from .folders import folders_group
 from .hook import hook_group
 from .index import index_command
+from .ingest import ingest_command
 from .init import init_command
 from .inject import inject_command
 from .install_agent import install_agent_command
@@ -23,8 +24,10 @@ from .plugin_detect import plugin_group
 from .query import query_command
 from .recall import recall_command
 from .records import records_group
+from .references import references_group
 from .remember import remember_command
 from .reset import reset_command
+from .rules import rules_group
 from .session_hooks import install_session_hooks_command
 from .sessions import session_path_command, submit_session_command
 from .start import start_command
@@ -47,6 +50,7 @@ __all__ = [
     "doctor_command",
     "folders_group",
     "index_command",
+    "ingest_command",
     "inject_command",
     "init_command",
     "install_agent_command",
@@ -61,9 +65,11 @@ __all__ = [
     "hook_group",
     "query_command",
     "records_group",
+    "references_group",
     "recall_command",
     "remember_command",
     "reset_command",
+    "rules_group",
     "session_path_command",
     "start_command",
     "submit_session_command",

brainpalace_cli-26.7.4/brainpalace_cli/commands/entities.py

@@ -0,0 +1,231 @@
+"""Identity commands (G5): person / alias / link over the engine's identity
+store. The engine stores and RANKS candidates; it never picks a winner — the
+consumer app decides (D7).
+
+``--json`` contract (mirrors ``ingest``): on success the result dict is printed;
+on failure a ``{"error": ...}`` object is printed with a non-zero exit and NO
+``results`` key."""
+
+import json as _json
+from collections.abc import Callable
+from typing import Any
+
+import click
+from rich.console import Console
+
+from ..client import (
+    ConnectionError,
+    DocServeClient,
+    ServerError,
+    exit_on_connection_error,
+)
+from ..config import get_server_url
+
+console = Console()
+
+
+def _emit(result: dict[str, Any], json_output: bool) -> None:
+    if json_output:
+        click.echo(_json.dumps(result, indent=2))
+    else:
+        console.print(result)
+
+
+def _run(
+    resolved_url: str,
+    json_output: bool,
+    fn: Callable[[DocServeClient], dict[str, Any]],
+) -> None:
+    """Execute ``fn(client)`` with the shared connection/error handling and
+    the ``--json`` failure contract."""
+    try:
+        with DocServeClient(base_url=resolved_url) as client:
+            result = fn(client)
+        _emit(result, json_output)
+    except ConnectionError as e:
+        exit_on_connection_error(e, base_url=resolved_url, json_output=json_output)
+    except ServerError as e:
+        if json_output:
+            click.echo(_json.dumps({"error": str(e), "detail": e.detail}))
+        else:
+            console.print(f"[red]Server Error ({e.status_code}):[/] {e.detail}")
+        raise SystemExit(1) from e
+
+
+_URL = click.option(
+    "--url",
+    envvar="BRAINPALACE_URL",
+    default=None,
+    help="BrainPalace server URL (default: from config or http://127.0.0.1:8000)",
+)
+_JSON = click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+
+
+@click.group("entities")
+def entities_group() -> None:
+    """Manage identity: person / alias / link (who someone is)."""
+
+
+@entities_group.command("person")
+@click.option("--id", "person_id", default=None, help="Existing person id (upsert).")
+@click.option("--name", default=None, help="Display name (omit for an unknown person).")
+@click.option("--kind", default="person", show_default=True, help="person|place|org.")
+@click.option("--domain", required=True, help="Domain the person belongs to.")
+@click.option("--sensitivity", default="normal", show_default=True)
+@_URL
+@_JSON
+def person_cmd(
+    person_id: str | None,
+    name: str | None,
+    kind: str,
+    domain: str,
+    sensitivity: str,
+    url: str | None,
+    json_output: bool,
+) -> None:
+    """Upsert a person (naming an unknown one is an update in place)."""
+    resolved_url = url or get_server_url()
+    body = {"kind": kind, "domain": domain, "sensitivity": sensitivity}
+    if person_id:
+        body["id"] = person_id
+    if name is not None:
+        body["name"] = name
+    _run(resolved_url, json_output, lambda c: c.entities_person(body))
+
+
+@entities_group.command("alias")
+@click.option("--surface", required=True, help='Surface string, e.g. "Mama".')
+@click.option(
+    "--person-id", "person_id", required=True, help="Person the surface names."
+)
+@click.option("--scope", default=None, help="Speaker person id; omit for global.")
+@click.option("--valid-from", "valid_from", default=None)
+@click.option("--valid-to", "valid_to", default=None)
+@_URL
+@_JSON
+def alias_cmd(
+    surface: str,
+    person_id: str,
+    scope: str | None,
+    valid_from: str | None,
+    valid_to: str | None,
+    url: str | None,
+    json_output: bool,
+) -> None:
+    """Bind a surface to a person (scoped + time-bounded)."""
+    resolved_url = url or get_server_url()
+    body = {"surface": surface, "person_id": person_id}
+    if scope is not None:
+        body["scope"] = scope
+    if valid_from is not None:
+        body["valid_from"] = valid_from
+    if valid_to is not None:
+        body["valid_to"] = valid_to
+    _run(resolved_url, json_output, lambda c: c.entities_alias(body))
+
+
+@entities_group.command("link")
+@click.option(
+    "--ref", required=True, help="chunk address, session id, or external key."
+)
+@click.option(
+    "--ref-kind", "ref_kind", required=True, help="chunk|span|session|external."
+)
+@click.option("--role", required=True, help="speaker|mentioned|participant.")
+@click.option(
+    "--method", required=True, help="user_asserted|call_log|llm_inferred|alias_match."
+)
+@click.option("--at", required=True, help="Mention timestamp (ISO-8601).")
+@click.option(
+    "--person-id", "person_id", default=None, help="Resolved person; omit = unresolved."
+)
+@click.option("--span-start", "span_start", type=int, default=None)
+@click.option("--span-end", "span_end", type=int, default=None)
+@click.option("--surface", default=None, help="Surface being resolved (for backfill).")
+@click.option("--scope", default=None, help="Scope of that surface (for backfill).")
+@click.option("--confidence", type=float, default=None)
+@_URL
+@_JSON
+def link_cmd(
+    ref: str,
+    ref_kind: str,
+    role: str,
+    method: str,
+    at: str,
+    person_id: str | None,
+    span_start: int | None,
+    span_end: int | None,
+    surface: str | None,
+    scope: str | None,
+    confidence: float | None,
+    url: str | None,
+    json_output: bool,
+) -> None:
+    """Attach a ref to a person, or record it unresolved."""
+    resolved_url = url or get_server_url()
+    body: dict[str, Any] = {
+        "ref": ref,
+        "ref_kind": ref_kind,
+        "role": role,
+        "method": method,
+        "at": at,
+    }
+    if person_id is not None:
+        body["person_id"] = person_id
+    if span_start is not None:
+        body["span_start"] = span_start
+    if span_end is not None:
+        body["span_end"] = span_end
+    if surface is not None:
+        body["surface"] = surface
+    if scope is not None:
+        body["scope"] = scope
+    if confidence is not None:
+        body["confidence"] = confidence
+    _run(resolved_url, json_output, lambda c: c.entities_link(body))
+
+
+@entities_group.command("resolve")
+@click.option("--surface", required=True, help="Surface string to resolve.")
+@click.option("--scope", default=None, help="Speaker person id; omit for global.")
+@click.option("--at", default=None, help="Resolution timestamp (defaults to now).")
+@click.option("--ref", default=None, help="Chunk/session ref for co-occurrence.")
+@click.option("--session-id", "session_id", default=None, help="Session for recency.")
+@_URL
+@_JSON
+def resolve_cmd(
+    surface: str,
+    scope: str | None,
+    at: str | None,
+    ref: str | None,
+    session_id: str | None,
+    url: str | None,
+    json_output: bool,
+) -> None:
+    """Ranked candidates + evidence. Never picks a winner."""
+    resolved_url = url or get_server_url()
+    _run(
+        resolved_url,
+        json_output,
+        lambda c: c.entities_resolve(
+            surface=surface, scope=scope, at=at, ref=ref, session_id=session_id
+        ),
+    )
+
+
+@entities_group.command("unresolved")
+@_URL
+@_JSON
+def unresolved_cmd(url: str | None, json_output: bool) -> None:
+    """List unresolved links (the bucket the app must decide or ask about)."""
+    resolved_url = url or get_server_url()
+    _run(resolved_url, json_output, lambda c: c.entities_unresolved())
+
+
+@entities_group.command("backfill")
+@_URL
+@_JSON
+def backfill_cmd(url: str | None, json_output: bool) -> None:
+    """Re-score unresolved links against the current aliases."""
+    resolved_url = url or get_server_url()
+    _run(resolved_url, json_output, lambda c: c.entities_backfill())