mistralai 1.11.1__py3-none-any.whl → 1.12.0__py3-none-any.whl

mistralai/_version.py

@@ -3,10 +3,10 @@
 import importlib.metadata
 
 __title__: str = "mistralai"
-__version__: str = "1.11.1"
+__version__: str = "1.12.0"
 __openapi_doc_version__: str = "1.0.0"
 __gen_version__: str = "2.794.1"
-__user_agent__: str = "speakeasy-sdk/python 1.11.1 2.794.1 1.0.0 mistralai"
+__user_agent__: str = "speakeasy-sdk/python 1.12.0 2.794.1 1.0.0 mistralai"
 
 try:
     if __package__ is not None:

mistralai/audio.py

@@ -5,6 +5,13 @@ from .sdkconfiguration import SDKConfiguration
 from mistralai.transcriptions import Transcriptions
 from typing import Optional
 
+# region imports
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mistralai.extra.realtime import RealtimeTranscription
+# endregion imports
+
 
 class Audio(BaseSDK):
     transcriptions: Transcriptions
@@ -21,3 +28,16 @@ class Audio(BaseSDK):
         self.transcriptions = Transcriptions(
             self.sdk_configuration, parent_ref=self.parent_ref
         )
+
+    # region sdk-class-body
+    @property
+    def realtime(self) -> "RealtimeTranscription":
+        """Returns a client for real-time audio transcription via WebSocket."""
+        if not hasattr(self, "_realtime"):
+            from mistralai.extra.realtime import RealtimeTranscription  # pylint: disable=import-outside-toplevel
+
+            self._realtime = RealtimeTranscription(self.sdk_configuration)  # pylint: disable=attribute-defined-outside-init
+
+        return self._realtime
+
+    # endregion sdk-class-body

mistralai/conversations.py

@@ -259,7 +259,12 @@ class Conversations(BaseSDK):
         description: OptionalNullable[str] = UNSET,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
         agent_id: OptionalNullable[str] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrequest.AgentVersion,
+                models_conversationrequest.AgentVersionTypedDict,
+            ]
+        ] = UNSET,
         model: OptionalNullable[str] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -405,7 +410,12 @@ class Conversations(BaseSDK):
         description: OptionalNullable[str] = UNSET,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
         agent_id: OptionalNullable[str] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrequest.AgentVersion,
+                models_conversationrequest.AgentVersionTypedDict,
+            ]
+        ] = UNSET,
         model: OptionalNullable[str] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -1711,7 +1721,12 @@ class Conversations(BaseSDK):
             ]
         ] = None,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrestartrequest.ConversationRestartRequestAgentVersion,
+                models_conversationrestartrequest.ConversationRestartRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
         timeout_ms: Optional[int] = None,
@@ -1846,7 +1861,12 @@ class Conversations(BaseSDK):
             ]
         ] = None,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrestartrequest.ConversationRestartRequestAgentVersion,
+                models_conversationrestartrequest.ConversationRestartRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
         timeout_ms: Optional[int] = None,
@@ -1991,7 +2011,12 @@ class Conversations(BaseSDK):
         description: OptionalNullable[str] = UNSET,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
         agent_id: OptionalNullable[str] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationstreamrequest.ConversationStreamRequestAgentVersion,
+                models_conversationstreamrequest.ConversationStreamRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         model: OptionalNullable[str] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -2148,7 +2173,12 @@ class Conversations(BaseSDK):
         description: OptionalNullable[str] = UNSET,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
         agent_id: OptionalNullable[str] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationstreamrequest.ConversationStreamRequestAgentVersion,
+                models_conversationstreamrequest.ConversationStreamRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         model: OptionalNullable[str] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -2561,7 +2591,12 @@ class Conversations(BaseSDK):
             ]
         ] = None,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrestartstreamrequest.ConversationRestartStreamRequestAgentVersion,
+                models_conversationrestartstreamrequest.ConversationRestartStreamRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
         timeout_ms: Optional[int] = None,
@@ -2703,7 +2738,12 @@ class Conversations(BaseSDK):
             ]
         ] = None,
         metadata: OptionalNullable[Dict[str, Any]] = UNSET,
-        agent_version: OptionalNullable[int] = UNSET,
+        agent_version: OptionalNullable[
+            Union[
+                models_conversationrestartstreamrequest.ConversationRestartStreamRequestAgentVersion,
+                models_conversationrestartstreamrequest.ConversationRestartStreamRequestAgentVersionTypedDict,
+            ]
+        ] = UNSET,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
         timeout_ms: Optional[int] = None,

mistralai/extra/__init__.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING
+
 from .struct_chat import (
     ParsedChatCompletionResponse,
     convert_to_parsed_chat_completion_response,
@@ -5,9 +7,55 @@ from .struct_chat import (
 from .utils import response_format_from_pydantic_model
 from .utils.response_format import CustomPydanticModel
 
+if TYPE_CHECKING:
+    from .realtime import (
+        AudioEncoding,
+        AudioFormat,
+        RealtimeConnection,
+        RealtimeTranscriptionError,
+        RealtimeTranscriptionErrorDetail,
+        RealtimeTranscriptionSession,
+        RealtimeTranscriptionSessionCreated,
+        RealtimeTranscriptionSessionUpdated,
+        RealtimeTranscription,
+        UnknownRealtimeEvent,
+    )
+
+_REALTIME_EXPORTS = {
+    "RealtimeTranscription",
+    "RealtimeConnection",
+    "AudioEncoding",
+    "AudioFormat",
+    "UnknownRealtimeEvent",
+    "RealtimeTranscriptionError",
+    "RealtimeTranscriptionErrorDetail",
+    "RealtimeTranscriptionSession",
+    "RealtimeTranscriptionSessionCreated",
+    "RealtimeTranscriptionSessionUpdated",
+}
+
+
+def __getattr__(name: str):
+    if name in _REALTIME_EXPORTS:
+        from . import realtime
+
+        return getattr(realtime, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     "convert_to_parsed_chat_completion_response",
     "response_format_from_pydantic_model",
     "CustomPydanticModel",
     "ParsedChatCompletionResponse",
+    "RealtimeTranscription",
+    "RealtimeConnection",
+    "AudioEncoding",
+    "AudioFormat",
+    "UnknownRealtimeEvent",
+    "RealtimeTranscriptionError",
+    "RealtimeTranscriptionErrorDetail",
+    "RealtimeTranscriptionSession",
+    "RealtimeTranscriptionSessionCreated",
+    "RealtimeTranscriptionSessionUpdated",
 ]

mistralai/extra/exceptions.py

@@ -1,14 +1,59 @@
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mistralai.models import RealtimeTranscriptionError
+
+
 class MistralClientException(Exception):
-    """Base exception for all the client errors."""
+    """Base exception for client errors."""
 
 
 class RunException(MistralClientException):
-    """Exception raised for errors during a conversation run."""
+    """Conversation run errors."""
 
 
 class MCPException(MistralClientException):
-    """Exception raised for errors related to MCP operations."""
+    """MCP operation errors."""
 
 
 class MCPAuthException(MCPException):
-    """Exception raised for authentication errors with an MCP server."""
+    """MCP authentication errors."""
+
+
+class RealtimeTranscriptionException(MistralClientException):
+    """Base realtime transcription exception."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[int] = None,
+        payload: Optional[object] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.payload = payload
+
+
+class RealtimeTranscriptionWSError(RealtimeTranscriptionException):
+    def __init__(
+        self,
+        message: str,
+        *,
+        payload: Optional["RealtimeTranscriptionError"] = None,
+        raw: Optional[object] = None,
+    ) -> None:
+        code: Optional[int] = None
+        if payload is not None:
+            try:
+                maybe_code = getattr(payload.error, "code", None)
+                if isinstance(maybe_code, int):
+                    code = maybe_code
+            except Exception:
+                code = None
+
+        super().__init__(
+            message, code=code, payload=payload if payload is not None else raw
+        )
+        self.payload_typed = payload
+        self.payload_raw = raw

mistralai/extra/realtime/__init__.py

@@ -0,0 +1,25 @@
+from mistralai.models import (
+    AudioEncoding,
+    AudioFormat,
+    RealtimeTranscriptionError,
+    RealtimeTranscriptionErrorDetail,
+    RealtimeTranscriptionSession,
+    RealtimeTranscriptionSessionCreated,
+    RealtimeTranscriptionSessionUpdated,
+)
+
+from .connection import UnknownRealtimeEvent, RealtimeConnection
+from .transcription import RealtimeTranscription
+
+__all__ = [
+    "AudioEncoding",
+    "AudioFormat",
+    "RealtimeTranscriptionError",
+    "RealtimeTranscriptionErrorDetail",
+    "RealtimeTranscriptionSession",
+    "RealtimeTranscriptionSessionCreated",
+    "RealtimeTranscriptionSessionUpdated",
+    "RealtimeConnection",
+    "RealtimeTranscription",
+    "UnknownRealtimeEvent",
+]

mistralai/extra/realtime/connection.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import base64
+import json
+from asyncio import CancelledError
+from collections import deque
+from typing import Any, AsyncIterator, Deque, Optional, Union
+
+from pydantic import ValidationError, BaseModel
+
+try:
+    from websockets.asyncio.client import ClientConnection  # websockets >= 13.0
+except ImportError as exc:
+    raise ImportError(
+        "The `websockets` package (>=13.0) is required for real-time transcription. "
+        "Install with: pip install 'mistralai[realtime]'"
+    ) from exc
+
+from mistralai.models import (
+    AudioFormat,
+    RealtimeTranscriptionError,
+    RealtimeTranscriptionSession,
+    RealtimeTranscriptionSessionCreated,
+    RealtimeTranscriptionSessionUpdated,
+    TranscriptionStreamDone,
+    TranscriptionStreamLanguage,
+    TranscriptionStreamSegmentDelta,
+    TranscriptionStreamTextDelta,
+)
+
+
+class UnknownRealtimeEvent(BaseModel):
+    """
+    Forward-compat fallback event:
+    - unknown message type
+    - invalid JSON payload
+    - schema validation failure
+    """
+    type: Optional[str]
+    content: Any
+    error: Optional[str] = None
+
+
+RealtimeEvent = Union[
+    # session lifecycle
+    RealtimeTranscriptionSessionCreated,
+    RealtimeTranscriptionSessionUpdated,
+    # server errors
+    RealtimeTranscriptionError,
+    # transcription events
+    TranscriptionStreamLanguage,
+    TranscriptionStreamSegmentDelta,
+    TranscriptionStreamTextDelta,
+    TranscriptionStreamDone,
+    # forward-compat fallback
+    UnknownRealtimeEvent,
+]
+
+
+_MESSAGE_MODELS: dict[str, Any] = {
+    "session.created": RealtimeTranscriptionSessionCreated,
+    "session.updated": RealtimeTranscriptionSessionUpdated,
+    "error": RealtimeTranscriptionError,
+    "transcription.language": TranscriptionStreamLanguage,
+    "transcription.segment": TranscriptionStreamSegmentDelta,
+    "transcription.text.delta": TranscriptionStreamTextDelta,
+    "transcription.done": TranscriptionStreamDone,
+}
+
+
+def parse_realtime_event(payload: Any) -> RealtimeEvent:
+    """
+    Tolerant parser:
+    - unknown event type -> UnknownRealtimeEvent
+    - validation failures -> UnknownRealtimeEvent (includes error string)
+    - invalid payload -> UnknownRealtimeEvent
+    """
+    if not isinstance(payload, dict):
+        return UnknownRealtimeEvent(
+            type=None, content=payload, error="expected JSON object"
+        )
+
+    msg_type = payload.get("type")
+    if not isinstance(msg_type, str):
+        return UnknownRealtimeEvent(
+            type=None, content=payload, error="missing/invalid 'type'"
+        )
+
+    model_cls = _MESSAGE_MODELS.get(msg_type)
+    if model_cls is None:
+        return UnknownRealtimeEvent(
+            type=msg_type, content=payload, error="unknown event type"
+        )
+    try:
+        parsed = model_cls.model_validate(payload)
+        return parsed
+    except ValidationError as exc:
+        return UnknownRealtimeEvent(type=msg_type, content=payload, error=str(exc))
+
+
+class RealtimeConnection:
+    def __init__(
+        self,
+        websocket: ClientConnection,
+        session: RealtimeTranscriptionSession,
+        *,
+        initial_events: Optional[list[RealtimeEvent]] = None,
+    ) -> None:
+        self._websocket = websocket
+        self._session = session
+        self._audio_format = session.audio_format
+        self._closed = False
+        self._initial_events: Deque[RealtimeEvent] = deque(initial_events or [])
+
+    @property
+    def request_id(self) -> str:
+        return self._session.request_id
+
+    @property
+    def session(self) -> RealtimeTranscriptionSession:
+        return self._session
+
+    @property
+    def audio_format(self) -> AudioFormat:
+        return self._audio_format
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    async def send_audio(
+        self, audio_bytes: Union[bytes, bytearray, memoryview]
+    ) -> None:
+        if self._closed:
+            raise RuntimeError("Connection is closed")
+
+        message = {
+            "type": "input_audio.append",
+            "audio": base64.b64encode(bytes(audio_bytes)).decode("ascii"),
+        }
+        await self._websocket.send(json.dumps(message))
+
+    async def update_session(self, audio_format: AudioFormat) -> None:
+        if self._closed:
+            raise RuntimeError("Connection is closed")
+
+        self._audio_format = audio_format
+        message = {
+            "type": "session.update",
+            "session": {"audio_format": audio_format.model_dump(mode="json")},
+        }
+        await self._websocket.send(json.dumps(message))
+
+    async def end_audio(self) -> None:
+        if self._closed:
+            return
+        await self._websocket.send(json.dumps({"type": "input_audio.end"}))
+
+    async def close(self, *, code: int = 1000, reason: str = "") -> None:
+        if self._closed:
+            return
+        self._closed = True
+        await self._websocket.close(code=code, reason=reason)
+
+    async def __aenter__(self) -> "RealtimeConnection":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    def __aiter__(self) -> AsyncIterator[RealtimeEvent]:
+        return self.events()
+
+    async def events(self) -> AsyncIterator[RealtimeEvent]:
+        # replay any handshake/prelude events (including session.created)
+        while self._initial_events:
+            ev = self._initial_events.popleft()
+            self._apply_session_updates(ev)
+            yield ev
+
+        try:
+            async for msg in self._websocket:
+                text = (
+                    msg.decode("utf-8", errors="replace")
+                    if isinstance(msg, (bytes, bytearray))
+                    else msg
+                )
+                try:
+                    data = json.loads(text)
+                except Exception as exc:
+                    yield UnknownRealtimeEvent(
+                        type=None, content=text, error=f"invalid JSON: {exc}"
+                    )
+                    continue
+
+                ev = parse_realtime_event(data)
+                self._apply_session_updates(ev)
+                yield ev
+        except CancelledError:
+            pass
+        finally:
+            await self.close()
+
+    def _apply_session_updates(self, ev: RealtimeEvent) -> None:
+        if isinstance(ev, RealtimeTranscriptionSessionCreated) or isinstance(ev, RealtimeTranscriptionSessionUpdated):
+            self._session = ev.session
+            self._audio_format = ev.session.audio_format