ndi-cli 0.4.0__py3-none-any.whl

ndi_cli/_sources.py

@@ -0,0 +1,154 @@
+"""Turn a CLI source spec into a typed ``DocumentSource``.
+
+A spec is a local path, a directory of supported files, an HTTPS URL, a staged
+upload handle, a prior parse job, a workspace file, or ``-`` (stdin).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import uuid
+from pathlib import Path
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.models.common import DocumentSource, ParseResultSource, UploadSource, UrlSource, WorkspaceFileSource
+
+JOBID_PREFIX = "jobid://"
+UPLOAD_PREFIX = "ndi://upload/"
+WS_PREFIX = "ws://"
+_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(
+    {
+        ".pdf",
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".tif",
+        ".tiff",
+        ".webp",
+        ".doc",
+        ".docx",
+        ".ppt",
+        ".pptx",
+        ".xls",
+        ".xlsx",
+        ".xlsm",
+        ".xlsb",
+        ".ods",
+        ".csv",
+        ".tsv",
+        ".parquet",
+        ".jsonl",
+        ".ndjson",
+        ".json",
+        ".wav",
+        ".mp3",
+        ".m4a",
+        ".mp4",
+        ".mov",
+    }
+)
+
+
+class SourceError(ValueError):
+    """The source spec could not be resolved."""
+
+
+def collect_specs(spec: str) -> list[str]:
+    """Expand a directory into supported files; leave every other spec alone."""
+    if _is_handle(spec) or spec == "-":
+        return [spec]
+    # An empty spec is Path("") -> ".", which would recursively sweep and upload
+    # the whole working directory.
+    if not spec.strip():
+        raise SourceError("SOURCE is empty; pass a file, directory, URL, ndi://, jobid://, ws://, or -")
+    path = Path(spec)
+    if path.is_dir():
+        children = [child for child in path.rglob("*") if child.is_file()]
+        found = sorted(str(child) for child in children if child.suffix.lower() in SUPPORTED_SUFFIXES)
+        if not found:
+            raise SourceError(f"no supported files under {spec}")
+        # Silence here reads as "everything was processed"; say what was left out.
+        if skipped := len(children) - len(found):
+            print(f"note: skipped {skipped} unsupported file(s) under {spec}", file=sys.stderr)
+        return found
+    return [spec]
+
+
+def resolve_source(
+    spec: str,
+    *,
+    client: NdiClient,
+    workspace_id: str | None = None,
+    file_name: str | None = None,
+    allow_parse_result: bool = True,
+    stdin=None,
+) -> DocumentSource:
+    """Map one spec onto the document-operation source union."""
+    if spec.startswith(JOBID_PREFIX) or _UUID.match(spec or ""):
+        if not allow_parse_result:
+            raise SourceError("classify cannot reuse a parse job; pass a file, URL, upload, or workspace file")
+        raw = spec.removeprefix(JOBID_PREFIX)
+        return ParseResultSource(job_id=_uuid(raw, "jobid://"))
+    if spec.startswith(UPLOAD_PREFIX):
+        return UploadSource(upload_id=_uuid(spec.removeprefix(UPLOAD_PREFIX), "ndi://upload/"))
+    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://")
+        )
+    if spec.startswith(("https://", "http://")):
+        name = file_name or Path(spec.split("?", 1)[0]).name or "document"
+        return UrlSource(url=spec, file_name=name)
+    if spec == "-":
+        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}")
+    try:
+        upload = client.documents.create_upload(path, file_name=file_name or path.name)
+    except OSError as exc:
+        # Unreadable / vanished local files are usage errors, not crashes.
+        raise SourceError(f"cannot read {spec}: {exc.strerror or exc}") from None
+    return UploadSource(upload_id=upload.upload_id)
+
+
+def _from_stdin(client: NdiClient, *, file_name: str | None, allow_parse_result: bool, stdin) -> DocumentSource:
+    stream = stdin if stdin is not None else sys.stdin.buffer
+    raw = stream.read()
+    if not raw:
+        raise SourceError("stdin is empty; pipe a job id or file bytes")
+    text = _as_handle_line(raw)
+    if text is not None:
+        return resolve_source(text, client=client, allow_parse_result=allow_parse_result, file_name=file_name)
+    if not file_name:
+        raise SourceError("stdin bytes need --file-name (or pipe a jobid:// / uuid line)")
+    upload = client.documents.create_upload(raw, file_name=file_name)
+    return UploadSource(upload_id=upload.upload_id)
+
+
+def _as_handle_line(raw: bytes) -> str | None:
+    if b"\0" in raw:
+        return None
+    try:
+        text = raw.decode().strip()
+    except UnicodeDecodeError:
+        return None
+    if "\n" in text:
+        return None
+    if text.startswith(JOBID_PREFIX) or text.startswith(UPLOAD_PREFIX) or text.startswith(WS_PREFIX) or _UUID.match(text):
+        return text
+    return None
+
+
+def _is_handle(spec: str) -> bool:
+    return spec.startswith(("https://", "http://", JOBID_PREFIX, UPLOAD_PREFIX, WS_PREFIX)) or bool(_UUID.match(spec))
+
+
+def _uuid(value: str, kind: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(value)
+    except ValueError as exc:
+        raise SourceError(f"bad {kind} id: {value!r}") from exc

ndi_cli/_tools.py

@@ -0,0 +1,210 @@
+"""The six workspace-tool verbs. Shared with the in-sandbox agent CLI."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ndi_sdk.resources.tools import SyncTools
+
+from ndi_cli import _render
+from ndi_cli.commands import WorkspaceCommand
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    folder = sub.add_parser(
+        WorkspaceCommand.FOLDER_METADATA,
+        parents=[common],
+        help="Orient in one directory: counts, category mix, one page of files.",
+        description=(
+            "Progressive exploration: call on / first (non-recursive), read the subdirectory summaries, then descend "
+            "or narrow. Any narrow implies recursion over the subtree unless --recursive/--no-recursive is explicit."
+        ),
+    )
+    folder.add_argument("directory", nargs="?", default="/", help="Directory to describe (default /).")
+    recursion = folder.add_mutually_exclusive_group()
+    recursion.add_argument("--recursive", dest="recursive", action="store_true", default=None, help="Whole-subtree census.")
+    recursion.add_argument(
+        "--no-recursive", dest="recursive", action="store_false", help="This directory only, even when narrowed."
+    )
+    folder.add_argument("--category", default=None, help="Exact category name from a previous response.")
+    folder.add_argument("--status", default=None, metavar="STATUS", help="Ingestion status narrow (e.g. failed).")
+    folder.add_argument("--kind", default=None, help="Ingestion lane narrow: table, document, or media.")
+    folder.add_argument("--name-contains", default=None, metavar="TEXT", help="Case-insensitive filename/path substring.")
+    folder.add_argument("--page-size", type=int, default=100, help="Listing page size (default 100).")
+    folder.add_argument("--start-after", default=None, metavar="PATH", help="Resume the listing after this path.")
+    folder.add_argument(
+        "--tables",
+        dest="include_tables",
+        action="store_true",
+        help=(
+            "Add the table census: every queryable tab in scope (rows x columns, sql table name) plus "
+            "shared-column join hints (unverified). Scope with a directory or name filter; implies --recursive. "
+            "Read file-metadata for column schemas before writing SQL."
+        ),
+    )
+    folder.set_defaults(
+        run=_run_folder_metadata, render=_render.folder_metadata, family="tool", needs_workspace=True, needs_client=True
+    )
+
+    file_meta = sub.add_parser(
+        WorkspaceCommand.FILE_METADATA,
+        parents=[common],
+        help="What is inside one uploaded file, without opening it.",
+        description=(
+            "Components come back with sizes, extents, summaries, readable/queryable flags saying which content "
+            "tool applies (readable suits read-file; queryable tabs suit run-sql), and each queryable tab's "
+            "sql table name and column schema (names, SQL types, statistics) for writing run-sql directly."
+        ),
+    )
+    file_meta.add_argument("path", help="Uploaded source path (never a derivative).")
+    file_meta.add_argument(
+        "--component", default=None, help="Describe only this tab or section, using its public component name."
+    )
+    file_meta.set_defaults(
+        run=_run_file_metadata, render=_render.file_metadata, family="tool", needs_workspace=True, needs_client=True
+    )
+
+    read = sub.add_parser(
+        WorkspaceCommand.READ_FILE,
+        parents=[common],
+        help="Print the text of one uploaded file.",
+        description=(
+            "Content goes to stdout; a one-line footer (pages, components returned/omitted, truncation) goes to "
+            "stderr. Scope with --component (names from file-metadata) or --pages; images are refused — use ask-file."
+        ),
+    )
+    read.add_argument("path", help="Uploaded source path.")
+    read.add_argument("--component", default=None, help="One tab or section, named as file-metadata lists it.")
+    read.add_argument("--pages", default=None, metavar="SPEC", help="1-based pages, e.g. 3 or 1-5,8. Not for spreadsheets.")
+    read.add_argument("--max-chars", type=int, default=None, help="Character budget for the returned text.")
+    read.set_defaults(run=_run_read_file, render=_render_read_file, family="tool", needs_workspace=True, needs_client=True)
+
+    ask_file = sub.add_parser(
+        WorkspaceCommand.ASK_FILE,
+        parents=[common],
+        help="Ask a question of one document, media, or image file.",
+        description=(
+            "Slow but cited: the engine follows what the file is (vision for images, a recursive reader for long "
+            "text, a QA agent for multi-part files). A whole table file is refused — query its rows with "
+            "run-sql; to ask about one tab's rendered text, pass --component <tab>."
+        ),
+    )
+    ask_file.add_argument("path", help="Uploaded source path.")
+    ask_file.add_argument("query", help="The question, in natural language.")
+    ask_file.add_argument("--component", default=None, help="Scope to one section, named as file-metadata lists it.")
+    ask_file.add_argument("--no-citations", dest="citations", action="store_false", help="Skip citations in the answer.")
+    ask_file.set_defaults(run=_run_ask_file, render=_render.qa_file, family="tool", needs_workspace=True, needs_client=True)
+
+    run_sql = sub.add_parser(
+        WorkspaceCommand.RUN_SQL,
+        parents=[common],
+        help="Run one read-only SELECT over the workspace's tables.",
+        description=(
+            "Fast, no agent in the loop: your SQL runs directly in the guarded engine. Table names come from "
+            "file-metadata (each queryable tab's 'sql table') or 'folder-metadata --tables'; joins across files "
+            "are ordinary SQL joins. The full result is retained as parquet (download link in the reply) and its "
+            "res_... handle is a registered table in your next statement — join it, aggregate it, or page it "
+            "with LIMIT/OFFSET. Non-SELECT statements and unregistered tables are refused with the rule named."
+        ),
+    )
+    run_sql.add_argument("sql", help="One SELECT statement (DuckDB dialect).")
+    run_sql.set_defaults(run=_run_run_sql, render=_render.run_sql, family="tool", needs_workspace=True, needs_client=True)
+
+    search = sub.add_parser(
+        WorkspaceCommand.HYBRID_SEARCH,
+        parents=[common],
+        help="Search the workspace: BM25 + dense vectors fused with RRF.",
+        description=(
+            "The workspace's one search method — exact identifiers and paraphrases in the same call, no retrieval "
+            "knobs. Hits name source files and components; follow up with file-metadata / read-file / ask-file."
+        ),
+    )
+    search.add_argument("query", help="What to look for.")
+    search.add_argument("-k", type=int, default=10, help="Number of hits (default 10).")
+    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)
+
+
+def _run_folder_metadata(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.folder_metadata(
+        workspace_id,
+        directory=args.directory,
+        recursive=args.recursive,
+        category=args.category,
+        ingestion_status=args.status,
+        kind=args.kind,
+        name_contains=args.name_contains,
+        page_size=args.page_size,
+        start_after=args.start_after,
+        include_tables=args.include_tables,
+    )
+
+
+def _run_file_metadata(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.file_metadata(workspace_id, path=args.path, component=args.component)
+
+
+def parse_pages(spec: str | None) -> list[int] | None:
+    if spec is None:
+        return None
+    pages: list[int] = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        start, dash, end = part.partition("-")
+        try:
+            if dash:
+                first, last = int(start), int(end)
+                if first < 1 or last < first:
+                    raise ValueError
+                pages.extend(range(first, last + 1))
+            else:
+                page = int(part)
+                if page < 1:
+                    raise ValueError
+                pages.append(page)
+        except ValueError:
+            raise ValueError(f"bad --pages {spec!r}: use forms like 3 or 1-5,8 (pages are 1-based)") from None
+    return pages or None
+
+
+def _run_read_file(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.read_file(
+        workspace_id,
+        path=args.path,
+        pages=parse_pages(args.pages),
+        component=args.component,
+        max_chars=args.max_chars,
+    )
+
+
+def _render_read_file(response) -> str:
+    print(_render.read_file_footer(response), file=sys.stderr)
+    return response.content
+
+
+def _run_ask_file(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.qa_file(
+        workspace_id,
+        path=args.path,
+        query=args.query,
+        include_citations=args.citations,
+        component=args.component,
+    )
+
+
+def _run_run_sql(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.run_sql(workspace_id, sql=args.sql)
+
+
+def _run_search(tools: SyncTools, workspace_id: str, args: argparse.Namespace):
+    return tools.hybrid_search(
+        workspace_id,
+        query=args.query,
+        k=args.k,
+        path_prefix=args.path_prefix,
+        categories=args.categories,
+    )

ndi_cli/_workspace.py

@@ -0,0 +1,226 @@
+"""Workspace lifecycle, files, ingest, and search jobs."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.credentials import write_config
+from ndi_sdk.models.jobs import Job
+
+from ndi_cli import _render
+from ndi_cli._config import ConfigError, config_path, read_config_values, resolve_settings
+from ndi_cli._jobs import wait_and_report
+from ndi_cli._output import add_job_output_args, emit_text, output_mode
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    workspace = sub.add_parser("workspace", help="Create, list, inspect, or select a workspace.")
+    ws = workspace.add_subparsers(dest="workspace_command", required=True)
+
+    create = ws.add_parser("create", parents=[common], help="Provision a workspace.")
+    create.add_argument("name")
+    create.add_argument("--domain", default="generic", dest="domain_slug")
+    create.set_defaults(run=_run_ws_create, family="workspace", needs_workspace=False, needs_client=True)
+
+    listing = ws.add_parser("list", parents=[common], help="List workspaces.")
+    listing.add_argument("--name-contains", default=None)
+    listing.set_defaults(run=_run_ws_list, family="workspace", needs_workspace=False, needs_client=True)
+
+    get = ws.add_parser("get", parents=[common], help="Read one workspace.")
+    get.add_argument("workspace_id", nargs="?", default=None)
+    get.set_defaults(run=_run_ws_get, family="workspace", needs_workspace=False, needs_client=True)
+
+    stats = ws.add_parser("stats", parents=[common], help="Content summary for a workspace.")
+    stats.add_argument("workspace_id", nargs="?", default=None)
+    stats.set_defaults(run=_run_ws_stats, family="workspace", needs_workspace=False, needs_client=True)
+
+    delete = ws.add_parser("delete", parents=[common], help="Delete a workspace.")
+    delete.add_argument("workspace_id")
+    delete.add_argument("--confirm-name", required=True)
+    add_job_output_args(delete)
+    delete.set_defaults(run=_run_ws_delete, family="workspace", needs_workspace=False, needs_client=True)
+
+    use = ws.add_parser("use", help="Persist a workspace id in ~/.ndi/config.toml.")
+    use.add_argument("workspace_id")
+    use.set_defaults(run=_run_ws_use, family="standalone", needs_workspace=False, needs_client=False)
+
+    files = sub.add_parser("files", help="Upload, list, inspect, or delete workspace files.")
+    fs = files.add_subparsers(dest="files_command", required=True)
+
+    f_upload = fs.add_parser("upload", parents=[common], help="Upload a file into a workspace.")
+    f_upload.add_argument("file")
+    f_upload.add_argument("--path", required=True, help="Workspace destination path.")
+    f_upload.add_argument("--on-conflict", choices=("reject", "new_version"), default="reject")
+    f_upload.add_argument("--ingest", action="store_true", help="Queue ingestion after the upload.")
+    add_job_output_args(f_upload)
+    f_upload.set_defaults(run=_run_files_upload, family="workspace", needs_workspace=True, needs_client=True)
+
+    f_list = fs.add_parser("list", parents=[common], help="List workspace files.")
+    f_list.add_argument("--prefix", default=None, dest="path_prefix")
+    f_list.add_argument("--status", action="append", dest="statuses", default=None)
+    f_list.set_defaults(run=_run_files_list, family="workspace", needs_workspace=True, needs_client=True)
+
+    f_get = fs.add_parser("get", parents=[common], help="Read one file.")
+    f_get.add_argument("file_id")
+    f_get.set_defaults(run=_run_files_get, family="workspace", needs_workspace=True, needs_client=True)
+
+    f_delete = fs.add_parser("delete", parents=[common], help="Delete a file.")
+    f_delete.add_argument("file_id")
+    add_job_output_args(f_delete)
+    f_delete.set_defaults(run=_run_files_delete, family="workspace", needs_workspace=True, needs_client=True)
+
+    ingest = sub.add_parser("ingest", parents=[common], help="Queue ingestion over files or a folder.")
+    ingest.add_argument("--prefix", default=None, dest="path_prefix")
+    ingest.add_argument("--file-id", action="append", dest="file_ids", default=None)
+    ingest.add_argument("--stale-only", action="store_true")
+    add_job_output_args(ingest)
+    ingest.set_defaults(run=_run_ingest, family="workspace", needs_workspace=True, needs_client=True)
+
+    deep = sub.add_parser("deep-search", parents=[common], help="Run an agentic workspace search.")
+    deep.add_argument("query")
+    deep.add_argument("--effort", choices=("low", "medium", "high"), default=None)
+    deep.add_argument("--prefix", default=None, dest="path_prefix")
+    deep.add_argument("--context", default=None)
+    add_job_output_args(deep)
+    deep.set_defaults(run=_run_deep_search, family="workspace", needs_workspace=True, needs_client=True)
+
+    fact = sub.add_parser("fact-search", parents=[common], help="Run the fixed single-shot search pipeline.")
+    fact.add_argument("query")
+    fact.add_argument("--prefix", default=None, dest="path_prefix")
+    fact.add_argument("--top-k", type=int, default=None)
+    fact.add_argument("--context", default=None)
+    add_job_output_args(fact)
+    fact.set_defaults(run=_run_fact_search, 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
+    if not value:
+        raise ConfigError("no workspace: set $NDI_WORKSPACE_ID or pass an id")
+    return value
+
+
+def _dump_or_text(model, args, *, text: str, stem: str) -> int:
+    if output_mode(args) == "json":
+        return emit_text(model.model_dump_json(indent=2, exclude_none=True), args, default_stem=stem, suffix=".json")
+    print(text)
+    return 0
+
+
+def _finish_job(client: NdiClient, job: Job, args: argparse.Namespace, auto, stem: str) -> int:
+    return wait_and_report(client, job, args, auto=auto, stem=stem)
+
+
+def _run_ws_create(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    workspace = client.workspaces.create(name=args.name, domain_slug=args.domain_slug)
+    return _dump_or_text(workspace, args, text=_render.workspace(workspace), stem="workspace")
+
+
+def _run_ws_list(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    page = client.workspaces.list(name_contains=args.name_contains)
+    return _dump_or_text(page, args, text=_render.workspace_page(page), stem="workspaces")
+
+
+def _run_ws_get(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    workspace = client.workspaces.get(_workspace_id(args, workspace_id))
+    return _dump_or_text(workspace, args, text=_render.workspace(workspace), stem="workspace")
+
+
+def _run_ws_stats(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    stats = client.workspaces.stats(_workspace_id(args, workspace_id))
+    return _dump_or_text(stats, args, text=_render.workspace_stats(stats), stem="stats")
+
+
+def _run_ws_delete(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.workspaces.delete(args.workspace_id, confirm_name=args.confirm_name)
+    return _finish_job(client, job, args, _render.job_line, "workspace-delete")
+
+
+def _run_ws_use(args: argparse.Namespace) -> int:
+    if not args.workspace_id.strip():
+        raise ValueError("workspace use needs a workspace id")
+    target = config_path()
+    # Selecting a workspace must not quietly persist whatever credentials happen
+    # to be in the environment: keep the file's own key/url when it has them.
+    stored = read_config_values(target)
+    settings = resolve_settings(require_workspace=False)
+    path = write_config(
+        api_key=stored.get("api_key") or settings.api_key,
+        base_url=stored.get("base_url") or settings.base_url,
+        workspace_id=args.workspace_id.strip(),
+        path=target,
+    )
+    print(f"using workspace {args.workspace_id.strip()} ({path})", file=sys.stderr)
+    return 0
+
+
+def _run_files_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
+    dest = args.path.lstrip("/")
+    if args.ingest:
+        result = client.upload_and_ingest(
+            workspace_id,
+            path,
+            path=dest,
+            on_conflict=args.on_conflict,
+        )
+        print(f"file {result.file.file_id} {result.file.path}", file=sys.stderr)
+        return _finish_job(client, result.ingestion_job, args, _render.ingestion_job, path.stem)
+    job = client.files.upload(workspace_id, path, path=dest, on_conflict=args.on_conflict)
+    return _finish_job(client, job, args, _render.job_line, path.stem)
+
+
+def _run_files_list(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    page = client.files.list(workspace_id, path_prefix=args.path_prefix, ingestion_status=args.statuses)
+    return _dump_or_text(page, args, text=_render.file_page(page), stem="files")
+
+
+def _run_files_get(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    detail = client.files.get(workspace_id, args.file_id)
+    return _dump_or_text(detail, args, text=_render.file_detail(detail), stem="file")
+
+
+def _run_files_delete(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.files.delete(workspace_id, args.file_id)
+    return _finish_job(client, job, args, _render.job_line, "file-delete")
+
+
+def _run_ingest(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    if args.file_ids and args.path_prefix:
+        print("error: pass --prefix or --file-id, not both", file=sys.stderr)
+        return 2
+    job = client.ingestion.ingest(
+        workspace_id,
+        file_ids=args.file_ids,
+        path_prefix=args.path_prefix,
+        stale_only=args.stale_only,
+    )
+    return _finish_job(client, job, args, _render.ingestion_job, "ingest")
+
+
+def _run_deep_search(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.search.deep(
+        workspace_id,
+        query=args.query,
+        context=args.context,
+        effort=args.effort,
+        path_prefix=args.path_prefix,
+    )
+    return _finish_job(client, job, args, _render.search_job, "deep-search")
+
+
+def _run_fact_search(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.search.fact(
+        workspace_id,
+        query=args.query,
+        context=args.context,
+        path_prefix=args.path_prefix,
+        top_k=args.top_k,
+    )
+    return _finish_job(client, job, args, _render.search_job, "fact-search")

ndi_cli/commands.py

@@ -0,0 +1,23 @@
+"""Workspace command identities and their human-facing activity labels."""
+
+from enum import StrEnum
+
+
+class WorkspaceCommand(StrEnum):
+    FOLDER_METADATA = "folder-metadata"
+    FILE_METADATA = "file-metadata"
+    READ_FILE = "read-file"
+    ASK_FILE = "ask-file"
+    RUN_SQL = "run-sql"
+    HYBRID_SEARCH = "hybrid-search"
+
+    @property
+    def activity_label(self) -> str:
+        return {
+            self.FOLDER_METADATA: "Exploring workspace folders",
+            self.FILE_METADATA: "Inspecting file metadata",
+            self.READ_FILE: "Reading file contents",
+            self.ASK_FILE: "Asking about a file",
+            self.RUN_SQL: "Querying tables with SQL",
+            self.HYBRID_SEARCH: "Searching workspace files",
+        }[self]