nace-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{nace_cli-0.1.0 → nace_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nace-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Nace CLI: calibrated decisions and document jobs from the shell
 Keywords: drex,nace,cli,document-intelligence
 Author: Nace AI
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Dist: nace-sdk>=0.1,<1
+Requires-Dist: nace-sdk>=0.3.0,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://console.nace.ai
@@ -83,7 +83,7 @@ nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use uploa
 nace upload-session --path big.csv --total-size-bytes 734003200
 ```
 
-`upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
+`nace upload DIR` uploads every file under a folder, keeping its path inside the folder under `--path` (default: the folder's name), `-j` at a time (default 8). Hidden files and folders are left out, and a file the document service refuses as `unsupported_file_type` is skipped: stderr lists them when the run ends. `--ingest` (with `--workspace`) then ingests what was uploaded, 1000 files per ingestion. `upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
 
 ## Jobs and their files
 
@@ -111,13 +111,42 @@ nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for t
 nace schema-version sch_... 1
 ```
 
+## Workspaces and search
+
+```bash
+nace workspace-create fy25-audit
+nace workspace-use <workspace_id>          # later commands use it; --workspace ID or $NACE_WORKSPACE_ID win
+nace upload ./report.pdf --workspace <workspace_id> --path reports/2025/report.pdf
+nace upload ./fy25 --workspace <workspace_id> --ingest   # every file under a folder, 8 at a time, then ingested
+nace ingest --path-prefix reports/         # makes the files searchable
+nace workspace-files --status failed
+nace search "What were total liabilities at year end?"
+nace qa "What was total freight spend in FY2024?"   # stderr: session <id>; follow up with --session
+```
+
+`search` and `qa` print the answer as the ndi CLI did: the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
+
+## Domains
+
+A domain is the two-level taxonomy (group and subgroup classes) a workspace classifies its files against. Nace provides some; your account can author its own. A draft is edited in place and published once; a published or Nace-provided domain is frozen, so duplicate it and edit the copy.
+
+```bash
+nace domains list --owner platform --status published   # domains (N):, then <domain_id>  <slug>  v<n>  <status>  <owner>  <display_name>
+nace domains get --id <domain_id>                       # the domain's line, then its classes
+nace domains create --slug leases --display-name "Lease files" --taxonomy leases.taxonomy.json   # --taxonomy: JSON, @FILE or -
+nace domains update --id <domain_id> --display-name "Leases"
+nace domains publish --id <domain_id>                   # one-way; a taxonomy that fails validation exits 1 and lists each error
+nace domains duplicate --id <domain_id>                 # a draft copy of any domain you see
+nace workspace-create fy25-leases --domain leases  # a published domain's slug; it can't be changed later
+```
+
 ## Output and exit codes
 
-Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. Exit `0` on success, `1` on an API or job failure (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
+Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
 
-Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create` and `schema-version-add` are never retried.
+Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create`, `schema-version-add`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
 
-Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 
 ## License
 

{nace_cli-0.1.0 → nace_cli-0.3.0}/README.md

@@ -58,7 +58,7 @@ nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use uploa
 nace upload-session --path big.csv --total-size-bytes 734003200
 ```
 
-`upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
+`nace upload DIR` uploads every file under a folder, keeping its path inside the folder under `--path` (default: the folder's name), `-j` at a time (default 8). Hidden files and folders are left out, and a file the document service refuses as `unsupported_file_type` is skipped: stderr lists them when the run ends. `--ingest` (with `--workspace`) then ingests what was uploaded, 1000 files per ingestion. `upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
 
 ## Jobs and their files
 
@@ -86,13 +86,42 @@ nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for t
 nace schema-version sch_... 1
 ```
 
+## Workspaces and search
+
+```bash
+nace workspace-create fy25-audit
+nace workspace-use <workspace_id>          # later commands use it; --workspace ID or $NACE_WORKSPACE_ID win
+nace upload ./report.pdf --workspace <workspace_id> --path reports/2025/report.pdf
+nace upload ./fy25 --workspace <workspace_id> --ingest   # every file under a folder, 8 at a time, then ingested
+nace ingest --path-prefix reports/         # makes the files searchable
+nace workspace-files --status failed
+nace search "What were total liabilities at year end?"
+nace qa "What was total freight spend in FY2024?"   # stderr: session <id>; follow up with --session
+```
+
+`search` and `qa` print the answer as the ndi CLI did: the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
+
+## Domains
+
+A domain is the two-level taxonomy (group and subgroup classes) a workspace classifies its files against. Nace provides some; your account can author its own. A draft is edited in place and published once; a published or Nace-provided domain is frozen, so duplicate it and edit the copy.
+
+```bash
+nace domains list --owner platform --status published   # domains (N):, then <domain_id>  <slug>  v<n>  <status>  <owner>  <display_name>
+nace domains get --id <domain_id>                       # the domain's line, then its classes
+nace domains create --slug leases --display-name "Lease files" --taxonomy leases.taxonomy.json   # --taxonomy: JSON, @FILE or -
+nace domains update --id <domain_id> --display-name "Leases"
+nace domains publish --id <domain_id>                   # one-way; a taxonomy that fails validation exits 1 and lists each error
+nace domains duplicate --id <domain_id>                 # a draft copy of any domain you see
+nace workspace-create fy25-leases --domain leases  # a published domain's slug; it can't be changed later
+```
+
 ## Output and exit codes
 
-Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. Exit `0` on success, `1` on an API or job failure (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
+Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
 
-Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create` and `schema-version-add` are never retried.
+Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create`, `schema-version-add`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
 
-Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 
 ## License
 

{nace_cli-0.1.0 → nace_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Nace CLI: calibrated decisions and document jobs from the shell"
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "nace-sdk>=0.1,<1",
+    "nace-sdk>=0.3.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.1.0 → nace_cli-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Nace CLI: calibrated decisions and document jobs from the shell"
 authors = [
     { name = "Nace AI", email = "engineering@nace.ai" }
@@ -27,7 +27,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "nace-sdk>=0.1,<1",
+    "nace-sdk>=0.3.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.1.0 → nace_cli-0.3.0}/src/nace_cli/__init__.py

@@ -6,4 +6,4 @@ over ``nace-sdk``. Credentials come from
 ``$NACE_API_KEY`` / ``$NACE_BASE_URL`` or ``~/.nace/config.toml``.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

nace_cli-0.3.0/src/nace_cli/_browser.py

@@ -0,0 +1,241 @@
+"""``nace browser run|get|list|cancel|artifacts``: a cloud browser agent that does a task on the sites you allow.
+
+A run is billed once, when it ends: its Drex Max and LLM tokens and its browser seconds, never more
+than ``--max-cost``. Reading and listing runs is free;
+a run that fails, times out, or is cancelled before completion is not charged.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from nace_sdk import BROWSER_RUN_STATUSES, BrowserRun, BrowserRunRef, NaceBrowserRunTimeoutError, NaceClient
+from nace_sdk._core.endpoints import BROWSER_RUN_MAX_PAGE_SIZE, DEFAULT_BROWSER_WAIT_SECONDS
+
+from nace_cli._inputs import read_json
+from nace_cli._output import to_json
+from nace_cli._schemas import _add_page_args, _emit_page
+
+#: What `--max-cost`, `--max-seconds` and `--max-llm-calls` take, as Drex accepts them.
+MAX_COST_RANGE = (0.01, 1.0)
+MAX_SECONDS_RANGE = (1, 1800)
+MAX_LLM_CALLS_RANGE = (1, 100)
+#: How much of a run's task a `nace browser list` line shows.
+_TASK_CHARS = 60
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    browser = sub.add_parser(
+        "browser",
+        help="Browser runs: a cloud browser agent does a task on the sites you allow and returns an answer.",
+        description="Browser runs: a cloud browser agent does a task on the sites you allow and returns an answer.",
+    )
+    commands = browser.add_subparsers(dest="browser_command", metavar="{run,get,list,cancel,artifacts}", required=True)
+
+    run = commands.add_parser("run", parents=[common], help="Start a run and wait for it; print its answer.")
+    run.add_argument("task", help="What the agent should do, in plain language: 1 to 4000 characters.")
+    run.add_argument("--start-url", required=True, metavar="URL", help="The page to open first: an http:// or https:// URL.")
+    run.add_argument(
+        "--allow",
+        dest="allowed_origins",
+        action="append",
+        default=None,
+        metavar="ORIGIN",
+        help="An origin the browser may load, such as https://shop.example.com. Repeatable. Without it, only the start URL's origin.",
+    )
+    run.add_argument(
+        "--answer-schema", default=None, metavar="SCHEMA", help="JSON Schema for a structured answer: a file path, @FILE, inline JSON, or -."
+    )
+    run.add_argument(
+        "--max-cost", type=float, default=None, metavar="USD", help="The most the run may be charged, in US dollars, 0.01 up to 1 (default 0.04)."
+    )
+    run.add_argument("--max-seconds", type=int, default=None, metavar="N", help="How long the run may browse, 1 to 1800 seconds (default 600).")
+    run.add_argument(
+        "--max-llm-calls", type=int, default=None, metavar="N", help="How many planning and reading calls it may make, 1 to 100 (default 20)."
+    )
+    run.add_argument(
+        "--metadata", action="append", default=None, metavar="KEY=VALUE", help="A string of your own, returned with the run. Repeatable."
+    )
+    run.add_argument("--idempotency-key", default=None, metavar="KEY", help="The same key returns the same run instead of starting another.")
+    run.add_argument("--no-wait", action="store_true", help="Print the run id and return at once.")
+    run.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=DEFAULT_BROWSER_WAIT_SECONDS,
+        metavar="SECONDS",
+        help=f"How long to wait for the run (default {DEFAULT_BROWSER_WAIT_SECONDS:.0f}s). It keeps going server-side after.",
+    )
+    run.set_defaults(run=run_run, family="client")
+
+    get = commands.add_parser("get", parents=[common], help="Read one run: its status, answer and cost.")
+    get.add_argument("run_id", help="The run's id (brun_...).")
+    get.set_defaults(run=run_get, family="client")
+
+    listing = commands.add_parser("list", parents=[common], help="List your runs, newest first.")
+    listing.add_argument("--status", choices=BROWSER_RUN_STATUSES, default=None, help="Only runs in this status.")
+    _add_page_args(listing, "Runs", maximum=BROWSER_RUN_MAX_PAGE_SIZE)
+    listing.set_defaults(run=run_list, family="client")
+
+    cancel = commands.add_parser("cancel", parents=[common], help="Cancel a queued or running run.")
+    cancel.add_argument("run_id", help="The run's id (brun_...).")
+    cancel.set_defaults(run=run_cancel, family="client")
+
+    artifacts = commands.add_parser("artifacts", parents=[common], help="List a run's artifacts, such as screenshots, with their links.")
+    artifacts.add_argument("run_id", help="The run's id (brun_...).")
+    artifacts.set_defaults(run=run_artifacts, family="client")
+
+
+def start_origin(start_url: str) -> str:
+    """The origin of ``start_url`` (``https://shop.example.com``), which a run without ``--allow`` may load.
+
+    Raises:
+        ValueError: Not an ``http://`` or ``https://`` URL with a host.
+    """
+    parts = urlsplit(start_url.strip())
+    host = parts.netloc.rpartition("@")[2].lower()
+    if parts.scheme.lower() not in ("http", "https") or not host:
+        raise ValueError(f"--start-url must be an http:// or https:// URL, got {start_url!r}")
+    return f"{parts.scheme.lower()}://{host}"
+
+
+def _in_range(flag: str, value: float | None, bounds: tuple[float, float]) -> None:
+    low, high = bounds
+    if value is not None and not low <= value <= high:
+        raise ValueError(f"{flag} must be between {low:g} and {high:g}, got {value:g}")
+
+
+def _limits(args: argparse.Namespace) -> dict[str, Any] | None:
+    """The limits named on the command line; one left out takes Drex's default."""
+    _in_range("--max-cost", args.max_cost, MAX_COST_RANGE)
+    _in_range("--max-seconds", args.max_seconds, MAX_SECONDS_RANGE)
+    _in_range("--max-llm-calls", args.max_llm_calls, MAX_LLM_CALLS_RANGE)
+    limits = {"max_cost_usd": args.max_cost, "max_seconds": args.max_seconds, "max_llm_calls": args.max_llm_calls}
+    named = {key: value for key, value in limits.items() if value is not None}
+    return named or None
+
+
+def _metadata(pairs: list[str] | None) -> dict[str, str] | None:
+    if not pairs:
+        return None
+    metadata: dict[str, str] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise ValueError(f"--metadata needs KEY=VALUE, got {pair!r}")
+        metadata[key] = value
+    return metadata
+
+
+def _status_line(run: BrowserRun | BrowserRunRef) -> str:
+    kind = run.outcome.kind if isinstance(run, BrowserRun) and run.outcome is not None else None
+    return f"browser run {run.id} {run.status}" + (f" ({kind})" if kind and kind != run.status else "")
+
+
+def _run_json(run: BrowserRun | BrowserRunRef) -> str:
+    return run.model_dump_json(indent=2, exclude_none=True)
+
+
+def _print_run(run: BrowserRun, args: argparse.Namespace) -> None:
+    """The run whole with ``--json``; otherwise its answer on stdout and its status, reason and cost on stderr."""
+    if args.json:
+        print(_run_json(run))
+        return
+    print(_status_line(run), file=sys.stderr)
+    if run.outcome is not None and run.outcome.reason:
+        print(f"  {run.outcome.reason}", file=sys.stderr)
+    if run.final_url:
+        print(f"  final url: {run.final_url}", file=sys.stderr)
+    if run.usage is not None and run.usage.cost_usd is not None:
+        print(f"  cost: ${run.usage.cost_usd:.4f}", file=sys.stderr)
+    if run.answer is not None:
+        print(to_json(run.answer))
+    elif run.answer_text:
+        print(run.answer_text)
+
+
+def run_run(client: NaceClient, args: argparse.Namespace) -> int:
+    """Start a run, then wait for it unless ``--no-wait``. A run that ended other than ``succeeded`` exits ``1``."""
+    origin = start_origin(args.start_url)
+    origins = args.allowed_origins or [origin]
+    limits = _limits(args)
+    metadata = _metadata(args.metadata)
+    answer_schema = None
+    if args.answer_schema is not None:
+        answer_schema = read_json(args.answer_schema, what="--answer-schema")
+        if not isinstance(answer_schema, dict):
+            raise ValueError("--answer-schema must be a JSON object")
+    if not args.wait_timeout >= 0:
+        raise ValueError("--wait-timeout must be 0 or more seconds")
+    runs = client.browser_runs
+    created = runs.create(
+        task=args.task,
+        start_url=args.start_url,
+        allowed_origins=origins,
+        answer_schema=answer_schema,
+        limits=limits,
+        metadata=metadata,
+        idempotency_key=args.idempotency_key,
+    )
+    print(_status_line(created), file=sys.stderr)
+    if args.no_wait:
+        print(_run_json(created) if args.json else created.id)
+        return 0
+    try:
+        run = runs.wait(created.id, timeout=args.wait_timeout)
+    except NaceBrowserRunTimeoutError as exc:
+        print(f"error: {exc}; read it later with `nace browser get {exc.run.id}`", file=sys.stderr)
+        print(_run_json(exc.run) if args.json else exc.run.id)
+        return 1
+    _print_run(run, args)
+    if run.status == "succeeded":
+        return 0
+    kind = f" [{run.outcome.kind}]" if run.outcome is not None else ""
+    print(f"error: browser run {run.id} ended {run.status}{kind}", file=sys.stderr)
+    return 1
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    _print_run(client.browser_runs.get(args.run_id), args)
+    return 0
+
+
+def _list_line(run: BrowserRun) -> str:
+    task = run.task if len(run.task) <= _TASK_CHARS else f"{run.task[: _TASK_CHARS - 1]}…"
+    cost = f"${run.usage.cost_usd:.4f}" if run.usage is not None and run.usage.cost_usd is not None else "-"
+    return f"{run.id}  {run.status}  {cost}  {run.created_at}  {task}".rstrip()
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    runs = client.browser_runs
+    return _emit_page(
+        args,
+        "runs",
+        lambda: runs.list(limit=args.limit, status=args.status, cursor=args.cursor),
+        lambda: runs.iter_all(status=args.status),
+        summary=_list_line,
+    )
+
+
+def run_cancel(client: NaceClient, args: argparse.Namespace) -> int:
+    ref = client.browser_runs.cancel(args.run_id)
+    if args.json:
+        print(_run_json(ref))
+    else:
+        print(_status_line(ref), file=sys.stderr)
+    return 0
+
+
+def run_artifacts(client: NaceClient, args: argparse.Namespace) -> int:
+    listed = client.browser_runs.artifacts(args.run_id)
+    if args.json:
+        print(to_json({"items": [item.model_dump(mode="json", exclude_none=True) for item in listed.items]}))
+        return 0
+    for item in listed.items:
+        step = f"step {item.step}" if item.step is not None else "-"
+        print(f"{item.kind}  {step}  {item.url or '-'}")
+    if not listed.items:
+        print("no artifacts", file=sys.stderr)
+    return 0

{nace_cli-0.1.0 → nace_cli-0.3.0}/src/nace_cli/_cli.py

@@ -16,7 +16,8 @@ from nace_sdk import NaceAPIConnectionError, NaceAPIError, NaceClient, NaceError
 from nace_sdk.constants import LOG_LEVEL_ENV, read_env
 from nace_sdk.credentials import CredentialsError, resolve_credentials
 
-from nace_cli import _decide, _docops, _jobs, _login, _schemas
+from nace_cli import _browser, _decide, _docops, _domains, _jobs, _login, _schemas, _search, _upload, _workspaces
+from nace_cli._inputs import check_one_stdin_flag
 from nace_cli._output import CommandFailed
 
 #: Long enough for a decision (Drex holds one up to 60 s) and for a document
@@ -46,6 +47,7 @@ def main(argv: list[str] | None = None) -> int:
         return 2
     _log_to_stderr()
     try:
+        check_one_stdin_flag(args)
         if args.family == "standalone":
             return args.run(args)
         credentials = resolve_credentials()
@@ -80,6 +82,14 @@ def _validation_lines(exc: NaceAPIError) -> list[dict[str, Any]]:
     """Where a request failed validation: ``error.issues``, else the document routes' ``error.detail.errors``."""
     if exc.issues:
         return exc.issues
+    if isinstance(exc.detail, dict) and isinstance(exc.detail.get("validation"), dict):
+        # A refused domain publish: `detail.validation.errors` is each `{code, path, message}` to fix.
+        found = exc.detail["validation"].get("errors")
+        return [
+            {"path": entry.get("path") or "", "message": f"{entry.get('message') or ''} ({entry.get('code') or 'invalid'})"}
+            for entry in found or []
+            if isinstance(entry, dict)
+        ]
     errors = exc.detail.get("errors") if isinstance(exc.detail, dict) else None
     if not isinstance(errors, list):
         return []
@@ -93,6 +103,15 @@ def _validation_lines(exc: NaceAPIError) -> list[dict[str, Any]]:
     return lines
 
 
+#: What to do next for the workspace and search errors, by code.
+_WORKSPACE_HINTS = {
+    "workspace_not_found": "`nace workspaces` lists the workspaces your key can use; `nace workspace-use ID` saves one.",
+    "session_busy": "The conversation's last turn is still running: wait for it with `nace job <id> --wait`, then ask again.",
+    "rate_limited": "Automatic searches and QA turns share a limit of 60 per account every 10 minutes.",
+    "access_denied": "Your key can use the workspace but not do this: ask an account owner or admin, or whoever created the workspace.",
+}
+
+
 def report_status_error(exc: NaceAPIError) -> None:
     """One line a person can act on, plus where a request failed validation."""
     label = "/".join(str(part) for part in (exc.type, exc.code) if part)
@@ -112,6 +131,16 @@ def report_status_error(exc: NaceAPIError) -> None:
             print(f"  Pay the unpaid invoice at {billing}", file=sys.stderr)
         else:
             print(f"  Top up or add a card at {billing}", file=sys.stderr)
+    # An older nace-sdk (>=0.1) has no `idempotency_key` on its errors.
+    resume_key = getattr(exc, "idempotency_key", None)
+    if exc.code == "job_pending" and resume_key:
+        # The job may have started and be billed; the same key and body resume it instead of creating another.
+        print(f"  The job may still be running. Rerun the same command with --idempotency-key {resume_key} to resume it.", file=sys.stderr)
+    hint = _WORKSPACE_HINTS.get(exc.code or "")
+    if hint:
+        print(f"  {hint}", file=sys.stderr)
+    if exc.code == "rate_limited" and (wait := exc.headers.get("retry-after")):
+        print(f"  Run it again in {wait}s.", file=sys.stderr)
     if exc.code == "path_conflict":
         print(
             "  Upload to another path (--upload-path, or --path on `nace upload`), or pass --on-conflict new_version to add a version of that file.",
@@ -123,7 +152,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="nace",
         description=(
-            "Nace CLI: calibrated decisions and document jobs. Credentials come from "
+            "Nace CLI: calibrated decisions, document jobs, workspaces, search and browser runs. Credentials come from "
             "$NACE_API_KEY / $NACE_BASE_URL or ~/.nace/config.toml (`nace login`). "
             "Set $NACE_LOG_LEVEL=debug to log each request to stderr."
         ),
@@ -141,9 +170,14 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command")
     _login.add_parsers(sub)
     _decide.add_parsers(sub, common)
+    _upload.add_parsers(sub, common)
     _docops.add_parsers(sub, common)
     _jobs.add_parsers(sub, common)
     _schemas.add_parsers(sub, common)
+    _workspaces.add_parsers(sub, common)
+    _domains.add_parsers(sub, common)
+    _search.add_parsers(sub, common)
+    _browser.add_parsers(sub, common)
     return parser
 
 

{nace_cli-0.1.0 → nace_cli-0.3.0}/src/nace_cli/_decide.py

@@ -3,14 +3,27 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import sys
+from pathlib import Path
 from typing import Any
 
-from nace_sdk import Choice, ChoiceAnswer, ListModelsResponse, NaceClient, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse
+from nace_sdk import Choice, ChoiceAnswer, ListModelsResponse, NaceClient, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse, image_input
+from nace_sdk.images import _media_type
 
+from nace_cli._docops import parse_ws_source, upload_file, workspace_source
 from nace_cli._inputs import read_json, read_text
 from nace_cli._output import to_json
 
+#: The only model that reads images, and the one `--image` picks when no model is named.
+IMAGE_MODEL = "drex-max"
+#: Drex Max reads at most this many images per request.
+MAX_IMAGES = 8
+#: Local images up to this size are sent inline; larger ones are uploaded first (8 inline fit the 4 MiB body).
+INLINE_IMAGE_BYTES = 256 * 1024
+#: Where `--image` uploads larger images, named by their content.
+IMAGE_UPLOAD_FOLDER = "drex-max-images"
+
 
 def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
     decide = sub.add_parser(
@@ -31,6 +44,18 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     decide.add_argument("--score", action="append", default=[], metavar="NAME=LOW,...,HIGH[: INSTRUCTIONS]", help="Ordered levels.")
     decide.add_argument("--questions", default=None, metavar="JSON", help="Questions object: inline JSON, @FILE or a path.")
     decide.add_argument("--body", default=None, metavar="JSON", help="A whole request body; other flags override its fields.")
+    decide.add_argument(
+        "--image",
+        dest="images",
+        action="append",
+        default=[],
+        metavar="IMAGE",
+        help=(
+            f"An image for Drex Max (PNG, JPEG or WebP); repeatable, up to {MAX_IMAGES}, read in order as Image 1, Image 2... "
+            f"A local file up to {INLINE_IMAGE_BYTES // 1024} KiB is sent inline; a larger one is uploaded first. "
+            f"Sets --model {IMAGE_MODEL} unless you name one."
+        ),
+    )
     decide.add_argument("-m", "--model", default=None, help="Model id (default drex-latest). See `nace models`.")
     decide.set_defaults(run=run_decide, family="client")
 
@@ -66,10 +91,52 @@ def build_request(args: argparse.Namespace) -> dict[str, Any]:
         raise ValueError("--state is required (text, @FILE, or - for stdin)")
     if args.model:
         body["model"] = args.model
+    elif args.images and "model" not in body:
+        body["model"] = IMAGE_MODEL
+    if len(args.images) > MAX_IMAGES:
+        raise ValueError(f"at most {MAX_IMAGES} --image per request, got {len(args.images)}")
+    for spec in args.images:
+        _check_image(spec)
     body["questions"] = questions
     return body
 
 
+def _check_image(spec: str) -> None:
+    """Refuse a bad ``--image`` before anything is uploaded or sent."""
+    if spec.startswith("ws:"):
+        parse_ws_source(spec)
+        return
+    path = Path(spec)
+    if not path.is_file():
+        raise ValueError(f"--image: no such file, and not ws:<workspace>/<file>: {spec}")
+    with path.open("rb") as handle:
+        head = handle.read(12)
+    if _media_type(head) is None:
+        raise ValueError(f"--image: {spec} is not a PNG, JPEG or WebP image")
+
+
+def resolve_images(client: NaceClient, specs: list[str]) -> list[Any]:
+    """Each ``--image`` as an ``images`` entry: ws: as a file reference, a small file inline, a larger one uploaded."""
+    images: list[Any] = []
+    for spec in specs:
+        if spec.startswith("ws:"):
+            workspace_id, file_id = parse_ws_source(spec)
+            images.append({"type": "workspace_file", "workspace_id": workspace_id, "file_id": file_id})
+            continue
+        path = Path(spec)
+        data = path.read_bytes()
+        if len(data) <= INLINE_IMAGE_BYTES:
+            images.append(image_input(data))
+            continue
+        # Named by content, so the same image again returns the file already there.
+        target = f"{IMAGE_UPLOAD_FOLDER}/{hashlib.sha256(data).hexdigest()[:16]}{path.suffix.lower()}"
+        print(f"uploading {path.name}", file=sys.stderr)
+        uploaded = upload_file(client, path, path=target, on_conflict=None)
+        print(f"uploaded {workspace_source(uploaded)}", file=sys.stderr)
+        images.append(image_input(uploaded))
+    return images
+
+
 def _state(text: str) -> Any:
     """A state that parses as a JSON object or array is sent as JSON; anything else as text."""
     stripped = text.strip()
@@ -99,14 +166,17 @@ def _labelled(spec: str, flag: str) -> tuple[str, list[str], str | None]:
 
 def run_decide(client: NaceClient, args: argparse.Namespace) -> int:
     body = build_request(args)
-    extra = {key: value for key, value in body.items() if key not in ("state", "questions", "model")}
-    response = client.system_one(body["state"], body["questions"], model=body.get("model"), extra_body=extra or None)
+    if args.images:
+        body["images"] = resolve_images(client, args.images)
+    extra = {key: value for key, value in body.items() if key not in ("state", "questions", "model", "images")}
+    response = client.system_one(body["state"], body["questions"], model=body.get("model"), images=body.get("images"), extra_body=extra or None)
     if args.json:
         print(response_json(response))
         return 0
     print(render_answers(response))
     timing = f" · {response.evaluation_time_ms:.0f} ms" if response.evaluation_time_ms is not None else ""
-    print(f"{response.model} · {response.usage.input_tokens} input tokens{timing} · {response.request_id}", file=sys.stderr)
+    image_tokens = f" ({response.usage.image_tokens} image)" if response.usage.image_tokens else ""
+    print(f"{response.model} · {response.usage.input_tokens} input tokens{image_tokens}{timing} · {response.request_id}", file=sys.stderr)
     return 0