cu-cli 0.1.0b1__py3-none-any.whl

cu_cli/resources/azd_template/infra/main.bicep

@@ -0,0 +1,115 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+targetScope = 'subscription'
+
+@minLength(1)
+@maxLength(64)
+@description('Name of the environment. Used to derive resource names including resource group (rg-<name>), Foundry project (proj-<name>), and a unique suffix for the Foundry resource name.')
+param environmentName string
+
+@minLength(1)
+@allowed([
+  'australiaeast'
+  'eastus'
+  'eastus2'
+  'japaneast'
+  'northeurope'
+  'southcentralus'
+  'southeastasia'
+  'swedencentral'
+  'uksouth'
+  'westeurope'
+  'westus'
+  'westus3'
+])
+@description('Primary Azure region for the Foundry resource. Must be a supported region for Azure Content Understanding (https://learn.microsoft.com/azure/ai-services/content-understanding/language-region-support)')
+param location string
+
+@description('Optional prefix for the Foundry resource name. The final resource name becomes <prefix>-<unique-suffix>. Leave empty to use the default aif- prefix.')
+param foundryResourcePrefix string = ''
+
+@description('Optional existing Foundry endpoint. When set, this template skips creating Foundry account/project and deploys models to this existing account.')
+param existingFoundryEndpoint string = ''
+
+@description('Resource group of the existing Foundry account when existingFoundryEndpoint is set.')
+param existingFoundryResourceGroup string = ''
+
+@description('Object ID of the user or service principal that should receive Cognitive Services User on the Foundry resource. azd injects AZURE_PRINCIPAL_ID automatically.')
+param principalId string
+
+@description('Type of principal for the role assignments.')
+@allowed([ 'User', 'ServicePrincipal' ])
+param principalType string = 'User'
+
+@description('If "true", assign Cognitive Services User to principalId for Entra-authenticated CU operations. Requires Owner, User Access Administrator, or Role Based Access Control Administrator. Set to "false" when you only have Contributor.')
+param assignRolesToPrincipal string = 'true'
+
+// Model deployments are loaded from infra/models.json so the file is
+// hand-editable and round-trippable through other tooling (e.g. `cu infra generate`).
+var modelDeployments = loadJsonContent('models.json')
+
+var foundryUniqueSuffix = toLower(uniqueString(subscription().id, environmentName, location))
+var rgName       = 'rg-${environmentName}'
+var useExistingFoundry = !empty(trim(existingFoundryEndpoint))
+var existingFoundryAccountName = useExistingFoundry
+  ? split(replace(replace(toLower(trim(existingFoundryEndpoint)), 'https://', ''), 'http://', ''), '.')[0]
+  : ''
+var normalizedResourcePrefix = toLower(trim(foundryResourcePrefix))
+var resourceNamePrefix = empty(normalizedResourcePrefix) ? 'aif' : normalizedResourcePrefix
+var foundryResourceName  = useExistingFoundry ? existingFoundryAccountName : '${resourceNamePrefix}-${foundryUniqueSuffix}'
+var projectName  = 'proj-${environmentName}'
+
+resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = if (!useExistingFoundry) {
+  name: rgName
+  location: location
+  tags: {
+    'azd-env-name': environmentName
+  }
+}
+
+resource existingRg 'Microsoft.Resources/resourceGroups@2024-03-01' existing = if (useExistingFoundry) {
+  name: existingFoundryResourceGroup
+}
+
+module foundryNew 'modules/foundry.bicep' = if (!useExistingFoundry) {
+  name: 'foundry-new'
+  scope: rg
+  params: {
+    useExistingFoundry: useExistingFoundry
+    accountName: foundryResourceName
+    projectName: projectName
+    location: location
+    principalId: principalId
+    principalType: principalType
+    assignRolesToPrincipal: toLower(assignRolesToPrincipal) == 'true'
+    modelDeployments: modelDeployments
+  }
+}
+
+module foundryExisting 'modules/foundry.bicep' = if (useExistingFoundry) {
+  name: 'foundry-existing'
+  scope: existingRg
+  params: {
+    useExistingFoundry: useExistingFoundry
+    accountName: foundryResourceName
+    projectName: projectName
+    location: location
+    principalId: principalId
+    principalType: principalType
+    assignRolesToPrincipal: toLower(assignRolesToPrincipal) == 'true'
+    modelDeployments: modelDeployments
+  }
+}
+
+output AZURE_LOCATION              string = location
+output AZURE_RESOURCE_GROUP        string = useExistingFoundry ? existingRg.name : rg.name
+output AZURE_TENANT_ID             string = tenant().tenantId
+output AZURE_SUBSCRIPTION_ID       string = subscription().subscriptionId
+
+output FOUNDRY_RESOURCE_NAME       string = useExistingFoundry ? foundryExisting!.outputs.accountName : foundryNew!.outputs.accountName
+output FOUNDRY_PROJECT_NAME        string = useExistingFoundry ? foundryExisting!.outputs.projectName : foundryNew!.outputs.projectName
+output FOUNDRY_ENDPOINT            string = useExistingFoundry ? existingFoundryEndpoint : foundryNew!.outputs.accountEndpoint
+output FOUNDRY_PROJECT_ENDPOINT    string = useExistingFoundry ? foundryExisting!.outputs.projectEndpoint : foundryNew!.outputs.projectEndpoint
+output CU_ENDPOINT                 string = useExistingFoundry ? existingFoundryEndpoint : foundryNew!.outputs.accountEndpoint
+output MODEL_DEPLOYMENTS           array  = useExistingFoundry ? foundryExisting!.outputs.modelDeployments : foundryNew!.outputs.modelDeployments

cu_cli/resources/azd_template/infra/main.parameters.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "environmentName": {
+      "value": "${AZURE_ENV_NAME}"
+    },
+    "location": {
+      "value": "${AZURE_LOCATION}"
+    },
+    "foundryResourcePrefix": {
+      "value": "${FOUNDRY_RESOURCE_PREFIX=}"
+    },
+    "existingFoundryEndpoint": {
+      "value": "${FOUNDRY_EXISTING_ENDPOINT=}"
+    },
+    "existingFoundryResourceGroup": {
+      "value": "${FOUNDRY_EXISTING_RESOURCE_GROUP=}"
+    },
+    "principalId": {
+      "value": "${AZURE_PRINCIPAL_ID}"
+    },
+    "principalType": {
+      "value": "${AZURE_PRINCIPAL_TYPE=User}"
+    },
+    "assignRolesToPrincipal": {
+      "value": "${AZD_ASSIGN_ROLES=true}"
+    }
+  }
+}

cu_cli/resources/azd_template/infra/models.json

@@ -0,0 +1 @@
+[]

cu_cli/resources/azd_template/infra/modules/foundry.bicep

@@ -0,0 +1,122 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+@description('Name of the Microsoft Foundry (AIServices) account.')
+param accountName string
+
+@description('When true, treat accountName as an existing Foundry account and skip account/project creation.')
+param useExistingFoundry bool = false
+
+@description('Name of the Foundry project (child of the account).')
+param projectName string
+
+@description('Region for the account and project.')
+param location string
+
+@description('Principal ID receiving data-plane access.')
+param principalId string
+
+@allowed([ 'User', 'ServicePrincipal' ])
+param principalType string
+
+@description('If true, create role assignments for principalId on the account.')
+param assignRolesToPrincipal bool = true
+
+@description('Model deployments to create on the account.')
+param modelDeployments array
+
+resource accountNew 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' = if (!useExistingFoundry) {
+  name: accountName
+  location: location
+  kind: 'AIServices'
+  sku: {
+    name: 'S0'
+  }
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    allowProjectManagement: true
+    customSubDomainName: accountName
+    publicNetworkAccess: 'Enabled'
+    disableLocalAuth: false
+  }
+}
+
+resource accountExisting 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' existing = if (useExistingFoundry) {
+  name: accountName
+}
+
+resource project 'Microsoft.CognitiveServices/accounts/projects@2025-04-01-preview' = if (!useExistingFoundry) {
+  parent: accountNew
+  name: projectName
+  location: location
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {}
+}
+
+// Model deployments — created sequentially to avoid Cognitive Services
+// 'another operation in progress' conflicts.
+@batchSize(1)
+resource deploymentsOnNew 'Microsoft.CognitiveServices/accounts/deployments@2025-04-01-preview' = [for d in modelDeployments: if (!useExistingFoundry) {
+  parent: accountNew
+  name: d.name
+  sku: {
+    name: d.skuName
+    capacity: d.skuCapacity
+  }
+  properties: {
+    model: {
+      format: d.format
+      name: d.model
+      version: d.version
+    }
+  }
+}]
+
+@batchSize(1)
+resource deploymentsOnExisting 'Microsoft.CognitiveServices/accounts/deployments@2025-04-01-preview' = [for d in modelDeployments: if (useExistingFoundry) {
+  parent: accountExisting
+  name: d.name
+  sku: {
+    name: d.skuName
+    capacity: d.skuCapacity
+  }
+  properties: {
+    model: {
+      format: d.format
+      name: d.model
+      version: d.version
+    }
+  }
+}]
+
+// Built-in Azure RBAC role GUIDs.
+// https://learn.microsoft.com/azure/role-based-access-control/built-in-roles
+var roleDefinitions = {
+  cognitiveServicesUser: 'a97b65f3-24c7-4388-baec-2e87135dc908'
+}
+
+resource roleCogUserOnNew 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (!useExistingFoundry && assignRolesToPrincipal && !empty(principalId)) {
+  name: guid(accountNew.id, principalId, roleDefinitions.cognitiveServicesUser)
+  scope: accountNew
+  properties: {
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitions.cognitiveServicesUser)
+    principalId: principalId
+    principalType: principalType
+  }
+}
+
+output accountName     string = accountName
+output projectName     string = useExistingFoundry ? '' : project.name
+output accountEndpoint string = 'https://${accountName}.services.ai.azure.com/'
+output projectEndpoint string = useExistingFoundry ? '' : 'https://${accountName}.services.ai.azure.com/api/projects/${project.name}'
+output modelDeployments array = [for (d, i) in modelDeployments: {
+  name: d.name
+  model: d.model
+  version: d.version
+  sku: d.skuName
+  capacity: d.skuCapacity
+}]

cu_cli/schema_validate.py

@@ -0,0 +1,28 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Compatibility exports for schema validation now owned by ``cu-cli-core``."""
+
+from cu_cli_core.schema_validation import (
+    ALLOWED_METHODS,
+    ALLOWED_TYPES,
+    Finding,
+    ValidationResult,
+    custom_analyzer_id_error,
+    first_error_line,
+    parse_and_validate,
+    schema_pinned_version,
+    validate_schema,
+)
+
+__all__ = [
+    "ALLOWED_METHODS",
+    "ALLOWED_TYPES",
+    "Finding",
+    "ValidationResult",
+    "custom_analyzer_id_error",
+    "first_error_line",
+    "parse_and_validate",
+    "schema_pinned_version",
+    "validate_schema",
+]

cu_cli/spec_validate.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Compatibility exports for spec validation now owned by ``cu-cli-core``."""
+
+from cu_cli_core.spec_validation import (
+    spec_allowed_methods,
+    spec_allowed_types,
+    spec_available,
+    validate_against_spec,
+)
+
+__all__ = [
+    "spec_allowed_methods",
+    "spec_allowed_types",
+    "spec_available",
+    "validate_against_spec",
+]

cu_cli/telemetry.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Telemetry.
+
+The CLI's only telemetry is the Azure-SDK ``User-Agent`` header on CU service
+calls. The CLI stamps an application-id prefix ``cu-cli/<version>`` for adoption
+attribution; the Azure SDK (azure-core) then appends its standard
+``azsdk-python-<package>/<version> Python/<version> (<platform>)`` identifier.
+**No customer content, and no usage/analytics data, is collected.**
+
+``CU_TELEMETRY=off`` (or ``0``/``false``/``no``) drops only the ``cu-cli``
+prefix. It does **not** (and cannot) remove the Azure SDK's own
+``azsdk-python-...`` User-Agent — azure-core always sends one, per the Azure SDK
+telemetry policy (https://azure.github.io/azure-sdk/general_azurecore.html). To
+customize the header further, use the standard azure-core ``AZURE_HTTP_USER_AGENT``
+environment variable, which the SDK appends.
+"""
+
+from __future__ import annotations
+
+import os
+
+from . import __version__
+
+USER_AGENT = f"cu-cli/{__version__}"
+_OPT_OUT_VALUES = {"off", "0", "false", "no"}
+
+
+def telemetry_enabled() -> bool:
+    return os.getenv("CU_TELEMETRY", "on").strip().lower() not in _OPT_OUT_VALUES
+
+
+def user_agent() -> str:
+    """The ``User-Agent`` prefix stamped on CU API calls (respecting opt-out).
+
+    When opted out we return an empty prefix. azure-core never sends an empty
+    header — it falls back to its standard ``azsdk-python-...`` User-Agent, so
+    the request carries no ``cu-cli`` marker and is stable across cu-cli
+    versions.
+    """
+    return USER_AGENT if telemetry_enabled() else ""

cu_cli/update_check.py

@@ -0,0 +1,154 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Package update check.
+
+Follows the pip convention: compare the installed version against the latest
+version from the installed update provider and, when a newer one exists, prompt
+the user to upgrade with the exact command and a release-notes pointer. The
+public default provider uses PyPI. **Never auto-updates.** The check is cached
+and also runs implicitly at the end of every command.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+from packaging.version import InvalidVersion, Version
+
+from . import __version__
+from .update_provider import (
+    RELEASE_NOTES_URL,
+    get_update_provider,
+)
+_CACHE_PATH = Path.home() / ".cu" / ".update-check.json"
+_CACHE_TTL_SECONDS = 24 * 60 * 60
+_NETWORK_TIMEOUT = 1.5
+
+
+def _checks_disabled() -> bool:
+    return os.getenv("CU_NO_UPDATE_CHECK", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _read_cache(provider_name: str) -> tuple[bool, Optional[str]]:
+    try:
+        import json
+
+        data = json.loads(_CACHE_PATH.read_text(encoding="utf-8"))
+        if data.get("provider") != provider_name:
+            return False, None
+
+        last_attempt = float(data.get("last_attempt_timestamp", 0))
+        if time.time() - last_attempt >= _CACHE_TTL_SECONDS:
+            return False, None
+
+        latest = data.get("latest")
+        if isinstance(latest, str) and latest:
+            return True, latest
+        return True, None
+    except Exception:
+        return False, None
+
+
+def _write_cache(provider_name: str, latest: Optional[str]) -> None:
+    try:
+        import json
+
+        now = time.time()
+        data: dict[str, object] = {}
+        try:
+            existing = json.loads(_CACHE_PATH.read_text(encoding="utf-8"))
+            if isinstance(existing, dict) and existing.get("provider") == provider_name:
+                data = existing
+        except (OSError, ValueError):
+            pass
+
+        data.update(
+            {
+                "provider": provider_name,
+                "last_attempt_timestamp": now,
+            }
+        )
+        if latest:
+            data["latest"] = latest
+            data["last_success_timestamp"] = now
+
+        _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_PATH.write_text(
+            json.dumps(data),
+            encoding="utf-8",
+        )
+    except Exception:
+        pass
+
+
+def fetch_latest_version(*, use_cache: bool = True) -> Optional[str]:
+    """Return the latest ``cu-cli`` version, or ``None`` on any failure.
+
+    Network failures are swallowed so an update check never breaks a command.
+    """
+    return fetch_latest_version_detailed(use_cache=use_cache)[0]
+
+
+def fetch_latest_version_detailed(*, use_cache: bool = True) -> Tuple[Optional[str], str]:
+    """Like :func:`fetch_latest_version` but also return a reason code.
+
+    Reason is one of ``"ok"``, ``"disabled"``, ``"not_published"``, or
+    ``"network_error"`` so callers can give accurate, non-misleading advice.
+    """
+    if _checks_disabled():
+        return None, "disabled"
+    provider = get_update_provider()
+    if use_cache:
+        is_recent, latest = _read_cache(provider.name)
+        if is_recent:
+            return latest, "ok" if latest else "network_error"
+    latest, reason = provider.fetch_latest_version()
+    _write_cache(provider.name, latest)
+    return latest, reason
+
+
+def _parse(version: str) -> tuple:
+    parts = []
+    for chunk in version.split(".")[:3]:
+        num = "".join(ch for ch in chunk if ch.isdigit())
+        parts.append(int(num) if num else 0)
+    while len(parts) < 3:
+        parts.append(0)
+    return tuple(parts)
+
+
+def is_newer(latest: Optional[str], current: str = __version__) -> bool:
+    if not latest:
+        return False
+    try:
+        return Version(latest) > Version(current)
+    except InvalidVersion:
+        # Fallback for any unexpected non-PEP440 version strings.
+        return _parse(latest) > _parse(current)
+    except Exception:
+        return False
+
+
+def upgrade_hint(latest: str, release_notes_url: str = RELEASE_NOTES_URL) -> str:
+    return (
+        f"A new release of cu-cli is available: {__version__} -> {latest}.\n"
+        f"  Upgrade with:  cu upgrade\n"
+        f"  Release notes: {release_notes_url}"
+    )
+
+
+def maybe_notify(*, stream=None) -> None:
+    """Implicit end-of-command check. Cached + time-limited; never blocks long."""
+    if _checks_disabled():
+        return
+    latest = fetch_latest_version(use_cache=True)
+    if latest and is_newer(latest):
+        from .output import console
+        provider = get_update_provider()
+        console.print(
+            f"[dim]{upgrade_hint(latest, provider.release_notes_url)}[/dim]"
+        )

cu_cli/update_provider.py

@@ -0,0 +1,92 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Update source abstraction used by the shared upgrade workflow."""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib.metadata import entry_points
+from typing import Mapping, Protocol, Tuple
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+
+PYPI_URL = "https://pypi.org/pypi/cu-cli/json"
+RELEASE_NOTES_URL = "https://github.com/Azure/content-understanding-toolkit/releases"
+SOURCE_INSTALL_HINT = (
+    "git clone https://github.com/Azure/content-understanding-toolkit && "
+    "pip install -e content-understanding-toolkit/cu-cli"
+)
+_NETWORK_TIMEOUT = 1.5
+
+
+class UpdateProvider(Protocol):
+    """Supply release discovery and pip configuration to the upgrade engine."""
+
+    name: str
+    release_notes_url: str
+    source_install_hint: str
+
+    def fetch_latest_version(self) -> Tuple[str | None, str]: ...
+
+    def pip_environment(self) -> Mapping[str, str]: ...
+
+
+class PyPIUpdateProvider:
+    """Default update provider for public releases."""
+
+    name = "PyPI"
+    release_notes_url = RELEASE_NOTES_URL
+    source_install_hint = SOURCE_INSTALL_HINT
+
+    def fetch_latest_version(self) -> Tuple[str | None, str]:
+        try:
+            req = Request(PYPI_URL, headers={"Accept": "application/json"})
+            with urlopen(req, timeout=_NETWORK_TIMEOUT) as resp:  # noqa: S310
+                payload = json.loads(resp.read().decode("utf-8"))
+            latest = payload.get("info", {}).get("version")
+            return (latest, "ok") if latest else (None, "network_error")
+        except HTTPError as exc:
+            return None, "not_published" if exc.code == 404 else "network_error"
+        except Exception:
+            return None, "network_error"
+
+    def pip_environment(self) -> Mapping[str, str]:
+        return {}
+
+
+def get_update_provider() -> UpdateProvider:
+    """Load one installed update-provider extension, or use public PyPI."""
+    providers = list(entry_points(group="cu_cli.update_providers"))
+    if not providers:
+        return PyPIUpdateProvider()
+    if len(providers) != 1:
+        names = ", ".join(sorted(provider.name for provider in providers))
+        raise RuntimeError(f"Expected one cu-cli update provider, found: {names}")
+    provider = providers[0].load()()
+    if not all(
+        hasattr(provider, attribute)
+        for attribute in (
+            "name",
+            "release_notes_url",
+            "source_install_hint",
+            "fetch_latest_version",
+            "pip_environment",
+        )
+    ):
+        raise RuntimeError(f"Invalid cu-cli update provider: {providers[0].name}")
+    return provider
+
+
+def pip_install_args(latest: str) -> list[str]:
+    """Return the shared, exact-version pip upgrade arguments."""
+    return [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        f"cu-cli=={latest}",
+    ]