nace-cli 0.1.0__py3-none-any.whl

nace_cli/__init__.py

@@ -0,0 +1,9 @@
+"""``nace`` — the Nace CLI.
+
+Decisions (``POST /v1/systemone``), document jobs and uploads
+(``/v1/documents/*``) and saved extraction schemas (``/v1/extraction-schemas``)
+over ``nace-sdk``. Credentials come from
+``$NACE_API_KEY`` / ``$NACE_BASE_URL`` or ``~/.nace/config.toml``.
+"""
+
+__version__ = "0.1.0"

nace_cli/_cli.py

@@ -0,0 +1,151 @@
+"""``nace`` entry point: parser, client construction, and error reporting.
+
+Exit codes: ``0`` success, ``1`` an API or job failure, ``2`` a usage or
+configuration error. Stdout carries the payload; stderr carries status, so
+``nace parse doc.pdf > doc.md`` captures only the document.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from typing import Any
+
+from nace_sdk import NaceAPIConnectionError, NaceAPIError, NaceClient, NaceError, NaceJobFailedError, NaceJobTimeoutError
+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._output import CommandFailed
+
+#: Long enough for a decision (Drex holds one up to 60 s) and for a document
+#: create that waits server-side; job waits have their own budget (--wait-timeout).
+DEFAULT_TIMEOUT_SECONDS = 120.0
+_ISSUE_LIMIT = 5
+
+
+class _StderrHandler(logging.Handler):
+    """Writes to whatever ``sys.stderr`` is at the time, so redirection and capture see SDK logs."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        print(self.format(record), file=sys.stderr)
+
+
+_SDK_LOG = _StderrHandler()
+_SDK_LOG.setFormatter(logging.Formatter("nace_sdk %(levelname)s %(message)s"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.show_version:
+        return _login.run_version(args)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    _log_to_stderr()
+    try:
+        if args.family == "standalone":
+            return args.run(args)
+        credentials = resolve_credentials()
+        with NaceClient(api_key=credentials.api_key, base_url=credentials.base_url, timeout=args.timeout) as client:
+            return args.run(client, args)
+    except CredentialsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except NaceAPIError as exc:
+        report_status_error(exc)
+        return 1
+    except (NaceAPIConnectionError, NaceJobFailedError, NaceJobTimeoutError, CommandFailed) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except NaceError as exc:
+        # Raised before any request: a bad argument the SDK refused locally.
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _log_to_stderr() -> None:
+    """``$NACE_LOG_LEVEL`` sets the SDK logger's level when it loads; the CLI gives those records a place to go."""
+    logger = logging.getLogger("nace_sdk")
+    if read_env(LOG_LEVEL_ENV) and _SDK_LOG not in logger.handlers:
+        logger.addHandler(_SDK_LOG)
+
+
+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
+    errors = exc.detail.get("errors") if isinstance(exc.detail, dict) else None
+    if not isinstance(errors, list):
+        return []
+    lines = []
+    for entry in errors:
+        if not isinstance(entry, dict):
+            continue
+        location = entry.get("loc")
+        path = entry.get("path") or (".".join(str(part) for part in location if part != "body") if isinstance(location, list) else "")
+        lines.append({"path": path, "message": entry.get("message") or entry.get("msg") or ""})
+    return lines
+
+
+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)
+    tag = f" [{label}]" if label else ""
+    request = f" ({exc.request_id})" if exc.request_id else ""
+    print(f"error: {exc.status}{tag} {exc.message}{request}", file=sys.stderr)
+    issues = _validation_lines(exc)
+    for issue in issues[:_ISSUE_LIMIT]:
+        where = f"{issue.get('path')}: " if issue.get("path") else ""
+        print(f"  - {where}{issue.get('message', '')}", file=sys.stderr)
+    if len(issues) > _ISSUE_LIMIT:
+        print(f"  (+{len(issues) - _ISSUE_LIMIT} more)", file=sys.stderr)
+    if exc.status == 402:
+        billing = _login.dashboard_url("/dashboard/billing")
+        # payment_required is an unpaid invoice: a top-up doesn't lift it, paying the invoice does.
+        if exc.type == "payment_required":
+            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)
+    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.",
+            file=sys.stderr,
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nace",
+        description=(
+            "Nace CLI: calibrated decisions and document jobs. 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."
+        ),
+    )
+    parser.add_argument("--version", dest="show_version", action="store_true", help="Print CLI and SDK versions (same as `nace version`).")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Print the raw response JSON.")
+    common.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        metavar="SECONDS",
+        help=f"Per-request HTTP timeout (default {DEFAULT_TIMEOUT_SECONDS:.0f}s).",
+    )
+    sub = parser.add_subparsers(dest="command")
+    _login.add_parsers(sub)
+    _decide.add_parsers(sub, common)
+    _docops.add_parsers(sub, common)
+    _jobs.add_parsers(sub, common)
+    _schemas.add_parsers(sub, common)
+    return parser
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nace_cli/_decide.py

@@ -0,0 +1,147 @@
+"""``nace decide`` (``POST /v1/systemone``) and ``nace models``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from nace_sdk import Choice, ChoiceAnswer, ListModelsResponse, NaceClient, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse
+
+from nace_cli._inputs import read_json, read_text
+from nace_cli._output import to_json
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    decide = sub.add_parser(
+        "decide",
+        parents=[common],
+        help="Ask calibrated questions about a state.",
+        description=(
+            "Ask named questions about a state. Shorthand questions: "
+            "--noul 'refund=Is the customer asking for a refund?', "
+            "--choice 'topic=billing,shipping,other: Which topic?', "
+            "--score 'urgency=low,medium,high: How urgent?'. "
+            "Anything richer goes in --questions as JSON."
+        ),
+    )
+    decide.add_argument("--state", default=None, help="The state: text, @FILE, or - for stdin. JSON is sent as JSON.")
+    decide.add_argument("--noul", action="append", default=[], metavar="NAME=INSTRUCTIONS", help="Yes/no question; repeatable.")
+    decide.add_argument("--choice", action="append", default=[], metavar="NAME=A,B,C[: INSTRUCTIONS]", help="Pick-one question.")
+    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("-m", "--model", default=None, help="Model id (default drex-latest). See `nace models`.")
+    decide.set_defaults(run=run_decide, family="client")
+
+    models = sub.add_parser("models", parents=[common], help="List the models your key can call.")
+    models.set_defaults(run=run_models, family="client")
+
+
+def build_request(args: argparse.Namespace) -> dict[str, Any]:
+    loaded = read_json(args.body, what="--body") if args.body else {}
+    if not isinstance(loaded, dict):
+        raise ValueError("--body must be a JSON object")
+    body: dict[str, Any] = dict(loaded)
+    questions: dict[str, Any] = dict(body.get("questions") or {})
+    if args.questions:
+        loaded = read_json(args.questions, what="--questions")
+        if not isinstance(loaded, dict):
+            raise ValueError("--questions must be a JSON object of name to question")
+        questions.update(loaded)
+    for spec in args.noul:
+        name, text = _named(spec, "--noul")
+        questions[name] = Noul(instructions=text or None)
+    for spec in args.choice:
+        name, labels, text = _labelled(spec, "--choice")
+        questions[name] = Choice(instructions=text, criteria=dict.fromkeys(labels))
+    for spec in args.score:
+        name, levels, text = _labelled(spec, "--score")
+        questions[name] = Score(instructions=text, criteria=levels)
+    if not questions:
+        raise ValueError("ask at least one question (--noul, --choice, --score or --questions)")
+    if args.state is not None:
+        body["state"] = _state(read_text(args.state))
+    if "state" not in body:
+        raise ValueError("--state is required (text, @FILE, or - for stdin)")
+    if args.model:
+        body["model"] = args.model
+    body["questions"] = questions
+    return body
+
+
+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()
+    if stripped.startswith(("{", "[")):
+        try:
+            return read_json(stripped, what="--state")
+        except ValueError:
+            return text
+    return text
+
+
+def _named(spec: str, flag: str) -> tuple[str, str]:
+    name, sep, rest = spec.partition("=")
+    if not sep or not name.strip():
+        raise ValueError(f"{flag} needs NAME=..., got {spec!r}")
+    return name.strip(), rest.strip()
+
+
+def _labelled(spec: str, flag: str) -> tuple[str, list[str], str | None]:
+    name, rest = _named(spec, flag)
+    labels_text, _, text = rest.partition(":")
+    labels = [label.strip() for label in labels_text.split(",") if label.strip()]
+    if not labels:
+        raise ValueError(f"{flag} needs at least one label: NAME=A,B,C[: INSTRUCTIONS]")
+    return name, labels, text.strip() or 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.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)
+    return 0
+
+
+def response_json(response: SystemOneResponse | ListModelsResponse) -> str:
+    """The body as Drex sent it, ``request_id`` included: the model keeps the id out of its fields."""
+    body = response.raw_http_response.json()
+    request_id = response.raw_http_response.headers.get("x-request-id")
+    if isinstance(body, dict) and "request_id" not in body and request_id:
+        body["request_id"] = request_id
+    return to_json(body)
+
+
+def render_answers(response: SystemOneResponse) -> str:
+    width = max((len(name) for name in response.answers), default=0)
+    lines = []
+    for name, answer in response.answers.items():
+        if isinstance(answer, NoulAnswer):
+            detail = f"{answer.noul:.3f}"
+        elif isinstance(answer, ChoiceAnswer):
+            detail = f"{answer.choice} (confidence {answer.confidence:.3f})"
+        elif isinstance(answer, ScoreAnswer):
+            detail = f"{answer.score:.3f} on {' < '.join(answer.legend)} (confidence {answer.confidence:.3f})"
+        else:  # pragma: no cover - the union is closed today
+            detail = str(answer)
+        lines.append(f"{name.ljust(width)}  {answer.type:<6}  {detail}")
+    return "\n".join(lines)
+
+
+def run_models(client: NaceClient, args: argparse.Namespace) -> int:
+    response = client.models.list()
+    if args.json:
+        print(response_json(response))
+        return 0
+    width = max((len(model.name) for model in response.models), default=0)
+    for model in response.models:
+        alias = f" -> {model.alias_for}" if model.alias_for else ""
+        print(f"{model.name.ljust(width)}  {model.release_date}{alias}  {model.description}")
+    return 0