ndi-cli 0.29.0__tar.gz → 0.30.0__tar.gz

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.29.0
+Version: 0.30.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.50,<1
+Requires-Dist: ndi-sdk>=0.51,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://ndi-api.nace.ai
@@ -47,11 +47,12 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi login` | Authorize and save the API key |
 | `ndi version` | CLI + SDK versions |
 | `ndi upload FILE` | Stage bytes; prints `ndi://upload/<id>` |
+| `ndi upload-delete UPLOAD_ID` | Delete an unused upload; used uploads require deleting their jobs first |
 | `ndi parse SOURCE` | Markdown / text / blocks |
 | `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 (standalone quotes only; after search, poll `grounding_job_ids`) |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (after search, poll any `grounding_job_ids`; when none are planned, use `ndi ground` explicitly) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
 | `ndi workspace global-context [--set TEXT\|--file PATH\|--clear]` | Show, replace, or remove (`--clear`) the background every query without `--context` runs with; `--no-context` on a query runs with none |
@@ -124,3 +125,5 @@ 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 reading a workspace with `ndi`.
+
+To select existing customer storage, run `ndi storage-connections list`, then `ndi workspace create "Customer workspace" --storage-connection CONNECTION_ID`. Customer storage is not generally available; disabled deployments return `not_implemented` for every connection operation (including `storage-connections list`) and for creating a workspace with a connection, retries included; enabled deployments with incomplete configuration return `storage_unavailable`. Set up connections and rotate credentials through the console or Python/TypeScript SDK. The CLI does not accept cloud secrets as command-line arguments.

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/README.md

@@ -23,11 +23,12 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi login` | Authorize and save the API key |
 | `ndi version` | CLI + SDK versions |
 | `ndi upload FILE` | Stage bytes; prints `ndi://upload/<id>` |
+| `ndi upload-delete UPLOAD_ID` | Delete an unused upload; used uploads require deleting their jobs first |
 | `ndi parse SOURCE` | Markdown / text / blocks |
 | `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 (standalone quotes only; after search, poll `grounding_job_ids`) |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (after search, poll any `grounding_job_ids`; when none are planned, use `ndi ground` explicitly) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
 | `ndi workspace global-context [--set TEXT\|--file PATH\|--clear]` | Show, replace, or remove (`--clear`) the background every query without `--context` runs with; `--no-context` on a query runs with none |
@@ -100,3 +101,5 @@ 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 reading a workspace with `ndi`.
+
+To select existing customer storage, run `ndi storage-connections list`, then `ndi workspace create "Customer workspace" --storage-connection CONNECTION_ID`. Customer storage is not generally available; disabled deployments return `not_implemented` for every connection operation (including `storage-connections list`) and for creating a workspace with a connection, retries included; enabled deployments with incomplete configuration return `storage_unavailable`. Set up connections and rotate credentials through the console or Python/TypeScript SDK. The CLI does not accept cloud secrets as command-line arguments.

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.29.0"
+version = "0.30.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.50,<1",
+    "ndi-sdk>=0.51,<1",
     "truststore>=0.10.4,<1",
 ]
 

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.29.0"
+version = "0.30.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.50,<1",
+    "ndi-sdk>=0.51,<1",
     "truststore>=0.10.4,<1",
 ]
 

ndi_cli-0.30.0/src/ndi_cli/__init__.py

@@ -0,0 +1,14 @@
+"""``ndi`` — the NDI platform CLI.
+
+Document operations, jobs, and workspace lifecycle wrap ``ndi-sdk`` ``/v1``
+methods. Inside an agent sandbox the workspace tools (``folder-metadata``,
+``file-metadata``, ``read-file``, ``ask-file``, ``run-sql``, ``hybrid-search``, ``grep``)
+are the whole surface; outside one only ``ask-file`` is.
+"""
+
+__version__ = "0.30.0"
+
+#: Set (even empty) only inside an agent run: every command then goes to the worker over this socket.
+SOCKET_ENV = "NDI_CLI_SOCKET"
+#: Set by the worker when the deployment enables ``ndi grep`` (``NDI_GREP``); without it the verb does not exist.
+GREP_ENV = "NDI_GREP"

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_cli.py

@@ -36,7 +36,15 @@ def main(argv: list[str] | None = None) -> int:
     # agent run", and must not silently unlock the full platform CLI.
     in_agent_run = socket_path is not None
     parser = _build_parser(in_agent_run=in_agent_run)
-    args = parser.parse_args(argv)
+    args, extras = parser.parse_known_args(_bind_regexp(sys.argv[1:] if argv is None else list(argv)))
+    # argparse leaves a positional that follows an option unparsed (`grep PATTERN -i PATH`); a command whose
+    # positionals end in a list takes such strays into it, as grep and rg take paths after their flags.
+    extra_into = getattr(args, "extra_positionals", None)
+    if extras and extra_into and not any(extra.startswith("-") for extra in extras):
+        setattr(args, extra_into, [*(getattr(args, extra_into) or []), *extras])
+        args.folded_positionals = extras
+    elif extras:
+        parser.error(f"unrecognized arguments: {' '.join(extras)}")
     if args.command is None:
         parser.print_help()
         return 2
@@ -98,6 +106,21 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
 
+def _bind_regexp(argv: list[str]) -> list[str]:
+    """``grep -e PATTERN``: the word after -e is the pattern even when it starts with "-" (that is what -e is for);
+    argparse would read ``-e -5%`` as two options."""
+    if "grep" not in argv:
+        return argv
+    bound: list[str] = []
+    words = iter(argv)
+    for word in words:
+        if word in ("-e", "--regexp") and (pattern := next(words, None)) is not None:
+            bound.append(f"--regexp={pattern}")
+        else:
+            bound.append(word)
+    return bound
+
+
 def _run_tool(args: argparse.Namespace, tools: SyncTools, workspace_id: str, printer) -> int:
     """Run a tool once per positional target (``file-metadata a b``), each printed as its own call would print it.
 
@@ -106,6 +129,10 @@ def _run_tool(args: argparse.Namespace, tools: SyncTools, workspace_id: str, pri
     the caller that path's error line, not every other path's answer.
     """
     targets = getattr(args, "targets", [None])
+    names = getattr(args, "name_contains", None)
+    if isinstance(names, list) and len(names) > 1:  # folder-metadata --name-contains A --name-contains B
+        targets = [(target, name) for target in targets for name in names]
+        args.label_targets = True
     if len(targets) == 1:
         args.target = targets[0]
         return printer(args, args.run(tools, workspace_id, args))
@@ -125,7 +152,8 @@ def _run_tool(args: argparse.Namespace, tools: SyncTools, workspace_id: str, pri
         if index:
             print()
         if getattr(args, "label_targets", False):
-            print(f"==> {per_target.target} <==")
+            target = per_target.target
+            print(f"==> {f'{target[0]} --name-contains {target[1]}' if isinstance(target, tuple) else target} <==")
         if isinstance(response, NdiError):
             status = max(status, _report_error(response, target=per_target.target))
         else:

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_docops.py

@@ -37,10 +37,13 @@ DEFAULT_PARALLEL = 4
 def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
     upload = sub.add_parser("upload", parents=[common], help="Stage a file for a document operation.")
     upload.add_argument("file", help="Local file to stage.")
-    upload.add_argument("--ttl", type=int, default=None, dest="ttl_seconds", metavar="SECONDS")
     upload.add_argument("--file-name", default=None, help="Override the uploaded name.")
     upload.set_defaults(run=_run_upload, family="docops", needs_workspace=False, needs_client=True)
 
+    delete_upload = sub.add_parser("upload-delete", parents=[common], help="Erase an unused upload.")
+    delete_upload.add_argument("upload_id", help="Upload ID returned by upload; used uploads require deleting their jobs.")
+    delete_upload.set_defaults(run=_run_delete_upload, family="docops", needs_workspace=False, needs_client=True)
+
     parse = sub.add_parser("parse", parents=[common], help="Turn a document into markdown, text, and blocks.")
     _add_source_args(parse)
     parse.add_argument("-p", "--pages", default=None, metavar="SPEC", help="1-based pages, e.g. 3 or 1-5,8.")
@@ -88,7 +91,9 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
 
 
 def _add_source_args(parser: argparse.ArgumentParser, *, required: bool = True) -> None:
-    parser.add_argument("source", nargs=None if required else "?", help="File, directory, URL, ndi://, jobid://, ws://, or -.")
+    parser.add_argument(
+        "source", nargs=None if required else "?", help="File, directory, URL, ndi://, jobid://, ws://FILE_ID, or -."
+    )
     parser.add_argument("--file-name", default=None, help="Name for stdin bytes or a URL without a filename.")
     parser.add_argument("-j", type=int, default=DEFAULT_PARALLEL, dest="parallel", help="Parallel jobs for a directory.")
     add_job_output_args(parser)
@@ -99,12 +104,17 @@ def _add_class_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--classes", dest="classes_file", default=None, help="JSON array of classes.")
 
 
+def _run_delete_upload(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    client.documents.delete_upload(args.upload_id)
+    return 0
+
+
 def _run_upload(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
     path = Path(args.file)
     if not path.is_file():
         print(f"error: file not found: {args.file}", file=sys.stderr)
         return 2
-    upload = client.documents.create_upload(path, file_name=args.file_name or path.name, ttl_seconds=args.ttl_seconds)
+    upload = client.documents.create_upload(path, file_name=args.file_name or path.name)
     print(f"ndi://upload/{upload.upload_id}")
     print(f"upload {upload.upload_id} {upload.file_name} {upload.size_bytes}B", file=sys.stderr)
     return 0

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_entrypoint.py

@@ -3,14 +3,20 @@
 from __future__ import annotations
 
 import io
+import os
 import sys
 
-import truststore
+from ndi_cli import SOCKET_ENV
 
 
 def main(argv: list[str] | None = None) -> int:
     """Enable native certificate verification and UTF-8 stdio before loading the CLI and SDK."""
-    truststore.inject_into_ssl()
+    # An agent run's commands reach the worker over the local socket, never TLS, and the
+    # trust-store patch (it also loads urllib3 and requests) would slow every one of them.
+    if SOCKET_ENV not in os.environ:
+        import truststore  # noqa: PLC0415
+
+        truststore.inject_into_ssl()
     # Piped stdio otherwise follows the Windows ANSI code page, which cannot encode every character a result may hold.
     for stream in (sys.stdout, sys.stderr):
         if isinstance(stream, io.TextIOWrapper):

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_local.py

@@ -17,9 +17,9 @@ from ndi_sdk.errors import ErrorBody, NdiConnectionError, NdiTimeoutError, error
 from ndi_sdk.models.tools import QaFileRequest
 from pydantic import BaseModel, Field, TypeAdapter
 
+from ndi_cli import SOCKET_ENV as SOCKET_ENV  # re-exported: the worker imports it from here
 from ndi_cli.commands import WorkspaceCommand
 
-SOCKET_ENV = "NDI_CLI_SOCKET"
 TOKEN_ENV = "NDI_CLI_TOKEN"
 MAX_MESSAGE_BYTES = 16 * 1024 * 1024
 ModelT = TypeVar("ModelT", bound=BaseModel)
@@ -55,6 +55,8 @@ class ReadFileRequest(BaseModel):
     pages: list[int] | None = None
     component: str | None = None
     max_chars: int | None = None
+    line_start: int | None = None
+    line_end: int | None = None
 
 
 class RunSqlRequest(BaseModel):
@@ -68,6 +70,18 @@ class SearchRequest(BaseModel):
     categories: list[str] | None = None
 
 
+class GrepRequest(BaseModel):
+    pattern: str
+    path_prefix: str | None = None
+    paths: list[str] | None = None
+    before: int = 0
+    after: int = 0
+    files_only: bool = False
+    ignore_case: bool = False
+    fixed_strings: bool = False
+    max_matches: int = 50
+
+
 class FolderCommand(BaseModel):
     command: Literal[WorkspaceCommand.FOLDER_METADATA] = WorkspaceCommand.FOLDER_METADATA
     body: FolderMetadataRequest
@@ -98,8 +112,13 @@ class SearchCommand(BaseModel):
     body: SearchRequest
 
 
+class GrepCommand(BaseModel):
+    command: Literal[WorkspaceCommand.GREP] = WorkspaceCommand.GREP
+    body: GrepRequest
+
+
 Command = Annotated[
-    FolderCommand | FileCommand | ReadCommand | AskCommand | SqlCommand | SearchCommand,
+    FolderCommand | FileCommand | ReadCommand | AskCommand | SqlCommand | SearchCommand | GrepCommand,
     Field(discriminator="command"),
 ]
 COMMAND = TypeAdapter(Command)

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_render.py

@@ -10,8 +10,10 @@ output limit (``_output.FULL_OUTPUT_LIMIT``); ``--json`` always prints it whole.
 from __future__ import annotations
 
 import json
+import os
 import sys
 import uuid
+from collections import Counter
 
 import html
 import re
@@ -47,6 +49,8 @@ from ndi_sdk.models.workspaces import Workspace, WorkspaceStats
 from ndi_sdk.models.tools import (
     FileMetadataToolResponse,
     FolderMetadataResponse,
+    GrepMatch,
+    GrepResponse,
     QaFileResponse,
     ReadFileResponse,
     RunSqlResponse,
@@ -56,6 +60,19 @@ from ndi_sdk.models.tools import (
 _SNIPPET_LIMIT = 500
 
 
+#: What a document's rows table is and what it is for, printed once per table by file-metadata.
+_ROWS_TABLE_NOTE = (
+    "every row this document's tables print, one SQL table for the document (a section's rows are the ones "
+    "printed on its pages). `page`, `table_no`, `row_no` place a row; the other columns are its cells, left to "
+    "right (`c1`, `c2`, … unless the tables repeat a header); a header printed once is among a table's first rows, "
+    "and `context` is the text printed above the table, followed by any system alignment warning. "
+    "Only the fixed Parse alignment sentence marks unverified columns; other lookalikes are printed source text. "
+    "Keep the warning separate from printed headings. "
+    "For counting, totalling or ranking rows; to read one "
+    "printed table, read-file its page or lines"
+)
+
+
 def _size(num_bytes: int) -> str:
     value = float(num_bytes)
     for unit in ("B", "KB", "MB", "GB"):
@@ -143,22 +160,97 @@ def _locator(locator) -> str:
     return locator.kind
 
 
+#: Hits whose snippets agree on this many leading characters (digits masked) are one passage printed in several
+#: files: a serial corpus restates its headings, tables of contents and boilerplate in every issue.
+_SAME_PASSAGE_CHARS = 120
+_DIGITS = re.compile(r"\d")
+
+
+def _passage_key(hit: Evidence) -> str | None:
+    text = _flatten_markup(hit.snippet or "")
+    return _DIGITS.sub("#", " ".join(text.split()))[:_SAME_PASSAGE_CHARS] or None
+
+
+def _same_passage_groups(hits: list[Evidence]) -> dict[int, list[Evidence]]:
+    """For each hit (by position) that leads a run of hits sharing its passage, the later hits it stands for.
+
+    Only hits in **other files** fold under a leader: two hits in one file are two places to read. Folded hits
+    keep their rank order; the leader is the best-ranked."""
+    folded: dict[int, list[Evidence]] = {}
+    taken: set[int] = set()
+    for i, hit in enumerate(hits):
+        if i in taken or (key := _passage_key(hit)) is None:
+            continue
+        same = [
+            other
+            for j, other in enumerate(hits[i + 1 :], start=i + 1)
+            if j not in taken and other.path != hit.path and _passage_key(other) == key
+        ]
+        if same:
+            folded[i] = same
+            taken.update(j for j, other in enumerate(hits) if other in same)
+    return folded
+
+
 def _evidence_lines(hits: list[Evidence]) -> list[str]:
     lines: list[str] = []
+    folded = _same_passage_groups(hits)
+    hidden = {id(other) for same in folded.values() for other in same}
     for index, hit in enumerate(hits, start=1):
+        if id(hit) in hidden:
+            continue
         where = f" [{hit.component}]" if hit.component else ""
         page = f", page {hit.page}" if hit.page is not None else ""
         at = f" @ {_locator(hit.locator)}" if hit.locator is not None else ""
-        lines.append(f"{index}. {hit.path}{where} (score {hit.relevance_score:.3f}{page}){at}")
+        span = ""
+        if hit.line_start is not None and hit.line_end is not None:
+            span = f" · lines {hit.line_start}-{hit.line_end}" if hit.line_end != hit.line_start else f" · line {hit.line_start}"
+        lines.append(f"{index}. {hit.path}{where} (score {hit.relevance_score:.3f}{page}){at}{span}")
         if hit.sql_table:
             lines.append(f"   sql table: {hit.sql_table}")
         if hit.snippet:
             lines.append(f"   {_clip(_flatten_markup(hit.snippet))}")
         if hit.why:
             lines.append(f"   why: {_clip(hit.why, 300)}")
+        if same := folded.get(index - 1):
+            where = ", ".join(f"{other.path}" + (f" p.{other.page}" if other.page is not None else "") for other in same)
+            lines.append(f"   same passage in {len(same)} more file(s): {where}")
     return lines
 
 
+def folder_names(response: FolderMetadataResponse) -> str:
+    """``folder-metadata --names-only``: the paths, one per line, and a last line only when the list was cut."""
+    lines = [entry.path for entry in response.file_entries]
+    if response.files_truncated:
+        lines.append(f"... more files: narrow with a directory or --name-contains, or --start-after {lines[-1]}")
+    elif not lines:
+        lines.append("no files")
+    return "\n".join(lines)
+
+
+#: A truncated page is digested only when its names share this much of a common prefix: fewer and the names
+#: are unrelated, and a row each says more than a prefix would.
+_DIGEST_MIN_PREFIX = 4
+#: ...and holds at least this many entries: a short page reads faster as rows.
+_DIGEST_MIN_ENTRIES = 20
+
+
+def _listing_digest(entries) -> str | None:
+    """One line for a page of same-shaped names: ``treasury_bulletin_*.pdf, treasury_bulletin_1939_01.pdf ...
+    treasury_bulletin_1947_05.pdf, 2.2MB-7.5MB, ingested x100`` — or None when the names share no prefix."""
+    names = [entry.path.rsplit("/", 1)[-1] for entry in entries]
+    prefix = os.path.commonprefix(names)
+    if len(names) < _DIGEST_MIN_ENTRIES or len(prefix) < _DIGEST_MIN_PREFIX:
+        return None
+    suffixes = {name.rsplit(".", 1)[-1] for name in names if "." in name}
+    shape = prefix + "*" + (f".{suffixes.pop()}" if len(suffixes) == 1 else "")
+    sizes = [entry.size_bytes for entry in entries if entry.size_bytes is not None]
+    span = f", {_size(min(sizes))}-{_size(max(sizes))}" if sizes else ""
+    statuses = Counter(entry.ingestion_status for entry in entries)
+    status = ", ".join(f"{name} x{count}" for name, count in sorted(statuses.items()))
+    return f"({shape}): {entries[0].path} ... {entries[-1].path}{span}, {status}"
+
+
 def folder_metadata(response: FolderMetadataResponse) -> str:
     lines = [f"directory: {response.directory}", f"files in scope: {response.overall_files}"]
     if response.categories:
@@ -172,7 +264,14 @@ def folder_metadata(response: FolderMetadataResponse) -> str:
             failed = f"  ({sub.failed_files} failed)" if sub.failed_files else ""
             cats = f"  categories: {_categories(sub.top_categories, limit=3)}" if sub.top_categories else ""
             lines.append(f"  {sub.name}/  {sub.overall_files} files{failed}{cats}")
-    if response.file_entries:
+    if response.file_entries and response.files_truncated and (digest := _listing_digest(response.file_entries)):
+        # A page of a larger listing: the agent cannot act on a hundred rows that stop short of the file it
+        # needs, so the page reads as what the names have in common, and how to list or narrow them.
+        lines.append(f"files listed ({len(response.file_entries)} of {response.overall_files}, truncated) {digest}")
+        lines.append(
+            "  every path: --names-only (pipe to grep); by name: --name-contains TEXT; by content: hybrid-search or grep"
+        )
+    elif response.file_entries:
         cut = " (truncated — resume with --start-after, or narrow)" if response.files_truncated else ""
         lines.append(f"files listed ({len(response.file_entries)}){cut}:")
         for entry in response.file_entries:
@@ -358,10 +457,7 @@ def file_metadata(response: FileMetadataToolResponse) -> str:
             shared = comp.kind == "section" and comp.columns and any(col.name == "origin" for col in comp.columns)
             shown = comp.table_name in shown_tables
             if shared and not shown:
-                lines.append(
-                    f"      {comp.table_name}: one SQL table for every section that lists it; "
-                    "a section's rows are the ones printed on its pages"
-                )
+                lines.append(f"      {comp.table_name}: {_ROWS_TABLE_NOTE}")
             if comp.columns and not (shared and shown):
                 lines.extend(_column_lines(comp.columns, bool(comp.columns_truncated)))
             if comp.table_preamble and not shown:
@@ -371,6 +467,11 @@ def file_metadata(response: FileMetadataToolResponse) -> str:
                 shown_tables.add(comp.table_name)
             if comp.error:
                 lines.append(f"      error: {comp.error}")
+    if response.figures:
+        lines.append(f'figures ({len(response.figures)}) — ask one with: ask-file PATH "question" --component "<name>":')
+        for figure in response.figures:
+            seen = figure.description or (f"text: {figure.text}" if figure.text else "not described")
+            lines.append(f"  [{figure.name}] page {figure.page} — {' '.join(seen.split())}")
     return "\n".join(lines)
 
 
@@ -429,6 +530,11 @@ def _column_lines(columns: list, truncated: bool) -> list[str]:
 
 def read_file_footer(response: ReadFileResponse) -> str:
     parts = [f"read {response.path}"]
+    if response.line_count is not None:
+        if response.line_end is None:
+            parts.append(f"no lines (the text has {response.line_count})")
+        else:
+            parts.append(f"lines {response.line_start}-{response.line_end} of {response.line_count}")
     if response.pages_returned:
         parts.append(f"pages {_page_ranges(response.pages_returned)}")
     if response.components_returned:
@@ -516,6 +622,90 @@ def search(response: SearchResponse) -> str:
     return "\n".join(lines)
 
 
+def grep(response: GrepResponse) -> str:
+    """Matches grouped by file and component, ``LINE[ p.PAGE]: text`` like grep -n, with the follow-up names.
+
+    A tab, image or recording match has no line: it is printed bare, and a closing note says where its answer is.
+    A grep that found nothing shows its near misses the same way, under a line saying what they are.
+    """
+    lines = _grep_lines(response.matches)
+    if not response.matches:
+        lines.append("no matches")
+        if response.near_misses:
+            lines.append("nearest lines (most of the pattern's words, not the pattern as written):")
+            lines += _grep_lines(response.near_misses)
+    tail = (
+        f"{len(response.matches)} matching lines shown; {response.files_matched} of {response.files_scanned} files read matched"
+    )
+    # Index mode reads every file whose indexed text holds the pattern's words; say so, or an agent takes the answer
+    # for a sample and searches again.
+    tail += " (the files holding the pattern's words; the rest of the scope lacks them)" if response.mode == "index" else ""
+    if response.truncated:
+        tail += f"; STOPPED at the limit — {response.files_unscanned} more files may match: raise -m or narrow the PATHs"
+    lines.append(tail)
+    lines += [f"note: {note}" for note in response.notes]
+    kinds = {match.kind for match in response.matches}
+    if "tab" in kinds:
+        note = (
+            "Tab matches are pointers: a tab's stored text is a preview of its rows (a parquet's, a column profile), "
+            "so the answer — and any row missing here — very likely comes from run-sql on the sql table shown."
+        )
+        if any(match.kind == "tab" and match.sql_table is None for match in response.matches):
+            note += " A tab shown without one has no table: read it with read-file --component."
+        lines.append(note)
+    if kinds & {"image", "media"}:
+        lines.append("Image and recording matches are pointers (an image's text or summary matched): read them with ask-file.")
+    return "\n".join(lines)
+
+
+def _grep_lines(matches: list[GrepMatch]) -> list[str]:
+    lines: list[str] = []
+    current: tuple[str, str | None] | None = None
+    current_table: tuple[str, str | None, int] | None = None
+    shown = 0  # last line printed in the current file/component, so overlapping context prints once
+    for match in matches:
+        if (match.path, match.component) != current:
+            current, shown = (match.path, match.component), 0
+            label = match.component or (match.kind if match.kind in {"image", "media"} else None)
+            where = f" [{label}]" if label else ""
+            table = f"  (sql table: {match.sql_table})" if match.sql_table else ""
+            lines.append(f"{match.path}{where}{table}")
+        if match.line is None:
+            lines.append(f"  {match.text}")
+            continue
+        page = f" p.{match.page}" if match.page is not None else ""
+        table = match.table
+        if table is not None and (match.path, match.component, table.first_line) != current_table:
+            # A row's cells mean nothing without their column names: each table's lines, title and header, once.
+            current_table, shown = (match.path, match.component, table.first_line), 0  # the block separates
+            if table.rows is not None:  # a table stored as one HTML line: its header once, then each matching row
+                lines.append(
+                    f"  [table on line {table.first_line}, {table.rows} rows]" + (f" {table.title}" if table.title else "")
+                )
+                if table.header and match.text != table.header:  # a match on the header itself is the header
+                    lines.append(f"  header: {table.header}")
+                lines.append(f"  {match.line}{page}: {match.text}")
+                continue
+            span = f"  [table lines {table.first_line}-{table.last_line}]"
+            if match.line < table.first_line:  # the match is the table's title
+                lines += [f"  {match.line}{page}: {match.text}", f"{span} {table.first_line}: {table.header}"]
+                continue
+            lines.append(span + (f" {table.title}" if table.title else ""))
+            if match.line != table.first_line and table.first_line < match.line - len(match.context_before):
+                lines.append(f"  {table.first_line}: {table.header}")
+        if match.context_before or match.context_after:  # grep -A/-B/-C: context lines print as N- text
+            first = match.line - len(match.context_before)
+            if shown and first > shown + 1:
+                lines.append("  --")
+            lines += [f"  {n}- {text}" for n, text in enumerate(match.context_before, start=first) if n > shown]
+            lines.append(f"  {match.line}{page}: {match.text}")
+            lines += [f"  {n}- {text}" for n, text in enumerate(match.context_after, start=match.line + 1) if n > match.line]
+            shown = match.line + len(match.context_after)
+            continue
+        lines.append(f"  {match.line}{page}: {match.text}")
+    return lines
+
+
 def parse_job(job: Job) -> str:
     result = job.result
     if not isinstance(result, ParseResult):
@@ -741,7 +931,10 @@ def automatic_search_job(job: Job) -> str:
         body = filtered_search_job(job.model_copy(update={"result": output}))
     else:
         body = search_job(job.model_copy(update={"result": output}))
-    return f"route: {result.routing.final} — {result.routing.reason}\noutput job: {result.output_job_id}\n{body}"
+    routing = result.routing
+    # The reason explains the router's choice, so a hand-over names both routes.
+    route = routing.final if routing.selected == routing.final else f"{routing.selected} → {routing.final} (no fact answer)"
+    return f"route: {route} — {routing.reason}\noutput job: {result.output_job_id}\n{body}"
 
 
 def search_job(job: Job) -> str:

{ndi_cli-0.29.0 → ndi_cli-0.30.0}/src/ndi_cli/_sources.py

@@ -18,6 +18,7 @@ from ndi_sdk.models.common import DocumentSource, ParseResultSource, UploadSourc
 JOBID_PREFIX = "jobid://"
 UPLOAD_PREFIX = "ndi://upload/"
 WS_PREFIX = "ws://"
+_WS_FILE_ID_HINT = "workspace files are ws://FILE_ID; find the id with `ndi files list`"
 _UUID = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
 SUPPORTED_SUFFIXES = frozenset(
     {
@@ -165,9 +166,10 @@ def resolve_source(
     if spec.startswith(WS_PREFIX):
         if not workspace_id:
             raise SourceError("ws:// sources need a workspace: set $NDI_WORKSPACE_ID or pass --workspace")
-        return WorkspaceFileSource(
-            workspace_id=_uuid(workspace_id, "workspace"), file_id=_uuid(spec.removeprefix(WS_PREFIX), "ws://")
-        )
+        file_id = spec.removeprefix(WS_PREFIX)
+        if not _UUID.match(file_id):
+            raise SourceError(f"bad ws:// id: {file_id!r}; {_WS_FILE_ID_HINT}")
+        return WorkspaceFileSource(workspace_id=_uuid(workspace_id, "workspace"), file_id=uuid.UUID(file_id))
     if spec.startswith(("https://", "http://")):
         name = file_name or Path(spec.split("?", 1)[0]).name or "document"
         return UrlSource(url=spec, file_name=name)
@@ -175,7 +177,8 @@ def resolve_source(
         return _from_stdin(client, file_name=file_name, allow_parse_result=allow_parse_result, stdin=stdin)
     path = Path(spec)
     if not path.is_file():
-        raise SourceError(f"file not found: {spec}")
+        hint = f"; {_WS_FILE_ID_HINT}" if spec.startswith("ws:") else ""
+        raise SourceError(f"file not found: {spec}{hint}")
     try:
         upload = client.documents.create_upload(path, file_name=file_name or path.name)
     except OSError as exc: