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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.8.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
@@ -50,14 +50,15 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
 | `ndi split SOURCE --class id:label` | Logical sections |
 | `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
-| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (standalone quotes only; after search, poll `grounding_job_ids`) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
-| `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
+| `ndi files upload\|list\|get\|delete` | Workspace files (a directory walks nested files; `--ingest` then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
-| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
+| `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, `--effort` for the level) |
+| `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
@@ -74,8 +75,19 @@ 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
+directory name) and uploads in parallel (`-j`, default 8). Unsupported
+files (and `.DS_Store`) are skipped; a warning on stderr lists them when
+the run finishes. `--ingest` then queues ingestion in batches of 1000
+file ids. A single file still requires `--path`.
+
 ## Output
 
 Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
@@ -94,6 +106,11 @@ URLs automatically.
 API failures exit 1. Usage / config errors exit 2. Schema-validation
 failures also show up to five field constraints, each limited to 500
 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.8.0 → ndi_cli-0.10.0}/README.md

@@ -26,14 +26,15 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
 | `ndi split SOURCE --class id:label` | Logical sections |
 | `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
-| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (standalone quotes only; after search, poll `grounding_job_ids`) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
-| `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
+| `ndi files upload\|list\|get\|delete` | Workspace files (a directory walks nested files; `--ingest` then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
-| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
+| `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, `--effort` for the level) |
+| `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
@@ -50,8 +51,19 @@ 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
+directory name) and uploads in parallel (`-j`, default 8). Unsupported
+files (and `.DS_Store`) are skipped; a warning on stderr lists them when
+the run finishes. `--ingest` then queues ingestion in batches of 1000
+file ids. A single file still requires `--path`.
+
 ## Output
 
 Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
@@ -70,6 +82,11 @@ URLs automatically.
 API failures exit 1. Usage / config errors exit 2. Schema-validation
 failures also show up to five field constraints, each limited to 500
 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.8.0 → ndi_cli-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.8.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.8.0 → ndi_cli-0.10.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.8.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.8.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.8.0"
+__version__ = "0.10.0"

{ndi_cli-0.8.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.8.0 → ndi_cli-0.10.0}/src/ndi_cli/_jobs.py

@@ -36,18 +36,17 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     cancel.set_defaults(run=_run_cancel, family="job", needs_workspace=False, needs_client=True)
 
 
-def wait_and_report(
+def wait_job(
     client: NdiClient,
     job: Job,
     args: argparse.Namespace,
     *,
-    auto: Callable[[Job], str],
-    stem: str,
-) -> int:
+    print_timeout_id: bool = True,
+) -> tuple[Job | None, int]:
+    """Wait for ``job``; status lines go to stderr. Does not render the result."""
     print(f"job {job.job_id} {job.status}", file=sys.stderr)
     if getattr(args, "async_submit", False):
-        print(job.job_id)
-        return 0
+        return job, 0
     try:
         if job.is_terminal:
             check_terminal(job, raise_on_failure=True)
@@ -56,12 +55,30 @@ def wait_and_report(
     except JobFailedError as exc:
         code = f" [{exc.job.error.code}]" if exc.job.error and exc.job.error.code else ""
         print(f"error:{code} {exc}", file=sys.stderr)
-        return 1
+        return exc.job, 1
     except JobTimeoutError as exc:
         print(f"error: {exc}", file=sys.stderr)
-        print(exc.job.job_id)
-        return 1
+        if print_timeout_id:
+            print(exc.job.job_id)
+        return exc.job, 1
     print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    return job, 0
+
+
+def wait_and_report(
+    client: NdiClient,
+    job: Job,
+    args: argparse.Namespace,
+    *,
+    auto: Callable[[Job], str],
+    stem: str,
+) -> int:
+    job, code = wait_job(client, job, args)
+    if code != 0 or job is None:
+        return code or 1
+    if getattr(args, "async_submit", False):
+        print(job.job_id)
+        return 0
     return render_job(job, args, auto=auto, stem=stem)
 
 

{ndi_cli-0.8.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)