unstract-cli 0.1.0rc1__py3-none-any.whl

unstract_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Unstract CLI."""
+
+__version__ = "0.1.0rc1"

unstract_cli/__main__.py

@@ -0,0 +1,100 @@
+"""Entry point: turns every failure into an envelope plus a stable exit code.
+
+Click's own error handling is bypassed on purpose. By default it prints prose to
+stderr and exits 1 or 2 with nothing on stdout, which leaves a caller parsing
+stdout with an empty stream and no way to tell a usage error from a server
+failure.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+
+import click
+
+from unstract_cli.app import Context, cli
+from unstract_cli.config import ConfigError
+from unstract_cli.core.errors import CLIError, ExitCode, set_warning_sink
+from unstract_cli.core.output import AgentMode, OutputFormat, emit_error, resolve_format
+
+
+def _option_from_argv(argv: list[str], *spellings: str) -> str | None:
+    """Best-effort read of one option before Click has parsed anything.
+
+    A failure during parsing still has to be rendered, and the parsed context
+    does not exist yet at that point.
+    """
+    for i, arg in enumerate(argv):
+        for spelling in spellings:
+            if arg.startswith(f"{spelling}="):
+                return arg.split("=", 1)[1]
+            if arg == spelling and i + 1 < len(argv):
+                return argv[i + 1]
+    return None
+
+
+def _format_from_argv(argv: list[str]) -> OutputFormat:
+    """Resolve the format the same way the parsed run would."""
+    try:
+        return resolve_format(
+            _option_from_argv(argv, "--output", "-o"),
+            _option_from_argv(argv, "--agent") or AgentMode.AUTO,
+        )
+    except CLIError:
+        # Nothing renders an envelope this early, so a bad value is left for
+        # Click's own Choice to reject once parsing reaches it.
+        return resolve_format(None)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    # Guessed from argv, then corrected by the root callback: a failure after
+    # parsing has to render in the format the run actually resolved.
+    ctx = Context(output=_format_from_argv(args))
+    try:
+        cli.main(args=args, standalone_mode=False, obj=ctx)
+    except CLIError as exc:
+        return int(emit_error(exc, ctx.output))
+    except ConfigError as exc:
+        return int(emit_error(CLIError(str(exc), ExitCode.USAGE), ctx.output))
+    except click.UsageError as exc:
+        return int(
+            emit_error(
+                CLIError(exc.format_message(), ExitCode.USAGE, hint="Run with --help."),
+                ctx.output,
+            )
+        )
+    except BrokenPipeError:
+        # Nowhere left to render the envelope. Python flushes stdout at exit,
+        # so point it at devnull or this is raised again on the way out.
+        with contextlib.suppress(OSError):
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return int(ExitCode.GENERIC)
+    except OSError as exc:
+        # A full disk or an unwritable path is the caller's to fix, and they
+        # still need a parseable envelope rather than a traceback.
+        return int(
+            emit_error(
+                CLIError(str(exc), ExitCode.GENERIC, hint="Check the path and disk."),
+                ctx.output,
+            )
+        )
+    except (click.Abort, KeyboardInterrupt):
+        # Nothing here prompts, so Click's Abort can only mean an interrupt.
+        return int(
+            emit_error(
+                CLIError("Interrupted.", ExitCode.INTERRUPTED, retryable=True), ctx.output
+            )
+        )
+    except click.exceptions.Exit as exc:  # --help and --version exit through here
+        return int(exc.exit_code)
+    finally:
+        # Notes held before a sink was bound still have to reach the user.
+        set_warning_sink(None)
+    return int(ExitCode.SUCCESS)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

unstract_cli/app.py

@@ -0,0 +1,321 @@
+"""The root Click application: global options and the command groups.
+
+Global options are declared once here and reach every command through the Click
+context, so no command re-implements profile selection or output formatting.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+import click
+
+from unstract_cli.commands.config_cmd import config_group
+from unstract_cli.config import (
+    DOCSTUDIO,
+    LLMWHISPERER,
+    SECRET_SETTINGS,
+    ConfigError,
+    ResolvedConfig,
+    load_config,
+    set_config_path,
+)
+from unstract_cli.core.clients import DEFAULT_TRANSPORT_TIMEOUT
+from unstract_cli.core.discover import TIERS, discover
+from unstract_cli.core.errors import CLIError, ExitCode, set_warning_sink
+from unstract_cli.core.output import (
+    AgentMode,
+    OutputFormat,
+    diagnostic,
+    emit_result,
+    resolve_format,
+)
+
+
+@dataclass
+class Context:
+    """Everything a command needs from the global options."""
+
+    output: OutputFormat = OutputFormat.TABLE
+    quiet: bool = False
+    verbosity: int = 0
+    profile: str | None = None
+    #: Transport timeout for the clients that have none of their own.
+    transport_timeout: float | None = DEFAULT_TRANSPORT_TIMEOUT
+    #: Command-line overrides, keyed `product.setting` -- the top tier of
+    #: flag > env > profile > default.
+    overrides: dict[str, Any] = field(default_factory=dict)
+    _config: ResolvedConfig | None = field(default=None, repr=False)
+
+    @property
+    def config(self) -> ResolvedConfig:
+        """Load the config lazily, so commands that need none never read a file."""
+        if self._config is None:
+            try:
+                cfg = load_config()
+            except ConfigError as exc:
+                raise CLIError(str(exc), ExitCode.USAGE) from exc
+            for warning in cfg.warnings:
+                diagnostic(warning, quiet=self.quiet, verbosity=self.verbosity)
+            self._config = ResolvedConfig(
+                file=cfg, profile_name=self.profile, overrides=self.overrides
+            )
+        return self._config
+
+    def override(self, product: str, values: dict[str, Any]) -> None:
+        """Record the connection flags given for one product.
+
+        Called from the product group, before any command runs, so the flag tier
+        is populated by the time a command resolves anything.
+        """
+        for key, value in values.items():
+            if value is None:
+                continue
+            if key in SECRET_SETTINGS:
+                diagnostic(
+                    "warning: a key passed on the command line lands in shell "
+                    "history and in the process list. Prefer the environment "
+                    "variable or `env:` indirection in a profile.",
+                    quiet=self.quiet,
+                    verbosity=self.verbosity,
+                )
+            self.overrides[f"{product}.{key}"] = value
+
+    def secrets(self) -> list[str]:
+        """Resolved credentials, for scrubbing anything on its way to a stream."""
+        out: list[str] = []
+        for product, key in (
+            (LLMWHISPERER, "api_key"),
+            (DOCSTUDIO, "api_key"),
+            (DOCSTUDIO, "platform_key"),
+        ):
+            try:
+                if value := self.config.get(product, key):
+                    out.append(str(value))
+            except (ConfigError, CLIError):
+                # Unresolvable means unprintable too, and raising would
+                # replace a finished report with a config error.
+                continue
+        return out
+
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+# `invoke_without_command` so `--discover` answers on its own: it is how a
+# caller learns which commands exist.
+@click.group(
+    invoke_without_command=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.option(
+    "--config",
+    "config_file",
+    default=None,
+    type=click.Path(dir_okay=False),
+    help="Config file to use, overriding discovery.",
+)
+@click.option("--profile", "-p", default=None, help="Configuration profile to use.")
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    type=click.Choice([f.value for f in OutputFormat]),
+    help="Output format. Defaults to table, or to json when --agent resolves "
+    "to yes; pass it explicitly to parse the output.",
+)
+@click.option(
+    "--agent",
+    type=click.Choice([m.value for m in AgentMode]),
+    default=AgentMode.AUTO.value,
+    help="Whether a coding agent is driving this: sets the default format to "
+    "json. Only the default -- an explicit --output always wins.",
+)
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    default=False,
+    help="Suppress diagnostics on stderr. stdout is unaffected.",
+)
+@click.option("--verbose", "-v", count=True, help="Increase diagnostic detail.")
+@click.option(
+    "--discover",
+    "discover_tier",
+    type=click.Choice(TIERS),
+    default=None,
+    help="Describe this CLI as JSON instead of running a command, useful for agents.",
+)
+@click.version_option(package_name="unstract-cli")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    config_file: str | None,
+    profile: str | None,
+    output: str | None,
+    agent: str,
+    quiet: bool,
+    verbose: int,
+    discover_tier: str | None,
+) -> None:
+    """The official CLI for Unstract.
+
+    LLMWhisperer extracts text and layout from documents; Document Studio runs
+    them through API deployments that return structured JSON.
+
+    Scripting or driving this from an agent: `-o json` prints one
+    `{ok, data, error, meta}` envelope on stdout and nothing else, failures
+    exit non-zero with a stable code, and `--discover groups|summary|full`
+    describes the commands, their flags and the output contract as JSON without
+    running anything.
+    """
+    set_config_path(config_file)
+    # Filled in rather than replaced: the entry point holds this object, so a
+    # failure anywhere below renders in the format resolved here.
+    obj = ctx.ensure_object(Context)
+    obj.output = resolve_format(output, agent)
+    obj.quiet = quiet
+    obj.verbosity = verbose
+    obj.profile = profile
+    # Modules the output layer imports cannot import it back, so their notes
+    # reach it through this sink rather than stderr unfiltered.
+    set_warning_sink(
+        lambda message: diagnostic(message, quiet=obj.quiet, verbosity=obj.verbosity)
+    )
+    if discover_tier:
+        # Discovery has to answer before any configuration exists.
+        emit_result(discover(cli, discover_tier), OutputFormat.JSON)
+        ctx.exit(int(ExitCode.SUCCESS))
+    if ctx.invoked_subcommand is None:
+        if obj.output is not OutputFormat.TABLE:
+            # stdout carries one envelope and nothing else: help printed there
+            # with exit 0 tells a parser that work it never did succeeded.
+            raise CLIError(
+                "No command given.",
+                ExitCode.USAGE,
+                hint="`--discover groups` lists what can be run, as JSON.",
+            )
+        click.echo(ctx.get_help())
+        ctx.exit(int(ExitCode.SUCCESS))
+
+
+#: The connection flags a product group can carry, named after the setting
+#: each one overrides.
+_CONNECTION_FLAGS: dict[str, str] = {
+    "base_url": "Service URL to use.",
+    "api_key": "API key to use.",
+    "org_id": "Organisation to run against.",
+    "platform_key": "Platform key to use, for the commands that take one.",
+}
+
+
+def _connection_options(*settings: str) -> Callable[[Any], Any]:
+    """The per-product connection settings, as flags.
+
+    They sit on the product group rather than on each command: they say where to
+    connect, which is the same question for every command underneath.
+    """
+    options = [
+        click.option(
+            f"--{name.replace('_', '-')}", default=None, help=_CONNECTION_FLAGS[name]
+        )
+        for name in ("base_url", *settings)
+    ]
+
+    def decorate(func: Any) -> Any:
+        for option in reversed(options):
+            func = option(func)
+        return func
+
+    return decorate
+
+
+@cli.group("whisper")
+@_connection_options("api_key")
+@pass_context
+def whisper_group(ctx: Context, **overrides: str | None) -> None:
+    """Extract text and layout from documents with LLMWhisperer."""
+    ctx.override(LLMWHISPERER, overrides)
+
+
+@cli.group("docstudio")
+@_connection_options("api_key", "org_id", "platform_key")
+@click.option(
+    "--transport-timeout",
+    type=click.FloatRange(min=0),
+    default=DEFAULT_TRANSPORT_TIMEOUT,
+    show_default=True,
+    help="Seconds before a stalled connection is given up on. 0 waits forever.",
+)
+@pass_context
+def docstudio_group(
+    ctx: Context, transport_timeout: float, **overrides: str | None
+) -> None:
+    """Run Document Studio API deployments."""
+    ctx.transport_timeout = transport_timeout or None
+    ctx.override(DOCSTUDIO, overrides)
+
+
+@docstudio_group.group("deployment")
+def deployment_group() -> None:
+    """Work with a deployed API."""
+
+
+@cli.group("auth")
+@_connection_options("platform_key")
+@click.option(
+    "--transport-timeout",
+    type=click.FloatRange(min=0),
+    default=DEFAULT_TRANSPORT_TIMEOUT,
+    show_default=True,
+    help="Seconds before a stalled connection is given up on. 0 waits forever.",
+)
+@pass_context
+def auth_group(
+    ctx: Context, transport_timeout: float | None, **overrides: str | None
+) -> None:
+    """Sign in, and identify the credential you are using.
+
+    Its flags configure the platform key, which is the credential that knows
+    which organisation it belongs to. A deployment key does not: it authenticates
+    against the deployment it was minted for and never reaches this endpoint.
+    """
+    # The same spelling as every other group: the clients are given no bound
+    # of their own, so an unset flag would wait on a black-holed host forever.
+    ctx.transport_timeout = transport_timeout or None
+    ctx.override(DOCSTUDIO, overrides)
+
+
+cli.add_command(config_group)
+
+# Imported for the side effect of registering commands, and last because they
+# hang those commands off the groups declared above.
+from unstract_cli.commands import (  # noqa: E402,F401
+    clone_cmd,
+    docstudio_cmd,
+    platform_cmd,
+    whisper_cmd,
+)
+
+
+def command_tree() -> dict[str, Any]:
+    """The registered command tree, read back from Click itself.
+
+    Describing commands anywhere but from the parser lets the description drift
+    from what the parser accepts, so discovery and help always read this.
+    """
+
+    def walk(command: click.Command) -> dict[str, Any]:
+        entry: dict[str, Any] = {"help": (command.help or "").strip().split("\n")[0]}
+        if isinstance(command, click.Group):
+            entry["commands"] = {
+                name: walk(sub) for name, sub in sorted(command.commands.items())
+            }
+        return entry
+
+    return walk(cli)["commands"]
+
+
+__all__ = ["Context", "cli", "command_tree", "pass_context"]