Introduce unified TranscriptionOptions for better parameter management across providers.

Author: akshay1100

aisuite/client.py

@@ -1,7 +1,11 @@
 from .provider import ProviderFactory
 import os
 from .utils.tools import Tools
-from typing import Union, BinaryIO
+from typing import Union, BinaryIO, Optional, Any
+from .framework.message import (
+    TranscriptionOptions,
+    TranscriptionResponse,
+)
 
 
 class Client:
@@ -51,7 +55,7 @@ def _validate_provider_key(self, provider_key):
 
         return provider_key
 
-    def configure(self, provider_configs: dict = None):
+    def configure(self, provider_configs: Optional[dict] = None):
         """
         Configure the client with provider configurations.
         """
@@ -124,7 +128,7 @@ def _tool_runner(
         provider,
         model_name: str,
         messages: list,
-        tools: any,
+        tools: Any,
         max_turns: int,
         **kwargs,
     ):
@@ -273,18 +277,47 @@ class Transcriptions:
     def __init__(self, client: "Client"):
         self.client = client
 
-    def create(self, *, model: str, file: Union[str, BinaryIO], **kwargs):
+    def create(
+        self,
+        *,
+        model: str,
+        file: Union[str, BinaryIO],
+        options: Optional[TranscriptionOptions] = None,
+        **kwargs,
+    ) -> TranscriptionResponse:
         """
         Create a transcription using the specified model and file.
 
         Args:
             model: Provider and model in format 'provider:model' (e.g., 'openai:whisper-1')
             file: Audio file to transcribe (file path or file-like object)
-            **kwargs: Additional parameters to pass to the provider
+            options: TranscriptionOptions instance with unified parameters (includes stream control)
+            **kwargs: Additional parameters (used if options is None, assumed to be OpenAI format)
 
         Returns:
-            TranscriptionResult: Unified transcription result
+            TranscriptionResponse: Unified response (batch or streaming based on options.stream)
         """
+        # Validate options and kwargs
+        if options is not None:
+            if not options.has_any_parameters():
+                raise ValueError(
+                    "TranscriptionOptions provided but no parameters are set. "
+                    "Please set at least one parameter or pass None to use kwargs."
+                )
+            # TranscriptionOptions takes precedence, ignore kwargs
+            if kwargs:
+                import warnings
+
+                warnings.warn(
+                    "Both TranscriptionOptions and kwargs provided. Using TranscriptionOptions and ignoring kwargs.",
+                    UserWarning,
+                )
+        elif not kwargs:
+            # Neither options nor kwargs provided
+            raise ValueError(
+                "Either TranscriptionOptions or kwargs must be provided for transcription parameters."
+            )
+
         # Check that correct format is used
         if ":" not in model:
             raise ValueError(
@@ -294,29 +327,61 @@ def create(self, *, model: str, file: Union[str, BinaryIO], **kwargs):
         # Extract the provider key from the model identifier
         provider_key, model_name = model.split(":", 1)
 
-        # Validate if the provider is supported
-        supported_providers = ProviderFactory.get_supported_providers()
-        if provider_key not in supported_providers:
-            raise ValueError(
-                f"Invalid provider key '{provider_key}'. Supported providers: {supported_providers}. "
-                "Make sure the model string is formatted correctly as 'provider:model'."
-            )
-
         # Initialize provider if not already initialized
         if provider_key not in self.client.providers:
             config = self.client.provider_configs.get(provider_key, {})
-            self.client.providers[provider_key] = ProviderFactory.create_provider(
-                provider_key, config
-            )
+            try:
+                self.client.providers[provider_key] = ProviderFactory.create_provider(
+                    provider_key, config
+                )
+            except ImportError as e:
+                raise ValueError(f"Provider '{provider_key}' is not available: {e}")
 
         provider = self.client.providers.get(provider_key)
         if not provider:
             raise ValueError(f"Could not load provider for '{provider_key}'.")
 
+        # Check if provider supports audio transcription
+        if not hasattr(provider, "audio") or provider.audio is None:
+            raise ValueError(
+                f"Provider '{provider_key}' does not support audio transcription."
+            )
+
+        # Determine if streaming is requested
+        should_stream = False  # Default to batch processing
+        if options and options.stream is not None:
+            should_stream = options.stream
+        elif kwargs.get("stream"):
+            should_stream = kwargs.get("stream", False)
+
         # Delegate the transcription to the correct provider's implementation
-        # The provider will raise NotImplementedError if it doesn't support ASR
         try:
-            return provider.audio_transcriptions_create(model_name, file, **kwargs)
+            if should_stream:
+                # Check if provider supports output streaming
+                if (
+                    hasattr(provider.audio, "transcriptions")
+                    and hasattr(provider.audio.transcriptions, "create_stream_output")
+                ):
+                    return provider.audio.transcriptions.create_stream_output(
+                        model_name, file, options=options, **kwargs
+                    )
+                else:
+                    raise ValueError(
+                        f"Provider '{provider_key}' does not support output streaming transcription."
+                    )
+            else:
+                # Non-streaming (batch) transcription
+                if (
+                    hasattr(provider.audio, "transcriptions")
+                    and hasattr(provider.audio.transcriptions, "create")
+                ):
+                    return provider.audio.transcriptions.create(
+                        model_name, file, options=options, **kwargs
+                    )
+                else:
+                    raise ValueError(
+                        f"Provider '{provider_key}' does not support audio transcription."
+                    )
         except NotImplementedError:
             raise ValueError(
                 f"Provider '{provider_key}' does not support audio transcription."

aisuite/framework/message.py

@@ -3,8 +3,9 @@
 to the OpenAI style response.
 """
 
-from typing import Literal, Optional, List
+from typing import Literal, Optional, List, AsyncGenerator, Union, Dict, Any
 from pydantic import BaseModel
+from dataclasses import dataclass, field
 
 
 class Function(BaseModel):
@@ -168,3 +169,129 @@ class TranscriptionResult(BaseModel):
     # Metadata
     metadata: Optional[dict] = None  # Provider-specific metadata
     model_info: Optional[dict] = None  # Model information
+
+
+class StreamingTranscriptionChunk(BaseModel):
+    """Represents a single chunk of streaming transcription data."""
+
+    text: str
+    is_final: bool
+    confidence: Optional[float] = None
+    start_time: Optional[float] = None
+    end_time: Optional[float] = None
+    speaker_id: Optional[int] = None
+    speaker_confidence: Optional[float] = None
+    words: Optional[List[Word]] = None
+    sequence_number: Optional[int] = None
+    channel: Optional[int] = None
+    provider_data: Optional[dict] = None
+
+
+# Type alias for streaming transcription responses
+StreamingTranscriptionResponse = AsyncGenerator[StreamingTranscriptionChunk, None]
+
+# Union type for both batch and streaming responses
+TranscriptionResponse = Union[TranscriptionResult, StreamingTranscriptionResponse]
+
+
+@dataclass
+class TranscriptionOptions:
+    """Unified transcription options for ASR providers."""
+
+    # Core parameters
+    language: Optional[str] = None
+
+    # Audio format parameters
+    audio_format: Optional[str] = None
+    sample_rate: Optional[int] = None
+    channels: Optional[int] = None
+    encoding: Optional[str] = None  # Audio encoding type
+
+    # Output format
+    response_format: Optional[str] = None
+    include_word_timestamps: Optional[bool] = None
+    include_segment_timestamps: Optional[bool] = None
+
+    # Context and guidance
+    prompt: Optional[str] = None
+    context_phrases: Optional[List[str]] = None
+    boost_phrases: Optional[List[str]] = None
+
+    # Speaker features
+    enable_speaker_diarization: Optional[bool] = None
+    max_speakers: Optional[int] = None
+    min_speakers: Optional[int] = None
+
+    # Text processing
+    enable_automatic_punctuation: Optional[bool] = None
+    enable_profanity_filter: Optional[bool] = None
+    enable_smart_formatting: Optional[bool] = None
+    enable_word_confidence: Optional[bool] = None
+    enable_spoken_punctuation: Optional[bool] = None
+    enable_spoken_emojis: Optional[bool] = None
+
+    # Advanced features
+    enable_sentiment_analysis: Optional[bool] = None
+    enable_topic_detection: Optional[bool] = None
+    enable_intent_recognition: Optional[bool] = None
+    enable_summarization: Optional[bool] = None
+    enable_translation: Optional[bool] = None
+    translation_target_language: Optional[str] = None
+
+    # Confidence and alternatives
+    include_confidence_scores: Optional[bool] = None
+    max_alternatives: Optional[int] = None
+
+    # Processing options
+    temperature: Optional[float] = None
+    interim_results: Optional[bool] = None
+    vad_sensitivity: Optional[float] = None
+    stream: Optional[bool] = None  # Enable streaming output
+
+    # Custom parameters
+    custom_parameters: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate parameters and constraints."""
+        # Validate constraints
+        if self.temperature is not None and not (0.0 <= self.temperature <= 1.0):
+            raise ValueError("temperature must be between 0.0 and 1.0")
+
+        if self.max_speakers is not None and self.max_speakers < 1:
+            raise ValueError("max_speakers must be at least 1")
+
+        if self.min_speakers is not None and self.min_speakers < 1:
+            raise ValueError("min_speakers must be at least 1")
+
+        if (
+            self.max_speakers is not None
+            and self.min_speakers is not None
+            and self.min_speakers > self.max_speakers
+        ):
+            raise ValueError("min_speakers cannot be greater than max_speakers")
+
+        if self.vad_sensitivity is not None and not (
+            0.0 <= self.vad_sensitivity <= 1.0
+        ):
+            raise ValueError("vad_sensitivity must be between 0.0 and 1.0")
+
+    def has_any_parameters(self) -> bool:
+        """Check if any parameters are set."""
+        for field_name, field_value in self.__dict__.items():
+            if field_name == "custom_parameters":
+                if field_value:
+                    return True
+            elif field_value is not None:
+                return True
+        return False
+
+    def get_set_parameters(self) -> Dict[str, Any]:
+        """Get only the parameters that are set."""
+        set_params = {}
+        for field_name, field_value in self.__dict__.items():
+            if field_name == "custom_parameters":
+                if field_value:
+                    set_params[field_name] = field_value
+            elif field_value is not None:
+                set_params[field_name] = field_value
+        return set_params