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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nace-cli
-Version: 0.2.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.2,<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
@@ -114,7 +114,7 @@ nace schema-version sch_... 1
 ## Workspaces and search
 
 ```bash
-nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+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
@@ -122,16 +122,29 @@ 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
-nace kg-build
 ```
 
 `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. 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`, `schema-version-add` and `workspace-create` 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, workspaces, search, exit codes).
 

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

@@ -89,7 +89,7 @@ nace schema-version sch_... 1
 ## Workspaces and search
 
 ```bash
-nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+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
@@ -97,16 +97,29 @@ 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
-nace kg-build
 ```
 
 `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. 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`, `schema-version-add` and `workspace-create` 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, workspaces, search, exit codes).
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.2.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.2,<1",
+    "nace-sdk>=0.3.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.2.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.2,<1",
+    "nace-sdk>=0.3.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.2.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.2.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.2.0 → nace_cli-0.3.0}/src/nace_cli/_cli.py

@@ -16,7 +16,7 @@ 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, _search, _upload, _workspaces
+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
 
@@ -82,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 []
@@ -144,7 +152,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="nace",
         description=(
-            "Nace CLI: calibrated decisions, document jobs, workspaces and search. 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."
         ),
@@ -167,7 +175,9 @@ def build_parser() -> argparse.ArgumentParser:
     _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.3.0/src/nace_cli/_domains.py

@@ -0,0 +1,178 @@
+"""Domains: the taxonomies a workspace classifies its files against.
+
+``nace domains`` takes an action: ``list`` lists them as ``nace workspaces`` lists workspaces, ``get``
+reads one with its classes, and ``create``, ``update``, ``publish`` and ``duplicate`` write them. Every
+input is a flag (``--id``, ``--slug``, ...). A draft is edited in place and published once, and a
+published or platform domain is frozen, so ``nace domains duplicate`` copies it into a draft.
+``nace workspace-create --domain SLUG`` pins a published one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from nace_sdk import Domain, DomainSummary, DomainWrite, NaceClient
+from nace_sdk._core.endpoints import DOMAIN_MAX_PAGE_SIZE
+
+from nace_cli._inputs import read_json
+from nace_cli._output import CommandFailed
+from nace_cli._schemas import _add_page_args
+from nace_cli._workspaces import _emit_listing, _total
+
+#: The two owners a domain has, for ``nace domains list --owner``.
+OWNERS = ("platform", "tenant")
+#: The two statuses a domain version has, for ``nace domains list --status``.
+STATUSES = ("draft", "published")
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    domains = sub.add_parser("domains", help="List, read, create, update, publish and duplicate domains.")
+    actions = domains.add_subparsers(dest="domains_action", metavar="{list,get,create,update,publish,duplicate}", required=True)
+
+    listing = actions.add_parser("list", parents=[common], help="List the domains your account sees: Nace's and its own.")
+    listing.add_argument("--owner", default=None, choices=OWNERS, help="Only the platform's domains, or only the account's own.")
+    listing.add_argument("--status", default=None, choices=STATUSES, help="Only drafts, or only published versions.")
+    listing.add_argument("--slug", default=None, metavar="SLUG", help="Only the versions of this slug.")
+    _add_page_args(listing, "Domains", default=50, maximum=DOMAIN_MAX_PAGE_SIZE)
+    listing.set_defaults(run=run_list, family="client")
+
+    show = actions.add_parser("get", parents=[common], help="Print a domain with its taxonomy classes.")
+    show.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The domain's id, as `nace domains list` lists it.")
+    show.set_defaults(run=run_get, family="client")
+
+    create = actions.add_parser("create", parents=[common], help="Create a draft domain owned by your account.")
+    create.add_argument(
+        "--slug", required=True, metavar="SLUG", help="The name a workspace is created against with --domain. It can't be changed later."
+    )
+    create.add_argument("--display-name", required=True, metavar="NAME", help="The name people see.")
+    create.add_argument("--taxonomy", default=None, metavar="JSON", help='The classes, as {"classes": [...]}: inline JSON, @FILE, a path, or -.')
+    create.set_defaults(run=run_create, family="client")
+
+    update = actions.add_parser("update", parents=[common], help="Rename a draft domain or replace its taxonomy.")
+    update.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The draft's id.")
+    update.add_argument("--display-name", default=None, metavar="NAME", help="The new name people see.")
+    update.add_argument("--taxonomy", default=None, metavar="JSON", help="The whole new taxonomy: inline JSON, @FILE, a path, or -.")
+    update.set_defaults(run=run_update, family="client")
+
+    publish = actions.add_parser("publish", parents=[common], help="Publish a draft domain so workspaces can use it. It can't be undone.")
+    publish.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The draft's id.")
+    publish.set_defaults(run=run_publish, family="client")
+
+    duplicate = actions.add_parser("duplicate", parents=[common], help="Copy any domain you can see into a new draft.")
+    duplicate.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The id of the domain to copy.")
+    duplicate.set_defaults(run=run_duplicate, family="client")
+
+
+# --- Rendering ----------------------------------------------------------------------------------
+
+
+def _domain_line(item: DomainSummary) -> str:
+    return f"{item.domain_id}  {item.slug}  v{item.version}  {item.status}  {item.owner}  {item.display_name}"
+
+
+def _written_line(item: DomainSummary) -> str:
+    return f"{item.domain_id}  {item.slug}  v{item.version}  {item.status}"
+
+
+def _one_line(text: Any) -> str:
+    return " ".join(str(text or "").split())
+
+
+def _domain_detail(item: Domain) -> str:
+    """The domain's line, ``inherits:`` when it has a parent, then ``classes (N):`` with each class and its aliases."""
+    lines = [_domain_line(item)]
+    if item.parent_slug:
+        lines.append(f"inherits: {item.parent_slug}")
+    classes = [entry for entry in item.taxonomy.get("classes") or [] if isinstance(entry, dict)]
+    lines.append(f"classes ({len(classes)}):")
+    for entry in classes:
+        description = _one_line(entry.get("description"))
+        lines.append(f"  {entry.get('group')} / {entry.get('subgroup')}{f': {description}' if description else ''}")
+        aliases = [str(alias) for alias in entry.get("aliases") or []]
+        if aliases:
+            lines.append(f"    aliases: {', '.join(aliases)}")
+    return "\n".join(lines)
+
+
+def _validation_errors(written: DomainWrite) -> list[dict[str, Any]]:
+    return [dict(error) for error in written.validation.errors]
+
+
+def _error_line(error: dict[str, Any]) -> str:
+    where = f"{error['path']}: " if error.get("path") else ""
+    return f"  - {where}{error.get('message', '')} ({error.get('code', 'invalid')})"
+
+
+def _emit_write(written: DomainWrite, args: argparse.Namespace) -> int:
+    """The saved domain's line, or ``{domain, validation}`` with ``--json``; what validation found goes to stderr."""
+    if args.json:
+        print(written.model_dump_json(indent=2, by_alias=True, exclude_none=True))
+        return 0
+    print(_written_line(written.domain))
+    errors = _validation_errors(written)
+    if errors:
+        print(f"the taxonomy has {len(errors)} validation errors:", file=sys.stderr)
+        for error in errors:
+            print(_error_line(error), file=sys.stderr)
+    return 0
+
+
+def _taxonomy(value: str | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    loaded = read_json(value, what="--taxonomy")
+    if not isinstance(loaded, dict):
+        raise ValueError("--taxonomy must be a JSON object")
+    return loaded
+
+
+# --- Commands -----------------------------------------------------------------------------------
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    domains = client.domains
+    filters = {"owner": args.owner, "status": args.status, "slug": args.slug}
+    return _emit_listing(
+        args,
+        "domains",
+        lambda: domains.list(limit=args.limit, cursor=args.cursor, **filters),
+        lambda: domains.iter(**filters),
+        line=_domain_line,
+        extra=lambda page, items: {"total_count": _total(page, items)},
+    )
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    item = client.domains.get(args.domain_id.strip())
+    print(item.model_dump_json(indent=2, by_alias=True, exclude_none=True) if args.json else _domain_detail(item))
+    return 0
+
+
+def run_create(client: NaceClient, args: argparse.Namespace) -> int:
+    if not args.slug.strip():
+        raise ValueError("--slug must not be blank")
+    if not args.display_name.strip():
+        raise ValueError("--display-name must not be blank")
+    written = client.domains.create(slug=args.slug.strip(), display_name=args.display_name, taxonomy=_taxonomy(args.taxonomy))
+    return _emit_write(written, args)
+
+
+def run_update(client: NaceClient, args: argparse.Namespace) -> int:
+    if args.display_name is None and args.taxonomy is None:
+        raise ValueError("pass at least one change: --display-name or --taxonomy")
+    written = client.domains.update(args.domain_id.strip(), display_name=args.display_name, taxonomy=_taxonomy(args.taxonomy))
+    return _emit_write(written, args)
+
+
+def run_publish(client: NaceClient, args: argparse.Namespace) -> int:
+    written = client.domains.publish(args.domain_id.strip())
+    code = _emit_write(written, args)
+    if not written.validation.valid:
+        raise CommandFailed("the domain was not published: fix the taxonomy errors above")
+    return code
+
+
+def run_duplicate(client: NaceClient, args: argparse.Namespace) -> int:
+    return _emit_write(client.domains.duplicate(args.domain_id.strip()), args)

{nace_cli-0.2.0 → nace_cli-0.3.0}/src/nace_cli/_inputs.py

@@ -22,10 +22,10 @@ STDIN_FLAGS = {
     "targets_file": "--targets",
     "password": "--password",
     "access": "--access",
-    "retention_policy": "--retention-policy",
-    "knowledge_graph": "--knowledge-graph",
+    "taxonomy": "--taxonomy",
     "output_schema": "--output-schema",
     "clarification_answers": "--clarification-answers",
+    "answer_schema": "--answer-schema",
 }
 
 

{nace_cli-0.2.0 → nace_cli-0.3.0}/src/nace_cli/_search.py

@@ -56,11 +56,9 @@ def _add_common_args(parser: argparse.ArgumentParser) -> None:
         "--path", action="append", dest="paths", default=[], metavar="PATH", help="Search this uploaded file too, by its path; repeatable."
     )
     context = parser.add_mutually_exclusive_group()
-    context.add_argument(
-        "--context", default=None, metavar="TEXT", help='Background the answer takes as given; "" for none (default: the workspace\'s).'
-    )
-    # The ndi CLI's way to say --context "": the API reads an empty context as none, an omitted one as the workspace's.
-    context.add_argument("--no-context", action="store_true", help="Run with no context at all, not even the workspace's global context.")
+    context.add_argument("--context", default=None, metavar="TEXT", help="Background the answer takes as given; without it, none.")
+    # The ndi CLI's way to say --context "": an empty context is sent as given.
+    context.add_argument("--no-context", action="store_true", help='Send an empty context: the same as --context "".')
     parser.add_argument(
         "--output-schema", default=None, metavar="JSON", help="A JSON Schema the answer must follow: inline JSON, @FILE, a path, or -."
     )
@@ -68,7 +66,12 @@ def _add_common_args(parser: argparse.ArgumentParser) -> None:
 
 def _add_run_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--wait-seconds", type=int, default=None, metavar="N", help=f"Hold the create open up to N seconds (max {MAX_WAIT_SECONDS}).")
-    parser.add_argument("--idempotency-key", default=None, metavar="KEY", help="Retry-safe key; the same key and body return the same job.")
+    parser.add_argument(
+        "--idempotency-key",
+        default=None,
+        metavar="KEY",
+        help="Retry identical inputs with the same key; use a new key for changed inputs.",
+    )
     add_async_args(parser)
     parser.add_argument(
         "-o",

{nace_cli-0.2.0 → nace_cli-0.3.0}/src/nace_cli/_workspaces.py

@@ -1,4 +1,4 @@
-"""Workspaces, their files, ingestion, reconciliation and knowledge-graph builds.
+"""Workspaces, their files, and ingestion.
 
 Every command that works on one workspace picks it with ``--workspace``, else ``$NACE_WORKSPACE_ID``,
 else the workspace ``nace workspace-use`` saved; with none, it exits ``2``. ``workspace-delete`` and
@@ -11,7 +11,6 @@ from __future__ import annotations
 
 import argparse
 import sys
-import textwrap
 from collections.abc import Callable, Iterable, Iterator
 from typing import Any
 
@@ -28,7 +27,7 @@ from nace_cli._schemas import _add_page_args
 
 #: The ingestion statuses a file can be in, for ``nace workspace-files --status``.
 INGESTION_STATUSES = ("discovered", "queued", "ingesting", "ingested", "stale", "expired", "failed", "not_required")
-#: Ingestions and knowledge-graph builds run long: their wait defaults to an hour.
+#: Ingestions run long: their wait defaults to an hour.
 LONG_WAIT_SECONDS = 3600.0
 NO_WORKSPACE = (
     "no workspace: pass --workspace ID, set $NACE_WORKSPACE_ID, or save one with `nace workspace-use ID` "
@@ -85,7 +84,9 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     add_workspace_arg(show, "The workspace to print")
     show.set_defaults(run=run_get, family="client")
 
-    stats = sub.add_parser("workspace-stats", parents=[common], help="Summarize a workspace: files by ingestion status, bytes, graph size.")
+    stats = sub.add_parser(
+        "workspace-stats", parents=[common], help="Summarize a workspace: files by ingestion status, bytes, pages, index documents."
+    )
     add_workspace_arg(stats, "The workspace to summarize")
     stats.set_defaults(run=run_stats, family="client")
 
@@ -100,19 +101,13 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
         "--domain",
         default=None,
         metavar="SLUG",
-        help="The published domain to sort the workspace's files into (default generic). It can't be changed later.",
+        help="The slug of a published domain the workspace classifies its files against (`nace domains list`). It can't be changed later.",
     )
     create.add_argument(
         "--access", default=None, metavar="JSON", help='Access labels, {"labels": [...], "default_label": ...}: inline JSON, @FILE, a path, or -.'
     )
-    _add_settings_args(create, creating=True)
     create.set_defaults(run=run_create, family="client")
 
-    update = sub.add_parser("workspace-update", parents=[common], help="Change a workspace's settings.")
-    add_workspace_arg(update, "The workspace to change")
-    _add_settings_args(update, creating=False)
-    update.set_defaults(run=run_update, family="client")
-
     delete = sub.add_parser("workspace-delete", parents=[common], help="Delete a workspace and everything in it. It can't be undone.")
     # Only the flag, as in the ndi CLI and the MCP server's delete_workspace: a deletion never falls
     # back to $NACE_WORKSPACE_ID or the saved workspace.
@@ -126,13 +121,6 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     add_async_args(delete)
     delete.set_defaults(run=run_delete, family="client")
 
-    build = sub.add_parser("kg-build", parents=[common], help="Build a workspace's knowledge graph over its ingested files.")
-    add_workspace_arg(build)
-    build.add_argument("--force", action="store_true", help="Clear the graph and rebuild it from scratch.")
-    add_async_args(build, wait_timeout=LONG_WAIT_SECONDS)
-    build.add_argument("--idempotency-key", default=None, metavar="KEY", help="Retry-safe key; the same key returns the same job.")
-    build.set_defaults(run=run_kg_build, family="client")
-
     files = sub.add_parser("workspace-files", parents=[common], help="List a workspace's files.")
     add_workspace_arg(files)
     add_path_prefix(files, "Only files whose path starts with PATH.")
@@ -179,42 +167,13 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     ingest.add_argument("--stale-only", action="store_true", help="Only files that changed since they were last ingested.")
     ingest.add_argument("--reingest-unchanged", action="store_true", help="Also rebuild files that are ingested and unchanged.")
     add_async_args(ingest, wait_timeout=LONG_WAIT_SECONDS)
-    ingest.add_argument("--idempotency-key", default=None, metavar="KEY", help="Retry-safe key; the same key and selection return the same job.")
-    ingest.set_defaults(run=run_ingest, family="client")
-
-    reconcile = sub.add_parser("reconcile", parents=[common], help="Check a workspace's stored files against its file records.")
-    add_workspace_arg(reconcile)
-    add_path_prefix(reconcile, "Only check files under PATH (default: the whole workspace).")
-    reconcile.add_argument("--auto-ingest", action="store_true", help="Also start an ingestion of what it finds.")
-    add_async_args(reconcile)
-    reconcile.set_defaults(run=run_reconcile, family="client")
-
-
-def _add_settings_args(parser: argparse.ArgumentParser, *, creating: bool) -> None:
-    parser.add_argument(
-        "--retention-policy", default=None, metavar="JSON", help="derived_ttl_days, source_ttl_days and job_ttl_days, as a JSON object."
-    )
-    graph = parser.add_mutually_exclusive_group()
-    graph.add_argument(
-        "--knowledge-graph", default=None, metavar="JSON", help="auto_build, exclude_path_prefixes and exclude_categories, as a JSON object."
-    )
-    graph.add_argument(
-        "--auto-build",
-        choices=("on", "off"),
+    ingest.add_argument(
+        "--idempotency-key",
         default=None,
-        help="Build the graph after every ingestion (default off)."
-        if creating
-        else "Change only knowledge_graph.auto_build, keeping the rest of the block.",
+        metavar="KEY",
+        help="Retry identical inputs with the same key; use a new key for changed inputs.",
     )
-    parser.add_argument(
-        "--currency",
-        default=None,
-        metavar="CODE",
-        help="ISO 4217 code ingestion reads for a symbol several currencies share, or none (default USD)."
-        if creating
-        else "ISO 4217 code ingestion reads from the next ingestion on, or none.",
-    )
-    parser.add_argument("--global-context", default=None, metavar="TEXT", help="Background every search in the workspace should know.")
+    ingest.set_defaults(run=run_ingest, family="client")
 
 
 # --- Rendering ---------------------------------------------------------------------------------
@@ -235,13 +194,6 @@ def _workspace_line(item: Workspace) -> str:
     return f"{item.workspace_id}  {item.name}  {item.status}"
 
 
-def _workspace_detail(item: Workspace) -> str:
-    """The workspace's line, then its global context indented under ``global context:`` when it has one."""
-    if not item.global_context:
-        return _workspace_line(item)
-    return f"{_workspace_line(item)}\nglobal context:\n{textwrap.indent(item.global_context, '  ')}"
-
-
 def _name_line(item: Workspace) -> str:
     return f"{item.workspace_id}  {item.name}"
 
@@ -260,7 +212,6 @@ def _stats_lines(stats: WorkspaceStats) -> str:
         f"bytes: {stats.bytes_total or 0}",
         f"pages ingested: {stats.pages_ingested or 0}",
         f"index documents: {stats.index_documents or 0}",
-        f"kg: {stats.kg_nodes or 0} nodes / {stats.kg_edges or 0} edges",
     ]
     return "\n".join(lines)
 
@@ -329,7 +280,7 @@ def run_list(client: NaceClient, args: argparse.Namespace) -> int:
 def run_get(client: NaceClient, args: argparse.Namespace) -> int:
     item = client.workspaces.get(workspace_id(args))
     print(f"from {_picked_by(args)}", file=sys.stderr)
-    return _emit_workspace(item, args, _workspace_detail(item))
+    return _emit_workspace(item, args, _workspace_line(item))
 
 
 def run_stats(client: NaceClient, args: argparse.Namespace) -> int:
@@ -367,48 +318,12 @@ def _json_object(value: str | None, flag: str) -> dict[str, Any] | None:
     return loaded
 
 
-def _currency(value: str | None) -> dict[str, Any] | None:
-    if value is None:
-        return None
-    code = value.strip()
-    if code.lower() == "none":
-        return {"default": None}
-    if len(code) != 3 or not code.isalpha():
-        raise ValueError(f"--currency takes a three-letter ISO 4217 code, such as USD or EUR, or none; got {value!r}")
-    return {"default": code.upper()}
-
-
-def _settings(args: argparse.Namespace) -> dict[str, Any]:
-    return {
-        "retention_policy": _json_object(args.retention_policy, "--retention-policy"),
-        "knowledge_graph": _json_object(args.knowledge_graph, "--knowledge-graph"),
-        "currency": _currency(args.currency),
-        "global_context": args.global_context,
-    }
-
-
 def run_create(client: NaceClient, args: argparse.Namespace) -> int:
     name = args.name
     if not name.strip() or len(name) > 120:
         raise ValueError("NAME must be 1 to 120 characters, not blank")
-    settings = _settings(args)
-    if args.auto_build is not None:
-        settings["knowledge_graph"] = {"auto_build": args.auto_build == "on"}
     access = _json_object(args.access, "--access")
-    item = client.workspaces.create(name=name, domain_slug=args.domain, access=access, **settings)
-    return _emit_workspace(item, args, _name_line(item))
-
-
-def run_update(client: NaceClient, args: argparse.Namespace) -> int:
-    settings = _settings(args)
-    if args.auto_build is None and all(value is None for value in settings.values()):
-        raise ValueError("pass at least one setting to change: --auto-build, --knowledge-graph, --retention-policy, --currency or --global-context")
-    target = workspace_id(args)
-    if args.auto_build is not None:
-        # The block replaces whole: send the current one back with only auto_build changed.
-        current = client.workspaces.get(target).knowledge_graph
-        settings["knowledge_graph"] = {**current, "auto_build": args.auto_build == "on"}
-    item = client.workspaces.update(target, **settings)
+    item = client.workspaces.create(name=name, domain_slug=args.domain, access=access)
     return _emit_workspace(item, args, _name_line(item))
 
 
@@ -423,10 +338,15 @@ def run_delete(client: NaceClient, args: argparse.Namespace) -> int:
     if not target:
         raise ValueError("workspace-delete needs --workspace ID: it never deletes the workspace $NACE_WORKSPACE_ID or `nace workspace-use` names")
     job = client.workspaces.delete(target, confirm_name=args.confirm_name)
+    # Acceptance removes the workspace immediately; teardown may still be running.
+    try:
+        _forget_if_saved(target)
+    except OSError as exc:
+        # The delete cannot be undone: still show its job if the config cannot be written.
+        print(f"couldn't forget it as the saved workspace: {exc}", file=sys.stderr)
     if job is None:
         # 204: deleted before, and no job is left to read.
         print("the workspace was already deleted", file=sys.stderr)
-        _forget_if_saved(target)
         print(f"deleted {target}")
         return 0
 
@@ -440,31 +360,9 @@ def run_delete(client: NaceClient, args: argparse.Namespace) -> int:
             f"the workspace is already gone from your list; quote job {job.job_id} to support to finish the teardown",
             file=sys.stderr,
         )
-    elif not args.async_submit:
-        _forget_if_saved(target)
     return code
 
 
-def run_kg_build(client: NaceClient, args: argparse.Namespace) -> int:
-    job = client.workspaces.build_knowledge_graph(workspace_id(args), force=True if args.force else None, idempotency_key=args.idempotency_key)
-
-    def summarize(done: DocumentJob) -> int:
-        result = _result(done)
-        print(f"{done.job_id}  {done.status}  {count(result.get('node_count'))} nodes  {count(result.get('edge_count'))} edges")
-        _failed_files(result.get("files_failed"))
-        return 0
-
-    return finish_job(client, job, args, summarize)
-
-
-def _failed_files(entries: Any) -> None:
-    for entry in entries if isinstance(entries, list) else []:
-        if isinstance(entry, dict):
-            error = entry.get("error")
-            message = error.get("message") or error.get("code") if isinstance(error, dict) else error
-            print(f"failed {entry.get('path')}: {message or 'no detail'}", file=sys.stderr)
-
-
 # --- Files --------------------------------------------------------------------------------------
 
 
@@ -565,7 +463,7 @@ def run_ingest(client: NaceClient, args: argparse.Namespace) -> int:
 
 
 def summarize_ingestion(done: DocumentJob) -> int:
-    """The ndi CLI's summary of an ingestion on stdout; each failed file, and the build it started, on stderr too.
+    """The ndi CLI's summary of an ingestion on stdout; each failed file on stderr too.
 
     ``ingested N | skipped N | failed N | U units`` (with ``| empty N`` after ``skipped`` when some
     file had no rows), then one ``  <status>  <path>[ <error>]`` line per file, its status as given.
@@ -584,21 +482,4 @@ def summarize_ingestion(done: DocumentJob) -> int:
         print(f"  {outcome.get('status')}  {outcome.get('path')}{f' {message}' if message else ''}")
         if outcome.get("status") == "failed":
             print(f"failed {outcome.get('path')}: {message or 'no detail'}", file=sys.stderr)
-    if result.get("kg_build_job_id"):
-        print(f"knowledge-graph build {result['kg_build_job_id']}", file=sys.stderr)
     return 0
-
-
-def run_reconcile(client: NaceClient, args: argparse.Namespace) -> int:
-    job = client.workspaces.reconcile(workspace_id(args), path_prefix=args.path_prefix, auto_ingest=True if args.auto_ingest else None)
-
-    def summarize(done: DocumentJob) -> int:
-        result = _result(done)
-        counts = ("scanned", "files_scanned"), ("discovered", "discovered"), ("stale", "marked_stale"), ("orphans", "orphans_removed")
-        line = ", ".join(f"{word} {count(result.get(field))}" for word, field in counts)
-        if result.get("ingestion_job_id"):
-            line += f"; ingestion {result['ingestion_job_id']}"
-        print(line)
-        return 0
-
-    return finish_job(client, job, args, summarize)