[VoiceLive] Update models for GA version (#43202)

* [VoiceLive] Add async function-calling agent sample

* add phrase list

* fix typo

* Update sdk/ai/azure-ai-voicelive/samples/async_function_calling_sample.py

Co-authored-by: Copilot <[email protected]>

* Update sdk/ai/azure-ai-voicelive/samples/async_function_calling_sample.py

Co-authored-by: Copilot <[email protected]>

* update

* fix typo

* update changelog

* update

* remove breaking change section

* update changelog

* fix change log

* revert changelog I lost

* update version and change log

* enable type verification

* update

* [VoiceLive] Relase 1.0.0b4

* Update EouDetection

* update websocket option

* Separate ResponseSession and RequestSession

* make AgentConfig internal

* update test for AgentConfig

* update

* fix pylint

* update status

* rename OAIVoice and ToolChoiceObject

* update

---------

Co-authored-by: Xiting Zhang <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

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

@@ -1,5 +1,51 @@
 # Release History
 
+## 1.0.0 (Unreleased)
+
+### Features Added
+
+- **Enhanced WebSocket Connection Options**: Significantly improved WebSocket connection configuration with transport-agnostic design:
+  - Added new timeout configuration options: `receive_timeout`, `close_timeout`, and `handshake_timeout` for fine-grained control
+  - Enhanced `compression` parameter to support both boolean and integer types for advanced zlib window configuration
+  - Added `vendor_options` parameter for implementation-specific options passthrough (escape hatch for advanced users)
+  - Improved documentation with clearer descriptions for all connection parameters
+  - Better support for common aliases from other WebSocket ecosystems (`max_size`, `ping_interval`, etc.)
+  - More robust option mapping with proper type conversion and safety checks
+- **Enhanced Type Safety**: Improved type safety for content parts with proper enum usage:
+  - `InputAudioContentPart`, `InputTextContentPart`, and `OutputTextContentPart` now use `ContentPartType` enum values instead of string literals
+  - Better IntelliSense support and compile-time type checking for content part discriminators
+
+### Breaking Changes
+
+- **Improved Naming Conventions**: Updated model and enum names for better clarity and consistency:
+  - `OAIVoice` enum renamed to `OpenAIVoiceName` for more descriptive naming
+  - `ToolChoiceObject` model renamed to `ToolChoiceSelection` for better semantic meaning
+  - `ToolChoiceFunctionObject` model renamed to `ToolChoiceFunctionSelection` for consistency
+  - Updated type unions and imports to reflect the new naming conventions
+  - Cross-language package mappings updated to maintain compatibility across SDKs
+- **Session Model Architecture**: Separated `ResponseSession` and `RequestSession` models for better design clarity:
+  - `ResponseSession` no longer inherits from `RequestSession` and now inherits directly from `_Model`
+  - All session configuration fields are now explicitly defined in `ResponseSession` instead of being inherited
+  - This provides clearer separation of concerns between request and response session configurations
+  - May affect type checking and code that relied on the previous inheritance relationship
+- **Model Cleanup**: Removed unused `AgentConfig` model and related fields from the public API:
+  - `AgentConfig` class has been completely removed from imports and exports
+  - `agent` field removed from `ResponseSession` model (including constructor parameter)
+  - Updated cross-language package mappings to reflect the removal
+- **Model Naming Convention Update**: Renamed `EOUDetection` to `EouDetection` for better naming consistency:
+  - Class name changed from `EOUDetection` to `EouDetection` 
+  - All inheritance relationships updated: `AzureSemanticDetection`, `AzureSemanticDetectionEn`, and `AzureSemanticDetectionMultilingual` now inherit from `EouDetection`
+  - Type annotations updated in `AzureSemanticVad`, `AzureSemanticVadEn`, `AzureSemanticVadMultilingual`, and `ServerVad` classes
+  - Import statements and exports updated to reflect the new naming
+- **Enhanced Content Part Type Safety**: Content part discriminators now use enum values instead of string literals:
+  - `InputAudioContentPart.type` now uses `ContentPartType.INPUT_AUDIO` instead of `"input_audio"`
+  - `InputTextContentPart.type` now uses `ContentPartType.INPUT_TEXT` instead of `"input_text"`  
+  - `OutputTextContentPart.type` now uses `ContentPartType.TEXT` instead of `"text"`
+
+### Other Changes
+
+- Initial GA release
+
 ## 1.0.0b5 (2025-09-26)
 
 ### Features Added

sdk/ai/azure-ai-voicelive/apiview-properties.json

@@ -1,7 +1,6 @@
 {
-    "CrossLanguagePackageId": "VoiceLive.WebSocket",
+    "CrossLanguagePackageId": "VoiceLive",
     "CrossLanguageDefinitionId": {
-        "azure.ai.voicelive.models.AgentConfig": "VoiceLive.AgentConfig",
         "azure.ai.voicelive.models.Animation": "VoiceLive.Animation",
         "azure.ai.voicelive.models.ConversationRequestItem": "VoiceLive.ConversationRequestItem",
         "azure.ai.voicelive.models.MessageItem": "VoiceLive.MessageItem",
@@ -13,7 +12,7 @@
         "azure.ai.voicelive.models.AzureVoice": "VoiceLive.AzureVoice",
         "azure.ai.voicelive.models.AzureCustomVoice": "VoiceLive.AzureCustomVoice",
         "azure.ai.voicelive.models.AzurePersonalVoice": "VoiceLive.AzurePersonalVoice",
-        "azure.ai.voicelive.models.EOUDetection": "VoiceLive.EOUDetection",
+        "azure.ai.voicelive.models.EouDetection": "VoiceLive.EouDetection",
         "azure.ai.voicelive.models.AzureSemanticDetection": "VoiceLive.AzureSemanticDetection",
         "azure.ai.voicelive.models.AzureSemanticDetectionEn": "VoiceLive.AzureSemanticDetectionEn",
         "azure.ai.voicelive.models.AzureSemanticDetectionMultilingual": "VoiceLive.AzureSemanticDetectionMultilingual",
@@ -114,8 +113,8 @@
         "azure.ai.voicelive.models.SessionBase": "VoiceLive.SessionBase",
         "azure.ai.voicelive.models.SystemMessageItem": "VoiceLive.SystemMessageItem",
         "azure.ai.voicelive.models.TokenUsage": "VoiceLive.TokenUsage",
-        "azure.ai.voicelive.models.ToolChoiceObject": "VoiceLive.ToolChoiceObject",
-        "azure.ai.voicelive.models.ToolChoiceFunctionObject": "VoiceLive.ToolChoiceFunctionObject",
+        "azure.ai.voicelive.models.ToolChoiceSelection": "VoiceLive.ToolChoiceObject",
+        "azure.ai.voicelive.models.ToolChoiceFunctionSelection": "VoiceLive.ToolChoiceFunctionObject",
         "azure.ai.voicelive.models.UserMessageItem": "VoiceLive.UserMessageItem",
         "azure.ai.voicelive.models.VideoCrop": "VoiceLive.VideoCrop",
         "azure.ai.voicelive.models.VideoParams": "VoiceLive.VideoParams",
@@ -125,8 +124,9 @@
         "azure.ai.voicelive.models.ItemType": "VoiceLive.ItemType",
         "azure.ai.voicelive.models.ItemParamStatus": "VoiceLive.ItemParamStatus",
         "azure.ai.voicelive.models.MessageRole": "VoiceLive.MessageRole",
+        "azure.ai.voicelive.models.ContentPartType": "VoiceLive.ContentPartType",
         "azure.ai.voicelive.models.Modality": "VoiceLive.Modality",
-        "azure.ai.voicelive.models.OAIVoice": "VoiceLive.OAIVoice",
+        "azure.ai.voicelive.models.OpenAIVoiceName": "VoiceLive.OAIVoice",
         "azure.ai.voicelive.models.AzureVoiceType": "VoiceLive.AzureVoiceType",
         "azure.ai.voicelive.models.PersonalVoiceModels": "VoiceLive.PersonalVoiceModels",
         "azure.ai.voicelive.models.OutputAudioFormat": "VoiceLive.OutputAudioFormat",
@@ -139,7 +139,6 @@
         "azure.ai.voicelive.models.ToolChoiceLiteral": "VoiceLive.ToolChoiceLiteral",
         "azure.ai.voicelive.models.ResponseStatus": "VoiceLive.ResponseStatus",
         "azure.ai.voicelive.models.ResponseItemStatus": "VoiceLive.ResponseItemStatus",
-        "azure.ai.voicelive.models.ContentPartType": "VoiceLive.ContentPartType",
         "azure.ai.voicelive.models.ServerEventType": "VoiceLive.ServerEventType"
     }
 }

sdk/ai/azure-ai-voicelive/azure/ai/voicelive/_types.py

@@ -10,5 +10,5 @@
 
 if TYPE_CHECKING:
     from . import models as _models
-Voice = Union[str, "_models.OAIVoice", "_models.OpenAIVoice", "_models.AzureVoice"]
-ToolChoice = Union[str, "_models.ToolChoiceLiteral", "_models.ToolChoiceObject"]
+Voice = Union[str, "_models.OpenAIVoiceName", "_models.OpenAIVoice", "_models.AzureVoice"]
+ToolChoice = Union[str, "_models.ToolChoiceLiteral", "_models.ToolChoiceSelection"]

sdk/ai/azure-ai-voicelive/azure/ai/voicelive/_version.py

@@ -6,4 +6,4 @@
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
-VERSION = "1.0.0b5"
+VERSION = "1.0.0"

sdk/ai/azure-ai-voicelive/azure/ai/voicelive/aio/_patch.py

@@ -575,47 +575,56 @@ async def close(self, *, code: int = 1000, reason: str = "") -> None:
 
 class WebsocketConnectionOptions(TypedDict, total=False):
     """
-    Advanced WebSocket connection options for VoiceLive API connections.
+    Transport-agnostic WebSocket connection options for VoiceLive.
 
-    These options correspond to parameters accepted by :mod:`aiohttp`'s
-    `ws_connect` method and control low-level WebSocket behavior.
-    All keys are optional — if omitted, default values will be applied.
+    These control common WS behaviors (compression, message size limits,
+    timeouts, ping/pong handling). Unless specified, defaults are determined
+    by the underlying WebSocket library.
 
-    :keyword compression: Enable per-message compression.
-        - ``True`` enables compression.
-        - ``False`` disables compression.
-        If omitted, defaults to the aiohttp default.
-    :type compression: bool
+    :keyword compression: Enable per-message compression. Use ``True`` to enable,
+        ``False`` to disable. Advanced users may pass an ``int`` to select a zlib
+        window value if supported by the transport.
+    :type compression: bool | int
 
-    :keyword max_msg_size: Maximum message size in bytes.
-        Messages larger than this limit will cause the connection to close.
-        If omitted, defaults to 10 MiB (10 * 1024 * 1024).
+    :keyword max_msg_size: Maximum message size in bytes before the client closes
+        the connection.
     :type max_msg_size: int
 
-    :keyword timeout: Close timeout in seconds.
-        Maximum time to wait for the connection to close gracefully.
-        If omitted, defaults to aiohttp's internal default.
-    :type timeout: float
-
-    :keyword heartbeat: Interval in seconds for sending ping frames to keep
-        the connection alive. If omitted, defaults to 30 seconds.
+    :keyword heartbeat: Interval in seconds between keep-alive pings.
     :type heartbeat: float
 
-    :keyword autoclose: Automatically close the connection when a close frame
-        is received. Defaults to True if omitted.
+    :keyword autoclose: Automatically close when a close frame is received.
     :type autoclose: bool
 
     :keyword autoping: Automatically respond to ping frames with pong frames.
-        Defaults to True if omitted.
     :type autoping: bool
+
+    :keyword receive_timeout: Max seconds to wait for a single incoming message
+        on an established WebSocket.
+    :type receive_timeout: float
+
+    :keyword close_timeout: Max seconds to wait for a graceful close handshake.
+    :type close_timeout: float
+
+    :keyword handshake_timeout: Max seconds for connection establishment
+        (DNS/TCP/TLS + WS upgrade). Note: with aiohttp this is applied on the
+        ClientSession (not a ws_connect kwarg), so must be handled by the caller.
+    :type handshake_timeout: float
+
+    :keyword vendor_options: Optional implementation-specific options passed
+        through as-is to the underlying library (not part of the stable API).
+    :type vendor_options: Mapping[str, Any]
     """
 
-    compression: NotRequired[bool]
+    compression: NotRequired[Union[bool, int]]
     max_msg_size: NotRequired[int]
-    timeout: NotRequired[float]
     heartbeat: NotRequired[float]
     autoclose: NotRequired[bool]
     autoping: NotRequired[bool]
+    receive_timeout: NotRequired[float]
+    close_timeout: NotRequired[float]
+    handshake_timeout: NotRequired[float]
+    vendor_options: NotRequired[Mapping[str, Any]]
 
 
 class _VoiceLiveConnectionManager(AbstractAsyncContextManager["VoiceLiveConnection"]):
@@ -624,9 +633,9 @@ class _VoiceLiveConnectionManager(AbstractAsyncContextManager["VoiceLiveConnecti
     def __init__(
         self,
         *,
-        credential: Union[AzureKeyCredential, AsyncTokenCredential],
+        credential: Union["AzureKeyCredential", "AsyncTokenCredential"],
         endpoint: str,
-        api_version: str = "2025-05-01-preview",
+        api_version: str = "2025-10-01",
         model: Optional[str] = None,
         extra_query: Mapping[str, Any],
         extra_headers: Mapping[str, Any],
@@ -635,48 +644,82 @@ def __init__(
     ) -> None:
         self._credential = credential
         self._endpoint = endpoint
-        raw_scopes = kwargs.pop(
-            "credential_scopes",
-            ["https://ai.azure.com/.default"],
-        )
-        if isinstance(raw_scopes, str):
-            self.__credential_scopes = [raw_scopes]
-        else:
-            self.__credential_scopes = list(raw_scopes)
+        raw_scopes = kwargs.pop("credential_scopes", ["https://ai.azure.com/.default"])
+        self.__credential_scopes = [raw_scopes] if isinstance(raw_scopes, str) else list(raw_scopes)
         self.__api_version = api_version
         self.__model = model
 
-        self.__connection: Optional[VoiceLiveConnection] = None
+        self.__connection: Optional["VoiceLiveConnection"] = None
         self.__extra_query = extra_query
         self.__extra_headers = extra_headers
-        self.__connection_options = self._map_websocket_options(connection_options or {})
+        self.__connection_options = self._map_to_aiohttp_ws_options(connection_options or {})
         self.__proxy_policy = kwargs.get("proxy_policy") or policies.ProxyPolicy(**kwargs)
 
-    def _map_websocket_options(self, options: WebsocketConnectionOptions) -> dict[str, Any]:
+    def _map_to_aiohttp_ws_options(self, options: WebsocketConnectionOptions) -> dict[str, Any]:
         """
-        Map user options to :mod:`aiohttp` ``ws_connect`` kwargs (accept both TypedDict keys and common aliases).
+        Map neutral WebSocket options to :mod:`aiohttp` ``ClientSession.ws_connect`` kwargs.
 
-        :param options: The user-provided WebSocket options.
+        NOTE:
+        - ``receive_timeout`` and ``close_timeout`` are mapped into a single
+          ``aiohttp.ClientWSTimeout`` instance passed as the ``timeout=`` kwarg.
+        - ``handshake_timeout`` is NOT an ``ws_connect`` kwarg in aiohttp; it must be
+          applied via ``aiohttp.ClientTimeout`` on the session by the caller.
+
+        :param options: User-provided WebSocket options.
         :type options: ~azure.ai.voicelive.aio.WebsocketConnectionOptions
-        :return: Mapped options suitable for ``aiohttp.ClientSession.ws_connect``.
+        :return: Options suitable for ``aiohttp.ClientSession.ws_connect``.
         :rtype: dict[str, Any]
         """
-        # copy to a plain dict so we can safely check/pop alias keys without mypy complaints
         src: dict[str, Any] = dict(options)
         mapped: dict[str, Any] = {}
-        # aliases commonly used by other libs
-        if "max_size" in src:
-            mapped["max_msg_size"] = src.pop("max_size")
-        if "close_timeout" in src:
-            mapped["timeout"] = src.pop("close_timeout")
-        if "ping_interval" in src:
-            mapped["heartbeat"] = src.pop("ping_interval")
-        if "compression" in src:
-            mapped["compress"] = src.pop("compression")
-        # pass through supported aiohttp-style keys from our TypedDict
-        for key in ("max_msg_size", "timeout", "heartbeat", "autoclose", "autoping"):
-            if key in src:
-                mapped[key] = src[key]
+
+        # --- Neutral -> aiohttp mapping ---
+
+        # compression (neutral) -> compress (aiohttp expects int or None)
+        comp = src.pop("compression", None)
+        if comp is True:
+            mapped["compress"] = -1  # enable compression with default window bits
+        elif comp is False:
+            mapped["compress"] = None  # disable compression
+        elif isinstance(comp, int):
+            mapped["compress"] = comp  # power user provided zlib window value
+
+        # max message size
+        if "max_msg_size" in src:
+            mapped["max_msg_size"] = int(src.pop("max_msg_size"))
+
+        # ping interval
+        if "heartbeat" in src:
+            mapped["heartbeat"] = float(src.pop("heartbeat"))
+
+        # autoclose / autoping
+        if "autoclose" in src:
+            mapped["autoclose"] = bool(src.pop("autoclose"))
+        if "autoping" in src:
+            mapped["autoping"] = bool(src.pop("autoping"))
+
+        # Build ClientWSTimeout for receive/close timeouts
+        ws_timeout_kwargs: dict[str, float] = {}
+        recv_to = src.pop("receive_timeout", None)
+        if recv_to is not None:
+            ws_timeout_kwargs["ws_receive"] = float(recv_to)
+        close_to = src.pop("close_timeout", None)
+        if close_to is not None:
+            ws_timeout_kwargs["ws_close"] = float(close_to)
+        if ws_timeout_kwargs:
+            mapped["timeout"] = aiohttp.ClientWSTimeout(**ws_timeout_kwargs)
+
+        # handshake_timeout is not a ws_connect kwarg; caller must apply it on session
+        _ = src.pop("handshake_timeout", None)  # intentionally ignored here
+
+        # --- Vendor-specific passthrough (escape hatch) ---
+        vendor = src.pop("vendor_options", None)
+        if isinstance(vendor, Mapping):
+            for k, v in vendor.items():
+                mapped.setdefault(k, v)
+
+        # Any leftover keys in `src` are intentionally ignored to avoid leaking
+        # transport-specific names into our public surface.
         return mapped
 
     async def __aenter__(self) -> VoiceLiveConnection:
@@ -690,7 +733,7 @@ async def __aenter__(self) -> VoiceLiveConnection:
             url = self._prepare_url()
             log.debug("Connecting to %s", url)
 
-            self.__connection_options.setdefault("max_msg_size", 10 * 1024 * 1024)
+            self.__connection_options.setdefault("max_msg_size", 4 * 1024 * 1024)
             self.__connection_options.setdefault("heartbeat", 30)
 
             if self.__proxy_policy:
@@ -778,7 +821,7 @@ def connect(
     *,
     credential: Union[AzureKeyCredential, AsyncTokenCredential],
     endpoint: str,
-    api_version: str = "2025-05-01-preview",
+    api_version: str = "2025-10-01",
     model: Optional[str] = None,
     query: Optional[Mapping[str, Any]] = None,
     headers: Optional[Mapping[str, Any]] = None,
@@ -798,7 +841,7 @@ def connect(
     :paramtype type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.AsyncTokenCredential
     :keyword endpoint: Service endpoint, e.g., ``https://<region>.api.cognitive.microsoft.com``.
     :paramtype type endpoint: str
-    :keyword api_version: The API version to use. Defaults to ``"2025-05-01-preview"``.
+    :keyword api_version: The API version to use. Defaults to ``"2025-10-01"``.
     :paramtype type api_version: str
     :keyword model: Model identifier to use for the session.
      In most scenarios, this parameter is required.