ndi-cli 0.4.0__tar.gz

ndi_cli-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nace AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ndi_cli-0.4.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: ndi-cli
+Version: 0.4.0
+Summary: NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools
+Keywords: ndi,cli,document-intelligence,coding-agents
+Author: Nace AI
+Author-email: Nace AI <engineering@nace.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: ndi-sdk>=0.20,<1
+Requires-Python: >=3.11, <3.14
+Project-URL: Homepage, https://ndi-api.nace.ai
+Description-Content-Type: text/markdown
+
+# ndi-cli
+
+`ndi` — the NDI platform CLI. Document operations, jobs, and workspace
+lifecycle wrap the same `/v1` methods as `ndi-sdk`. The six workspace tools
+also run inside an agent sandbox; every other verb is refused there.
+
+## Setup
+
+```bash
+ndi login                                          # browser device-code; writes ~/.ndi/config.toml
+export NDI_BASE_URL="https://ndi-api.nace.ai"      # optional; default shown
+export NDI_WORKSPACE_ID="<workspace uuid>"         # or: ndi workspace use <id>
+```
+
+`$NDI_API_KEY` still wins over the file. `$NDI_CONFIG_PATH` overrides the
+config location. Workspace-scoped verbs also take `--workspace ID`.
+
+## Commands
+
+| Command | Use |
+|---|---|
+| `ndi login` | Authorize and save the API key |
+| `ndi version` | CLI + SDK versions |
+| `ndi upload FILE` | Stage bytes; prints `ndi://upload/<id>` |
+| `ndi parse SOURCE` | Markdown / text / blocks |
+| `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
+| `ndi split SOURCE --class id:label` | Logical sections |
+| `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
+| `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
+| `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 folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
+
+## Sources
+
+`SOURCE` for document ops:
+
+- local file — uploaded, then the handle is used
+- directory — supported files, one job each (`-j N`, default 4)
+- `https://...` — fetched by the server
+- `ndi://upload/<uuid>` — a prior `ndi upload`
+- `jobid://<uuid>` or a bare UUID — reuse a parse job (not classify)
+- `ws://<file_id>` — a workspace file (needs a workspace)
+- `-` — a `jobid://` / UUID line, or raw bytes with `--file-name`
+
+```bash
+ndi parse a.pdf -o id | ndi extract - -s schema.json
+```
+
+## Output
+
+Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
+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.
+
+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.

ndi_cli-0.4.0/README.md

@@ -0,0 +1,64 @@
+# ndi-cli
+
+`ndi` — the NDI platform CLI. Document operations, jobs, and workspace
+lifecycle wrap the same `/v1` methods as `ndi-sdk`. The six workspace tools
+also run inside an agent sandbox; every other verb is refused there.
+
+## Setup
+
+```bash
+ndi login                                          # browser device-code; writes ~/.ndi/config.toml
+export NDI_BASE_URL="https://ndi-api.nace.ai"      # optional; default shown
+export NDI_WORKSPACE_ID="<workspace uuid>"         # or: ndi workspace use <id>
+```
+
+`$NDI_API_KEY` still wins over the file. `$NDI_CONFIG_PATH` overrides the
+config location. Workspace-scoped verbs also take `--workspace ID`.
+
+## Commands
+
+| Command | Use |
+|---|---|
+| `ndi login` | Authorize and save the API key |
+| `ndi version` | CLI + SDK versions |
+| `ndi upload FILE` | Stage bytes; prints `ndi://upload/<id>` |
+| `ndi parse SOURCE` | Markdown / text / blocks |
+| `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
+| `ndi split SOURCE --class id:label` | Logical sections |
+| `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
+| `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
+| `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 folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
+
+## Sources
+
+`SOURCE` for document ops:
+
+- local file — uploaded, then the handle is used
+- directory — supported files, one job each (`-j N`, default 4)
+- `https://...` — fetched by the server
+- `ndi://upload/<uuid>` — a prior `ndi upload`
+- `jobid://<uuid>` or a bare UUID — reuse a parse job (not classify)
+- `ws://<file_id>` — a workspace file (needs a workspace)
+- `-` — a `jobid://` / UUID line, or raw bytes with `--file-name`
+
+```bash
+ndi parse a.pdf -o id | ndi extract - -s schema.json
+```
+
+## Output
+
+Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
+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.
+
+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.

ndi_cli-0.4.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "ndi-cli"
+version = "0.4.0"
+description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.14"
+keywords = [
+    "ndi",
+    "cli",
+    "document-intelligence",
+    "coding-agents",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["ndi-sdk>=0.20,<1"]
+
+[[project.authors]]
+name = "Nace AI"
+email = "engineering@nace.ai"
+
+[project.urls]
+Homepage = "https://ndi-api.nace.ai"
+
+[project.scripts]
+ndi = "ndi_cli._cli:main"
+
+[tool.uv.sources.ndi-sdk]
+workspace = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 130
+fix = true
+
+[tool.ruff.lint]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [
+    "src",
+    "tests",
+]
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+]
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.0.0,<2",
+    "pytest>=8.4.0",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"

ndi_cli-0.4.0/pyproject.toml.orig

@@ -0,0 +1,67 @@
+[project]
+name = "ndi-cli"
+version = "0.4.0"
+description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
+authors = [
+    { name = "Nace AI", email = "engineering@nace.ai" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.14"
+keywords = [
+    "ndi",
+    "cli",
+    "document-intelligence",
+    "coding-agents",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ndi-sdk>=0.20,<1",
+]
+
+[project.urls]
+Homepage = "https://ndi-api.nace.ai"
+
+[project.scripts]
+ndi = "ndi_cli._cli:main"
+
+[tool.uv.sources]
+ndi-sdk = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.0.0,<2",
+    "pytest>=8.4.0",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 130
+fix = true
+
+[tool.ruff.lint]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+addopts = ["--strict-markers", "--tb=short"]

ndi_cli-0.4.0/src/ndi_cli/__init__.py

@@ -0,0 +1,9 @@
+"""``ndi`` — the NDI platform CLI.
+
+Document operations, jobs, and workspace lifecycle wrap ``ndi-sdk`` ``/v1``
+methods. The six workspace tools (``folder-metadata``, ``file-metadata``,
+``read-file``, ``ask-file``, ``run-sql``, ``hybrid-search``) remain the
+in-sandbox surface.
+"""
+
+__version__ = "0.4.0"

ndi_cli-0.4.0/src/ndi_cli/_cli.py

@@ -0,0 +1,166 @@
+"""``ndi`` entry point: workspace tools plus the platform verbs.
+
+The six workspace tools stay available inside an agent sandbox. Every other
+verb is refused when ``$NDI_CLI_SOCKET`` is set, before any client is built.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.errors import NdiError, NdiStatusError
+from ndi_sdk.resources.tools import SyncTools
+
+from ndi_cli import _docops, _jobs, _login, _tools, _workspace
+from ndi_cli._config import ConfigError, resolve_settings
+from ndi_cli._local import SOCKET_ENV, TOKEN_ENV, LocalTransport
+from ndi_cli._tools import parse_pages
+
+# qa-file runs a durable workflow that legitimately takes minutes; the metadata,
+# read, and run-sql tools answer in seconds but share the generous bound.
+DEFAULT_TIMEOUT_SECONDS = 900.0
+_VALIDATION_ERROR_LIMIT = 5
+_VALIDATION_ERROR_CHARS = 500
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    family = getattr(args, "family", None)
+    socket_path = os.environ.get(SOCKET_ENV)
+    # Presence, not truthiness: an empty $NDI_CLI_SOCKET still means "inside an
+    # agent run", and must not silently unlock the full platform CLI.
+    in_agent_run = socket_path is not None
+    workspace_flag = getattr(args, "workspace", None)
+    if workspace_flag is not None and not workspace_flag.strip():
+        print("error: --workspace needs a workspace id", file=sys.stderr)
+        return 2
+    if in_agent_run:
+        if family != "tool":
+            print(f"error: {args.command} is not available in an agent run", file=sys.stderr)
+            return 2
+        if workspace_flag:
+            print(
+                "error: --workspace is not permitted in an agent run — the run is pinned to $NDI_WORKSPACE_ID.", file=sys.stderr
+            )
+            return 2
+        if not socket_path:
+            print(f"error: ${SOCKET_ENV} is set but empty; the agent run has no CLI socket to talk to.", file=sys.stderr)
+            return 2
+    if family == "standalone":
+        try:
+            return args.run(args)
+        except ConfigError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+    try:
+        if os.environ.get("NDI_JOB_ID") and not in_agent_run:
+            raise ConfigError("The internal NDI CLI execution context is unavailable.")
+        if in_agent_run:
+            workspace_id = os.environ.get("NDI_WORKSPACE_ID", "")
+            transport = LocalTransport(socket_path, args.timeout, os.environ.get(TOKEN_ENV, ""))
+            response = args.run(SyncTools(transport), workspace_id, args)
+            return _print_tool(args, response)
+        settings = resolve_settings(
+            workspace_override=workspace_flag,
+            require_workspace=getattr(args, "needs_workspace", True),
+        )
+        timeout = getattr(args, "timeout", DEFAULT_TIMEOUT_SECONDS)
+        with NdiClient(api_key=settings.api_key, base_url=settings.base_url, timeout=timeout) as client:
+            if family == "tool":
+                return _print_tool(args, args.run(client.tools, settings.workspace_id, args))
+            return args.run(client, settings.workspace_id, args)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except NdiStatusError as exc:
+        code = f" [{exc.code}]" if exc.code else ""
+        print(f"error: {exc.status_code}{code} {exc.message}", file=sys.stderr)
+        for line in _validation_error_lines(exc.body.detail if exc.body else None):
+            print(f"  - {line}", file=sys.stderr)
+        return 1
+    except NdiError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _print_tool(args: argparse.Namespace, response) -> int:
+    if args.json:
+        print(response.model_dump_json(indent=2, exclude_none=True))
+        return 0
+    print(args.render(response))
+    return 0
+
+
+def _validation_error_lines(detail: object) -> list[str]:
+    """Keep field constraints actionable without echoing request inputs or arbitrary detail."""
+    errors = detail.get("errors") if isinstance(detail, dict) else None
+    if not isinstance(errors, list):
+        return []
+    lines = []
+    for error in errors[:_VALIDATION_ERROR_LIMIT]:
+        if not isinstance(error, dict) or not isinstance(message := error.get("msg"), str) or not message.strip():
+            continue
+        location = error.get("loc")
+        if isinstance(location, (list, tuple)) and all(isinstance(part, (str, int)) for part in location):
+            if location and location[0] == "body":
+                location = location[1:]
+            field = ".".join(str(part) for part in location)
+        else:
+            field = ""
+        line = f"{field}: {message}" if field else message
+        truncated = len(line) > _VALIDATION_ERROR_CHARS
+        clipped = line[: _VALIDATION_ERROR_CHARS - 1] if truncated else line
+        clean = " ".join("".join(char if char.isprintable() else " " for char in clipped).split())
+        lines.append(clean + ("…" if truncated else ""))
+    if lines and len(errors) > _VALIDATION_ERROR_LIMIT:
+        lines.append(f"(+{len(errors) - _VALIDATION_ERROR_LIMIT} more validation errors)")
+    return lines
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ndi",
+        description=(
+            "NDI platform CLI. Login, document operations, jobs, and workspace lifecycle talk to /v1; "
+            "the six workspace tools also run inside an agent sandbox. Credentials come from "
+            "$NDI_API_KEY / $NDI_BASE_URL or ~/.ndi/config.toml."
+        ),
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Print the raw response JSON instead of the text rendering.")
+    common.add_argument("--workspace", metavar="ID", default=None, help="Override $NDI_WORKSPACE_ID for this call.")
+    common.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        metavar="SECONDS",
+        help=f"Per-request HTTP timeout (default {DEFAULT_TIMEOUT_SECONDS:.0f}s; ask-file and job waits can take minutes).",
+    )
+    sub = parser.add_subparsers(dest="command")
+    _login.add_parsers(sub)
+    _tools.add_parsers(sub, common)
+    _docops.add_parsers(sub, common)
+    _jobs.add_parsers(sub, common)
+    _workspace.add_parsers(sub, common)
+    return parser
+
+
+def _parse_pages(spec: str | None) -> list[int] | None:
+    return parse_pages(spec)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ndi_cli-0.4.0/src/ndi_cli/_config.py

@@ -0,0 +1,94 @@
+"""Resolve the API key, base URL, and workspace the CLI talks to.
+
+The agent-facing contract is that credentials never travel on the command line:
+
+- ``$NDI_API_KEY`` — else ``api_key`` in ``~/.ndi/config.toml`` (the file
+  ``ndi login`` / ``ndi-mcp login`` writes; ``$NDI_CONFIG_PATH`` overrides its location).
+- ``$NDI_BASE_URL`` — else ``base_url`` in the same file, else the SDK default.
+- ``$NDI_WORKSPACE_ID`` — else ``workspace_id`` in the same file (``--workspace``
+  overrides either for one call). A missing workspace is a startup failure
+  with a hint, not a 404 on the first call.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from ndi_sdk.client import API_KEY_ENV, BASE_URL_ENV
+
+WORKSPACE_ENV = "NDI_WORKSPACE_ID"
+CONFIG_PATH_ENV = "NDI_CONFIG_PATH"
+DEFAULT_CONFIG_PATH = Path.home() / ".ndi" / "config.toml"
+
+_CONFIG_KEYS = ("api_key", "base_url", "workspace_id")
+
+
+class ConfigError(ValueError):
+    """A required setting could not be resolved."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str
+    workspace_id: str
+    base_url: str | None = None
+
+
+def config_path() -> Path:
+    override = os.environ.get(CONFIG_PATH_ENV)
+    return Path(override) if override else DEFAULT_CONFIG_PATH
+
+
+def resolve_settings(*, workspace_override: str | None = None, require_workspace: bool = True) -> Settings:
+    """Environment first, then the config file.
+
+    Raises:
+        ConfigError: When the API key or a required workspace id is missing.
+    """
+    api_key = os.environ.get(API_KEY_ENV)
+    base_url = os.environ.get(BASE_URL_ENV)
+    workspace_id = workspace_override or os.environ.get(WORKSPACE_ENV)
+    # A broken config file only matters when a required value has to come from
+    # it — then the error names the real cause instead of "no API key".
+    file_error: ConfigError | None = None
+    if not api_key or not base_url or not workspace_id:
+        try:
+            file_values = _read_config(config_path())
+        except ConfigError as exc:
+            file_error = exc
+            file_values = {}
+        api_key = api_key or file_values.get("api_key")
+        base_url = base_url or file_values.get("base_url")
+        workspace_id = workspace_id or file_values.get("workspace_id")
+    if not api_key:
+        raise file_error or ConfigError(f"no API key: set ${API_KEY_ENV} or run `ndi login` (or api_key in {config_path()})")
+    if require_workspace and not workspace_id:
+        raise file_error or ConfigError(f"no workspace: set ${WORKSPACE_ENV} (or workspace_id in {config_path()})")
+    return Settings(api_key=api_key, workspace_id=workspace_id or "", base_url=base_url)
+
+
+def read_config_values(path: Path) -> dict[str, str]:
+    """The config file's own settings, or {} when it is missing or unreadable."""
+    try:
+        return _read_config(path)
+    except ConfigError:
+        return {}
+
+
+def _read_config(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as handle:
+            parsed = tomllib.load(handle)
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError, OSError) as exc:
+        raise ConfigError(f"config file {path} is unreadable: {exc}") from exc
+    values: dict[str, str] = {}
+    for key in _CONFIG_KEYS:
+        value = parsed.get(key)
+        if isinstance(value, str) and value:
+            values[key] = value
+    return values