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

cu_cli_core/operations/analyzer_copy.py

@@ -0,0 +1,327 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Analyzer management service (Click-free, client-injected).
+
+Thin wrappers over the CU SDK's analyzer CRUD that add the small pieces of
+domain logic the CLI needs: stable sorting, custom-only filtering, treating a
+create that lands in ``FAILED`` as an error, and treating a delete of a missing
+analyzer as an error (server-side DELETE is idempotent, which otherwise makes a
+typo look like a success). Callers pass a built client; nothing here prints.
+"""
+
+from __future__ import annotations
+
+import shlex
+from typing import Any
+
+from ..errors import (
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    ServiceError,
+    UsageError,
+)
+
+
+def get_copy_source_analyzer(client: Any, analyzer_id: str) -> Any:
+    """Fetch a copy source with copy-specific 404 and auth guidance.
+
+    The command layer also needs the source definition for cross-resource
+    dependency preflight. Keeping the fetch and translation here ensures that
+    both that path and :func:`copy_analyzer` surface the same actionable errors.
+    """
+    from azure.core.exceptions import HttpResponseError, ResourceNotFoundError
+
+    try:
+        return client.get_analyzer(analyzer_id)
+    except ResourceNotFoundError as exc:
+        raise NotFoundError(
+            f"source analyzer '{analyzer_id}' was not found; nothing to copy.",
+            hint="check the source ID with `cu analyzer list` on the source resource.",
+        ) from exc
+    except HttpResponseError as exc:
+        if getattr(exc, "status_code", None) in (401, 403):
+            raise AuthenticationError(
+                "source analyzer lookup failed with an auth error on the source resource.",
+                hint="the signed-in identity needs *Cognitive Services User* on the "
+                     "**source** account. Run `az login` if needed.",
+            ) from exc
+        raise
+
+
+def _target_cli_command(
+    action: str,
+    analyzer_id: str,
+    *,
+    cross_resource: bool,
+    target_cli_options: str | None,
+) -> str | None:
+    """Build a destination-safe follow-up command, or ``None`` if it cannot be scoped."""
+    if cross_resource and not target_cli_options:
+        return None
+    suffix = f" {target_cli_options.strip()}" if target_cli_options else ""
+    return f"cu analyzer {action} {shlex.quote(analyzer_id)}{suffix}"
+
+
+def _target_exists_error(
+    target_analyzer_id: str,
+    *,
+    cross_resource: bool,
+    target_cli_options: str | None,
+) -> ConflictError:
+    """Return the non-destructive collision error used by preflight and 409 handling."""
+    delete_command = _target_cli_command(
+        "delete",
+        target_analyzer_id,
+        cross_resource=cross_resource,
+        target_cli_options=target_cli_options,
+    )
+    overwrite_hint = (
+        f"If you really want to overwrite, delete it explicitly at the destination "
+        f"with `{delete_command}`, then re-run copy."
+        if delete_command
+        else "If you really want to overwrite, explicitly delete it at the destination "
+             "resource, then re-run copy."
+    )
+    return ConflictError(
+        f"destination analyzer '{target_analyzer_id}' already exists.",
+        hint=f"Content Understanding has no in-place replace. Prefer a versioned "
+             f"destination name (for example `{target_analyzer_id}_v2`) so the old copy "
+             f"stays available for validation. {overwrite_hint}",
+    )
+
+
+def copy_analyzer(
+    client: Any,
+    source_analyzer_id: str,
+    target_analyzer_id: str,
+    *,
+    target_client: Any = None,
+    source_azure_resource_id: str | None = None,
+    source_region: str | None = None,
+    target_azure_resource_id: str | None = None,
+    target_region: str | None = None,
+    progress: Any = None,
+    source_analyzer: Any = None,
+    target_cli_options: str | None = None,
+) -> Any:
+    """Copy an analyzer, same-resource or cross-resource.
+
+    **Same-resource** (default): only ``client`` is provided. The call goes to
+    ``client.begin_copy_analyzer(analyzer_id=TARGET, source_analyzer_id=SOURCE)``
+    and the service defaults source coordinates to the current resource.
+
+    **Cross-resource**: ``target_client`` is a second SDK client bound to the
+    destination resource, and the four ARM-ID + region args identify the two
+    resources canonically. Orchestration:
+
+    1. ``client.grant_copy_authorization(analyzer_id=SOURCE,
+       target_azure_resource_id=<destination ARM>,
+       target_region=<destination region>)``
+       on the *source* client.
+    2. ``target_client.begin_copy_analyzer(analyzer_id=TARGET,
+       source_analyzer_id=SOURCE, source_azure_resource_id=<source ARM>,
+       source_region=<source region>)`` on the *destination* client.
+
+    The authorization record is destination-scoped, time-limited, and never printed
+    or persisted — the service stores the grant server-side. The optional
+    ``progress`` callable, if supplied, is invoked with a one-line status
+    string before each data-plane call so callers can render live progress
+    without this module depending on ``rich``.
+
+    ``source_analyzer`` may carry the definition already fetched by the command
+    layer's dependency preflight, avoiding a duplicate source request.
+    ``target_cli_options`` contains non-secret CLI options that qualify recovery
+    commands to the destination (for example ``--profile prod`` or
+    ``--endpoint https://... --auth-mode login``).
+
+    Raises a typed core error on 404 or when the destination exists;
+    Content Understanding has no in-place replace. Also raises when the LRO
+    lands in ``FAILED`` or when authorization expires before the copy completes.
+    """
+    from azure.core.exceptions import HttpResponseError, ResourceNotFoundError
+
+    cross_resource = target_client is not None and target_client is not client
+    copier = target_client if cross_resource else client
+
+    if cross_resource and not (
+        source_azure_resource_id
+        and source_region
+        and target_azure_resource_id
+        and target_region
+    ):
+        raise UsageError(
+            "cross-resource copy requires source and destination Azure resource IDs and regions.",
+            hint="this is an internal error — the CLI should have resolved them "
+                 "via --source-resource/--destination-resource before calling copy_analyzer.",
+        )
+
+    # 1. Confirm the source exists up-front. The service returns 400
+    #    (InvalidRequest) rather than 404 on a missing source_analyzer_id,
+    #    which is harder to interpret than an explicit lookup. The command
+    #    layer may already have fetched it for dependency inspection.
+    if source_analyzer is None:
+        if progress is not None:
+            progress(f"checking source analyzer '{source_analyzer_id}'")
+        source_analyzer = get_copy_source_analyzer(client, source_analyzer_id)
+
+    # 2. Confirm the destination is absent *before* granting authorization. This is
+    #    both safer and more actionable than waiting for begin_copy_analyzer to
+    #    return 409. Keep the 409 handler below for races between this lookup
+    #    and LRO creation.
+    if progress is not None:
+        progress(f"checking destination analyzer '{target_analyzer_id}'")
+    try:
+        copier.get_analyzer(target_analyzer_id)
+    except ResourceNotFoundError:
+        pass
+    except HttpResponseError as exc:
+        status = getattr(exc, "status_code", None)
+        if status == 404:
+            pass
+        elif status in (401, 403):
+            raise AuthenticationError(
+                "destination analyzer lookup failed with an auth error "
+                "on the destination resource.",
+                hint="the signed-in identity needs *Cognitive Services User* on the "
+                     "**destination** account. Run `az login` if needed.",
+            ) from exc
+        else:
+            raise
+    else:
+        raise _target_exists_error(
+            target_analyzer_id,
+            cross_resource=cross_resource,
+            target_cli_options=target_cli_options,
+        )
+
+    # 3. Cross-resource: grant destination-scoped authorization first, so the
+    #    subsequent begin_copy_analyzer at the destination can pull the source.
+    if cross_resource:
+        if progress is not None:
+            progress("granting temporary copy authorization for the cross-resource copy")
+        try:
+            client.grant_copy_authorization(
+                analyzer_id=source_analyzer_id,
+                target_azure_resource_id=target_azure_resource_id,
+                target_region=target_region,
+            )
+        except HttpResponseError as exc:
+            status = getattr(exc, "status_code", None)
+            if status in (401, 403):
+                raise AuthenticationError(
+                    "grant_copy_authorization failed with an auth error on the source resource.",
+                    hint="the signed-in identity needs *Cognitive Services User* on the "
+                         "**source** account. Run `az login` if needed.",
+                ) from exc
+            raise
+        # Note: we do *not* print the returned CopyAuthorization record
+        # (source, target_azure_resource_id, expires_at). The service stores
+        # the grant server-side for the target's subsequent copy request.
+
+    # 4. Start the copy LRO on the destination client and wait.
+    copy_kwargs: dict[str, Any] = {
+        "analyzer_id": target_analyzer_id,
+        "source_analyzer_id": source_analyzer_id,
+    }
+    if cross_resource:
+        copy_kwargs["source_azure_resource_id"] = source_azure_resource_id
+        copy_kwargs["source_region"] = source_region
+    if progress is not None:
+        target_suffix = " on the destination resource" if cross_resource else ""
+        progress(
+            f"copying '{source_analyzer_id}' -> '{target_analyzer_id}'"
+            f"{target_suffix}; this may take several minutes"
+        )
+
+    try:
+        poller = copier.begin_copy_analyzer(**copy_kwargs)
+        result = poller.result()
+    except HttpResponseError as exc:
+        status = getattr(exc, "status_code", None)
+        if status == 409:
+            raise _target_exists_error(
+                target_analyzer_id,
+                cross_resource=cross_resource,
+                target_cli_options=target_cli_options,
+            ) from exc
+        if cross_resource and status in (401, 403):
+            raise AuthenticationError(
+                "copy failed with an auth error on the destination resource.",
+                hint="the signed-in identity needs *Cognitive Services User* on the "
+                "**destination** account. If authorization has expired between grant "
+                "and copy, simply re-run — the CLI grants a fresh one each call.",
+            ) from exc
+        raise
+
+    # 5. If the copy landed in a terminal FAILED state, treat like create_analyzer.
+    final_id = getattr(result, "analyzer_id", target_analyzer_id)
+    status = getattr(result, "status", None)
+    if status and str(status).lower().endswith("failed"):
+        show_command = _target_cli_command(
+            "show",
+            final_id,
+            cross_resource=cross_resource,
+            target_cli_options=target_cli_options,
+        )
+        raise ServiceError(
+            f"analyzer '{final_id}' was copied but its status is FAILED.",
+            hint=(f"run `{show_command}` for details."
+                  if show_command
+                  else "inspect the analyzer explicitly at the destination for details."),
+        )
+    return result
+
+
+def collect_custom_dependencies(source_analyzer: Any) -> list[str]:
+    """Return the list of *custom* analyzer IDs referenced by classifier / segmentation categories.
+
+    Walks ``source.config.content_categories`` (the SDK models this as a mapping
+    from category name to ``ContentCategoryDefinition``; list-shaped payloads
+    are accepted for compatibility). Each definition may reference another
+    analyzer via ``analyzer_id``. Prebuilt refs
+    (``prebuilt-<something>``) are skipped—the destination has the same
+    prebuilt catalog. Only *custom* refs need to exist at the destination before
+    the parent analyzer can be copied.
+
+    Returns an empty list when the analyzer has no categories or no refs.
+    """
+    result: list[str] = []
+    cfg = getattr(source_analyzer, "config", None)
+    if cfg is None:
+        return result
+    categories = getattr(cfg, "content_categories", None) or {}
+    category_definitions = categories.values() if isinstance(categories, dict) else categories
+    for cat in category_definitions:
+        aid = getattr(cat, "analyzer_id", None) or (cat.get("analyzer_id") if isinstance(cat, dict) else None)
+        if not aid:
+            continue
+        if aid.startswith("prebuilt-"):
+            continue
+        if aid not in result:
+            result.append(aid)
+    return result
+
+
+def preflight_dependencies_on_target(
+    target_client: Any,
+    dependencies: list[str],
+) -> list[str]:
+    """Return the subset of ``dependencies`` that are missing on ``target_client``.
+
+    Empty result means the target already has every custom analyzer the source
+    depends on. This is a black-box existence check — we call
+    ``target_client.get_analyzer(aid)`` and treat 404 as missing. Any other
+    error is surfaced verbatim so a broken target endpoint doesn't get
+    misreported as a missing dependency.
+    """
+    from azure.core.exceptions import ResourceNotFoundError
+
+    missing: list[str] = []
+    for aid in dependencies:
+        try:
+            target_client.get_analyzer(aid)
+        except ResourceNotFoundError:
+            missing.append(aid)
+    return missing

cu_cli_core/operations/analyzers.py

@@ -0,0 +1,85 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Client-injected analyzer operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import ConflictError, NotFoundError, ServiceError
+
+
+def _value(analyzer: Any, *keys: str) -> str:
+    for key in keys:
+        value = getattr(analyzer, key, None)
+        if value is not None:
+            return str(value)
+    value = analyzer.as_dict() if hasattr(analyzer, "as_dict") else {}
+    if isinstance(value, dict):
+        for key in keys:
+            if value.get(key) is not None:
+                return str(value[key])
+    return ""
+
+
+def list_analyzers(
+    client: Any,
+    *,
+    kind: str = "all",
+    sort_by: str = "analyzerId",
+) -> list[Any]:
+    items = list(client.list_analyzers())
+    if kind != "all":
+        items = [item for item in items if analyzer_kind(item) == kind]
+    sort_keys = {
+        "analyzerId": ("analyzer_id", "analyzerId"),
+        "createdAt": ("created_at", "createdAt"),
+        "lastModifiedAt": ("last_modified_at", "lastModifiedAt"),
+    }
+    return sorted(items, key=lambda item: _value(item, *sort_keys[sort_by]))
+
+
+def analyzer_kind(analyzer: Any) -> str:
+    analyzer_id = _value(analyzer, "analyzer_id", "analyzerId")
+    return "prebuilt" if analyzer_id.startswith("prebuilt-") else "custom"
+
+
+def get_analyzer(client: Any, analyzer_id: str) -> Any:
+    return client.get_analyzer(analyzer_id)
+
+
+def create_analyzer(client: Any, analyzer_id: str, body: dict[str, Any]) -> Any:
+    from azure.core.exceptions import HttpResponseError
+
+    try:
+        poller = client.begin_create_analyzer(analyzer_id, body)
+        result = poller.result()
+    except HttpResponseError as exc:
+        if exc.status_code == 409:
+            raise ConflictError(
+                f"analyzer '{analyzer_id}' already exists.",
+                hint="Delete the existing analyzer explicitly or choose a versioned name.",
+                status_code=409,
+            ) from exc
+        raise
+    status = getattr(result, "status", None)
+    if status and str(status).lower().endswith("failed"):
+        raise ServiceError(
+            f"analyzer '{getattr(result, 'analyzer_id', analyzer_id)}' "
+            "was created but its status is FAILED."
+        )
+    return result
+
+
+def delete_analyzer(client: Any, analyzer_id: str) -> None:
+    from azure.core.exceptions import ResourceNotFoundError
+
+    try:
+        client.get_analyzer(analyzer_id)
+    except ResourceNotFoundError as exc:
+        raise NotFoundError(
+            f"analyzer '{analyzer_id}' was not found; nothing was deleted.",
+            status_code=404,
+        ) from exc
+    client.delete_analyzer(analyzer_id)

cu_cli_core/operations/profiles.py

@@ -0,0 +1,146 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Shared profile operations with frontend-injected storage and discovered models."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping
+
+from ..contracts import (
+    ProfileCopyRequest,
+    ProfileCreateRequest,
+    ProfileDeleteRequest,
+    ProfileGetRequest,
+    ProfileListRequest,
+    ProfileRenameRequest,
+    ProfileSetActiveRequest,
+    ProfileSetRequest,
+    ProfileShowRequest,
+    ProfileSyncModelsRequest,
+    ProfileUnsetRequest,
+)
+from ..errors import NotFoundError
+from ..profiles import Profile, ProfileStore, validate_profile_name
+
+
+def show_profile(
+    request: ProfileShowRequest,
+    *,
+    path: Path | None = None,
+    include_environment: bool = True,
+) -> Profile:
+    loader = Profile.load if include_environment else Profile.load_saved
+    return loader(profile_name=request.name, path=path)
+
+
+def list_profiles(
+    request: ProfileListRequest,
+    *,
+    path: Path | None = None,
+) -> tuple[str, tuple[str, ...]]:
+    del request
+    store = ProfileStore.load(path)
+    return store.get_active_name(), tuple(store.list_names())
+
+
+def get_profile_value(
+    request: ProfileGetRequest,
+    *,
+    path: Path | None = None,
+) -> str | None:
+    return ProfileStore.load(path).get(request.key, name=request.name)
+
+
+def set_profile_value(
+    request: ProfileSetRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    store.set(request.key, request.value, name=request.name)
+    return store.save()
+
+
+def unset_profile_value(
+    request: ProfileUnsetRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    if not store.unset(request.key, name=request.name):
+        target = request.name or store.get_active_name()
+        raise NotFoundError(
+            f"'{request.key}' is not saved in profile '{target}'.",
+            hint="`cu profile show` includes inherited defaults and environment overrides; "
+            "only explicitly saved values can be unset.",
+        )
+    return store.save()
+
+
+def create_profile(
+    request: ProfileCreateRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    store.create_name(request.name)
+    return store.save()
+
+
+def delete_profile(
+    request: ProfileDeleteRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    store.delete_name(request.name)
+    return store.save()
+
+
+def copy_profile(
+    request: ProfileCopyRequest,
+    *,
+    path: Path | None = None,
+) -> tuple[Path, str]:
+    store = ProfileStore.load(path)
+    source = (
+        store.get_active_name()
+        if request.source is None
+        else validate_profile_name(request.source)
+    )
+    store.copy_name(source, request.destination)
+    return store.save(), source
+
+
+def rename_profile(
+    request: ProfileRenameRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    store.rename_name(request.source, request.destination)
+    return store.save()
+
+
+def set_active_profile(
+    request: ProfileSetActiveRequest,
+    *,
+    path: Path | None = None,
+) -> Path:
+    store = ProfileStore.load(path)
+    store.set_active_name(request.name)
+    return store.save()
+
+
+def sync_profile_models(
+    request: ProfileSyncModelsRequest,
+    model_deployments: Mapping[str, str],
+    *,
+    path: Path | None = None,
+) -> tuple[Path, str]:
+    store = ProfileStore.load(path)
+    target = store.get_active_name() if request.name is None else request.name
+    store.replace_model_deployments(model_deployments, name=target)
+    return store.save(), target

cu_cli_core/operations/schema.py

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Shared schema-create operation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..contracts import AnalyzerSchemaCreateRequest
+from ..errors import UsageError
+from ..schema import (
+    MODALITY_BASE,
+    starter_schema,
+    suggest_schema_from_sample,
+)
+
+
+def create_schema(
+    request: AnalyzerSchemaCreateRequest,
+    *,
+    api_version: str,
+    completion_model: str,
+    client: Any | None = None,
+) -> tuple[dict[str, Any], bool]:
+    """Create a starter or sample-derived schema from a normalized request."""
+
+    if request.from_sample is not None:
+        if client is None:
+            raise UsageError("sample-derived schema creation requires a CU client.")
+        return suggest_schema_from_sample(
+            client,
+            sample_path=request.from_sample,
+            analyzer_id=request.name,
+            api_version=api_version,
+            completion_model=completion_model,
+        )
+    return (
+        starter_schema(
+            request.name,
+            request.base or MODALITY_BASE[request.modality],
+            request.modality,
+            api_version,
+            completion_model=completion_model,
+            template_type=request.template_type,
+        ),
+        True,
+    )

cu_cli_core/operations/validation.py

@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Frontend-neutral schema validation."""
+
+from __future__ import annotations
+
+from ..contracts import AnalyzerValidateRequest
+from ..schema_validation import Finding, ValidationResult, parse_and_validate
+from ..spec_validation import validate_against_spec
+
+
+def validate_schema(
+    request: AnalyzerValidateRequest,
+    *,
+    api_version: str,
+) -> ValidationResult:
+    """Validate a schema with curated rules and the optional service contract."""
+
+    try:
+        text = request.schema.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, ValueError) as exc:
+        return ValidationResult(
+            ok=False,
+            errors=[
+                Finding(
+                    "$",
+                    f"{request.schema.name} is not a UTF-8 JSON schema file "
+                    f"({exc.__class__.__name__}); it looks like a binary or non-text file. "
+                    "Pass a JSON analyzer schema.",
+                )
+            ],
+        )
+
+    result, body = parse_and_validate(text, api_version=api_version)
+    if request.spec and body is not None:
+        spec_result = validate_against_spec(body, api_version=api_version)
+        result.errors.extend(spec_result.errors)
+        result.warnings.extend(spec_result.warnings)
+        result.ok = not result.errors
+    return result