SDK operations for Models, Unit tests and Sample notebook (#46842)

* SDK operations for Models, Unit tests and Sample notebook

* modifying sample to .py instead of .ipynb and update changelog

* post emitter fixes and resolving review comments

* fix cpell - azcopy

* re emit from typespec for PendingUploadType changes

* reverting pyproject.toml

* pulling base branch of foundry sdk release for build

* Revert aio _patch.py to base; minimize sync _patch.py diff for BetaModelsOperations

* Address PR #46842 review comments

Darren (dargilco):

- D1: Merge feature/azure-ai-projects/2.2.0 into branch (separate merge commit).

- D2: Remove duplicate '.beta.models' CHANGELOG bullet.

- D3: Remove stray blank line in CHANGELOG.

- D4: Revert apiview-properties.json to base.

- D5: Wire async patched BetaModelsOperations into aio/operations/_patch.py;

  add azure/ai/projects/aio/operations/_patch_models_async.py with async create_version()

  using azure.storage.blob.aio.ContainerClient.

Howie (howieleung):

- H1: Rename helper models_create -> create_version (and validator).

- H2: Rename sample_models{,_async}.py -> sample_models_basic{,_async}.py.

- H3: Print friendly per-field summaries in samples instead of raw model repr.

- H4: Guard against None return from create_version before accessing fields.

Also follows TypeSpec rename: generated create_async() -> pending_create_version().

* Rename .beta.models patched helper create_version -> create

- Renames patched BetaModelsOperations.create_version() to create() (sync + async).

- Renames internal validator _validate_create_version_inputs -> _validate_create_inputs.

- Updates samples, tests, README, and CHANGELOG to use the new name.

- Leaves generated spec method pending_create_version unchanged.

* Add sample recordings for .beta.models and fix generated arg names

- Add parameterized sample tests test_models_samples (sync + async).

- Add slim modelsServicePreparer (only foundry_project_endpoint).

- Add sanitizers for random model name, Foundry storage account/container,

  /workspaces/<name>, azureai:// asset URIs, account/project from FOUNDRY_PROJECT_ENDPOINT,

  and SAS query parameters (sig, skoid, sktid).

- Use per-recording random MODEL_NAME (recsmplmdl<hex>) and sanitize to a stable

  value on playback (Foundry asset-store reserves <name>/<version> permanently).

- Update assets.json tag to point at the new recordings.

Bug fixes surfaced by live runs (renamed generated kwargs):

- pending_upload: body= -> pending_upload_request=

- pending_create_version: body= -> model_version=

- get_credentials: body= -> credential_request=

Applied to patched create() helper (sync + async), all three model samples,

and the test_patch_models mock.

Notes:

- sample_models_basic.py (which uses AzCopy) is excluded from the parameterized

  sample tests because AzCopy traffic isn't captured by the test proxy.

- LLM print-call validation is not invoked for models tests (canary project

  has no Azure OpenAI connection).

* Exclude .beta.models.create from foundry-features header test

The multi-step orchestrator helper performs local input validation before any HTTP call, so the test framework's synthetic placeholder args (e.g. source={}) cause it to raise TypeError before _RequestCaptured is ever raised. Add a shared EXCLUDED_BETA_METHODS mapping and skip excluded methods in both sync and async discovery. The header invariant is still enforced for every underlying HTTP method create() calls (pending_upload, pending_create_version, get).

* Add cspell entries: recsmplmdl, simpleqna, skoid

* Fix pyright and pylint issues in BetaModelsOperations patches

- Replace hasattr-based duck typing with isinstance(dict) check so pyright can narrow types correctly on _extract_pending_upload_targets.
- Remove unused HttpResponseError import.
- Suppress do-not-import-asyncio for asyncio.sleep used in the async polling loop (transport sleep is not applicable).
- Add :param/:keyword/:return/:rtype docstring sections on private helpers to satisfy azure-pylint-guidelines-checker.

* Add @overload variants to .beta.models.create for precise return types

* Rename sample_models_without_patch.py to sample_models_create_and_poll.py

* Remove redundant 'if model is None' check in sample_models_basic.py (covered by overload)

Author: kshitij-microsoft

sdk/ai/azure-ai-projects/CHANGELOG.md

@@ -20,7 +20,7 @@
 * New optional `force` parameter on `agents.delete` and `agents.delete_version` methods.
 * New optional `blueprint_reference` parameters on `agents.create_version` method.
 * New sample `sample_dataset_generation_job_simpleqna_with_prompt_source.py` showing an end-to-end flow that generates a QnA dataset via `.beta.datasets.create_generation_job` and runs an OpenAI evaluation.
-
+* New convenience method `.beta.models.create()` that wraps the spec's three-step upload-first sequence (`pending_upload` → `azcopy copy` → `pending_create_version`) and polls `get()` until the new `ModelVersion` is observable.
 
 ### Breaking Changes
 
@@ -52,6 +52,10 @@ Breaking changes in beta classes:
 * The Hosted Agent creation sample also demonstrates assigning the hosted agent managed identity the Azure AI User RBAC role on the backing Azure AI account.
 * Updated the other Hosted Agent samples to reuse an existing Hosted Agent as a prerequisite, instead of creating a new hosted agent version in each sample.
 * Added Toolbox tool-search sample `sample_toolboxes_with_search_preview.py` and `sample_toolboxes_with_search_preview_async.py`, demonstrating creating a Toolbox version with `ToolboxSearchPreviewTool` and invoking `MCPTool`.
+* Added `.beta.models` samples under `samples/models/`:
+  * `sample_models_basic.py` — synchronous end-to-end registration via the `create` helper (uses `azcopy`), followed by `get`, `list_versions`, `list`, `get_credentials`, `update`, and `delete`.
+  * `sample_models_create_and_poll.py` — alternative synchronous registration that hand-rolls the spec's three-step flow (`pending_upload` → upload via `azure-storage-blob` → `pending_create_version` + poll), without taking a dependency on `azcopy`.
+  * `sample_models_basic_async.py` — asynchronous version of the same three-step flow using `azure.ai.projects.aio.AIProjectClient` and `azure.storage.blob.aio.ContainerClient`.
 
 ## 2.1.0 (2026-04-20)
 

sdk/ai/azure-ai-projects/README.md

@@ -35,6 +35,7 @@ resources in your Microsoft Foundry Project. Use it to:
 * **Enumerate AI Models** deployed to your Foundry Project using `.deployments` operations.
 * **Enumerate connected Azure resources** in your Foundry project using `.connections` operations.
 * **Upload documents and create Datasets** to reference them using `.datasets` operations.
+* **Register and manage local model weights** as Foundry `ModelVersion` resources using `.beta.models` operations, including the `create` end-to-end helper.
 * **Create and enumerate Search Indexes** using `.indexes` operations.
 
 The client library uses version `v1` of the Microsoft Foundry [data plane REST APIs](https://aka.ms/azsdk/azure-ai-projects-v2/api-reference-v1).
@@ -166,6 +167,7 @@ Full descriptions and working code for all of the above are available in:
 | Deployments | [Deployment types](https://learn.microsoft.com/azure/foundry/foundry-models/concepts/deployment-types) | `samples/deployments/` |
 | Connections | [Connections operations](https://learn.microsoft.com/python/api/overview/azure/ai-projects-readme?view=azure-python#connections-operations) | `samples/connections/` |
 | Datasets | [Dataset operations](https://learn.microsoft.com/python/api/overview/azure/ai-projects-readme?view=azure-python#dataset-operations) | `samples/datasets/` |
+| Models (preview) | Register local model weights as Foundry `ModelVersion` resources via `.beta.models` (`create`, `list`, `list_versions`, `get`, `update`, `delete`, `pending_upload`, `pending_create_version`, `get_credentials`). | `samples/models/` |
 | Indexes | [Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search) | `samples/indexes/` |
 | Files (upload, retrieve, list, delete) | [OpenAI Files API](https://platform.openai.com/docs/api-reference/files) | `samples/files/` |
 | Fine-tuning | [Fine-Tuning in AI Foundry](https://github.com/microsoft-foundry/fine-tuning) | `samples/finetuning/` |

sdk/ai/azure-ai-projects/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/ai/azure-ai-projects",
-  "Tag": "python/ai/azure-ai-projects_b13a910d61"
+  "Tag": "python/ai/azure-ai-projects_7fc443e02a"
 }

sdk/ai/azure-ai-projects/azure/ai/projects/aio/operations/_patch.py

@@ -15,14 +15,14 @@
 from ._patch_telemetry_async import TelemetryOperations
 from ._patch_connections_async import ConnectionsOperations
 from ._patch_memories_async import BetaMemoryStoresOperations
+from ._patch_models_async import BetaModelsOperations
 from ._patch_sessions_async import BetaAgentsOperations
 from ...operations._patch import _BETA_OPERATION_FEATURE_HEADERS, _OperationMethodHeaderProxy
 from ._operations import (
     BetaDatasetsOperations,
     BetaEvaluationTaxonomiesOperations,
     BetaEvaluatorsOperations,
     BetaInsightsOperations,
-    BetaModelsOperations,
     BetaOperations as GeneratedBetaOperations,
     BetaRedTeamsOperations,
     BetaRoutinesOperations,
@@ -75,6 +75,8 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.agents = BetaAgentsOperations(self._client, self._config, self._serialize, self._deserialize)
         # Replace with patched class that includes begin_update_memories
         self.memory_stores = BetaMemoryStoresOperations(self._client, self._config, self._serialize, self._deserialize)
+        # Replace with patched class that includes create (3-step upload helper)
+        self.models = BetaModelsOperations(self._client, self._config, self._serialize, self._deserialize)
 
         for property_name, foundry_features_value in _BETA_OPERATION_FEATURE_HEADERS.items():
             setattr(

sdk/ai/azure-ai-projects/azure/ai/projects/aio/operations/_patch_models_async.py

@@ -0,0 +1,331 @@
+# pylint: disable=line-too-long,useless-suppression
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+"""Customize generated code here.
+
+Follow our quickstart for examples: https://aka.ms/azsdk/python/dpcodegen/python/customize
+"""
+
+import asyncio  # pylint: disable=do-not-import-asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Any, Literal, Optional, Union, overload
+
+from azure.core.exceptions import ResourceNotFoundError
+from azure.core.tracing.decorator_async import distributed_trace_async
+
+from ._operations import BetaModelsOperations as BetaModelsOperationsGenerated
+from ...models._models import (
+    ModelPendingUploadRequest,
+    ModelPendingUploadResponse,
+    ModelVersion,
+    PendingUploadType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BetaModelsOperations(BetaModelsOperationsGenerated):
+    """
+    .. warning::
+        **DO NOT** instantiate this class directly.
+
+        Instead, you should access the following operations through
+        :class:`~azure.ai.projects.aio.AIProjectClient`'s
+        :attr:`beta.models <azure.ai.projects.aio.operations.BetaOperations.models>` attribute.
+    """
+
+    @staticmethod
+    def _extract_pending_upload_targets(
+        response: Union[ModelPendingUploadResponse, dict],
+    ) -> "tuple[str, str, Optional[str]]":
+        """Return ``(sas_uri, container_blob_uri, pending_upload_id)`` from a pending-upload response.
+
+        The service currently returns the raw datastore-style payload
+        (``blobReferenceForConsumption`` / ``temporaryDataReferenceId``) for some
+        Foundry deployments rather than the SDK-modeled ``ModelPendingUploadResponse``
+        shape (``blobReference`` / ``pendingUploadId``). Tolerate both wire
+        shapes so callers don't have to.
+
+        :param response: The pending-upload response from the service.
+        :type response: ~azure.ai.projects.models.ModelPendingUploadResponse or dict
+        :return: A tuple of ``(sas_uri, container_blob_uri, pending_upload_id)``.
+        :rtype: tuple[str, str, str or None]
+        """
+        payload = dict(response) if isinstance(response, dict) else response.as_dict()
+
+        blob_ref = payload.get("blobReferenceForConsumption") or payload.get("blobReference") or {}
+        sas_uri = (blob_ref.get("credential") or {}).get("sasUri")
+        container_blob_uri = blob_ref.get("blobUri")
+        pending_upload_id = payload.get("temporaryDataReferenceId") or payload.get("pendingUploadId")
+
+        if not sas_uri or not container_blob_uri:
+            raise ValueError("Could not locate SAS URI / blob URI in pending_upload response: " f"{payload!r}")
+        return sas_uri, container_blob_uri, pending_upload_id
+
+    @staticmethod
+    def _validate_create_inputs(
+        *,
+        name: str,
+        version: str,
+        source: Union[str, "os.PathLike[str]"],
+        wait_for_commit: bool,
+        polling_timeout: float,
+        polling_interval: float,
+    ) -> Path:
+        """Validate ``create`` inputs up-front, before any service call.
+
+        Returns the resolved ``Path`` for ``source``. Raises ``ValueError`` for
+        bad inputs.
+
+        :keyword name: Name of the model to register.
+        :paramtype name: str
+        :keyword version: Version identifier for the model.
+        :paramtype version: str
+        :keyword source: Local file or directory containing the model weights.
+        :paramtype source: str or os.PathLike[str]
+        :keyword wait_for_commit: Whether to poll for commit completion.
+        :paramtype wait_for_commit: bool
+        :keyword polling_timeout: Total seconds to poll for commit completion.
+        :paramtype polling_timeout: float
+        :keyword polling_interval: Seconds between poll attempts.
+        :paramtype polling_interval: float
+        :return: The resolved ``Path`` for ``source``.
+        :rtype: pathlib.Path
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("`name` must be a non-empty string.")
+        if not isinstance(version, str) or not version.strip():
+            raise ValueError("`version` must be a non-empty string.")
+
+        source_path = Path(os.fspath(source))
+        if not source_path.exists():
+            raise ValueError(f"Upload source does not exist: {source_path}")
+        if source_path.is_dir() and not any(p.is_file() for p in source_path.rglob("*")):
+            raise ValueError(f"Upload source directory is empty: {source_path}")
+        if source_path.is_file() and source_path.stat().st_size == 0:
+            raise ValueError(f"Upload source file is empty: {source_path}")
+
+        if wait_for_commit:
+            if polling_timeout <= 0:
+                raise ValueError("`polling_timeout` must be > 0 when `wait_for_commit` is True.")
+            if polling_interval <= 0:
+                raise ValueError("`polling_interval` must be > 0 when `wait_for_commit` is True.")
+
+        return source_path
+
+    @staticmethod
+    async def _upload_with_container_client(source: Path, sas_uri: str) -> None:
+        """Upload ``source`` to the SAS container using ``azure.storage.blob.aio.ContainerClient``.
+
+        :param source: Local file or directory to upload.
+        :type source: pathlib.Path
+        :param sas_uri: SAS URI for the destination container.
+        :type sas_uri: str
+        :raises RuntimeError: If ``azure-storage-blob`` is not installed.
+        """
+        try:
+            from azure.storage.blob.aio import ContainerClient  # pylint: disable=import-outside-toplevel
+        except ImportError as ex:
+            raise RuntimeError(
+                "`azure-storage-blob` is required for the async `create` helper. "
+                "Install it with `pip install azure-storage-blob aiohttp`."
+            ) from ex
+
+        if source.is_dir():
+            files = [p for p in source.rglob("*") if p.is_file()]
+            if not files:
+                raise ValueError(f"Upload source directory is empty: {source}")
+        elif source.is_file():
+            files = [source]
+        else:
+            raise ValueError(f"Upload source does not exist: {source}")
+
+        # Don't log the SAS query string — it's a credential.
+        redacted = sas_uri.split("?", 1)[0] + "?<sas-redacted>"
+        logger.info("[create] uploading %d file(s) to %s", len(files), redacted)
+
+        async with ContainerClient.from_container_url(sas_uri) as container_client:
+            for f in files:
+                rel = f.relative_to(source).as_posix() if source.is_dir() else f.name
+                with f.open("rb") as fp:
+                    await container_client.upload_blob(name=rel, data=fp, overwrite=True)
+                logger.debug("[create] uploaded %s (%d bytes)", rel, f.stat().st_size)
+
+    @overload
+    async def create(
+        self,
+        *,
+        name: str,
+        version: str,
+        source: Union[str, "os.PathLike[str]"],
+        weight_type: Optional[str] = None,
+        base_model: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional["dict[str, str]"] = None,
+        wait_for_commit: Literal[True] = True,
+        polling_timeout: float = 300.0,
+        polling_interval: float = 2.0,
+        **kwargs: Any,
+    ) -> ModelVersion:
+        ...
+
+    @overload
+    async def create(
+        self,
+        *,
+        name: str,
+        version: str,
+        source: Union[str, "os.PathLike[str]"],
+        weight_type: Optional[str] = None,
+        base_model: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional["dict[str, str]"] = None,
+        wait_for_commit: Literal[False],
+        polling_timeout: float = 300.0,
+        polling_interval: float = 2.0,
+        **kwargs: Any,
+    ) -> None:
+        ...
+
+    @distributed_trace_async
+    async def create(
+        self,
+        *,
+        name: str,
+        version: str,
+        source: Union[str, "os.PathLike[str]"],
+        weight_type: Optional[str] = None,
+        base_model: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional["dict[str, str]"] = None,
+        wait_for_commit: bool = True,
+        polling_timeout: float = 300.0,
+        polling_interval: float = 2.0,
+        **kwargs: Any,
+    ) -> Optional[ModelVersion]:
+        """Register a local model by running the full upload-first sequence (async).
+
+        This wraps the three mandatory steps of the model-registration spec
+        into a single call:
+
+        1. :meth:`pending_upload` — provision a project-managed blob container
+           and obtain a SAS URI.
+        2. Upload the local weight files to the SAS container using
+           :class:`azure.storage.blob.aio.ContainerClient`.
+        3. :meth:`pending_create_version` — finalize registration with the
+           ``ModelVersion`` body (``blob_uri``, ``weight_type``, ``base_model``,
+           ``description``, ``tags``).
+
+        Requires the ``azure-storage-blob`` package (with ``aiohttp``) for the
+        upload step.
+
+        :keyword name: Name of the model to register. Required.
+        :paramtype name: str
+        :keyword version: Version identifier for the model. Required.
+        :paramtype version: str
+        :keyword source: Local file or directory containing the model weights.
+            If a directory, its contents are uploaded recursively to the SAS
+            container root. Required.
+        :paramtype source: str or os.PathLike[str]
+        :keyword weight_type: Optional weight type (e.g. ``"FullWeight"``,
+            ``"LoRA"``, ``"DraftModel"``).
+        :paramtype weight_type: str
+        :keyword base_model: Optional base model asset ID.
+        :paramtype base_model: str
+        :keyword description: Optional asset description.
+        :paramtype description: str
+        :keyword tags: Optional asset tags.
+        :paramtype tags: dict[str, str]
+        :keyword wait_for_commit: When True (default) poll :meth:`get` until
+            the committed ``ModelVersion`` is observable, and return it.
+            When False, return ``None`` after the async commit is accepted.
+        :paramtype wait_for_commit: bool
+        :keyword polling_timeout: Total seconds to poll for commit completion.
+        :paramtype polling_timeout: float
+        :keyword polling_interval: Seconds between poll attempts.
+        :paramtype polling_interval: float
+        :return: The committed :class:`~azure.ai.projects.models.ModelVersion`
+            when ``wait_for_commit`` is True, otherwise ``None``.
+        :rtype: ~azure.ai.projects.models.ModelVersion or None
+        :raises ValueError: If ``name``/``version`` are empty, ``source`` does
+            not exist or is empty, polling parameters are non-positive, or the
+            pending-upload response is missing the SAS / blob URI.
+        :raises RuntimeError: If ``azure-storage-blob`` is not installed or
+            the registration does not commit before ``polling_timeout`` elapses.
+        """
+        # --- Step 0: validate inputs up-front --------------------------------
+        source_path = self._validate_create_inputs(
+            name=name,
+            version=version,
+            source=source,
+            wait_for_commit=wait_for_commit,
+            polling_timeout=polling_timeout,
+            polling_interval=polling_interval,
+        )
+
+        # --- Step 1: StartPendingUpload --------------------------------------
+        logger.info(
+            "[create] step 1/3 pending_upload(name=%r, version=%r)",
+            name,
+            version,
+        )
+        pending = await self.pending_upload(
+            name=name,
+            version=version,
+            pending_upload_request=ModelPendingUploadRequest(
+                pending_upload_type=PendingUploadType.TEMPORARY_BLOB_REFERENCE,
+            ),
+            **kwargs,
+        )
+        sas_uri, container_blob_uri, pending_upload_id = self._extract_pending_upload_targets(pending)
+        logger.info(
+            "[create] pending_upload_id=%s blob_uri=%s",
+            pending_upload_id,
+            container_blob_uri,
+        )
+
+        # --- Step 2: Upload via async ContainerClient ------------------------
+        logger.info("[create] step 2/3 async upload from %s", source_path)
+        await self._upload_with_container_client(source_path, sas_uri)
+
+        # --- Step 3: Commit registration -------------------------------------
+        model_version_body = ModelVersion(
+            blob_uri=container_blob_uri,
+            weight_type=weight_type,
+            base_model=base_model,
+            description=description,
+            tags=tags or {},
+        )
+        logger.info(
+            "[create] step 3/3 pending_create_version(name=%r, version=%r)",
+            name,
+            version,
+        )
+        await self.pending_create_version(name=name, version=version, model_version=model_version_body, **kwargs)
+
+        if not wait_for_commit:
+            return None
+
+        # The async op returns 202; the service materializes the ModelVersion
+        # asynchronously. Poll get() until it appears or we time out.
+        import time  # pylint: disable=import-outside-toplevel
+
+        deadline = time.monotonic() + polling_timeout
+        last_exc: Optional[BaseException] = None
+        while True:
+            try:
+                return await self.get(name=name, version=version, **kwargs)
+            except ResourceNotFoundError as ex:
+                last_exc = ex
+                if time.monotonic() >= deadline:
+                    raise RuntimeError(
+                        f"Model {name!r}@{version!r} did not appear within " f"{polling_timeout}s after pending_create_version."
+                    ) from last_exc
+                await asyncio.sleep(polling_interval)
+
+
+__all__ = ["BetaModelsOperations"]