ndi-cli 0.4.0__py3-none-any.whl

ndi_cli/_docops.py

@@ -0,0 +1,443 @@
+"""Document operations: upload, parse, extract, split, classify, ground."""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import sys
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.models.document_ops import (
+    ClassifyClass,
+    ExtractCitationOptions,
+    GroundOptions,
+    GroundTarget,
+    ParseChunkingOptions,
+    ParseFiguresOptions,
+    ParseOutputOptions,
+    ParseSpreadsheetOptions,
+    SplitCategory,
+    SplitOutputOptions,
+)
+from ndi_sdk.models.jobs import Job
+
+from ndi_cli import _render
+from ndi_cli._jobs import wait_and_report
+from ndi_cli._output import add_job_output_args, output_mode
+from ndi_cli._sources import SourceError, collect_specs, resolve_source
+from ndi_cli._tools import parse_pages
+
+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)
+
+    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.")
+    parse.add_argument("--mode", choices=("low", "medium", "high"), default="low")
+    parse.add_argument("--format", dest="formats", default=None, help="Comma list: markdown,text,blocks.")
+    parse.add_argument("--table-format", choices=("html", "markdown"), default="html")
+    parse.add_argument("--chunk", choices=("none", "page", "section"), default="none")
+    parse.add_argument("--figures", choices=("omit", "include", "describe"), default="describe")
+    parse.add_argument("--sheets", default=None, help="Comma-separated workbook sheet names.")
+    parse.add_argument("--password", default=None, help="PDF password. Never stored.")
+    parse.set_defaults(run=_run_parse, family="docops", needs_workspace=False, needs_client=True)
+
+    extract = sub.add_parser("extract", parents=[common], help="Pull structured data against a JSON Schema.")
+    _add_source_args(extract, required=False)
+    extract.add_argument("-s", "--schema", default=None, help="Schema file path or inline JSON object.")
+    extract.add_argument("--schema-id", default=None, help="Saved schema id.")
+    extract.add_argument("--instructions", default=None)
+    extract.add_argument("-p", "--pages", default=None, metavar="SPEC")
+    extract.add_argument("--no-citations", dest="citations", action="store_false")
+    extract.add_argument("--validate", action="store_true", help="Check the schema without creating a job.")
+    extract.set_defaults(run=_run_extract, family="docops", needs_workspace=False, needs_client=True)
+
+    split = sub.add_parser("split", parents=[common], help="Find logical sections of a document.")
+    _add_source_args(split)
+    _add_class_args(split)
+    split.add_argument("--unknown", choices=("include", "force", "error"), default="include")
+    split.add_argument("-p", "--pages", default=None, metavar="SPEC")
+    split.add_argument("--include-content", action="store_true")
+    split.set_defaults(run=_run_split, family="docops", needs_workspace=False, needs_client=True)
+
+    classify = sub.add_parser("classify", parents=[common], help="Label a document against your classes.")
+    _add_source_args(classify)
+    _add_class_args(classify)
+    classify.add_argument("--granularity", choices=("document", "page"), default="document")
+    classify.add_argument("--unknown", choices=("allow", "force_best"), default="allow")
+    classify.set_defaults(run=_run_classify, family="docops", needs_workspace=False, needs_client=True)
+
+    ground = sub.add_parser("ground", parents=[common], help="Locate quoted text back in the source.")
+    _add_source_args(ground)
+    ground.add_argument("--target", action="append", dest="targets", default=None, help="id=TEXT; repeatable.")
+    ground.add_argument("--targets", dest="targets_file", default=None, help="JSON array of targets.")
+    ground.add_argument("--max-matches", type=int, default=10)
+    ground.add_argument("--previews", action="store_true")
+    ground.set_defaults(run=_run_ground, family="docops", needs_workspace=False, needs_client=True)
+
+
+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("--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)
+
+
+def _add_class_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--class", action="append", dest="classes", default=None, help="id:label[:description]; repeatable.")
+    parser.add_argument("--classes", dest="classes_file", default=None, help="JSON array of classes.")
+
+
+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)
+    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
+
+
+def _run_parse(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    formats = args.formats.split(",") if args.formats else None
+    sheets = [name.strip() for name in args.sheets.split(",") if name.strip()] if args.sheets else None
+    output = ParseOutputOptions(formats=formats or ["markdown", "blocks"], table_format=args.table_format)
+    return _run_over_sources(
+        client,
+        workspace_id,
+        args,
+        allow_parse_result=True,
+        submit=lambda source: client.documents.parse(
+            source,
+            page_ranges=_page_ranges(args.pages),
+            parse_mode=args.mode,
+            output=output,
+            figures=ParseFiguresOptions(mode=args.figures),
+            chunking=ParseChunkingOptions(strategy=args.chunk),
+            spreadsheet=ParseSpreadsheetOptions(sheets=sheets) if sheets is not None else None,
+            password=args.password,
+        ),
+        auto=_render.parse_job,
+    )
+
+
+def _run_extract(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    schema, schema_id = _load_schema(args)
+    if args.validate:
+        result = client.documents.validate_extract_schema(json_schema=schema, schema_id=schema_id)
+        text = (
+            result.model_dump_json(indent=2, exclude_none=True)
+            if output_mode(args) == "json"
+            else _render.schema_validation(result)
+        )
+        print(text)
+        return 0 if result.valid else 1
+    if not args.source:
+        print("error: extract needs a SOURCE (or --validate)", file=sys.stderr)
+        return 2
+    return _run_over_sources(
+        client,
+        workspace_id,
+        args,
+        allow_parse_result=True,
+        submit=lambda source: client.documents.extract(
+            source,
+            json_schema=schema,
+            schema_id=schema_id,
+            instructions=args.instructions,
+            page_ranges=_page_ranges(args.pages),
+            citations=ExtractCitationOptions(enabled=args.citations),
+        ),
+        auto=_render.extract_job,
+    )
+
+
+def _run_split(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    classes = _load_split_classes(args)
+    return _run_over_sources(
+        client,
+        workspace_id,
+        args,
+        allow_parse_result=True,
+        submit=lambda source: client.documents.split(
+            source,
+            classes=classes,
+            unknown_policy=args.unknown,
+            page_ranges=_page_ranges(args.pages),
+            output=SplitOutputOptions(include_content=args.include_content),
+        ),
+        auto=_render.split_job,
+    )
+
+
+def _run_classify(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    classes = _load_classify_classes(args)
+    return _run_over_sources(
+        client,
+        workspace_id,
+        args,
+        allow_parse_result=False,
+        submit=lambda source: client.documents.classify(
+            source,
+            classes=classes,
+            granularity=args.granularity,
+            unknown_policy=args.unknown,
+        ),
+        auto=_render.classify_job,
+    )
+
+
+def _run_ground(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    targets = _load_targets(args)
+    options = GroundOptions(max_matches=args.max_matches, include_previews=args.previews)
+    return _run_over_sources(
+        client,
+        workspace_id,
+        args,
+        allow_parse_result=True,
+        submit=lambda source: client.documents.ground(source, targets=targets, options=options),
+        auto=_render.ground_job,
+    )
+
+
+def _run_over_sources(
+    client: NdiClient,
+    workspace_id: str,
+    args: argparse.Namespace,
+    *,
+    allow_parse_result: bool,
+    submit: Callable,
+    auto: Callable[[Job], str],
+) -> int:
+    try:
+        specs = collect_specs(args.source)
+    except SourceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if len(specs) == 1:
+        return _one(
+            client,
+            workspace_id,
+            args,
+            specs[0],
+            stem=_stem_for(specs[0]),
+            allow_parse_result=allow_parse_result,
+            submit=submit,
+            auto=auto,
+        )
+    if getattr(args, "save", None):
+        print("error: --save is for one input; use --out-dir for a directory", file=sys.stderr)
+        return 2
+    if getattr(args, "file_name", None):
+        # One name across many inputs would relabel every upload identically.
+        print("error: --file-name is for one input; it cannot name every file of a directory", file=sys.stderr)
+        return 2
+    stems = _out_stems(specs)
+    workers = max(1, args.parallel)
+    code = 0
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = [
+            pool.submit(
+                _one,
+                client,
+                workspace_id,
+                args,
+                spec,
+                stem=stems[spec],
+                allow_parse_result=allow_parse_result,
+                submit=submit,
+                auto=auto,
+            )
+            for spec in specs
+        ]
+        for future in as_completed(futures):
+            result = future.result()
+            if result != 0:
+                code = result
+    return code
+
+
+def _stem_for(spec: str) -> str:
+    return "stdin" if spec == "-" else Path(spec).stem
+
+
+def _out_stems(specs: list[str]) -> dict[str, str]:
+    """Give every input its own ``--out-dir`` file name.
+
+    ``Path(spec).stem`` alone collides for ``a/report.pdf`` + ``b/report.csv``,
+    and the later job silently overwrites the earlier one's result — work that
+    was already submitted and paid for. Disambiguate with the parent directory
+    and the extension, then with a counter, so one input never destroys another.
+    """
+    counts = collections.Counter(_stem_for(spec) for spec in specs)
+    taken: set[str] = set()
+    stems: dict[str, str] = {}
+    for spec in specs:
+        base = _stem_for(spec)
+        if counts[base] > 1:
+            path = Path(spec)
+            parent = path.parent.name
+            suffix = path.suffix.lstrip(".")
+            base = "-".join(part for part in (parent, path.stem, suffix) if part)
+        candidate, index = base, 2
+        while candidate in taken:
+            candidate = f"{base}-{index}"
+            index += 1
+        taken.add(candidate)
+        stems[spec] = candidate
+    return stems
+
+
+def _one(
+    client: NdiClient,
+    workspace_id: str,
+    args: argparse.Namespace,
+    spec: str,
+    *,
+    stem: str,
+    allow_parse_result: bool,
+    submit: Callable,
+    auto: Callable[[Job], str],
+) -> int:
+    try:
+        source = resolve_source(
+            spec,
+            client=client,
+            workspace_id=workspace_id or None,
+            file_name=args.file_name,
+            allow_parse_result=allow_parse_result,
+        )
+        job = submit(source)
+    except SourceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return wait_and_report(client, job, args, auto=auto, stem=stem)
+
+
+def _page_ranges(spec: str | None):
+    pages = parse_pages(spec)
+    if not pages:
+        return None
+    from ndi_sdk.models.document_ops import PageRange
+
+    ranges = []
+    start = prev = pages[0]
+    for page in pages[1:]:
+        if page == prev + 1:
+            prev = page
+            continue
+        ranges.append(PageRange(start=start, end=prev))
+        start = prev = page
+    ranges.append(PageRange(start=start, end=prev))
+    return ranges
+
+
+def _read_json_flag(path: str, flag: str):
+    """Read a JSON file named by a flag, turning every failure into a usage error.
+
+    ``read_text``/``json.loads`` raise OSError and JSONDecodeError. Only the
+    latter is a ValueError, so without this the CLI exits 1 with a traceback on
+    an ordinary path typo instead of the documented exit 2.
+    """
+    try:
+        raw = Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"cannot read {flag} {path!r}: {exc.strerror or exc}") from None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{flag} {path!r} is not valid JSON: {exc}") from None
+
+
+def _load_schema(args: argparse.Namespace) -> tuple[dict | None, str | None]:
+    # Treat an empty flag value as absent so `--schema-id ''` is a usage error
+    # rather than an AttributeError on the other branch.
+    schema = args.schema.strip() if isinstance(args.schema, str) else args.schema
+    schema_id = args.schema_id.strip() if isinstance(args.schema_id, str) else args.schema_id
+    if not schema:
+        schema = None
+    if not schema_id:
+        schema_id = None
+    if (schema is None) == (schema_id is None):
+        raise ValueError("pass exactly one of -s/--schema or --schema-id")
+    if schema_id:
+        return None, schema_id
+    if schema.startswith("{"):
+        try:
+            parsed = json.loads(schema)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"-s/--schema is not valid JSON: {exc}") from None
+    else:
+        parsed = _read_json_flag(schema, "-s/--schema")
+    if not isinstance(parsed, dict):
+        raise ValueError(f"-s/--schema must be a JSON object, got {type(parsed).__name__}")
+    return parsed, None
+
+
+def _load_split_classes(args: argparse.Namespace) -> list[SplitCategory]:
+    raw = _load_class_items(args)
+    return [SplitCategory.model_validate(item) if isinstance(item, dict) else _split_class_flag(item) for item in raw]
+
+
+def _load_classify_classes(args: argparse.Namespace) -> list[ClassifyClass]:
+    raw = _load_class_items(args)
+    return [ClassifyClass.model_validate(item) if isinstance(item, dict) else _classify_class_flag(item) for item in raw]
+
+
+def _load_targets(args: argparse.Namespace) -> list[GroundTarget]:
+    if args.targets_file:
+        items = _read_json_flag(args.targets_file, "--targets")
+        if not isinstance(items, list):
+            raise ValueError(f"--targets {args.targets_file!r} must hold a JSON array, got {type(items).__name__}")
+        return [GroundTarget.model_validate(item) for item in items]
+    if not args.targets:
+        raise ValueError("pass --target id=TEXT or --targets FILE.json")
+    return [_target_flag(item) for item in args.targets]
+
+
+def _load_class_items(args: argparse.Namespace) -> list:
+    if args.classes_file:
+        items = _read_json_flag(args.classes_file, "--classes")
+        # Without this a JSON object iterates as its keys, and each key is then
+        # reported as a bogus `bad --class '<key>'` the user never typed.
+        if not isinstance(items, list):
+            raise ValueError(f"--classes {args.classes_file!r} must hold a JSON array, got {type(items).__name__}")
+        return items
+    if args.classes:
+        return args.classes
+    raise ValueError("pass --class id:label or --classes FILE.json")
+
+
+def _split_class_flag(text: str) -> SplitCategory:
+    ident, _, rest = text.partition(":")
+    if not rest:
+        raise ValueError(f"bad --class {text!r}: use id:label[:description]")
+    label, _, description = rest.partition(":")
+    return SplitCategory(id=ident, label=label, description=description)
+
+
+def _classify_class_flag(text: str) -> ClassifyClass:
+    ident, _, rest = text.partition(":")
+    if not rest:
+        raise ValueError(f"bad --class {text!r}: use id:label[:description]")
+    label, _, description = rest.partition(":")
+    return ClassifyClass(id=ident, label=label, description=description)
+
+
+def _target_flag(text: str) -> GroundTarget:
+    ident, sep, body = text.partition("=")
+    if not sep or not body:
+        raise ValueError(f"bad --target {text!r}: use id=TEXT")
+    return GroundTarget(id=ident, text=body)

ndi_cli/_jobs.py

@@ -0,0 +1,106 @@
+"""Job inspect / list / cancel, plus the wait used by every job-returning verb."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import uuid
+from collections.abc import Callable
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.errors import JobFailedError, JobTimeoutError
+from ndi_sdk.models.jobs import Job
+from ndi_sdk.resources.jobs import check_terminal
+
+from ndi_cli import _render
+from ndi_cli._output import add_job_output_args, emit_text, output_mode, render_job
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    job = sub.add_parser("job", parents=[common], help="Read one job by id.")
+    job.add_argument("job_id", help="Job UUID.")
+    add_job_output_args(job)
+    job.set_defaults(run=_run_get, family="job", needs_workspace=False, needs_client=True)
+
+    jobs = sub.add_parser("jobs", parents=[common], help="List recent jobs.")
+    jobs.add_argument("--kind", action="append", dest="kinds", default=None, help="Kind filter; repeatable.")
+    jobs.add_argument("--status", action="append", dest="statuses", default=None, help="Status filter; repeatable.")
+    jobs.add_argument("--limit", type=int, default=None, help="Page size.")
+    add_job_output_args(jobs)
+    jobs.set_defaults(run=_run_list, family="job", needs_workspace=False, needs_client=True)
+
+    cancel = sub.add_parser("cancel", parents=[common], help="Cancel a queued or running job.")
+    cancel.add_argument("job_id", help="Job UUID.")
+    cancel.add_argument("--reason", default=None, help="Optional cancellation reason.")
+    add_job_output_args(cancel)
+    cancel.set_defaults(run=_run_cancel, family="job", needs_workspace=False, needs_client=True)
+
+
+def wait_and_report(
+    client: NdiClient,
+    job: Job,
+    args: argparse.Namespace,
+    *,
+    auto: Callable[[Job], str],
+    stem: str,
+) -> int:
+    print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    if getattr(args, "async_submit", False):
+        print(job.job_id)
+        return 0
+    try:
+        if job.is_terminal:
+            check_terminal(job, raise_on_failure=True)
+        else:
+            job = client.jobs.wait(job.job_id, timeout=args.timeout)
+    except JobFailedError as exc:
+        code = f" [{exc.job.error.code}]" if exc.job.error and exc.job.error.code else ""
+        print(f"error:{code} {exc}", file=sys.stderr)
+        return 1
+    except JobTimeoutError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print(exc.job.job_id)
+        return 1
+    print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    return render_job(job, args, auto=auto, stem=stem)
+
+
+def _job_uuid(value: str) -> str:
+    """Reject anything that is not a job UUID.
+
+    The id is interpolated straight into the request path, so a value holding
+    ``/`` or ``?`` addresses a different endpoint entirely.
+    """
+    try:
+        return str(uuid.UUID(value.strip()))
+    except (AttributeError, ValueError):
+        raise ValueError(f"bad job id: {value!r}") from None
+
+
+def _run_get(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.jobs.get(_job_uuid(args.job_id))
+    return render_job(job, args, auto=lambda item: _render.job_line(item), stem="job")
+
+
+def _run_list(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    page = client.jobs.list(
+        workspace_id=args.workspace or None,
+        kind=args.kinds,
+        status=args.statuses,
+        limit=args.limit,
+    )
+    mode = output_mode(args)
+    if mode == "json":
+        return emit_text(page.model_dump_json(indent=2, exclude_none=True), args, default_stem="jobs", suffix=".json")
+    if mode in ("md", "payload", "id"):
+        # A listing is not a job, so these shapes have nothing to render. Say so
+        # instead of silently printing the default listing.
+        print(f"error: -o {mode} is not available for `jobs`; use auto or json", file=sys.stderr)
+        return 2
+    # Route through emit_text so --save / --out-dir work here as they do elsewhere.
+    return emit_text(_render.job_page(page), args, default_stem="jobs", suffix=".txt")
+
+
+def _run_cancel(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    job = client.jobs.cancel(_job_uuid(args.job_id), reason=args.reason)
+    return render_job(job, args, auto=lambda item: _render.job_line(item), stem="job")

ndi_cli/_local.py

@@ -0,0 +1,130 @@
+"""Worker-local transport for the existing CLI and SDK command implementations.
+
+The socket is scoped to one shell activity. It carries typed commands, never an
+API key or a caller-selected job/workspace. Every request also carries the
+activity's connection token (``NDI_CLI_TOKEN``): the socket lives in a
+same-UID-only directory, but worker processes share one UID, so the token is
+what stops a command reaching a *sibling* activity's socket and running under
+that job's scope. Rendering remains in ``_cli``.
+"""
+
+from __future__ import annotations
+
+import socket
+from typing import Annotated, Literal, TypeVar
+
+from ndi_sdk.errors import ErrorBody, NdiConnectionError, NdiTimeoutError, error_class_for
+from ndi_sdk.models.tools import (
+    FileMetadataRequest,
+    FolderMetadataRequest,
+    QaFileRequest,
+    ReadFileRequest,
+    RunSqlRequest,
+    SearchRequest,
+)
+from pydantic import BaseModel, Field, TypeAdapter
+
+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)
+
+
+class FolderCommand(BaseModel):
+    command: Literal[WorkspaceCommand.FOLDER_METADATA] = WorkspaceCommand.FOLDER_METADATA
+    body: FolderMetadataRequest
+
+
+class FileCommand(BaseModel):
+    command: Literal[WorkspaceCommand.FILE_METADATA] = WorkspaceCommand.FILE_METADATA
+    body: FileMetadataRequest
+
+
+class ReadCommand(BaseModel):
+    command: Literal[WorkspaceCommand.READ_FILE] = WorkspaceCommand.READ_FILE
+    body: ReadFileRequest
+
+
+class AskCommand(BaseModel):
+    command: Literal[WorkspaceCommand.ASK_FILE] = WorkspaceCommand.ASK_FILE
+    body: QaFileRequest
+
+
+class SqlCommand(BaseModel):
+    command: Literal[WorkspaceCommand.RUN_SQL] = WorkspaceCommand.RUN_SQL
+    body: RunSqlRequest
+
+
+class SearchCommand(BaseModel):
+    command: Literal[WorkspaceCommand.HYBRID_SEARCH] = WorkspaceCommand.HYBRID_SEARCH
+    body: SearchRequest
+
+
+Command = Annotated[
+    FolderCommand | FileCommand | ReadCommand | AskCommand | SqlCommand | SearchCommand, Field(discriminator="command")
+]
+COMMAND = TypeAdapter(Command)
+
+
+class CommandEnvelope(BaseModel):
+    """One request line on the socket: the owning run's token plus its command."""
+
+    token: str
+    command: Command
+
+
+class CommandSuccess(BaseModel):
+    kind: Literal["success"] = "success"
+    result_json: str
+
+
+class CommandFailure(BaseModel):
+    kind: Literal["failure"] = "failure"
+    status: int
+    error: ErrorBody
+
+
+REPLY = TypeAdapter(Annotated[CommandSuccess | CommandFailure, Field(discriminator="kind")])
+
+
+class LocalTransport:
+    """Dispatch SDK tool requests to the activity that owns the shell subprocess."""
+
+    def __init__(self, path: str, timeout: float, token: str = "") -> None:
+        self.path = path
+        self.timeout = timeout
+        self.token = token
+
+    def request_model(self, model: type[ModelT], method: str, path: str, **kwargs: object) -> ModelT:
+        body = kwargs.get("body")
+        if method != "POST" or not isinstance(body, BaseModel):
+            raise ValueError("The internal CLI accepts workspace commands only.")
+        name = path.rsplit("/", 1)[-1]
+        command = WorkspaceCommand.ASK_FILE if name == "qa-file" else WorkspaceCommand(name)
+        request = CommandEnvelope(
+            token=self.token,
+            command=COMMAND.validate_python({"command": command, "body": body.model_dump(exclude_none=True)}),
+        )
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+                connection.settimeout(self.timeout)
+                connection.connect(self.path)
+                connection.sendall(request.model_dump_json().encode() + b"\n")
+                with connection.makefile("rb") as stream:
+                    # Match the HTTP transport: service/renderer budgets own
+                    # truncation; the transport must preserve the complete result.
+                    raw = stream.readline()
+            if not raw.endswith(b"\n"):
+                raise NdiConnectionError("The internal CLI returned an incomplete response.")
+        except TimeoutError as exc:
+            raise NdiTimeoutError(str(exc)) from exc
+        except OSError as exc:
+            raise NdiConnectionError("The internal CLI connection closed.") from exc
+        reply = REPLY.validate_json(raw)
+        if isinstance(reply, CommandFailure):
+            # The same typed exception the HTTP transport would raise for this
+            # status, so callers handle both transports identically.
+            raise error_class_for(reply.status)(status_code=reply.status, message=reply.error.message, body=reply.error)
+        return model.model_validate_json(reply.result_json)