# How the ParameterMapper Handles Provider Configuration Differences in AISuite

> Discover how the ParameterMapper in AISuite translates unified TranscriptionOptions into provider-specific payloads for OpenAI Whisper, Deepgram, and Google Speech-to-Text.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: internals
- Published: 2026-07-30

---

**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`](https://github.com/andrewyng/aisuite/blob/main/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.

```python
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.

```python
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.

```python
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`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py)).
2. The provider client in [`aisuite/mcp/client.py`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py) are converted to the correct format for the selected ASR service.