ndi-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.9.0
+Version: 0.10.0
 Summary: NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools
 Keywords: ndi,cli,document-intelligence,coding-agents
 Author: Nace AI
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: ndi-sdk>=0.22,<1
+Requires-Dist: ndi-sdk>=0.25,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://ndi-api.nace.ai
@@ -58,6 +58,7 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search; then `ndi job` on each printed `grounding_job_ids` entry |
 | `ndi filtered-search QUERY` | Corpus filter/rank/count over the metadata catalog (`--cursor` pages an earlier run) |
 | `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--reasoning-effort` for the thinking budget) |
+| `ndi ledger-understanding start\|get\|sources\|select\|selection` | Measure the ledger package, confirm sources, or read the latest report |
 | `ndi folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
 ## Sources
@@ -75,6 +76,10 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 ```bash
 ndi parse a.pdf -o id | ndi extract - -s schema.json
 ndi files upload ./corpus --ingest
+ndi ledger-understanding start          # --force to re-scan; --selection-id after confirm
+ndi ledger-understanding get
+ndi ledger-understanding sources --review-reading-id READING
+ndi ledger-understanding select --primary SRC --supporting SRC --revision REV
 ```
 
 `ndi files upload DIR` keeps relative paths under `--path` (default: the
@@ -104,6 +109,8 @@ characters; request input and unrelated error-detail fields are omitted.
 Unsupported inputs print `error: 422 [unsupported_file_type] ...` to stderr and
 exit 1. `ndi upload` prints no handle, document operations print no job ID, and
 `ndi files upload --ingest` creates no workspace file or ingestion job.
+The server checks a bounded byte prefix, rejects conclusive filename/content
+conflicts, and treats the multipart `Content-Type` as advisory.
 
 See the [CLI guide](https://docs.ndi.nace.ai/guides/cli) for the full command
 reference. `SKILL.md` is the agent-facing guide to the six workspace tools.

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/README.md

@@ -34,6 +34,7 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search; then `ndi job` on each printed `grounding_job_ids` entry |
 | `ndi filtered-search QUERY` | Corpus filter/rank/count over the metadata catalog (`--cursor` pages an earlier run) |
 | `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--reasoning-effort` for the thinking budget) |
+| `ndi ledger-understanding start\|get\|sources\|select\|selection` | Measure the ledger package, confirm sources, or read the latest report |
 | `ndi folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
 ## Sources
@@ -51,6 +52,10 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 ```bash
 ndi parse a.pdf -o id | ndi extract - -s schema.json
 ndi files upload ./corpus --ingest
+ndi ledger-understanding start          # --force to re-scan; --selection-id after confirm
+ndi ledger-understanding get
+ndi ledger-understanding sources --review-reading-id READING
+ndi ledger-understanding select --primary SRC --supporting SRC --revision REV
 ```
 
 `ndi files upload DIR` keeps relative paths under `--path` (default: the
@@ -80,6 +85,8 @@ characters; request input and unrelated error-detail fields are omitted.
 Unsupported inputs print `error: 422 [unsupported_file_type] ...` to stderr and
 exit 1. `ndi upload` prints no handle, document operations print no job ID, and
 `ndi files upload --ingest` creates no workspace file or ingestion job.
+The server checks a bounded byte prefix, rejects conclusive filename/content
+conflicts, and treats the multipart `Content-Type` as advisory.
 
 See the [CLI guide](https://docs.ndi.nace.ai/guides/cli) for the full command
 reference. `SKILL.md` is the agent-facing guide to the six workspace tools.

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.9.0"
+version = "0.10.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "ndi-sdk>=0.22,<1",
+    "ndi-sdk>=0.25,<1",
     "truststore>=0.10.4,<1",
 ]
 

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.9.0"
+version = "0.10.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 authors = [
     { name = "Nace AI", email = "engineering@nace.ai" }
@@ -27,7 +27,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "ndi-sdk>=0.22,<1",
+    "ndi-sdk>=0.25,<1",
     "truststore>=0.10.4,<1",
 ]
 

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/__init__.py

@@ -6,4 +6,4 @@ methods. The six workspace tools (``folder-metadata``, ``file-metadata``,
 in-sandbox surface.
 """
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/_cli.py

@@ -16,7 +16,7 @@ from ndi_sdk.resources.tools import SyncTools
 
 from ndi_cli import _docops, _jobs, _login, _tools, _workspace
 from ndi_cli._config import ConfigError, resolve_settings
-from ndi_cli._local import SOCKET_ENV, TOKEN_ENV, LocalTransport
+from ndi_cli._local import KG_ENV, SOCKET_ENV, TOKEN_ENV, LocalTransport
 from ndi_cli._tools import parse_pages
 
 # qa-file runs a durable workflow that legitimately takes minutes; the metadata,
@@ -27,16 +27,18 @@ _VALIDATION_ERROR_CHARS = 500
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = _build_parser()
+    socket_path = os.environ.get(SOCKET_ENV)
+    # Presence, not truthiness: an empty $NDI_CLI_SOCKET still means "inside an
+    # agent run", and must not silently unlock the full platform CLI.
+    in_agent_run = socket_path is not None
+    # An agent run gets the graph commands only when the worker granted them; a
+    # run whose guide never mentions kg-* must not find them in --help either.
+    parser = _build_parser(graph=not in_agent_run or bool(os.environ.get(KG_ENV)))
     args = parser.parse_args(argv)
     if args.command is None:
         parser.print_help()
         return 2
     family = getattr(args, "family", None)
-    socket_path = os.environ.get(SOCKET_ENV)
-    # Presence, not truthiness: an empty $NDI_CLI_SOCKET still means "inside an
-    # agent run", and must not silently unlock the full platform CLI.
-    in_agent_run = socket_path is not None
     workspace_flag = getattr(args, "workspace", None)
     if workspace_flag is not None and not workspace_flag.strip():
         print("error: --workspace needs a workspace id", file=sys.stderr)
@@ -130,7 +132,7 @@ def _validation_error_lines(detail: object) -> list[str]:
     return lines
 
 
-def _build_parser() -> argparse.ArgumentParser:
+def _build_parser(*, graph: bool = True) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="ndi",
         description=(
@@ -151,7 +153,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     sub = parser.add_subparsers(dest="command")
     _login.add_parsers(sub)
-    _tools.add_parsers(sub, common)
+    _tools.add_parsers(sub, common, graph=graph)
     _docops.add_parsers(sub, common)
     _jobs.add_parsers(sub, common)
     _workspace.add_parsers(sub, common)

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/_local.py

@@ -17,6 +17,8 @@ from ndi_sdk.errors import ErrorBody, NdiConnectionError, NdiTimeoutError, error
 from ndi_sdk.models.tools import (
     FileMetadataRequest,
     FolderMetadataRequest,
+    KgSearchRequest,
+    KgWalkRequest,
     QaFileRequest,
     ReadFileRequest,
     RunSqlRequest,
@@ -28,6 +30,9 @@ from ndi_cli.commands import WorkspaceCommand
 
 SOCKET_ENV = "NDI_CLI_SOCKET"
 TOKEN_ENV = "NDI_CLI_TOKEN"
+#: Set (to any non-empty value) by the worker for an agent run that has the graph
+#: surface; inside an agent run the ``kg-*`` commands are registered only when it is.
+KG_ENV = "NDI_CLI_KG"
 MAX_MESSAGE_BYTES = 16 * 1024 * 1024
 ModelT = TypeVar("ModelT", bound=BaseModel)
 
@@ -62,12 +67,102 @@ class SearchCommand(BaseModel):
     body: SearchRequest
 
 
+class KgInfoRequest(BaseModel):
+    """``kg-info``'s scope as a socket body.
+
+    Defined here rather than imported from ``ndi_sdk.models.tools`` like its
+    siblings: on the wire ``kg-info`` is a GET carrying query parameters, so it has
+    no request model to reuse. Only the scope crosses — the drawable sample is for
+    a client that renders a graph, and ``_kg_info_command`` refuses it.
+    """
+
+    path_prefix: str | None = None
+    hub_node_type: str | None = None
+
+
+class KgInfoCommand(BaseModel):
+    command: Literal[WorkspaceCommand.KG_INFO] = WorkspaceCommand.KG_INFO
+    body: KgInfoRequest
+
+
+class KgSearchCommand(BaseModel):
+    command: Literal[WorkspaceCommand.KG_SEARCH] = WorkspaceCommand.KG_SEARCH
+    body: KgSearchRequest
+
+
+class KgWalkCommand(BaseModel):
+    command: Literal[WorkspaceCommand.KG_WALK] = WorkspaceCommand.KG_WALK
+    body: KgWalkRequest
+
+
+class KgAnswerRequest(BaseModel):
+    """``kg-answer``'s question as a socket body.
+
+    The agent passes its verbatim question; the server runs the graph pass and
+    returns the rendered outcome (answered text + citations, or evidence + gap).
+    """
+
+    query: str
+
+
+class KgAnswerResponse(BaseModel):
+    """The rendered outcome of one graph pass, ready to print or inject as a tool result."""
+
+    text: str
+
+
+class KgAnswerCommand(BaseModel):
+    command: Literal[WorkspaceCommand.KG_ANSWER] = WorkspaceCommand.KG_ANSWER
+    body: KgAnswerRequest
+
+
 Command = Annotated[
-    FolderCommand | FileCommand | ReadCommand | AskCommand | SqlCommand | SearchCommand, Field(discriminator="command")
+    FolderCommand
+    | FileCommand
+    | ReadCommand
+    | AskCommand
+    | SqlCommand
+    | SearchCommand
+    | KgInfoCommand
+    | KgSearchCommand
+    | KgWalkCommand
+    | KgAnswerCommand,
+    Field(discriminator="command"),
 ]
 COMMAND = TypeAdapter(Command)
 
 
+def _kg_info_command(params: object) -> Command:
+    """Build the ``kg-info`` command from the SDK method's query parameters.
+
+    Refuses ``include_graph`` instead of dropping it: the sample is the whole point
+    of that flag, and answering without one would read as a graph with no structure.
+    """
+    if not isinstance(params, dict):
+        raise ValueError("The internal CLI accepts workspace commands only.")
+    if params.get("include_graph"):
+        raise ValueError("The internal CLI does not serve kg-info's drawable graph sample.")
+    prefix = params.get("path_prefix")
+    if prefix is not None and not isinstance(prefix, str):
+        raise ValueError("kg-info's path_prefix must be a string.")
+    hub_node_type = params.get("hub_node_type")
+    if hub_node_type is not None and not isinstance(hub_node_type, str):
+        raise ValueError("kg-info's hub_node_type must be a string.")
+    return KgInfoCommand(body=KgInfoRequest(path_prefix=prefix, hub_node_type=hub_node_type))
+
+
+def _command(method: str, path: str, kwargs: dict[str, object]) -> Command:
+    """One socket command per SDK call, named by the endpoint the method addresses."""
+    name = path.rsplit("/", 1)[-1]
+    if method == "GET" and name == WorkspaceCommand.KG_INFO:
+        return _kg_info_command(kwargs.get("params"))
+    body = kwargs.get("body")
+    if method != "POST" or not isinstance(body, BaseModel):
+        raise ValueError("The internal CLI accepts workspace commands only.")
+    command = WorkspaceCommand.ASK_FILE if name == "qa-file" else WorkspaceCommand(name)
+    return COMMAND.validate_python({"command": command, "body": body.model_dump(exclude_none=True)})
+
+
 class CommandEnvelope(BaseModel):
     """One request line on the socket: the owning run's token plus its command."""
 
@@ -98,15 +193,7 @@ class LocalTransport:
         self.token = token
 
     def request_model(self, model: type[ModelT], method: str, path: str, **kwargs: object) -> ModelT:
-        body = kwargs.get("body")
-        if method != "POST" or not isinstance(body, BaseModel):
-            raise ValueError("The internal CLI accepts workspace commands only.")
-        name = path.rsplit("/", 1)[-1]
-        command = WorkspaceCommand.ASK_FILE if name == "qa-file" else WorkspaceCommand(name)
-        request = CommandEnvelope(
-            token=self.token,
-            command=COMMAND.validate_python({"command": command, "body": body.model_dump(exclude_none=True)}),
-        )
+        request = CommandEnvelope(token=self.token, command=_command(method, path, kwargs))
         try:
             with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
                 connection.settimeout(self.timeout)

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/_render.py

@@ -14,6 +14,7 @@ import uuid
 
 import html
 import re
+from typing import Literal
 
 from ndi_sdk.models.common import Coverage, Evidence, File
 from ndi_sdk.models.document_ops import ExtractSchemaValidationResponse
@@ -28,13 +29,26 @@ from ndi_sdk.models.jobs import (
     IntelligentSearchResult,
     JetResult,
     Job,
+    LedgerUnderstandingResult,
     ParseResult,
     SplitResult,
 )
+from ndi_sdk.models.ledger_understanding import (
+    LedgerUnderstandingReport,
+    SelectionDetails,
+    SelectionSummary,
+    SourceCatalog,
+)
 from ndi_sdk.models.workspaces import Workspace, WorkspaceStats
 from ndi_sdk.models.tools import (
     FileMetadataToolResponse,
     FolderMetadataResponse,
+    GraphEdge,
+    GraphFact,
+    GraphNode,
+    KgInfo,
+    KgSearchResponse,
+    KgWalkResponse,
     QaFileResponse,
     ReadFileResponse,
     RunSqlResponse,
@@ -477,6 +491,214 @@ def run_sql(response: RunSqlResponse) -> str:
     return "\n".join(lines)
 
 
+#: Source paths listed per entity in "sample" mode before the rest become a
+#: count. A corpus hub is cited by hundreds of files, which would bury the
+#: structure the caller asked for; the count stays exact and read-file still
+#: takes any path.
+FILE_SAMPLE = 5
+
+#: Matched facts printed per entity by kg-search. The server returns every fact
+#: the query hit on the node; the first few are the best-ranked and are what says
+#: WHY the entity matched — the rest, and the entity's own stated facts, are one
+#: kg-node away.
+FACT_SAMPLE = 5
+
+#: How much provenance a node row carries: none (kg-export, structure only),
+#: a sample (kg-search, a foothold) or every file (kg-node, the detail lookup
+#: that answers "which documents carry this entity").
+FilesMode = Literal["none", "sample", "all"]
+
+
+def _fact_row(fact: GraphFact) -> dict[str, object]:
+    row: dict[str, object] = {"predicate": fact.predicate, "value": fact.value, "source_file": fact.evidence.path}
+    if fact.evidence.page is not None:
+        row["page"] = fact.evidence.page
+    return row
+
+
+def _node_row(node: GraphNode, *, files: FilesMode) -> dict[str, object]:
+    row: dict[str, object] = {
+        "node_id": node.node_id,
+        "node_type": node.node_type,
+        "title": node.title,
+        "degree": node.degree,
+        "neighbor_count": node.neighbor_count,
+        "source_file_count": len(node.source_files),
+    }
+    if node.aliases:
+        row["aliases"] = list(node.aliases)
+    if len(node.stated_types) > 1:
+        row["stated_types"] = [{"node_type": role.node_type, "mention_count": role.mention_count} for role in node.stated_types]
+    match files:
+        case "sample":
+            row["source_files"] = [ref.path for ref in node.source_files[:FILE_SAMPLE]]
+        case "all":
+            row["source_files"] = [ref.path for ref in node.source_files]
+    return row
+
+
+def kg_info(response: KgInfo) -> str:
+    """The graph's shape and its entry points — the orient step before any kg-search.
+
+    Answers what a query cannot: whether the kind of thing being looked for is in
+    this graph at all, and which entities to seed from.
+    """
+    payload: dict[str, object] = {
+        "counts": {"nodes": response.node_total, "edges": response.edge_total},
+        "node_types": [{"type": item.type, "count": item.count} for item in response.node_types],
+        "edge_types": [{"type": item.type, "count": item.count} for item in response.edge_types],
+        "hubs": [
+            {
+                "node_id": hub.node_id,
+                "node_type": hub.node_type,
+                "title": hub.title,
+                "degree": hub.degree,
+                "neighbor_count": hub.neighbor_count,
+            }
+            for hub in response.hubs
+        ],
+    }
+    if response.path_prefix:
+        payload["path_prefix"] = response.path_prefix
+    payload["note"] = (
+        "node_types names every kind of entity this graph holds — a term matching none of them has nothing to find. "
+        "hubs are the entities connected to the most distinct things (neighbor_count; degree counts relation records, "
+        "one per file restating a relation) and valid kg-export seeds: a seed's own neighbours are always "
+        "returned, but hubs met further out are not walked through, so narrow a large neighbourhood with "
+        "--node-type / --edge-type rather than reading it whole."
+    )
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def kg_entities(response: KgSearchResponse) -> str:
+    """Entities with a few files to open next — kg-search's foothold.
+
+    JSON, not prose: the caller is a `python3 -c` on the other side of a pipe.
+    """
+    nodes: list[dict[str, object]] = []
+    for node in response.nodes:
+        row = _node_row(node, files="sample")
+        # The facts that matched the query, best first — why the entity is here.
+        row["facts"] = [_fact_row(fact) for fact in node.facts[:FACT_SAMPLE]]
+        if len(node.facts) > FACT_SAMPLE:
+            row["more_facts"] = len(node.facts) - FACT_SAMPLE
+        nodes.append(row)
+    payload: dict[str, object] = {"nodes": nodes}
+    if not response.nodes:
+        # A bare empty list says nothing about WHY, so a miss reads as a near miss
+        # worth one more try — which is how a run ends up walking an identifier
+        # space a guess at a time instead of asking what the graph contains.
+        payload["note"] = (
+            "No entities matched. Run `ndi kg-info` for the node types and hub entities this graph actually holds, "
+            "and search a term from that list — guessing or incrementing identifiers will not find one."
+        )
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def kg_node_detail(response: KgWalkResponse) -> str:
+    """Everything the graph holds on the chosen entities — kg-node's answer.
+
+    Per requested entity: the facts its documents state, its relations with the
+    other end named and the wording each was read from, and every file that
+    carries it. The export counts provenance and search samples it; this is the
+    one place the full list is printed, because "which documents mention X" is
+    closed here or not at all. The requested entities are the walk's seeds — the
+    nodes no path lands on; the rest of the response is the one-hop ring the
+    runner fetched so the relations can name their other end.
+    """
+    by_id = {node.node_id: node for node in response.nodes}
+    reached = {path.node_ids[-1] for path in response.paths}
+    incident: dict[str, list[GraphEdge]] = {}
+    for edge in response.edges:
+        for end in (edge.from_node_id, edge.to_node_id):
+            incident.setdefault(end, []).append(edge)
+    nodes: list[dict[str, object]] = []
+    for node in response.nodes:
+        if node.node_id in reached:
+            continue
+        row = _node_row(node, files="all")
+        row["facts"] = [_fact_row(fact) for fact in node.facts]
+        # One row per relation, not per record: a relation restated in another
+        # file is another edge, and a hub restates each of its hundreds of times.
+        # The first record's wording and file stand for it; ``records`` says how
+        # many files state it.
+        relations: dict[tuple[str, str, str], dict[str, object]] = {}
+        for edge in incident.get(node.node_id, []):
+            direction = "out" if edge.from_node_id == node.node_id else "in"
+            other_id = edge.to_node_id if direction == "out" else edge.from_node_id
+            key = (edge.edge_type, direction, other_id)
+            relation = relations.get(key)
+            if relation is not None:
+                relation["records"] = int(relation.get("records", 1)) + 1
+                continue
+            relation = {"edge_type": edge.edge_type, "direction": direction, "node_id": other_id}
+            other = by_id.get(other_id)
+            if other is not None:
+                relation["node_type"] = other.node_type
+                relation["title"] = other.title
+            if edge.evidence is not None:
+                relation["statement"] = edge.evidence.snippet
+                relation["source_file"] = edge.evidence.path
+                if edge.evidence.page is not None:
+                    relation["page"] = edge.evidence.page
+            relations[key] = relation
+        row["relations"] = list(relations.values())
+        # neighbor_count is the distinct entities connected; fewer other ends here
+        # means the ring cap (or the walk's own) cut the rest.
+        if len({other_id for _, _, other_id in relations}) < node.neighbor_count:
+            row["relations_truncated"] = True
+        nodes.append(row)
+    payload: dict[str, object] = {"nodes": nodes}
+    if any(row.get("relations_truncated") for row in nodes):
+        payload["note"] = (
+            "relations_truncated: the entity connects to more than is shown; `kg-export --seed NODE_ID` prints "
+            "the whole ring, narrowed with --node-type / --edge-type."
+        )
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def kg_export(response: KgWalkResponse) -> str:
+    """The whole neighbourhood as structure, with the prose left behind.
+
+    Sized to survive a pipe, not to be read: facts and relation wording would
+    multiply the payload by the number of edges and are what ``kg-node`` prints
+    per entity once the caller's own code has picked its few. Edge ids stay out
+    too — no command takes one, and each cost as much as a node id.
+    """
+    edges: list[dict[str, object]] = []
+    for edge in response.edges:
+        row: dict[str, object] = {
+            "src": edge.from_node_id,
+            "dst": edge.to_node_id,
+            "edge_type": edge.edge_type,
+        }
+        if edge.evidence is not None:
+            row["source_file"] = edge.evidence.path
+            if edge.evidence.page is not None:
+                row["page"] = edge.evidence.page
+        edges.append(row)
+    nodes = [_node_row(node, files="none") for node in response.nodes]
+    payload: dict[str, object] = {
+        "counts": {"nodes": len(nodes), "edges": len(edges)},
+        "truncated": response.truncated,
+        "nodes": nodes,
+        "edges": edges,
+    }
+    # Every node but a seed arrives over an edge, so an edgeless node is a seed
+    # with no relation the caller can see (none at all, or none left after the
+    # type filters). Unsaid, that reads as a walk that silently failed.
+    touched = {end for edge in response.edges for end in (edge.from_node_id, edge.to_node_id)}
+    unexpanded = [node.node_id for node in response.nodes if node.node_id not in touched]
+    if unexpanded:
+        payload["unexpanded"] = unexpanded
+        payload["note"] = (
+            "These seeds have no visible relations: a seed's own neighbours are always returned, so either the "
+            "entity has none here or --node-type / --edge-type filtered them all. Read its facts and files with "
+            "kg-node, or seed from another entity found via kg-search."
+        )
+    return json.dumps(payload, ensure_ascii=False)
+
+
 def search(response: SearchResponse) -> str:
     if not response.hits:
         lines = ["no hits"]
@@ -721,6 +943,76 @@ def je_testing_job(job: Job) -> str:
     return "\n".join(lines)
 
 
+def ledger_understanding_report(report: LedgerUnderstandingReport) -> str:
+    """Tables, integrity, open questions, and parse counts — the report at a glance."""
+    flags = [name for name, on in (("stale", report.stale), ("blocking", report.blocking)) if on]
+    head = "ledger understanding"
+    if flags:
+        head += f" ({', '.join(flags)})"
+    lines = [head, f"tables ({len(report.tables)}):"]
+    for table in report.tables:
+        key = f"  key {', '.join(table.journal_key)}" if table.journal_key else ""
+        share = f"  balanced {table.key_balanced_share:.2f}" if table.key_balanced_share is not None else ""
+        lines.append(f"  {table.role} {table.table_name}  {table.rows} rows{key}{share}")
+    lines.append(f"integrity: {len(report.integrity.findings)} findings, {len(report.integrity.skipped)} skipped")
+    for finding in report.integrity.findings:
+        lines.append(f"  {finding.severity} {finding.check}: {finding.message}")
+    for skipped in report.integrity.skipped:
+        lines.append(f"  skipped {skipped.check}: {skipped.reason}")
+    lines.append(f"open questions ({len(report.open_questions)}):")
+    for question in report.open_questions:
+        lines.append(f"  {question.id}: {question.question}")
+    parsing = report.parsing
+    if parsing is None:
+        lines.append("parsing: none")
+    elif parsing.skipped_reason:
+        lines.append(f"parsing: skipped ({parsing.skipped_reason})")
+    else:
+        lines.append(
+            f"parsing: {parsing.journals_total} journals, {parsing.parsed} parsed, "
+            f"{parsing.identity} identity, {parsing.hub} hub, {parsing.unbalanced} unbalanced"
+        )
+    return "\n".join(lines)
+
+
+def ledger_understanding_job(job: Job) -> str:
+    result = job.result
+    if isinstance(result, LedgerUnderstandingResult):
+        return ledger_understanding_report(result.report)
+    return job_line(job)
+
+
+def ledger_source_catalog(catalog: SourceCatalog) -> str:
+    lines = [f"revision {catalog.revision}", f"sources ({len(catalog.sources)}):"]
+    for source in catalog.sources:
+        flags = []
+        if source.recommended_as_primary:
+            flags.append("recommended")
+        if source.review_eligible is False:
+            flags.append("ineligible")
+        flag = f"  {', '.join(flags)}" if flags else ""
+        lines.append(f"  {source.label}  {source.rows} rows  {source.file_count} files  {source.source_id}{flag}")
+    if catalog.warnings:
+        lines.append("warnings:")
+        lines.extend(f"  {warning}" for warning in catalog.warnings)
+    return "\n".join(lines)
+
+
+def ledger_selection(summary: SelectionSummary) -> str:
+    lines = [
+        f"selection {summary.selection_id}",
+        f"primary {summary.primary}",
+        f"supporting ({len(summary.supporting)}): {', '.join(summary.supporting) or 'none'}",
+        f"files {summary.file_count}",
+    ]
+    if isinstance(summary, SelectionDetails):
+        lines.append(f"package {summary.package}")
+        lines.append(f"primary_source_id {summary.primary_source_id}")
+    if summary.stale:
+        lines.append("stale")
+    return "\n".join(lines)
+
+
 #: What a cell's non-``found`` status means, glossed for a reader who has only
 #: this text. A field nothing could be read from is not an absent one, and
 #: neither is one that resisted normalizing — keeping them distinct is what

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/_tools.py

@@ -1,4 +1,4 @@
-"""The six workspace-tool verbs. Shared with the in-sandbox agent CLI."""
+"""The workspace-tool verbs: six file commands plus the graph commands. Shared with the in-sandbox agent CLI."""
 
 from __future__ import annotations
 
@@ -8,10 +8,27 @@ import sys
 from ndi_sdk.resources.tools import SyncTools
 
 from ndi_cli import _render
+from ndi_cli._local import KgAnswerRequest, KgAnswerResponse
 from ndi_cli.commands import WorkspaceCommand
 
+#: Breadth the export defaults to: the seed's own relations. The agent's shell
+#: caps what it can see of any one command, and across the kg-walk eval runs no
+#: export ever asked for a hop count while two in five came back cut at that
+#: cap — a real seed's outer rings are larger than the caller can read, piped or
+#: not. One ring fits for any non-hub seed; ``--hops`` reaches further on purpose.
+#: The node ceiling stays under the walk endpoint's own limit.
+DEFAULT_EXPORT_HOPS = 1
+DEFAULT_EXPORT_NODES = 500
 
-def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+#: Neighbours kg-node fetches alongside the requested entities so their relations
+#: print with the other end named. A record-like entity (invoice, PO, payment)
+#: has a handful; a hub has hundreds, and those are kg-export's job — the render
+#: says so when the cap cut them.
+NODE_DETAIL_NEIGHBORS = 25
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser, *, graph: bool = True) -> None:
+    """Register the tool verbs; ``graph=False`` leaves the ``kg-*`` commands out entirely."""
     folder = sub.add_parser(
         WorkspaceCommand.FOLDER_METADATA,
         parents=[common],
@@ -125,6 +142,108 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     search.add_argument("--path-prefix", default=None, help="Only files under this directory prefix.")
     search.add_argument("--category", action="append", default=None, dest="categories", help="Category filter; repeatable.")
     search.set_defaults(run=_run_search, render=_render.search, family="tool", needs_workspace=True, needs_client=True)
+    if not graph:
+        return
+
+    kg_info = sub.add_parser(
+        WorkspaceCommand.KG_INFO,
+        parents=[common],
+        help="Orient in the knowledge graph: what kinds of entities it holds, and the busiest ones.",
+        description=(
+            "The graph's first call, the way folder-metadata is the corpus's. Returns JSON: node_types and "
+            "edge_types with counts, totals, and the best-connected hubs as node_ids kg-export takes. Read the "
+            "types before searching — a term naming none of them has nothing to match."
+        ),
+    )
+    kg_info.add_argument("--path-prefix", default=None, help="Scope the counts to entities sourced from under this prefix.")
+    kg_info.add_argument(
+        "--node-type",
+        default=None,
+        dest="hub_node_type",
+        help="Rank the hubs within this node type only: the best-connected entities of that kind. Counts are unaffected.",
+    )
+    kg_info.set_defaults(run=_run_kg_info, render=_render.kg_info, family="tool", needs_workspace=True, needs_client=True)
+
+    kg_search = sub.add_parser(
+        WorkspaceCommand.KG_SEARCH,
+        parents=[common],
+        help="Find entities the knowledge graph resolved across the corpus.",
+        description=(
+            "One entity per thing, however many files mention it. Returns JSON: each entity with the facts that "
+            "matched the query and a sample of its files; its node_id is what kg-node and kg-export --seed take."
+        ),
+    )
+    kg_search.add_argument("query", help="A name, identifier, title, role, or relationship, in plain words.")
+    kg_search.add_argument("-k", type=int, default=10, help="Number of entities (default 10).")
+    kg_search.add_argument("--node-type", action="append", default=None, dest="node_types", help="Type filter; repeatable.")
+    kg_search.add_argument("--path-prefix", default=None, help="Only entities sourced from under this prefix.")
+    kg_search.set_defaults(run=_run_kg_search, render=_render.kg_entities, family="tool", needs_workspace=True, needs_client=True)
+
+    kg_export = sub.add_parser(
+        "kg-export",
+        parents=[common],
+        help="Print a seed's relations as JSON, for piping into python3.",
+        description=(
+            "The graph as data instead of one question at a time: the nodes and edges around your seeds, ids and "
+            "structure only. By default the seeds' own relations; --hops reaches the next rings, which grow fast — "
+            "narrow them with --node-type / --edge-type. Pipe it into python3 and do the loop, filter, aggregation "
+            "or walk yourself in one call. Quotes and explanations are deliberately absent — fetch them per entity "
+            "with kg-node."
+        ),
+    )
+    kg_export.add_argument("--seed", action="append", required=True, dest="seeds", metavar="NODE_ID", help="Seed; repeatable.")
+    kg_export.add_argument(
+        "--hops",
+        type=int,
+        default=DEFAULT_EXPORT_HOPS,
+        help=f"Relation steps out from the seeds (default {DEFAULT_EXPORT_HOPS}: their own relations).",
+    )
+    kg_export.add_argument(
+        "--max-nodes", type=int, default=DEFAULT_EXPORT_NODES, help=f"Node ceiling (default {DEFAULT_EXPORT_NODES})."
+    )
+    kg_export.add_argument(
+        "--node-type",
+        action="append",
+        default=None,
+        dest="node_types",
+        help="Return only entities of this type, plus the seeds and the path that reaches each one; repeatable.",
+    )
+    kg_export.add_argument(
+        "--edge-type", action="append", default=None, dest="edge_types", help="Follow only relations of this type; repeatable."
+    )
+    kg_export.set_defaults(run=_run_kg_export, render=_render.kg_export, family="tool", needs_workspace=True, needs_client=True)
+
+    kg_node = sub.add_parser(
+        "kg-node",
+        parents=[common],
+        help="Everything the graph holds on a few entities: stated facts, relations with their wording, every source file.",
+        description=(
+            "The detail half of kg-export: pass the handful of node_ids kg-search or your own code picked and get, "
+            "per entity, the facts its documents state (amounts, dates, identifiers, descriptions, each with the "
+            "file and page it was read from), its relations with the other end named and the sentence each was "
+            "read from, and EVERY source file naming it — 'what is X', 'what is X connected to' and 'which "
+            "documents mention X' are answered here. The graph is extraction output, not evidence: before citing "
+            "a fact, open the file it names with read-file or ask-file and quote the document."
+        ),
+    )
+    kg_node.add_argument("ids", nargs="+", metavar="NODE_ID", help="Entity node_ids from kg-search or kg-export.")
+    kg_node.set_defaults(run=_run_kg_node, render=_render.kg_node_detail, family="tool", needs_workspace=True, needs_client=True)
+
+    kg_answer = sub.add_parser(
+        WorkspaceCommand.KG_ANSWER,
+        parents=[common],
+        help="Answer a question from the workspace knowledge graph in one call.",
+        description=(
+            "Runs the full graph pass: locates the entities the question names, reads the pages they cite, "
+            "drafts an answer, and gates it against the passages. Two outcomes: "
+            "(1) answered — prints the answer and its citations; verify at most one, then call final_result; "
+            "(2) evidence + gap — the graph found entities and read their pages but could not settle the answer; "
+            "start from the pages it names rather than repeating the same reads. "
+            "Call this first with the question verbatim."
+        ),
+    )
+    kg_answer.add_argument("query", help="The question, verbatim.")
+    kg_answer.set_defaults(run=_run_kg_answer, render=_render_kg_answer, family="tool", needs_workspace=True, needs_client=True)
 
 
 def _run_folder_metadata(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
@@ -208,3 +327,53 @@ def _run_search(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
         path_prefix=args.path_prefix,
         categories=args.categories,
     )
+
+
+def _run_kg_info(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    # No include_graph: the drawable sample serves a client that renders a graph,
+    # and it is orders of magnitude larger than the counts a caller reads here.
+    return tools.kg_info(workspace_id, path_prefix=args.path_prefix, hub_node_type=args.hub_node_type)
+
+
+def _run_kg_search(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.kg_search(workspace_id, query=args.query, k=args.k, node_types=args.node_types, path_prefix=args.path_prefix)
+
+
+def _run_kg_export(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.kg_walk(
+        workspace_id,
+        start_node_ids=args.seeds,
+        hops=args.hops,
+        max_nodes=args.max_nodes,
+        node_types=args.node_types,
+        edge_types=args.edge_types,
+    )
+
+
+def _run_kg_node(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    # One hop, with room for the requested ids plus a ring of neighbours: the
+    # requested entities' facts ride on their own nodes, and their relations need
+    # the other end returned to be named. The requested ids come first, in the
+    # order asked; the renderer tells them apart from the ring by the walk's
+    # paths (a seed is reached by none).
+    response = tools.kg_walk(workspace_id, start_node_ids=args.ids, hops=1, max_nodes=len(args.ids) + NODE_DETAIL_NEIGHBORS)
+    found = {node.node_id: node for node in response.nodes}
+    requested = [found[id_] for id_ in args.ids if id_ in found]
+    ring = [node for node in response.nodes if node.node_id not in set(args.ids)]
+    return response.model_copy(update={"nodes": [*requested, *ring]})
+
+
+def _run_kg_answer(tools: SyncTools, workspace_id: str, args: argparse.Namespace) -> KgAnswerResponse:
+    # kg-answer has no public HTTP route; it routes exclusively through the
+    # in-agent socket (LocalTransport).  We send the command directly through
+    # the underlying transport so no SDK method needs to exist for this verb.
+    return tools._transport.request_model(  # type: ignore[attr-defined]
+        KgAnswerResponse,
+        "POST",
+        f"/v1/workspaces/{workspace_id}/tools/{WorkspaceCommand.KG_ANSWER}",
+        body=KgAnswerRequest(query=args.query),
+    )
+
+
+def _render_kg_answer(response: KgAnswerResponse) -> str:
+    return response.text

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/_workspace.py

@@ -143,6 +143,53 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     add_job_output_args(jet)
     jet.set_defaults(run=_run_je_testing, family="workspace", needs_workspace=True, needs_client=True)
 
+    ledger = sub.add_parser("ledger-understanding", help="Start or read a ledger-understanding report.")
+    lu = ledger.add_subparsers(dest="ledger_command", required=True)
+
+    lu_start = lu.add_parser("start", parents=[common], help="Start a ledger-understanding run.")
+    lu_start.add_argument("--force", action="store_true", help="Re-measure even when a report for this package exists.")
+    _add_ledger_scope_args(lu_start)
+    add_job_output_args(lu_start)
+    lu_start.set_defaults(run=_run_ledger_understanding_start, family="workspace", needs_workspace=True, needs_client=True)
+
+    lu_get = lu.add_parser("get", parents=[common], help="Read the latest ledger-understanding report.")
+    _add_ledger_scope_args(lu_get)
+    lu_get.set_defaults(run=_run_ledger_understanding_get, family="workspace", needs_workspace=True, needs_client=True)
+
+    lu_sources = lu.add_parser("sources", parents=[common], help="List reviewable ledger sources.")
+    _add_ledger_scope_args(lu_sources)
+    lu_sources.add_argument("--review-reading-id", default=None, help="Bind the catalog to this reading's review.")
+    lu_sources.set_defaults(run=_run_ledger_sources, family="workspace", needs_workspace=True, needs_client=True)
+
+    lu_select = lu.add_parser("select", parents=[common], help="Confirm a primary population and supporting sources.")
+    lu_select.add_argument(
+        "--primary", required=True, dest="primary_source_id", help="Catalog handle for the primary population."
+    )
+    lu_select.add_argument(
+        "--supporting",
+        action="append",
+        dest="supporting_source_ids",
+        default=None,
+        help="Supporting source handle; repeatable.",
+    )
+    lu_select.add_argument("--revision", required=True, dest="expected_catalog_revision", help="Catalog revision last listed.")
+    lu_select.add_argument("--review-reading-id", default=None, help="Reading that requested this source review.")
+    lu_select.add_argument("--review-prefix", default=None, dest="review_path_prefix")
+    lu_select.add_argument("--review-path", action="append", dest="review_paths", default=None)
+    lu_select.add_argument("--review-selection-id", default=None)
+    lu_select.add_argument("--previous-selection-id", default=None)
+    lu_select.add_argument(
+        "--confirm-unrecognized",
+        action="store_true",
+        dest="confirm_unrecognized_primary",
+        help="Confirm a primary that structural recognition did not recommend.",
+    )
+    lu_select.set_defaults(run=_run_ledger_select, family="workspace", needs_workspace=True, needs_client=True)
+
+    lu_selection = lu.add_parser("selection", parents=[common], help="Read a confirmed source selection.")
+    lu_selection.add_argument("selection_id")
+    lu_selection.set_defaults(run=_run_ledger_selection, family="workspace", needs_workspace=True, needs_client=True)
+
 
 def _workspace_id(args: argparse.Namespace, fallback: str) -> str:
     value = getattr(args, "workspace_id", None) or args.workspace or fallback
@@ -473,3 +520,68 @@ def _run_je_testing(client: NdiClient, workspace_id: str, args: argparse.Namespa
         paths=args.paths,
     )
     return _finish_job(client, job, args, _render.je_testing_job, "je-testing")
+
+
+def _add_ledger_scope_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--prefix", default=None, dest="path_prefix")
+    parser.add_argument("--path", action="append", dest="paths", default=None, help="Scope to this file; repeatable.")
+    parser.add_argument(
+        "--selection-id", default=None, help="Confirmed source selection; cannot be combined with path selectors."
+    )
+
+
+def _ledger_scope(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "path_prefix": getattr(args, "path_prefix", None),
+        "paths": getattr(args, "paths", None),
+        "selection_id": getattr(args, "selection_id", None),
+    }
+
+
+def _run_ledger_understanding_start(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.workspaces.start_ledger_understanding(workspace_id, force=args.force, **_ledger_scope(args))
+    return _finish_job(client, job, args, _render.ledger_understanding_job, "ledger-understanding")
+
+
+def _run_ledger_understanding_get(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    report = client.workspaces.get_ledger_understanding(workspace_id, **_ledger_scope(args))
+    return _dump_or_text(report, args, text=_render.ledger_understanding_report(report), stem="ledger-understanding")
+
+
+def _run_ledger_sources(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    catalog = client.workspaces.list_ledger_sources(
+        workspace_id,
+        review_reading_id=args.review_reading_id,
+        **_ledger_scope(args),
+    )
+    return _dump_or_text(catalog, args, text=_render.ledger_source_catalog(catalog), stem="ledger-sources")
+
+
+def _run_ledger_select(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    from ndi_sdk.models.ledger_understanding import LedgerPackageScope, SourceReviewReference
+
+    review = None
+    if args.review_reading_id:
+        review = SourceReviewReference(
+            reading_id=args.review_reading_id,
+            scope=LedgerPackageScope(
+                path_prefix=args.review_path_prefix,
+                paths=args.review_paths or [],
+                selection_id=args.review_selection_id,
+            ),
+        )
+    summary = client.workspaces.select_ledger_sources(
+        workspace_id,
+        primary_source_id=args.primary_source_id,
+        supporting_source_ids=args.supporting_source_ids,
+        expected_catalog_revision=args.expected_catalog_revision,
+        review=review,
+        previous_selection_id=args.previous_selection_id,
+        confirm_unrecognized_primary=args.confirm_unrecognized_primary,
+    )
+    return _dump_or_text(summary, args, text=_render.ledger_selection(summary), stem="ledger-selection")
+
+
+def _run_ledger_selection(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    details = client.workspaces.get_ledger_selection(workspace_id, args.selection_id)
+    return _dump_or_text(details, args, text=_render.ledger_selection(details), stem="ledger-selection")

{ndi_cli-0.9.0 → ndi_cli-0.10.0}/src/ndi_cli/commands.py

@@ -10,6 +10,10 @@ class WorkspaceCommand(StrEnum):
     ASK_FILE = "ask-file"
     RUN_SQL = "run-sql"
     HYBRID_SEARCH = "hybrid-search"
+    KG_INFO = "kg-info"
+    KG_SEARCH = "kg-search"
+    KG_WALK = "kg-walk"
+    KG_ANSWER = "kg-answer"
 
     @property
     def activity_label(self) -> str:
@@ -20,4 +24,8 @@ class WorkspaceCommand(StrEnum):
             self.ASK_FILE: "Asking about a file",
             self.RUN_SQL: "Querying tables with SQL",
             self.HYBRID_SEARCH: "Searching workspace files",
+            self.KG_INFO: "Sizing up the knowledge graph",
+            self.KG_SEARCH: "Searching the knowledge graph",
+            self.KG_WALK: "Following graph relations",
+            self.KG_ANSWER: "Answering from the knowledge graph",
         }[self]