cu-cli 0.1.0b1__py3-none-any.whl

cu_cli/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""CU CLI — Azure Content Understanding Command Line Interface.
+
+A deterministic, no-LLM CLI over the Content Understanding SDK for authoring,
+validating, and running custom analyzers. See
+https://github.com/Azure/content-understanding-toolkit/tree/main/cu-cli.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("cu-cli")
+
+__all__ = ["__version__"]

cu_cli/__main__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Enable `python -m cu_cli`."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

cu_cli/apiversion.py

@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Central API-version resolution and validation.
+
+The CLI explicitly tests ``2025-11-01`` and ``2026-06-01-preview``. Any
+``YYYY-MM-DD-preview`` version is also accepted for forward compatibility,
+while feature detection remains limited to explicitly known versions.
+
+Resolution precedence (highest -> lowest):
+  1. ``--api-version`` flag on the command (per-invocation override)
+  2. schema-pinned ``apiVersion`` (schema-scoped commands only)
+  3. ``CU_API_VERSION`` environment variable
+  4. selected or active profile
+  5. built-in default (``2025-11-01`` GA)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from cu_cli_core.service_options import DEFAULT_API_VERSION
+
+from .errors import CuCliError
+
+
+@dataclass(frozen=True)
+class ApiVersion:
+    value: str
+    label: str
+    features: frozenset[str] = frozenset()
+
+
+API_VERSIONS = (
+    ApiVersion("2025-11-01", "GA"),
+    ApiVersion(
+        "2026-06-01-preview",
+        "preview",
+        frozenset({"inline-analysis"}),
+    ),
+)
+
+SUPPORTED_API_VERSIONS = tuple(item.value for item in API_VERSIONS)
+_PREVIEW_VERSION_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}-preview$")
+_KNOWN_VERSION_LABELS = tuple(
+    f"{item.value} ({item.label})" for item in API_VERSIONS
+)
+_KNOWN_VERSIONS_HELP = (
+    _KNOWN_VERSION_LABELS[0]
+    if len(_KNOWN_VERSION_LABELS) == 1
+    else f"{', '.join(_KNOWN_VERSION_LABELS[:-1])} and {_KNOWN_VERSION_LABELS[-1]}"
+)
+API_VERSION_HELP = (
+    f"Content Understanding API version. Known versions: {_KNOWN_VERSIONS_HELP}; "
+    "any YYYY-MM-DD-preview version is also accepted."
+)
+
+if API_VERSIONS[0].value != DEFAULT_API_VERSION:
+    raise RuntimeError("default API version must be the first supported API version")
+
+
+def _supported_list() -> str:
+    return ", ".join(f"{item.value} ({item.label})" for item in API_VERSIONS)
+
+
+def is_preview_version(version: Optional[str]) -> bool:
+    """Return whether *version* has the forward-compatible preview shape."""
+    return bool(version and _PREVIEW_VERSION_PATTERN.fullmatch(version))
+
+
+def is_supported(version: Optional[str]) -> bool:
+    return version in SUPPORTED_API_VERSIONS or is_preview_version(version)
+
+
+def ensure_supported(version: Optional[str]) -> str:
+    """Return *version* if supported, else raise the design-doc error."""
+    if not is_supported(version):
+        raise CuCliError(
+            f"API version {version} is not supported by this CLI build. "
+            f"Supported: {_supported_list()} (or any YYYY-MM-DD-preview version).",
+        )
+    assert version is not None
+    return version
+
+
+def supports_api_feature(version: Optional[str], feature: str) -> bool:
+    """Return whether an explicitly supported API version provides *feature*."""
+    canonical = ensure_supported(version)
+    return any(item.value == canonical and feature in item.features for item in API_VERSIONS)
+
+
+def resolve_api_version(
+    *,
+    flag: Optional[str] = None,
+    schema_pinned: Optional[str] = None,
+    profile: Optional[str] = None,
+    env: Optional[str] = None,
+    default: str = DEFAULT_API_VERSION,
+) -> str:
+    """Resolve the effective api-version per the precedence chain.
+
+    ``env`` defaults to ``CU_API_VERSION`` when not passed explicitly.
+
+    When both ``flag`` and ``schema_pinned`` are present and disagree, this is a
+    hard, fail-fast conflict: schema-scoped commands
+    must never silently diverge from the version their schema declares.
+    """
+    if env is None:
+        env = os.getenv("CU_API_VERSION")
+
+    if flag is not None and schema_pinned is not None and flag != schema_pinned:
+        raise CuCliError(
+            f"Schema pins apiVersion '{schema_pinned}' but --api-version "
+            f"'{flag}' was passed. Remove the flag or align the schema.",
+            exit_code=2,
+        )
+
+    for candidate in (flag, schema_pinned, env, profile):
+        if candidate:
+            return ensure_supported(candidate)
+    return ensure_supported(default)

cu_cli/cli.py

@@ -0,0 +1,138 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Top-level CLI: registers all command groups under ``cu`` / ``cu-cli``.
+
+Uses ``rich-click`` for the help UX. Running ``cu`` with no subcommand prints
+the full help.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import rich_click as click
+
+from . import __version__
+from .apiversion import API_VERSION_HELP
+from .commands.analyze import cmd_analyze
+from .commands.analyzer import analyzer_group
+from .commands.profile_cmd import profile_group
+from .commands.defaults import defaults_group
+from .commands.doctor import cmd_doctor
+from .commands.env_var import env_var_group
+from .commands.infra import infra_group
+from .commands.upgrade import cmd_upgrade
+from .commands._help import common_commands
+from .commands._infra_models import cmd_infra_models
+
+
+def _force_utf8_io() -> None:
+    """Make stdout/stderr UTF-8 so redirects on Windows cmd don't crash."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+
+_force_utf8_io()
+
+# --- rich-click look & feel ------------------------------------------------
+_rc = click.rich_click
+_rc.MAX_WIDTH = 110
+_rc.TEXT_MARKUP = "rich"
+_rc.STYLE_OPTION = "bold cyan"
+_rc.STYLE_COMMAND = "bold magenta"
+_rc.STYLE_SWITCH = "bold cyan"
+_rc.HEADER_TEXT = (
+    "[bold cyan]CU CLI[/] — [white]Azure Content Understanding Command Line Interface[/]"
+)
+_rc.FOOTER_TEXT = ""
+
+_COMMAND_GROUPS: list = [
+    {"name": "Setup", "commands": ["infra", "profile", "doctor", "env-var"]},
+    {"name": "Content Understanding", "commands": ["analyze", "analyzer", "defaults"]},
+    {"name": "Maintenance", "commands": ["upgrade"]},
+]
+_rc.COMMAND_GROUPS = {"cu": _COMMAND_GROUPS, "cu-cli": _COMMAND_GROUPS}
+
+
+CLI_HELP = (
+    "Use Azure Content Understanding through a Microsoft Foundry resource to process files from the "
+    "terminal. An analyzer processes a document, image, audio file, or video and "
+    "returns an analyzer result with extracted content and structured fields. Use "
+    "a ready-to-use prebuilt analyzer or create a custom analyzer for your scenario.\n\n"
+    "[white] [/white]\n\n"
+    "`cu infra generate` generates an azd/Bicep project used to provision the required "
+    "Microsoft Foundry resource, optionally deploy supported large language models "
+    "(LLMs) and embeddings models, and configure Content Understanding defaults. "
+    "The command writes files only; `azd up` performs the Azure provisioning. "
+    "A local "
+    "CU CLI profile stores the resource endpoint, authentication method, API version, "
+    "and model mappings."
+)
+
+class OrderedHelpGroup(click.RichGroup):
+    """Preserve command registration order in help output."""
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return list(self.commands)
+
+
+@click.group(
+    cls=OrderedHelpGroup,
+    help=CLI_HELP,
+    epilog=common_commands(
+        (
+            "cu infra generate",
+            "Generate the azd/Bicep project used to provision and configure a Microsoft "
+            "Foundry resource. Run `azd up` from the generated directory to provision it.",
+        ),
+        (
+            "cu profile set endpoint https://<resource-name>.services.ai.azure.com/",
+            "Connect CU CLI to an existing Microsoft Foundry resource endpoint. Replace "
+            "<resource-name> with the name of your resource.",
+        ),
+        (
+            "cu doctor",
+            "Verify the active profile, authentication, resource connectivity, and "
+            "Content Understanding defaults.",
+        ),
+        (
+            "cu analyze sample.pdf -a prebuilt-layout",
+            "Analyze a PDF with the prebuilt-layout analyzer and print its extracted text, "
+            "document structure, and layout information as Markdown.",
+        ),
+    )
+    + "\n\n[white]For environment-variable help, run "
+      "[bold cyan]cu env-var -h[/bold cyan].[/white]\n\n"
+      f"[bold]{API_VERSION_HELP}[/bold]",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+)
+@click.version_option(__version__, "-V", "--version", prog_name="cu")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """Root group. A bare ``cu`` prints help."""
+    _force_utf8_io()
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+        ctx.exit(0)
+
+
+main.add_command(infra_group)
+main.add_command(profile_group)
+main.add_command(cmd_doctor)
+main.add_command(env_var_group)
+main.add_command(cmd_analyze)
+main.add_command(analyzer_group)
+main.add_command(defaults_group)
+main.add_command(cmd_upgrade)
+main.add_command(cmd_infra_models)
+
+
+if __name__ == "__main__":
+    main()

cu_cli/client.py

@@ -0,0 +1,138 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Build a ContentUnderstandingClient honoring config precedence + api-version.
+
+The CLI is cloud-only: every client build requires an endpoint. The
+``User-Agent`` telemetry header is stamped here so
+every CU call carries it (opt-out honored — see ``telemetry.py``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from cu_cli_core.client import (
+    LRO_POLLING_INTERVAL_SECONDS,
+    build_content_understanding_client,
+)
+
+from .apiversion import ensure_supported
+from .core.foundry import normalize_foundry_endpoint
+from .profile import Profile
+from .errors import CuCliError
+from .telemetry import user_agent
+
+@dataclass
+class ResolvedAuth:
+    endpoint: str
+    auth_mode: str  # "entra" | "key"
+    api_version: str
+    api_key: Optional[str] = None
+
+
+def resolve(
+    profile: Profile,
+    *,
+    endpoint_override: Optional[str] = None,
+    api_key_override: Optional[str] = None,
+    api_version_override: Optional[str] = None,
+    force_entra: bool | str = False,
+    auth_mode_override: Optional[str] = None,
+) -> ResolvedAuth:
+    endpoint = endpoint_override or profile.endpoint
+    if not endpoint:
+        raise CuCliError(
+            f"No CU endpoint configured for CU CLI profile '{profile.profile_name}'.",
+            hint="set one with `cu profile set endpoint <URL>`, select another saved "
+                 "CU CLI profile with `cu profile set-active <name>`, or pass "
+                 "`--endpoint`. Run `cu profile show` to inspect the effective profile.",
+        )
+
+    api_version = ensure_supported(api_version_override or profile.api_version)
+
+    requested_mode = auth_mode_override
+    if requested_mode is None and isinstance(force_entra, str):
+        requested_mode = force_entra
+    elif requested_mode is None and force_entra:
+        requested_mode = "login"
+
+    endpoint = normalize_foundry_endpoint(
+        endpoint,
+        auth_mode=requested_mode or profile.auth_mode,
+    )
+
+    if requested_mode == "login":
+        return ResolvedAuth(endpoint=endpoint, auth_mode="entra",
+                            api_version=api_version, api_key=None)
+    if api_key_override or requested_mode == "key":
+        key = api_key_override or profile.api_key
+        if not key:
+            raise CuCliError(
+                "--auth-mode key requires an API key.",
+                hint="pass --api-key or configure api_key in the selected CU CLI profile.",
+            )
+        return ResolvedAuth(endpoint=endpoint, auth_mode="key",
+                            api_version=api_version, api_key=key)
+    if profile.auth_mode == "key":
+        if not profile.api_key:
+            raise CuCliError(
+                "auth is 'key' but no api_key is configured.",
+                hint="run 'cu profile set api_key <KEY>' or switch to login auth with "
+                     "'cu profile set auth_mode login' (then 'az login').",
+            )
+        return ResolvedAuth(endpoint=endpoint, auth_mode="key",
+                            api_version=api_version, api_key=profile.api_key)
+    return ResolvedAuth(endpoint=endpoint, auth_mode="entra",
+                        api_version=api_version, api_key=None)
+
+
+def build_client(
+    profile: Profile,
+    *,
+    endpoint_override: Optional[str] = None,
+    api_key_override: Optional[str] = None,
+    api_version_override: Optional[str] = None,
+    force_entra: bool | str = False,
+    auth_mode_override: Optional[str] = None,
+) -> Any:
+    """Construct a ``ContentUnderstandingClient`` for the resolved auth/version."""
+    from azure.core.credentials import AzureKeyCredential
+    from azure.identity import DefaultAzureCredential
+
+    if api_key_override:
+        # The value came from --api-key on argv, which is visible to `ps` and
+        # recorded in shell history. Nudge users toward safer alternatives.
+        from .output import console
+        console.print(
+            "[yellow]warning:[/yellow] --api-key on the command line is visible via "
+            "`ps`/shell history. Prefer the CU_API_KEY env var or "
+            "`cu profile set api_key`."
+        )
+        if force_entra is True or force_entra == "login" or auth_mode_override == "login":
+            console.print(
+                "[dim]note:[/dim] --auth-mode login overrides --api-key; "
+                "the provided key is ignored."
+            )
+
+    auth = resolve(
+        profile,
+        endpoint_override=endpoint_override,
+        api_key_override=api_key_override,
+        api_version_override=api_version_override,
+        force_entra=force_entra,
+        auth_mode_override=auth_mode_override,
+    )
+    credential = (
+        AzureKeyCredential(auth.api_key or "")
+        if auth.auth_mode == "key"
+        else DefaultAzureCredential()
+    )
+    return build_content_understanding_client(
+        endpoint=auth.endpoint,
+        credential=credential,
+        api_version=auth.api_version,
+        user_agent=user_agent(),
+        polling_interval=LRO_POLLING_INTERVAL_SECONDS,
+    )

cu_cli/commands/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""CLI command modules."""

cu_cli/commands/_command_spec.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Translate framework-neutral command arguments into Click decorators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import rich_click as click
+
+from cu_cli_core.command_spec import ArgumentSpec, ArgumentValueType, CommandSpec
+
+
+_SIMPLE_CLICK_TYPES: dict[ArgumentValueType, Any] = {
+    ArgumentValueType.STRING: str,
+    ArgumentValueType.BOOLEAN: bool,
+}
+
+
+def _click_type(argument: ArgumentSpec) -> Any:
+    if argument.value_type is ArgumentValueType.INTEGER:
+        return click.IntRange(argument.minimum, argument.maximum)
+    if argument.value_type is ArgumentValueType.PATH:
+        return click.Path(
+            exists=argument.path_exists,
+            file_okay=argument.file_okay,
+            dir_okay=argument.dir_okay,
+            path_type=Path,
+        )
+    return _SIMPLE_CLICK_TYPES[argument.value_type]
+
+
+def _click_argument(argument: ArgumentSpec) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    metavar = argument.name if argument.required else f"[{argument.name}]"
+    return click.argument(
+        argument.parser_name,
+        required=argument.required,
+        type=_click_type(argument),
+        metavar=argument.metavar or metavar,
+        nargs=-1 if argument.repeatable else 1,
+    )
+
+
+def _click_option(
+    argument: ArgumentSpec,
+    *,
+    has_alternate_binding: bool,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    declarations = (*argument.aliases, argument.name, argument.parser_name)
+    kwargs: dict[str, Any] = {
+        "required": argument.required and not has_alternate_binding,
+        "help": argument.help,
+    }
+    if argument.default is not None:
+        kwargs["default"] = argument.default
+    if argument.value_type is ArgumentValueType.BOOLEAN:
+        kwargs["is_flag"] = True
+    else:
+        kwargs["type"] = (
+            click.Choice(argument.choices)
+            if argument.choices
+            else _click_type(argument)
+        )
+        kwargs["multiple"] = argument.repeatable
+    if argument.metavar is not None:
+        kwargs["metavar"] = argument.metavar
+    return click.option(*declarations, **kwargs)
+
+
+def with_command_arguments(spec: CommandSpec):
+    """Attach the command-specific arguments declared by ``spec``."""
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        fields_with_alternates = {
+            argument.field
+            for argument in spec.arguments
+            if sum(item.field == argument.field for item in spec.arguments) > 1
+        }
+        for argument in reversed(spec.arguments):
+            option = (
+                _click_argument(argument)
+                if argument.positional
+                else _click_option(
+                    argument,
+                    has_alternate_binding=argument.field in fields_with_alternates,
+                )
+            )
+            fn = option(fn)
+        return fn
+
+    return decorate

cu_cli/commands/_help.py

@@ -0,0 +1,33 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Shared rendering for command examples in terminal help."""
+
+from __future__ import annotations
+
+from rich.markup import escape
+
+
+def common_commands(*examples: tuple[str, str]) -> str:
+    """Render command-first examples with consistent syntax highlighting."""
+    blocks = ["[bold cyan]Common commands:[/bold cyan]"]
+    for command, description in examples:
+        tokens = command.split()
+        styled: list[str] = []
+        command_path = True
+        for token in tokens:
+            safe = escape(token)
+            if token.startswith("-"):
+                style = "bold cyan"
+                command_path = False
+            elif token.isupper() or any(part.isupper() for part in token.split(".")):
+                style = "bold yellow"
+                command_path = False
+            elif command_path:
+                style = "bold green"
+            else:
+                style = "bold magenta"
+            styled.append(f"[{style}]{safe}[/{style}]")
+        blocks.append(" ".join(styled))
+        blocks.append(f"[white]\u00a0\u00a0{escape(description)}[/white]")
+    return "\n\n".join(blocks)