How the ParameterMapper Handles Provider Configuration Differences in AISuite

The ParameterMapper class translates unified TranscriptionOptions into provider-specific request payloads using dedicated mapping tables and conversion methods for OpenAI Whisper, Deepgram, and Google Speech-to-Text.

The AISuite library provides a single interface for automatic speech recognition (ASR) services, but each provider uses distinct API parameters and naming conventions. The ParameterMapper in aisuite/framework/parameter_mapper.py bridges these differences by converting generic TranscriptionOptions into the exact format required by each vendor's endpoint. This architecture enables developers to switch between transcription providers without rewriting configuration logic.

Provider-Specific Mapping Tables

The ParameterMapper defines hardcoded dictionaries that map generic option names to vendor-specific keys. These tables encapsulate naming differences so the rest of the codebase remains provider-agnostic.

OpenAI Whisper Mapping

The OPENAI_MAPPING dictionary (lines 15-23) maps standardized options like language, response_format, and temperature directly to OpenAI's Whisper API parameters. This mapping handles most options as direct key-value translations without additional transformation.

Deepgram Mapping

The DEEPGRAM_MAPPING dictionary (lines 25-48) translates unified options into Deepgram-specific keys. For example, enable_automatic_punctuation becomes punctuate, enable_speaker_diarization becomes diarize, and include_word_timestamps maps to utterances. This table accommodates Deepgram's unique boolean flag structure for audio processing features.

Google Speech-to-Text Mapping

The GOOGLE_MAPPING dictionary (lines 50-72) converts unified fields to Google Cloud Speech-to-Text request model keys. Critical translations include language to language_code, sample_rate to sample_rate_hertz, and audio_format to encoding. This mapping accounts for Google's specific protobuf field naming conventions.

Mapping Method Implementations

The ParameterMapper class implements three primary conversion methods that iterate over their respective mapping dictionaries and apply provider-specific logic.

map_to_openai Method

The map_to_openai method (lines 74-98) iterates over OPENAI_MAPPING and copies present values from TranscriptionOptions. It constructs a timestamp_granularities list when include_word_timestamps or include_segment_timestamps are enabled, converting boolean flags into OpenAI's expected array format. Finally, it injects any user-provided custom parameters under the openai namespace.

from aisuite.framework.message import TranscriptionOptions
from aisuite.framework.parameter_mapper import ParameterMapper

opts = TranscriptionOptions(
    language="en",
    response_format="srt",
    temperature=0.2,
    include_word_timestamps=True,
    custom_parameters={"openai": {"model": "whisper-1"}}
)

openai_params = ParameterMapper.map_to_openai(opts)

# Result includes timestamp_granularities and custom model parameter

map_to_deepgram Method

The map_to_deepgram method (lines 100-128) walks the DEEPGRAM_MAPPING dictionary, assigning non-None values directly. It handles two special conversions: context_phrases translates to keywords, and the unified timestamp_granularities list splits into Deepgram's utterances (word-level) and paragraphs (segment-level) boolean flags. The method then merges namespaced custom parameters under the deepgram key.

opts = TranscriptionOptions(
    language="en",
    enable_automatic_punctuation=True,
    include_word_timestamps=True,
    custom_parameters={"deepgram": {"search": ["keyword"]}}
)

deepgram_params = ParameterMapper.map_to_deepgram(opts)

# Result includes punctuate, utterances, and custom search parameters

map_to_google Method

The map_to_google method (lines 130-200) follows the same pattern but includes additional transformation logic for language codes and audio formats. It converts short language codes like "en" to "en-US" using an internal mapping, and translates audio format strings such as wav to LINEAR16 and mp3 to MP3. It also expands timestamp_granularities into Google's enable_word_time_offsets boolean flag.

opts = TranscriptionOptions(
    language="es",
    sample_rate=16000,
    audio_format="wav",
    include_word_timestamps=True,
    custom_parameters={"google": {"use_enhanced": True}}
)

google_params = ParameterMapper.map_to_google(opts)

# Result includes language_code, encoding, and enhanced model flag

Custom Parameter Support

All three mapping methods delegate to the private helper _apply_custom_parameters (lines 202-225). This method only respects keys namespaced by provider (e.g., "openai": {...}, "deepgram": {...}, "google": {...}), merging them into the final payload while silently ignoring stray entries. This design allows users to pass provider-specific features not covered by the unified TranscriptionOptions interface without breaking the abstraction for other providers.

Internal Architecture Flow

The ParameterMapper operates as the translation layer between AISuite's unified API and vendor-specific endpoints:

1. User code creates a TranscriptionOptions instance (defined in aisuite/framework/message.py).
2. The provider client in aisuite/mcp/client.py calls the appropriate ParameterMapper.map_to_<provider> method.
3. The mapper looks up the provider's mapping table, copies matching attributes, applies special conversions (timestamps, language codes, encodings), and inserts namespaced custom parameters.
4. The resulting dictionary is sent verbatim to the provider's HTTP endpoint via the MCP client.

This design cleanly separates what the user wants (unified options) from how each vendor expects the request, enabling a single high-level API while supporting any number of providers.

Summary

• The ParameterMapper in aisuite/framework/parameter_mapper.py centralizes provider-specific configuration logic for OpenAI, Deepgram, and Google.
• Mapping tables (OPENAI_MAPPING, DEEPGRAM_MAPPING, GOOGLE_MAPPING) define the translation from generic option names to vendor-specific keys.
• Conversion methods handle special logic for timestamps, language codes, audio formats, and encoding types.
• Custom parameters are supported through namespaced dictionaries (e.g., {"openai": {"model": "whisper-1"}}) merged via _apply_custom_parameters.
• The architecture allows aisuite/mcp/client.py to remain provider-agnostic while delivering correctly formatted requests to each ASR service.

Frequently Asked Questions

What is the ParameterMapper in AISuite?

The ParameterMapper is a utility class in aisuite/framework/parameter_mapper.py that translates unified TranscriptionOptions objects into the specific request formats required by OpenAI Whisper, Deepgram, and Google Speech-to-Text. It acts as the abstraction layer that allows AISuite to present a single consistent API while internally handling each provider's unique parameter naming and structure requirements.

How does ParameterMapper handle timestamp granularity options?

Each mapping method converts the unified timestamp_granularities list differently. For OpenAI, it passes the array directly. For Deepgram, it splits the list into separate utterances (word-level) and paragraphs (segment-level) boolean flags. For Google, it sets the enable_word_time_offsets boolean. These conversions occur in map_to_openai (lines 74-98), map_to_deepgram (lines 100-128), and map_to_google (lines 130-200) respectively.

Can I pass provider-specific parameters not defined in TranscriptionOptions?

Yes. The _apply_custom_parameters method (lines 202-225) merges namespaced custom parameters into the final payload. You can include a dictionary keyed by provider name (e.g., {"deepgram": {"search": ["term"]}} or {"google": {"use_enhanced": true}}) in the custom_parameters field of TranscriptionOptions. The mapper only applies keys matching the target provider namespace.

Where does ParameterMapper fit in the AISuite request lifecycle?

The ParameterMapper is invoked by aisuite/mcp/client.py after a user creates a TranscriptionOptions instance but before the HTTP request is sent to the provider. It sits between the unified user interface and the provider-specific client implementations, ensuring that TranscriptionOptions from aisuite/framework/message.py are converted to the correct format for the selected ASR service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}