cu-cli-core 0.1.0b1__py3-none-any.whl

cu_cli_core/contracts.py

@@ -0,0 +1,404 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Typed request and planning contracts shared by CU command frontends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Mapping
+
+
+class ResultView(str, Enum):
+    LLM_INPUT = "llm-input"
+    FULL = "full"
+
+
+class SelectionMode(str, Enum):
+    POSITIONAL = "positional"
+    NAMED_FILES = "named-files"
+    NAMED_SOURCES = "named-sources"
+
+
+class InputOrigin(str, Enum):
+    POSITIONAL_FILE = "positional-file"
+    POSITIONAL_SOURCE = "positional-source"
+    NAMED_FILE = "named-file"
+    NAMED_SOURCE = "named-source"
+
+
+class ExistingResultPolicy(str, Enum):
+    ERROR = "error"
+    SKIP = "skip"
+    REANALYZE = "reanalyze"
+
+
+class AuthMode(str, Enum):
+    LOGIN = "login"
+    KEY = "key"
+
+
+class OutcomeStatus(str, Enum):
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class ProfileShowRequest:
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class ProfileListRequest:
+    pass
+
+
+@dataclass(frozen=True)
+class ProfileGetRequest:
+    key: str
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class ProfileSetRequest:
+    key: str
+    value: str
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class ProfileUnsetRequest:
+    key: str
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class ProfileCreateRequest:
+    name: str
+
+
+@dataclass(frozen=True)
+class ProfileDeleteRequest:
+    name: str
+
+
+@dataclass(frozen=True)
+class ProfileCopyRequest:
+    destination: str
+    source: str | None = None
+
+
+@dataclass(frozen=True)
+class ProfileRenameRequest:
+    source: str
+    destination: str
+
+
+@dataclass(frozen=True)
+class ProfileSetActiveRequest:
+    name: str
+
+
+@dataclass(frozen=True)
+class ProfileSyncModelsRequest:
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class AnalyzerShowRequest:
+    """Canonical request for retrieving one analyzer."""
+
+    name: str
+
+    def __post_init__(self) -> None:
+        normalized = self.name.strip()
+        if not normalized:
+            raise ValueError("analyzer name cannot be empty.")
+        object.__setattr__(self, "name", normalized)
+
+
+@dataclass(frozen=True)
+class AnalyzerListRequest:
+    kind: str = "all"
+    sort_by: str = "analyzerId"
+
+    def __post_init__(self) -> None:
+        if self.kind not in {"all", "prebuilt", "custom"}:
+            raise ValueError(f"invalid analyzer kind: {self.kind}")
+        if self.sort_by not in {"analyzerId", "createdAt", "lastModifiedAt"}:
+            raise ValueError(f"invalid analyzer sort field: {self.sort_by}")
+
+
+@dataclass(frozen=True)
+class AnalyzerCreateRequest:
+    name: str
+    schema: Path
+
+    def __post_init__(self) -> None:
+        normalized = self.name.strip()
+        if not normalized:
+            raise ValueError("analyzer name cannot be empty.")
+        object.__setattr__(self, "name", normalized)
+        object.__setattr__(self, "schema", Path(self.schema))
+
+
+@dataclass(frozen=True)
+class AnalyzerDeleteRequest:
+    name: str
+    yes: bool = False
+
+    def __post_init__(self) -> None:
+        normalized = self.name.strip()
+        if not normalized:
+            raise ValueError("analyzer name cannot be empty.")
+        object.__setattr__(self, "name", normalized)
+
+
+@dataclass(frozen=True)
+class AnalyzeRequest:
+    positional_inputs: tuple[Path, ...] = ()
+    files: tuple[Path, ...] = ()
+    sources: tuple[Path, ...] = ()
+    pattern: str | None = None
+    recursive: bool = False
+    analyzer: str | None = None
+    inline: bool = False
+    usage: bool = False
+    llm_input: bool = False
+    output_file: Path | None = None
+    output_dir: Path | None = None
+    on_existing: ExistingResultPolicy | None = None
+    dry_run: bool = False
+    yes: bool = False
+    report_file: Path | None = None
+    concurrency: int = 4
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "positional_inputs",
+            tuple(Path(path) for path in self.positional_inputs),
+        )
+        object.__setattr__(self, "files", tuple(Path(path) for path in self.files))
+        object.__setattr__(self, "sources", tuple(Path(path) for path in self.sources))
+        if self.output_file is not None:
+            object.__setattr__(self, "output_file", Path(self.output_file))
+        if self.output_dir is not None:
+            object.__setattr__(self, "output_dir", Path(self.output_dir))
+        if self.report_file is not None:
+            object.__setattr__(self, "report_file", Path(self.report_file))
+        if isinstance(self.on_existing, str):
+            object.__setattr__(
+                self,
+                "on_existing",
+                ExistingResultPolicy(self.on_existing),
+            )
+        if not 1 <= self.concurrency <= 32:
+            raise ValueError("concurrency must be between 1 and 32.")
+
+
+@dataclass(frozen=True)
+class AnalyzerTestRequest:
+    name: str
+    positional_inputs: tuple[Path, ...] = ()
+    files: tuple[Path, ...] = ()
+    sources: tuple[Path, ...] = ()
+    pattern: str | None = None
+    recursive: bool = False
+    dry_run: bool = False
+    output_file: Path | None = None
+    force: bool = False
+    yes: bool = False
+    concurrency: int = 4
+
+    def __post_init__(self) -> None:
+        normalized = self.name.strip()
+        if not normalized:
+            raise ValueError("analyzer name cannot be empty.")
+        object.__setattr__(self, "name", normalized)
+        object.__setattr__(
+            self,
+            "positional_inputs",
+            tuple(Path(path) for path in self.positional_inputs),
+        )
+        object.__setattr__(self, "files", tuple(Path(path) for path in self.files))
+        object.__setattr__(self, "sources", tuple(Path(path) for path in self.sources))
+        if self.output_file is not None:
+            object.__setattr__(self, "output_file", Path(self.output_file))
+        if not 1 <= self.concurrency <= 16:
+            raise ValueError("concurrency must be between 1 and 16.")
+
+
+@dataclass(frozen=True)
+class AnalyzerCopyRequest:
+    source: str
+    destination: str
+    source_resource: str | None = None
+    source_subscription: str | None = None
+    source_resource_group: str | None = None
+    source_profile: str | None = None
+    destination_resource: str | None = None
+    destination_subscription: str | None = None
+    destination_resource_group: str | None = None
+    destination_profile: str | None = None
+
+    def __post_init__(self) -> None:
+        source = self.source.strip()
+        destination = self.destination.strip()
+        if not source or not destination:
+            raise ValueError("source and destination analyzer names are required.")
+        object.__setattr__(self, "source", source)
+        object.__setattr__(self, "destination", destination)
+        if self.source_resource and self.source_profile:
+            raise ValueError(
+                "--source-resource and --source-profile are mutually exclusive."
+            )
+        if self.destination_resource and self.destination_profile:
+            raise ValueError(
+                "--destination-resource and --destination-profile are mutually exclusive."
+            )
+
+
+@dataclass(frozen=True)
+class AnalyzerValidateRequest:
+    schema: Path
+    strict: bool = False
+    spec: bool = False
+    api_version: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "schema", Path(self.schema))
+
+
+@dataclass(frozen=True)
+class AnalyzerSchemaCreateRequest:
+    from_template: bool = False
+    from_sample: Path | None = None
+    name: str = "my_analyzer_v1"
+    base: str | None = None
+    modality: str = "document"
+    output_file: Path | None = None
+    template_type: str = "extraction"
+    force: bool = False
+
+    def __post_init__(self) -> None:
+        name = self.name.strip()
+        if not name:
+            raise ValueError("analyzer name cannot be empty.")
+        object.__setattr__(self, "name", name)
+        if self.from_sample is not None:
+            object.__setattr__(self, "from_sample", Path(self.from_sample))
+        if self.output_file is not None:
+            object.__setattr__(self, "output_file", Path(self.output_file))
+        if self.from_template and self.from_sample is not None:
+            raise ValueError("--from-template and --from-sample cannot be combined.")
+        if self.modality not in {"document", "image", "audio", "video"}:
+            raise ValueError(f"invalid modality: {self.modality}")
+        if self.template_type not in {"extraction", "classification"}:
+            raise ValueError(f"invalid schema type: {self.template_type}")
+        if self.from_sample is not None and (
+            self.template_type != "extraction"
+            or self.modality != "document"
+            or self.base is not None
+        ):
+            raise ValueError(
+                "--from-sample cannot be combined with --type classification, "
+                "--modality, or --base."
+            )
+
+
+@dataclass(frozen=True)
+class DefaultsShowRequest:
+    pass
+
+
+@dataclass(frozen=True)
+class DefaultsSetRequest:
+    models: tuple[str, ...] = ()
+    from_profile: bool = False
+    replace: bool = False
+
+
+@dataclass(frozen=True)
+class EnvironmentVariableListRequest:
+    pass
+
+
+@dataclass(frozen=True)
+class PlannedInput:
+    path: Path
+    source_root: Path
+    relative_path: Path
+    origin: InputOrigin
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class SkippedInput:
+    path: Path
+    reason: str
+
+
+@dataclass(frozen=True)
+class InputPlan:
+    inputs: tuple[PlannedInput, ...]
+    mode: SelectionMode
+    recursive: bool
+    pattern: str | None
+    total_bytes: int
+    extension_counts: Mapping[str, int] = field(default_factory=dict)
+    skipped: tuple[SkippedInput, ...] = ()
+
+
+@dataclass(frozen=True)
+class PlannedOutput:
+    source: PlannedInput
+    path: Path | None
+    exists: bool = False
+    skipped: bool = False
+
+
+@dataclass(frozen=True)
+class ExecutionPlan:
+    input_plan: InputPlan
+    outputs: tuple[PlannedOutput, ...]
+    on_existing: ExistingResultPolicy
+    dry_run: bool
+
+
+@dataclass(frozen=True)
+class ErrorDetail:
+    code: str | None = None
+    message: str | None = None
+    target: str | None = None
+
+
+@dataclass(frozen=True)
+class FileOutcome:
+    source: Path
+    status: OutcomeStatus
+    analyzer: str
+    output_path: Path | None = None
+    usage: Mapping[str, Any] | None = None
+    error: ErrorDetail | None = None
+    payload: Any = None
+
+
+@dataclass(frozen=True)
+class BatchReport:
+    outcomes: tuple[FileOutcome, ...]
+
+    @property
+    def succeeded(self) -> int:
+        return sum(item.status is OutcomeStatus.SUCCEEDED for item in self.outcomes)
+
+    @property
+    def failed(self) -> int:
+        return sum(item.status is OutcomeStatus.FAILED for item in self.outcomes)
+
+    @property
+    def skipped(self) -> int:
+        return sum(item.status is OutcomeStatus.SKIPPED for item in self.outcomes)

cu_cli_core/defaults.py

@@ -0,0 +1,150 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Client-injected CU service-default operations."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .errors import NotFoundError, ValidationError
+
+PREFERRED_EMBEDDING_MODEL = "text-embedding-3-large"
+COMPLETION_MODEL_PREFERENCE = ("gpt-5.2",)
+PREBUILT_COMPLETION_KEY = "prebuilt-analyzer-completion"
+PREBUILT_COMPLETION_MINI_KEY = "prebuilt-analyzer-completion-mini"
+PREBUILT_EMBEDDING_KEY = "prebuilt-analyzer-embedding"
+
+
+def with_prebuilt_default_mappings(
+    model_deployments: Mapping[str, str],
+) -> dict[str, str]:
+    """Return model mappings enriched with the aliases required by prebuilt analyzers."""
+
+    out = {str(key): str(value) for key, value in model_deployments.items()}
+    model_names = list(out)
+
+    def is_alias(name: str) -> bool:
+        return name.startswith("prebuilt-analyzer-")
+
+    completion_model = next(
+        (model for model in COMPLETION_MODEL_PREFERENCE if model in out),
+        None,
+    )
+    if completion_model is None:
+        completion_model = next(
+            (
+                name
+                for name in model_names
+                if not is_alias(name)
+                and not name.startswith("text-embedding-")
+                and not name.endswith("-mini")
+            ),
+            None,
+        )
+
+    mini_model = next(
+        (
+            model
+            for model in ("gpt-5.2-mini", "gpt-4.1-mini", "gpt-4o-mini")
+            if model in out
+        ),
+        None,
+    )
+    if mini_model is None:
+        mini_model = next(
+            (name for name in model_names if not is_alias(name) and name.endswith("-mini")),
+            None,
+        )
+
+    embedding_model = next(
+        (
+            name
+            for name in (PREFERRED_EMBEDDING_MODEL, *sorted(model_names))
+            if name in out and name.startswith("text-embedding-")
+        ),
+        None,
+    )
+
+    if completion_model is None and mini_model is not None:
+        completion_model = mini_model
+    if completion_model is not None:
+        out[PREBUILT_COMPLETION_KEY] = out[completion_model]
+        out[PREBUILT_COMPLETION_MINI_KEY] = (
+            out[mini_model] if mini_model else out[completion_model]
+        )
+    if embedding_model is not None:
+        out[PREBUILT_EMBEDDING_KEY] = out[embedding_model]
+    return out
+
+
+def is_defaults_not_set(exc: Exception) -> bool:
+    """Return whether a service exception means defaults have not been configured."""
+
+    message = getattr(exc, "message", None) or str(exc)
+    return "DefaultsNotSet" in message or "Defaults have not yet been set" in message
+
+
+def get_defaults(client: Any) -> Any:
+    """Return service defaults from an injected client."""
+
+    from azure.core.exceptions import HttpResponseError
+
+    try:
+        return client.get_defaults()
+    except HttpResponseError as exc:
+        if is_defaults_not_set(exc):
+            raise NotFoundError(
+                "defaults are not set yet on this resource.",
+                hint="Configure model deployments, then run defaults set.",
+            ) from exc
+        raise
+
+
+def extract_model_deployments(defaults_obj: Any) -> dict[str, str]:
+    """Return a defaults object's model-deployment mapping as strings."""
+
+    mapped = getattr(defaults_obj, "model_deployments", None) or {}
+    return {str(key): str(value) for key, value in mapped.items()}
+
+
+def parse_model_kv(values: Sequence[str]) -> dict[str, str]:
+    """Parse repeatable ``MODEL=DEPLOYMENT`` values."""
+
+    parsed: dict[str, str] = {}
+    for raw in values:
+        if "=" not in raw:
+            raise ValidationError(
+                f"invalid --model mapping '{raw}'.",
+                hint="use --model MODEL=DEPLOYMENT (repeatable).",
+            )
+        model, deployment = (part.strip() for part in raw.split("=", 1))
+        if not model or not deployment:
+            raise ValidationError(
+                f"invalid --model mapping '{raw}'.",
+                hint="use --model MODEL=DEPLOYMENT (repeatable).",
+            )
+        parsed[model] = deployment
+    return parsed
+
+
+def apply_defaults(
+    client: Any,
+    desired: Mapping[str, str],
+    *,
+    replace: bool,
+) -> tuple[Any, dict[str, str]]:
+    """Merge or replace service defaults and return the result and final mapping."""
+
+    existing: dict[str, str] = {}
+    if not replace:
+        from azure.core.exceptions import HttpResponseError
+
+        try:
+            existing = extract_model_deployments(client.get_defaults())
+        except HttpResponseError as exc:
+            if not is_defaults_not_set(exc):
+                raise
+    merged = dict(desired) if replace else {**existing, **desired}
+    merged = with_prebuilt_default_mappings(merged)
+    return client.update_defaults(model_deployments=merged), merged

cu_cli_core/environment.py

@@ -0,0 +1,102 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Static environment-variable metadata and redacted process inspection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Mapping
+
+REDACTED_VALUE = "********"
+
+
+@dataclass(frozen=True)
+class EnvironmentVariableSpec:
+    name: str
+    description: str
+    accepted_values: str
+    default: str
+    scope: str
+    precedence: str
+    sensitive: bool = False
+
+
+ENVIRONMENT_VARIABLES = (
+    EnvironmentVariableSpec(
+        name="CU_ENDPOINT",
+        description="Microsoft Foundry resource endpoint for Content Understanding.",
+        accepted_values="HTTPS URL",
+        default="not set",
+        scope="service commands",
+        precedence="Overrides the endpoint in the selected CU CLI profile.",
+    ),
+    EnvironmentVariableSpec(
+        name="CU_API_KEY",
+        description="API key used for key authentication.",
+        accepted_values="secret string",
+        default="not set",
+        scope="authentication",
+        precedence="Overrides the selected CU CLI profile and implies key authentication.",
+        sensitive=True,
+    ),
+    EnvironmentVariableSpec(
+        name="CU_AUTH_MODE",
+        description="Authentication mode.",
+        accepted_values="login | key",
+        default="login",
+        scope="authentication",
+        precedence="Overrides authentication in the selected CU CLI profile.",
+    ),
+    EnvironmentVariableSpec(
+        name="CU_API_VERSION",
+        description="Content Understanding API version.",
+        accepted_values="supported API version",
+        default="2025-11-01",
+        scope="service commands",
+        precedence="Overrides the API version in the selected CU CLI profile.",
+    ),
+    EnvironmentVariableSpec(
+        name="CU_TELEMETRY",
+        description="Controls the cu-cli User-Agent adoption marker.",
+        accepted_values="off | 0 | false | no to disable",
+        default="on",
+        scope="service commands",
+        precedence="Controls CLI telemetry behavior directly.",
+    ),
+    EnvironmentVariableSpec(
+        name="CU_NO_UPDATE_CHECK",
+        description="Disables the daily package update check.",
+        accepted_values="1 | true | yes | on to disable",
+        default="off",
+        scope="update check",
+        precedence="Controls update-check behavior directly.",
+    ),
+    EnvironmentVariableSpec(
+        name="CU_ON_EXISTS",
+        description="Chooses how analyze handles an existing result file.",
+        accepted_values="error | skip | reanalyze",
+        default="error",
+        scope="analyze",
+        precedence="Used when --on-existing is not specified.",
+    ),
+)
+
+
+def list_set_environment_variables(
+    environ: Mapping[str, str] | None = None,
+) -> list[dict[str, object]]:
+    """Return recognized variables currently set, redacting sensitive values."""
+
+    values = os.environ if environ is None else environ
+    return [
+        {
+            "name": spec.name,
+            "value": REDACTED_VALUE if spec.sensitive else values[spec.name],
+            "scope": spec.scope,
+            "sensitive": spec.sensitive,
+        }
+        for spec in ENVIRONMENT_VARIABLES
+        if spec.name in values
+    ]