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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.6.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
@@ -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.21,<1
+Requires-Dist: ndi-sdk>=0.22,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://ndi-api.nace.ai
@@ -56,6 +56,8 @@ 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) |
 
 ## Sources
@@ -81,8 +83,17 @@ 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.
 
-See `SKILL.md` for the agent-facing guide to the six workspace tools.
+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.6.0 → ndi_cli-0.8.0}/README.md

@@ -32,6 +32,8 @@ 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) |
 
 ## Sources
@@ -57,8 +59,17 @@ 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.
 
-See `SKILL.md` for the agent-facing guide to the six workspace tools.
+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.6.0 → ndi_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.6.0"
+version = "0.8.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.21,<1",
+    "ndi-sdk>=0.22,<1",
     "truststore>=0.10.4,<1",
 ]
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.6.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" }
@@ -27,7 +27,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "ndi-sdk>=0.21,<1",
+    "ndi-sdk>=0.22,<1",
     "truststore>=0.10.4,<1",
 ]
 

{ndi_cli-0.6.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.6.0"
+__version__ = "0.8.0"

{ndi_cli-0.6.0 → ndi_cli-0.8.0}/src/ndi_cli/_output.py

@@ -6,7 +6,7 @@ import sys
 from collections.abc import Callable
 from pathlib import Path
 
-from ndi_sdk.models.jobs import IngestionResult, Job, ParseResult
+from ndi_sdk.models.jobs import IngestionResult, JetResult, Job, ParseResult
 
 OUTPUT_CHOICES = ("auto", "md", "json", "payload", "id")
 
@@ -108,6 +108,13 @@ def _content_failure(job: Job) -> int:
             file=sys.stderr,
         )
         return 1
+    # A degraded JET run is the same shape: succeeded, but the procedure broke
+    # before it could finalize an answer, so `figures` is empty and only the
+    # working survives. `exhausted` and `partially_performed` stay zero — both
+    # are documented as successful partial answers, not failed work.
+    if isinstance(result, JetResult) and result.degraded:
+        print(f"error: journal-entry testing degraded: {result.degraded}", file=sys.stderr)
+        return 1
     return 0
 
 

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

@@ -21,9 +21,11 @@ from ndi_sdk.models.jobs import (
     ClassifyResult,
     DeepSearchV2Result,
     ExtractResult,
+    FilteredSearchResult,
     GroundResult,
     IngestionResult,
     IntelligentSearchResult,
+    JetResult,
     Job,
     ParseResult,
     SplitResult,
@@ -662,6 +664,174 @@ def search_job(job: Job) -> str:
     return job_line(job)
 
 
+def je_testing_job(job: Job) -> str:
+    """The answer, then the numbers behind it — a JET result read at a glance.
+
+    Unlike :func:`search_job` this leads with ``figures``: the answer is prose a
+    person reads, and the figures are the same content a reviewer can check.
+    Each one names the receipt its numbers are readable out of, so
+    ``ndi job <id> -o json`` is the next step rather than the only one.
+    """
+    result = job.result
+    if not isinstance(result, JetResult):
+        return job_line(job)
+    lines: list[str] = []
+    if result.degraded:
+        lines.append(f"degraded: {result.degraded}")
+    if result.answer:
+        lines.append(result.answer.strip())
+    if result.population_statement:
+        lines.append(f"population: {result.population_statement}")
+    if result.figures:
+        lines.append(f"figures ({len(result.figures)}):")
+        for figure in result.figures:
+            if figure.cannot_be_performed:
+                lines.append(f"  {figure.criterion}: not performed")
+            else:
+                value = f" | {figure.value}" if figure.value else ""
+                lines.append(f"  {figure.criterion}: {figure.count}/{figure.population}{value}")
+            # The exception listing is the receipt worth opening: an unfiltered
+            # count points at every row, a listing points at the rows that failed.
+            receipt = figure.exception_listing_result_id or next(iter(figure.result_ids), None)
+            if receipt:
+                lines.append(f"    receipt {receipt}")
+    for discrepancy in result.discrepancies:
+        lines.append(f"discrepancy: {discrepancy}")
+    lines.append(f"evidences ({len(result.evidences)}) | receipts ({len(result.sql_receipts)})")
+    if result.execution_status and result.execution_status != "performed":
+        lines.append(f"execution: {result.execution_status}")
+    if result.quality and result.quality.status != "clean":
+        lines.append(f"quality: {result.quality.status}")
+    if result.exhausted:
+        lines.append("exhausted: step budget ran out before the procedure finished")
+    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.6.0 → ndi_cli-0.8.0}/src/ndi_cli/_workspace.py

@@ -95,6 +95,33 @@ 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)
+    jet.add_argument("--prefix", default=None, dest="path_prefix")
+    jet.add_argument("--path", action="append", dest="paths", default=None, help="Scope to this file; repeatable.")
+    jet.add_argument("--context", default=None)
+    # No --session-id, for the reason deep-search omits it: a shell has nowhere
+    # to keep a thread. Omitting --effort leaves the deployment's own floor.
+    add_job_output_args(jet)
+    jet.set_defaults(run=_run_je_testing, 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
@@ -224,3 +251,40 @@ def _run_fact_search(client: NdiClient, workspace_id: str, args: argparse.Namesp
         top_k=args.top_k,
     )
     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,
+        query=args.query,
+        context=args.context,
+        effort=args.effort,
+        path_prefix=args.path_prefix,
+        paths=args.paths,
+    )
+    return _finish_job(client, job, args, _render.je_testing_job, "je-testing")