ndi-cli 0.4.0__py3-none-any.whl

ndi_cli/_render.py

@@ -0,0 +1,679 @@
+"""Compact, deterministic text renderings of the tool responses.
+
+The audience is a coding agent reading terminal output: every fact the
+response carries is either shown or explicitly counted, long free text is
+kept whole (summaries and answers are the payload), and nothing is styled.
+``--json`` on any command bypasses all of this with the raw response.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import html
+import re
+
+from ndi_sdk.models.common import Coverage, Evidence, File
+from ndi_sdk.models.document_ops import ExtractSchemaValidationResponse
+from ndi_sdk.models.files import FileDetail
+from ndi_sdk.models.jobs import (
+    ClassifyResult,
+    DeepSearchV2Result,
+    ExtractResult,
+    GroundResult,
+    IngestionResult,
+    IntelligentSearchResult,
+    Job,
+    ParseResult,
+    SplitResult,
+)
+from ndi_sdk.models.workspaces import Workspace, WorkspaceStats
+from ndi_sdk.models.tools import (
+    FileMetadataToolResponse,
+    FolderMetadataResponse,
+    QaFileResponse,
+    ReadFileResponse,
+    RunSqlResponse,
+    SearchResponse,
+)
+
+_SNIPPET_LIMIT = 500
+
+
+def _size(num_bytes: int) -> str:
+    value = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB"):
+        if value < 1024 or unit == "GB":
+            return f"{value:.1f}{unit}" if unit != "B" else f"{int(value)}B"
+        value /= 1024
+    return f"{int(value)}B"
+
+
+def _clip(text: str, limit: int = _SNIPPET_LIMIT) -> str:
+    text = text.strip()
+    if len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + f"… [{len(text) - limit} more chars, use --json for all]"
+
+
+#: A well-formed closing tag — the trigger for markup collapsing. Prose that
+#: merely contains ``<`` ("x < 5") never matches, so it rides through verbatim.
+_CLOSING_TAG = re.compile(r"</[a-zA-Z][^>]*>")
+_CELL_BOUNDARY = re.compile(r"</(?:td|th|tr)\s*>", re.IGNORECASE)
+#: Tag-like spans only (a letter or ``/`` after ``<``), matching the other two
+#: patterns — an in-cell inequality pair ("a < b and c > d") is content, not
+#: markup, and must survive even after flattening has triggered.
+_TAG = re.compile(r"</?[a-zA-Z][^>]*>")
+#: An unterminated tag opened at the very end — the server's snippet window cut
+#: mid-tag. Requires a letter after ``<``, so a bare trailing ``<`` or ``a < b``
+#: math survives.
+_TRUNCATED_TAG_TAIL = re.compile(r"</?[a-zA-Z][^>]*$")
+_SEPARATOR_RUN = re.compile(r"\|(?:\s*\|)+")
+
+
+def _flatten_markup(text: str) -> str:
+    """Collapse HTML table soup to readable cell text; markup-free text is untouched.
+
+    PDF-table snippets arrive as raw ``</td></tr><tr><td>…`` markup — roughly
+    half the snippet window was tags. Cell/row boundaries become ``" | "``,
+    every other tag becomes whitespace, entities are unescaped, and whitespace
+    is collapsed — so the clipped window carries content, not angle brackets.
+    Text mode only; ``--json`` stays raw.
+    """
+    if not _CLOSING_TAG.search(text):
+        return text
+    text = _TRUNCATED_TAG_TAIL.sub("", text)
+    text = _CELL_BOUNDARY.sub(" | ", text)
+    text = _TAG.sub(" ", text)
+    text = html.unescape(text)
+    text = re.sub(r"\s+", " ", text)
+    text = _SEPARATOR_RUN.sub("|", text)
+    return text.strip(" |")
+
+
+def _coverage_lines(coverage: Coverage) -> list[str]:
+    if coverage.restricted_candidates <= 0:
+        return []
+    labels = f" (labels required: {', '.join(coverage.labels_required)})" if coverage.labels_required else ""
+    lines = [f"note: {coverage.restricted_candidates} candidate(s) withheld by access controls{labels}"]
+    if coverage.request_access_hint:
+        lines.append(f"access: {coverage.request_access_hint}")
+    return lines
+
+
+def _categories(pairs: list, limit: int | None = None) -> str:
+    shown = pairs if limit is None else pairs[:limit]
+    rendered = ", ".join(f"{c.name} x{c.count}" for c in shown)
+    if limit is not None and len(pairs) > limit:
+        rendered += f", +{len(pairs) - limit} more"
+    return rendered
+
+
+def _locator(locator) -> str:
+    """One compact position per locator kind — the part of a citation an agent follows."""
+    match locator.kind:
+        case "spreadsheet_range":
+            return f"{locator.sheet}!{locator.a1_range}"
+        case "text_range":
+            page = f"page {locator.page}, " if locator.page is not None else ""
+            return f"{page}chars {locator.char_start}-{locator.char_end}"
+        case "visual_region":
+            return f"page {locator.page}, bbox {locator.bbox}"
+        case "jsonl_record":
+            column = f" col {locator.column}" if locator.column else ""
+            return f"row {locator.row_offset}{column}"
+        case "audio_range":
+            return f"{locator.start_ms / 1000:.0f}s-{locator.end_ms / 1000:.0f}s"
+    return locator.kind
+
+
+def _evidence_lines(hits: list[Evidence]) -> list[str]:
+    lines: list[str] = []
+    for index, hit in enumerate(hits, start=1):
+        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}")
+        if hit.snippet:
+            lines.append(f"   {_clip(_flatten_markup(hit.snippet))}")
+        if hit.why:
+            lines.append(f"   why: {_clip(hit.why, 300)}")
+    return lines
+
+
+def folder_metadata(response: FolderMetadataResponse) -> str:
+    lines = [f"directory: {response.directory}", f"files in scope: {response.overall_files}"]
+    if response.categories:
+        lines.append(f"categories: {_categories(response.categories)}")
+    if response.ingestion_summary:
+        summary = ", ".join(f"{status} x{count}" for status, count in sorted(response.ingestion_summary.items()))
+        lines.append(f"ingestion: {summary}")
+    if response.subdirectories:
+        lines.append(f"subdirectories ({len(response.subdirectories)}):")
+        for sub in response.subdirectories:
+            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:
+        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:
+            extras = "  ".join(part for part in (entry.category, entry.kind) if part)
+            extras = f"  [{extras}]" if extras else ""
+            uploaded = f"  {entry.uploaded_at:%Y-%m-%d}" if entry.uploaded_at is not None else ""
+            lines.append(f"  {entry.ingestion_status}  {_size(entry.size_bytes):>9}{uploaded}  {entry.path}{extras}")
+    elif response.files_truncated:
+        lines.append("files listed (0) — page cut before any entry; raise --page-size or narrow")
+    if response.hint:
+        lines.append(f"hint: {response.hint}")
+    if response.tables is not None:
+        cut = " (truncated — narrow the directory)" if response.tables_truncated else ""
+        lines.append(f"tables ({len(response.tables)}){cut}:")
+        lines.extend(_census_table_lines(response.tables))
+    if response.shared_columns:
+        sql_names = {(t.path, t.component): t.table_name for t in (response.tables or []) if t.table_name}
+        cut = " (list truncated)" if response.shared_columns_truncated else ""
+        lines.append(f"shared columns — UNVERIFIED join candidates, confirm with one run-sql join{cut}:")
+        for column in response.shared_columns:
+            sides = "; ".join(
+                _join_side(occ, sql_names.get((occ.path, occ.component))) for occ in column.appears_in[:_JOIN_EXAMPLES_MAX]
+            )
+            hidden = column.table_count - min(len(column.appears_in), _JOIN_EXAMPLES_MAX)
+            more = f"; +{hidden} more" if hidden > 0 else ""
+            lines.append(f"  {column.name} in {column.table_count} tables: {sides}{more}")
+    lines.extend(_coverage_lines(response.coverage))
+    return "\n".join(lines)
+
+
+#: Join-candidate examples shown per shared column in text mode.
+_JOIN_EXAMPLES_MAX = 3
+
+#: The partition vocabulary, mirroring je_testing's ``partitions.py``: a
+#: plausible four-digit year (1900–2099) or a ``p``/``P`` part marker (``p1``,
+#: ``P12``), alone between token boundaries. An arbitrary digit run
+#: (``invoice_1001``) is NOT a partition value — masking every digit run
+#: grouped unrelated ids into an invented population.
+_PARTITION_TOKEN = re.compile(r"(?<![A-Za-z0-9])(?:(?:19|20)\d{2}|[pP]\d+)(?![A-Za-z0-9])")
+_COLLISION_SUFFIX = re.compile(r"_\d+$")
+
+
+def _join_side(occ, sql_name: str | None) -> str:
+    """One join-candidate occurrence — named by its sql table when the census knows it."""
+    name = sql_name or f"{occ.path}::{occ.component}"
+    if occ.distinct_count is not None and occ.row_count is not None:
+        return f"{name} (distinct≈{occ.distinct_count}/{occ.row_count} rows)"
+    return name
+
+
+def _norm_name(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_")
+
+
+def _component_redundant(table) -> bool:
+    """True when the component restates the sql name (modulo case/sanitizing/collision suffix) or the file stem."""
+    if not table.table_name:
+        return False
+    component = _norm_name(table.component)
+    name = _norm_name(table.table_name)
+    stem = _norm_name(table.path.rsplit("/", 1)[-1].rsplit(".", 1)[0])
+    return component in (name, _COLLISION_SUFFIX.sub("", name), stem)
+
+
+def _extent(table) -> str:
+    extent = f"{table.row_count} rows" if table.row_count is not None else "rows unknown"
+    if table.column_count is not None:
+        extent += f" x {table.column_count} cols"
+    return extent
+
+
+def _family_key(table) -> tuple[str, str, str] | None:
+    """The partition-family a table belongs to, or None for a standalone table.
+
+    Siblings live in the SAME directory (real corpora nest files under numbered
+    directories, so directory digits never count as partition values) and
+    differ only in partition tokens — years or pN part markers, the
+    :data:`_PARTITION_TOKEN` vocabulary — with the SAME tokens in file stem and
+    sql name. The family line's shared directory + basename pattern plus a
+    member's values therefore reconstruct its exact path. A name whose only
+    digits are ids or a collision suffix carries no partition token and stays a
+    standalone row. A component that is not redundant carries information a
+    family row would hide, so it opts out.
+    """
+    if not table.table_name or not _component_redundant(table):
+        return None
+    values = _PARTITION_TOKEN.findall(table.table_name)
+    directory, _, basename = table.path.rpartition("/")
+    stem, dot, extension = basename.rpartition(".")
+    if not dot:
+        stem = basename
+    if not values or [v.casefold() for v in _PARTITION_TOKEN.findall(stem)] != [v.casefold() for v in values]:
+        return None
+    basename_pattern = _PARTITION_TOKEN.sub("*", stem) + (f".{extension}" if dot else "")
+    return (directory, basename_pattern, _PARTITION_TOKEN.sub("*", table.table_name))
+
+
+def _census_table_lines(tables: list) -> list[str]:
+    """One line per standalone table; partition families grouped under one header.
+
+    Grouping SURFACES the partition structure (the family line names the stem
+    and every partition value) and never hides a member's sql name or
+    rows×cols — those stay printed per member. The redundant ``[component]``
+    middle name is dropped whenever the sql name or file stem already says it.
+    """
+    members_by_family: dict[tuple[str, str, str], list] = {}
+    for table in tables:
+        key = _family_key(table)
+        if key is not None:
+            members_by_family.setdefault(key, []).append(table)
+    families = {key: members for key, members in members_by_family.items() if len(members) > 1}
+    lines: list[str] = []
+    rendered: set[tuple[str, str, str]] = set()
+    for table in tables:
+        key = _family_key(table)
+        if key in families:
+            if key in rendered:
+                continue
+            rendered.add(key)
+            members = families[key]
+            values = ["/".join(_PARTITION_TOKEN.findall(member.table_name)) for member in members]
+            directory, basename_pattern, name_pattern = key
+            path_pattern = f"{directory}/{basename_pattern}" if directory else basename_pattern
+            lines.append(f"  family {name_pattern} (partitions {', '.join(values)}) — {path_pattern}:")
+            lines.extend(f"    {value}: {_extent(member)}  sql: {member.table_name}" for value, member in zip(values, members))
+            continue
+        component = "" if _component_redundant(table) else f" [{table.component}]"
+        sql_name = f"  sql: {table.table_name}" if table.table_name else ""
+        lines.append(f"  {_extent(table)}  {table.path}{component}{sql_name}")
+    return lines
+
+
+def file_metadata(response: FileMetadataToolResponse) -> str:
+    facts = [f"status: {response.ingestion_status}", f"size: {_size(response.size_bytes)}"]
+    if response.kind:
+        facts.insert(0, f"kind: {response.kind}")
+    if response.page_count is not None:
+        facts.append(f"pages: {response.page_count}")
+    if response.tab_count is not None:
+        facts.append(f"tabs: {response.tab_count}")
+    if response.total_chars is not None:
+        facts.append(f"chars: {response.total_chars}")
+    elif response.total_approx_bytes is not None:
+        facts.append(f"~{_size(response.total_approx_bytes)} text")
+    lines = [f"path: {response.path}", " | ".join(facts)]
+    if response.ingestion_error:
+        lines.append(f"ingestion error: {response.ingestion_error}")
+    if response.summary:
+        lines.append(f"summary: {response.summary}")
+    if response.components:
+        lines.append(f"components ({len(response.components)}):")
+        for comp in response.components:
+            if comp.kind == "media":
+                seconds = comp.duration_ms / 1000
+                frames = f", {comp.frame_count} sampled frame(s)" if comp.frame_count else ""
+                lines.append(
+                    f"  [media/{comp.modality}] {seconds:.0f}s, {comp.speaker_count} speaker(s), "
+                    f"{comp.speech_segment_count} speech segment(s){frames} — ask with ask-file"
+                )
+                if comp.summary:
+                    lines.append(f"      {comp.summary}")
+                continue
+            extent: list[str] = []
+            if comp.page_start is not None and comp.page_end is not None:
+                extent.append(f"pages {comp.page_start}-{comp.page_end}")
+            if comp.row_count is not None:
+                cols = f" x {comp.column_count} cols" if comp.column_count is not None else ""
+                extent.append(f"{comp.row_count} rows{cols}")
+            if comp.char_count is not None:
+                extent.append(f"{comp.char_count} chars")
+            elif comp.approx_bytes is not None:
+                extent.append(f"~{_size(comp.approx_bytes)}")
+            abilities = [name for name, flag in (("readable", comp.readable), ("queryable", comp.queryable)) if flag]
+            if comp.table_name:
+                abilities.append(f"sql table: {comp.table_name}")
+            tail = ", ".join(extent + (abilities or ["no content tools apply"]))
+            name = comp.name or "(unnamed)"
+            lines.append(f"  [{comp.kind}] {name} — {tail}")
+            if comp.summary:
+                lines.append(f"      {comp.summary}")
+            if comp.columns:
+                lines.extend(_column_lines(comp.columns, bool(comp.columns_truncated)))
+            if comp.error:
+                lines.append(f"      error: {comp.error}")
+    return "\n".join(lines)
+
+
+#: Census values shown per column in text mode — the full list rides --json.
+_SHOWN_VALUES = 8
+
+
+def _column_lines(columns: list, truncated: bool) -> list[str]:
+    """Render a tab's schema: one dense line per column when stats are present.
+
+    A schema without stats (a sidecar from before profiling measured them)
+    stays a single names+types line, as before.
+    """
+    if not any(col.null_count is not None or col.top_values or col.sample_values for col in columns):
+        rendered = ", ".join(f"{col.name} ({col.data_type})" for col in columns)
+        cut = " …schema truncated" if truncated else ""
+        return [f"      columns ({len(columns)}): {rendered}{cut}"]
+    lines = [f"      columns ({len(columns)}){' …schema truncated' if truncated else ''}:"]
+    # Only the server's own proof (all_null, measured against the profile's exact row
+    # count) groups a column as empty; comparing counts from two sources here could
+    # hide a populated column. getattr: an older server's schema has no such field.
+    empty = [col for col in columns if getattr(col, "all_null", None)]
+    if empty:
+        lines.append("        all-null columns (no values): " + ", ".join(f"{col.name} ({col.data_type})" for col in empty))
+    for col in columns:
+        if col in empty:
+            continue
+        facts: list[str] = []
+        if col.distinct_count is not None:
+            facts.append(f"distinct≈{col.distinct_count}")
+        if col.null_count:
+            facts.append(f"nulls {col.null_count}")
+        if col.sum_value is not None:
+            facts.append(f"sum {col.sum_value}")
+        if col.min_value is not None and col.max_value is not None:
+            facts.append(f"range {col.min_value} .. {col.max_value}")
+        line = f"        {col.name} {col.data_type}" + (f"  {', '.join(facts)}" if facts else "")
+        values = col.top_values or []
+        if values:
+            shown = ", ".join(f"{entry.value} x{entry.count}" for entry in values[:_SHOWN_VALUES])
+            more = len(values) - _SHOWN_VALUES
+            tail = f", +{more} more" if more > 0 else ""
+            coverage = (
+                f" (top {len(values)} cover {col.top_values_coverage:.0%})"
+                if col.top_values_coverage is not None and col.top_values_coverage < 1
+                else ""
+            )
+            line += f"  values: {shown}{tail}{coverage}"
+        elif col.sample_values:
+            shown = ", ".join(col.sample_values[:_SHOWN_VALUES])
+            more = len(col.sample_values) - _SHOWN_VALUES
+            line += f"  values: {shown}" + (f", +{more} more" if more > 0 else "")
+        lines.append(line)
+    return lines
+
+
+def read_file_footer(response: ReadFileResponse) -> str:
+    parts = [f"read {response.path}"]
+    if response.pages_returned:
+        parts.append(f"pages {_page_ranges(response.pages_returned)}")
+    if response.components_returned:
+        parts.append(f"components: {', '.join(response.components_returned)}")
+    if response.components_omitted:
+        parts.append(f"omitted: {', '.join(response.components_omitted)}")
+    if response.truncated:
+        parts.append("TRUNCATED (raise --max-chars, or scope with --component/--pages)")
+    return " | ".join(parts)
+
+
+def _page_ranges(pages: list[int]) -> str:
+    ranges: list[str] = []
+    start = prev = pages[0]
+    for page in pages[1:]:
+        if page == prev + 1:
+            prev = page
+            continue
+        ranges.append(f"{start}-{prev}" if start != prev else str(start))
+        start = prev = page
+    ranges.append(f"{start}-{prev}" if start != prev else str(start))
+    return ",".join(ranges)
+
+
+def qa_file(response: QaFileResponse) -> str:
+    lines = [response.answer.strip(), "", f"engine: {response.engine}"]
+    if response.unavailable:
+        lines.append("unavailable:")
+        lines.extend(f"  {item.path}: {item.error}" for item in response.unavailable)
+    if response.citations:
+        lines.append(f"citations ({len(response.citations)}):")
+        lines.extend(f"  {line}" for line in _evidence_lines(response.citations))
+    return "\n".join(lines)
+
+
+def run_sql(response: RunSqlResponse) -> str:
+    lines: list[str] = []
+    result = response.result
+    cut = ""
+    if result.preview_truncated:
+        # The download hint must not outrun the response: when retention
+        # failed there is no citation and no link to follow.
+        cut = (
+            ", preview truncated (full result via the download link or LIMIT/OFFSET)"
+            if response.result_citation is not None
+            else ", preview truncated (page it with LIMIT/OFFSET)"
+        )
+    dup = " (duplicate — served from the stored result)" if response.duplicate else ""
+    lines.append(f"result table {result.handle} — {result.row_count} rows{cut}{dup}")
+    if result.columns:
+        names = [col.name for col in result.columns]
+        lines.append("  " + " | ".join(f"{col.name} ({col.data_type})" for col in result.columns))
+        if len(set(names)) < len(names):
+            # Object rows keep one value per key, so a duplicated name loses a column
+            # with no visible trace against the header — say so instead.
+            lines.append(
+                "  note: duplicate column names in the result — object rows keep only one value per name; alias duplicates (AS) to see both."
+            )
+        for row in result.rows:
+            # default=str keeps an unvalidated value from a future producer readable
+            # instead of crashing the render.
+            lines.append("  " + json.dumps({name: row.get(name, "") for name in names}, ensure_ascii=False, default=str))
+    lines.append(f"note: '{result.handle}' is a registered table — join or page it in your next run-sql call.")
+    citation = response.result_citation
+    # source_paths rides the response itself; older servers only set it on the
+    # citation, and agent-attributed statements have no citation at all.
+    sources = response.source_paths or (citation.source_paths if citation is not None else [])
+    if sources:
+        lines.append(f"sources: {', '.join(sources)}")
+    if citation is not None:
+        lines.append(f"download (parquet): {citation.result_file.download_url}")
+    if response.result_materialization_error:
+        lines.append(f"note: {response.result_materialization_error}")
+    return "\n".join(lines)
+
+
+def search(response: SearchResponse) -> str:
+    if not response.hits:
+        lines = ["no hits"]
+    else:
+        lines = _evidence_lines(response.hits)
+    tail = f"candidates seen: {response.candidates_seen}"
+    if response.truncated:
+        tail += " (truncated upstream of ranking — a matching file may be missing; narrow with --path-prefix)"
+    lines.append(tail)
+    lines.extend(_coverage_lines(response.coverage))
+    return "\n".join(lines)
+
+
+def parse_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, ParseResult):
+        return job_line(job)
+    print(
+        f"{result.file_name} | {result.document.page_count} pages | lane {result.lane} | "
+        f"ocr_applied={result.ocr_applied} | {result.units} units",
+        file=sys.stderr,
+    )
+    document = result.document
+    if document.markdown or document.text:
+        return document.markdown or document.text or ""
+    # `--format blocks` asks for neither markdown nor text. Returning "" here
+    # threw away the whole result — a 0-byte --save after a billed job.
+    if document.blocks is not None:
+        return json.dumps([block.model_dump(mode="json", exclude_none=True) for block in document.blocks], indent=2)
+    return ""
+
+
+def split_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, SplitResult):
+        return job_line(job)
+    lines = [f"{result.file_name} | {result.page_count} pages | {len(result.segments)} segments | lane {result.lane}"]
+    for segment in result.segments:
+        label = segment.split_class.label if segment.split_class is not None else segment.status
+        pages = f"pages {segment.start_page}-{segment.end_page}" if segment.start_page is not None else "pages ?"
+        sheet = f" sheet {segment.sheet_name}" if segment.sheet_name else ""
+        lines.append(f"  {segment.sequence}. {label} {pages}{sheet}")
+        if segment.content:
+            lines.append(f"     {segment.content}")
+    return "\n".join(lines)
+
+
+def classify_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, ClassifyResult):
+        return job_line(job)
+    lines = [f"units {len(result.units)} | unknown {result.unknown_units} | pages_read {result.pages_read_fraction:.0%}"]
+    for unit in result.units:
+        pages = f" pages {unit.page_range.start}-{unit.page_range.end}" if unit.page_range is not None else ""
+        unknown = " unknown" if unit.unknown else ""
+        lines.append(f"  {unit.granularity}{pages}{unknown}")
+        for label in unit.labels:
+            conf = f" {label.confidence:.2f}" if label.confidence is not None else ""
+            reason = f" — {label.reason}" if label.reason else ""
+            lines.append(f"    {label.rank}. {label.label} ({label.class_id}){conf}{reason}")
+    return "\n".join(lines)
+
+
+def extract_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, ExtractResult):
+        return job_line(job)
+    lines = [json.dumps(result.data, indent=2, ensure_ascii=False, default=str)]
+    if result.fields:
+        lines.append("fields:")
+        for field in result.fields:
+            conf = f" {field.confidence:.2f}" if field.confidence is not None else ""
+            cites = f" citations {len(field.citations)}" if field.citations else ""
+            lines.append(f"  {field.path}: {field.status}{conf}{cites}")
+    if result.warnings:
+        lines.append("warnings:")
+        lines.extend(f"  {warning}" for warning in result.warnings)
+    return "\n".join(lines)
+
+
+def ground_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, GroundResult):
+        return job_line(job)
+    lines = [f"targets {len(result.targets)} | {result.units} units"]
+    for target in result.targets:
+        lines.append(f"  {target.id}: {target.status}")
+        if target.error:
+            lines.append(f"    error: {target.error}")
+        for match in target.matches:
+            conf = f" {match.confidence:.2f}" if match.confidence is not None else ""
+            lines.append(f"    {match.rank}. {match.match_method}{conf} {match.matched_text}")
+    return "\n".join(lines)
+
+
+def schema_validation(result: ExtractSchemaValidationResponse) -> str:
+    if result.valid:
+        return "schema valid"
+    lines = [f"schema invalid ({len(result.errors)} error(s))"]
+    lines.extend(f"  {error.path}: {error.message}" for error in result.errors)
+    return "\n".join(lines)
+
+
+def workspace(item: Workspace) -> str:
+    purpose = f" purpose={item.purpose}" if item.purpose else ""
+    return f"{item.workspace_id}  {item.name}  {item.domain_slug}@{item.domain_version}  {item.status}{purpose}"
+
+
+def workspace_page(page) -> str:
+    lines = [f"workspaces ({page.total_count}):"]
+    lines.extend(f"  {workspace(item)}" for item in page.items)
+    if page.next_cursor:
+        lines.append(f"next: {page.next_cursor}")
+    return "\n".join(lines)
+
+
+def workspace_stats(stats: WorkspaceStats) -> str:
+    statuses = ", ".join(
+        f"{status} x{count}" for status, count in sorted(stats.files_by_ingestion_status.items(), key=lambda pair: str(pair[0]))
+    )
+    lines = [f"files: {stats.files_total}"]
+    if statuses:
+        lines.append(f"ingestion: {statuses}")
+    lines.extend(
+        (
+            f"bytes: {stats.bytes_total}",
+            f"pages ingested: {stats.pages_ingested}",
+            f"index documents: {stats.index_documents}",
+            f"kg: {stats.kg_nodes} nodes / {stats.kg_edges} edges",
+        )
+    )
+    return "\n".join(lines)
+
+
+def file_line(item: File) -> str:
+    return f"{item.ingestion_status}  {_size(item.size_bytes):>9}  {item.path}  {item.file_id}"
+
+
+def file_page(page) -> str:
+    lines = [f"files ({page.total_count}):"]
+    lines.extend(f"  {file_line(item)}" for item in page.items)
+    if page.next_cursor:
+        lines.append(f"next: {page.next_cursor}")
+    return "\n".join(lines)
+
+
+def file_detail(item: FileDetail) -> str:
+    lines = [file_line(item), f"download: {item.download_url}"]
+    if item.category:
+        lines.append(f"category: {item.category}")
+    return "\n".join(lines)
+
+
+def job_line(job: Job) -> str:
+    name = f" {job.name}" if job.name else ""
+    return f"{job.status} {job.kind} {job.job_id}{name}"
+
+
+def job_page(page) -> str:
+    lines = [f"jobs ({page.total_count}):"]
+    lines.extend(f"  {job_line(job)}" for job in page.items)
+    if page.next_cursor:
+        lines.append(f"next: {page.next_cursor}")
+    return "\n".join(lines)
+
+
+def ingestion_job(job: Job) -> str:
+    result = job.result
+    if not isinstance(result, IngestionResult):
+        return job_line(job)
+    lines = [
+        f"ingested {result.files_ingested} | skipped {result.files_skipped} | failed {result.files_failed} | {result.units_total} units"
+    ]
+    for outcome in result.outcomes:
+        extra = f" {outcome.error.message}" if outcome.error else ""
+        lines.append(f"  {outcome.status}  {outcome.path}{extra}")
+    return "\n".join(lines)
+
+
+def search_job(job: Job) -> str:
+    result = job.result
+    if isinstance(result, DeepSearchV2Result):
+        return _search_result(result.answer, result.clarification, result.evidences, receipts=len(result.sql_receipts))
+    if isinstance(result, IntelligentSearchResult):
+        return _search_result(result.answer, result.clarification, result.evidences, receipts=0)
+    return job_line(job)
+
+
+def _search_result(answer: str | None, clarification: str | None, evidences: list, *, receipts: int) -> str:
+    lines: list[str] = []
+    if clarification:
+        lines.append(f"clarification: {clarification}")
+    if answer:
+        lines.append(answer.strip())
+    lines.append(f"evidences ({len(evidences)}):")
+    for index, evidence in enumerate(evidences, start=1):
+        page = f", page {evidence.page}" if evidence.page is not None else ""
+        lines.append(f"{index}. {evidence.source_path}{page}")
+        if evidence.quote:
+            lines.append(f"   {evidence.quote}")
+    if receipts:
+        lines.append(f"receipts: {receipts}")
+    return "\n".join(lines)