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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools
 Keywords: ndi,cli,document-intelligence,coding-agents
 Author: Nace AI
@@ -56,6 +56,7 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
 | `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
+| `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 folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
@@ -82,6 +83,14 @@ to **stderr**. `-o auto|md|json|payload|id` picks the shape. `--json` is an
 alias for `-o json`. `--save PATH` / `--out-dir DIR` write files. `--async`
 submits and prints the job id.
 
+When a Parse result has external complete content, `-o auto` and `-o md` print
+the inline preview. Use `-o json` or `-o payload` to inspect its disclosure and
+authenticated full-content URL. A final-size preview carries
+`content_truncated`; reduced-layout Office parsing carries `parse_fidelity`.
+Documents use `document.content_url`; workbooks use the affected
+`document.spreadsheet.sheets[].content_url`. The CLI does not download these
+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.

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/README.md

@@ -32,6 +32,7 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
 | `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
+| `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 folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
@@ -58,6 +59,14 @@ to **stderr**. `-o auto|md|json|payload|id` picks the shape. `--json` is an
 alias for `-o json`. `--save PATH` / `--out-dir DIR` write files. `--async`
 submits and prints the job id.
 
+When a Parse result has external complete content, `-o auto` and `-o md` print
+the inline preview. Use `-o json` or `-o payload` to inspect its disclosure and
+authenticated full-content URL. A final-size preview carries
+`content_truncated`; reduced-layout Office parsing carries `parse_fidelity`.
+Documents use `document.content_url`; workbooks use the affected
+`document.spreadsheet.sheets[].content_url`. The CLI does not download these
+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.

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 readme = "README.md"
 license = "MIT"

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 authors = [
     { name = "Nace AI", email = "engineering@nace.ai" }

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/src/ndi_cli/__init__.py

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

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/src/ndi_cli/_render.py

@@ -21,6 +21,7 @@ from ndi_sdk.models.jobs import (
     ClassifyResult,
     DeepSearchV2Result,
     ExtractResult,
+    FilteredSearchResult,
     GroundResult,
     IngestionResult,
     IntelligentSearchResult,
@@ -706,6 +707,131 @@ def je_testing_job(job: Job) -> str:
     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
+#: makes a thin row interpretable without opening the JSON.
+_CELL_STATUS = {
+    "not_found": "examined; field absent",
+    "ambiguous": "present, not normalizable",
+    "unexamined": "extraction could not say",
+}
+
+
+def _cell_value(cell) -> str:
+    value = cell.value
+    if value is None:
+        return _CELL_STATUS.get(cell.status, cell.status)
+    match value.kind:
+        case "money":
+            # Amounts keep their own currency here because the server never
+            # converts one either; comparing across currencies is unsupported,
+            # so dropping the code would invent a comparison.
+            assumed = " (currency assumed)" if value.currency_source == "assumed" else ""
+            return f"{value.currency} {value.amount}{assumed}"
+        case "text":
+            return _clip(value.text)
+        case "date":
+            return value.date
+        case "number":
+            return value.number
+        case "boolean":
+            return "true" if value.value else "false"
+    return value.kind
+
+
+def _page_range(row) -> str:
+    if row.page_start is None:
+        return ""
+    if row.page_end is not None and row.page_end != row.page_start:
+        return f" (pages {row.page_start}-{row.page_end})"
+    return f" (page {row.page_start})"
+
+
+def _filtered_rows(result: FilteredSearchResult) -> list[str]:
+    """The rows, carrying the columns their membership hinges on.
+
+    A count-style question confirms ``total_matches`` and returns no rows at
+    all, so an empty listing is an answer rather than a gap — it prints nothing
+    instead of an empty header.
+    """
+    if not result.rows:
+        return []
+    # The server marks which columns its published query filtered or ranked on,
+    # and those are the values every row's membership depends on; `requested` is
+    # what the reader asked to see. Everything else is context, left for --json.
+    hinges = [column.field for column in result.columns if column.filtered]
+    shown = hinges + [column.field for column in result.columns if column.requested and column.field not in hinges]
+    lines = [f"rows ({len(result.rows)}):"]
+    for row in result.rows:
+        where = f" [{row.component}]" if row.component else ""
+        lines.append(f"  {row.source_path}{where}{_page_range(row)}")
+        for field in shown or list(dict.fromkeys(cell.field for cell in row.cells)):
+            # A repeated column carries one cell per item, so join them rather
+            # than showing the first and implying the field held one value.
+            values = [_cell_value(cell) for cell in row.cells if cell.field == field]
+            if values:
+                lines.append(f"    {field}: {'; '.join(values)}")
+    return lines
+
+
+def _filtered_caveats(result: FilteredSearchResult) -> list[str]:
+    lines: list[str] = []
+    if not result.exhaustive:
+        lines.append("not exhaustive: the matches are valid, but total_matches is a floor and not a census")
+    if result.truncated:
+        lines.append("truncated: the published query matched more than this page carries")
+    if result.catalog_drifted:
+        lines.append("catalog drifted: the underlying data changed since the query first ran")
+    # `exhaustive` is scope-wide and almost always false, so it cannot say *what*
+    # was incomplete. Only a resolved value satisfies a predicate, so a field the
+    # extraction could not read drops its components silently — a correct query
+    # coming back thin for a reason unrelated to the question.
+    for entry in result.field_readability:
+        read = f"{entry.readable} of {entry.in_scope} values read"
+        if entry.readable == 0:
+            lines.append(f"unreadable: {entry.field} — {read}; a thin result here reflects that, not an absence")
+        else:
+            lines.append(f"partly readable: {entry.field} — {read}")
+    check = result.content_verification
+    if check and check.unverified_candidates:
+        lines.append(
+            f"content check: {check.unverified_candidates} of {check.candidates} candidates unverified "
+            f"for {_clip(check.condition, 120)!r} — unknown is not a non-match"
+        )
+    lines.extend(_coverage_lines(result.coverage))
+    if result.exhausted:
+        lines.append("exhausted: step budget ran out before the query finished")
+    return lines
+
+
+def filtered_search_job(job: Job) -> str:
+    """The totals, then the rows behind them — a catalog answer read at a glance.
+
+    A filter/rank/count question is answered by a number, so this leads with the
+    counts and prints the published query under them: the figure and the
+    statement it came out of travel together, the way a JET figure names its
+    receipt. Rows carry the columns the matches hinge on; ``-o json`` has every
+    cell, citation and column the catalog returned.
+    """
+    result = job.result
+    if not isinstance(result, FilteredSearchResult):
+        return job_line(job)
+    lines: list[str] = []
+    if result.interpretation:
+        lines.append(f"interpretation: {_clip(result.interpretation)}")
+    files = f" ({result.total_files} files)" if result.total_files is not None else ""
+    confidence = f" | confidence: {result.confidence}" if result.confidence else ""
+    lines.append(f"matches: {result.total_matches}{files}{confidence}")
+    if result.applied_query:
+        lines.append(f"query: {_clip(result.applied_query, 300)}")
+    lines.extend(_filtered_rows(result))
+    lines.extend(_filtered_caveats(result))
+    if result.next_cursor:
+        lines.append(f"next: {result.next_cursor}")
+    return "\n".join(lines)
+
+
 def _search_result(answer: str | None, clarification: str | None, evidences: list, *, receipts: int) -> str:
     lines: list[str] = []
     if clarification:

{ndi_cli-0.7.0 → ndi_cli-0.8.0}/src/ndi_cli/_workspace.py

@@ -95,6 +95,22 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     add_job_output_args(fact)
     fact.set_defaults(run=_run_fact_search, family="workspace", needs_workspace=True, needs_client=True)
 
+    filtered = sub.add_parser(
+        "filtered-search", parents=[common], help="Run a filter/rank/count query over the metadata catalog."
+    )
+    filtered.add_argument("query", nargs="?", default=None)
+    filtered.add_argument(
+        "--cursor", default=None, help="Page an earlier run: paste its result's next_cursor. A page is a new job."
+    )
+    filtered.add_argument("--prefix", default=None, dest="path_prefix")
+    filtered.add_argument("--context", default=None)
+    # No --result-unit: the server deprecates the grouping override and returns
+    # catalog entries. No --allow-clarification: a clarification is answered by a
+    # new initial query, and a shell has nowhere to keep the thread — the reason
+    # deep-search omits --session-id.
+    add_job_output_args(filtered)
+    filtered.set_defaults(run=_run_filtered_search, family="workspace", needs_workspace=True, needs_client=True)
+
     jet = sub.add_parser("je-testing", parents=[common], help="Run journal-entry testing over a ledger package.")
     jet.add_argument("query")
     jet.add_argument("--effort", choices=("low", "medium", "high"), default=None)
@@ -237,6 +253,31 @@ def _run_fact_search(client: NdiClient, workspace_id: str, args: argparse.Namesp
     return _finish_job(client, job, args, _render.search_job, "fact-search")
 
 
+def _run_filtered_search(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    if args.query and args.cursor:
+        print("error: pass a query or --cursor, not both", file=sys.stderr)
+        return 2
+    if not args.query and not args.cursor:
+        print("error: pass a query, or --cursor to page an earlier run", file=sys.stderr)
+        return 2
+    if args.cursor:
+        # A page re-executes the parent's own stored query, so the scoping flags
+        # cannot apply to it. Accepting and dropping them would quietly answer a
+        # different question than the one typed.
+        if args.path_prefix or args.context:
+            print("error: --prefix and --context belong to the initial query, not a page", file=sys.stderr)
+            return 2
+        job = client.search.filtered_page(workspace_id, cursor=args.cursor)
+    else:
+        job = client.search.filtered(
+            workspace_id,
+            query=args.query,
+            context=args.context,
+            path_prefix=args.path_prefix,
+        )
+    return _finish_job(client, job, args, _render.filtered_search_job, "filtered-search")
+
+
 def _run_je_testing(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
     job = client.search.je_testing(
         workspace_id,