# How aisuite Handles Parameter Mapping Across Different LLM Providers

> Discover how aisuite simplifies LLM integration by mapping parameters across providers like OpenAI, Deepgram, and Google Speech-to-Text with its ParameterMapper. Streamline your development.

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

---

**aisuite isolates provider-specific API complexities behind a unified `TranscriptionOptions` model, using a centralized `ParameterMapper` class to translate configurations into OpenAI, Deepgram, and Google Speech-to-Text formats.**

aisuite simplifies multi-provider AI development through a sophisticated parameter mapping system that bridges unified client code with diverse provider APIs. The mapping logic lives primarily in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py), where static dictionaries and conversion helpers transform high-level configuration objects into provider-native request payloads.

## The Unified TranscriptionOptions Interface

At the core of aisuite's provider abstraction is the `TranscriptionOptions` class defined in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py). This model standardizes common parameters—such as `language`, `response_format`, `temperature`, and `include_word_timestamps`—regardless of the underlying service. Developers configure these unified options once, and the framework handles the translation to each provider's specific nomenclature and structure.

## Provider-Specific Mapping Architecture

The `ParameterMapper` class contains static mapping dictionaries for every supported provider, ensuring type-safe and consistent translation across different APIs.

### OpenAI Whisper Mapping

The `OPENAI_MAPPING` dictionary in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) maps unified fields directly to OpenAI's Whisper API parameters. Standard fields like `language`, `response_format`, and `temperature` pass through with minimal transformation, while timestamp configurations undergo specific granularity mapping.

### Deepgram Mapping

For Deepgram integration, the `DEEPGRAM_MAPPING` translates unified options into Deepgram-specific features. Fields such as `enable_automatic_punctuation` map to `punctuate`, and speaker diarization flags convert to Deepgram's boolean parameters. The mapper also handles Deepgram's unique search and numerals features through the custom parameters interface.

### Google Speech-to-Text Mapping

The `GOOGLE_MAPPING` handles more complex transformations required by Google's API. It converts `language` to `language_code` (expanding "en" to "en-US"), translates `sample_rate` to `sample_rate_hertz`, and maps audio file extensions to Google's specific `encoding` enum values like `LINEAR16`.

## Parameter Conversion Logic

Beyond simple key renaming, aisuite implements sophisticated conversion helpers within the `ParameterMapper` class to handle semantic differences between providers.

### Timestamp Granularity Translation

The `map_to_openai`, `map_to_deepgram`, and `map_to_google` methods contain specialized logic for timestamp handling. When `include_word_timestamps` is requested:

- **OpenAI**: Converts to `timestamp_granularities: ["word"]`
- **Deepgram**: Activates `utterances` and `paragraphs` flags
- **Google**: Sets `enable_word_time_offsets: true`

### Language Code Normalization

Google Speech-to-Text requires BCP-47 locale strings, while other providers accept two-letter codes. The mapper automatically expands codes like `"en"` to `"en-US"` and similar locale-specific formats for other languages when generating Google-compatible parameters.

### Audio Encoding Translation

For Google Speech-to-Text, the mapper inspects audio file extensions (such as `"wav"` or `"flac"`) and translates them into the Google-specific `encoding` enum values required by the API.

## Handling Custom Provider Parameters

aisuite supports provider-specific overrides through a namespaced `custom_parameters` dictionary within `TranscriptionOptions`. This allows access to unique features not covered by the unified interface:

```python
custom_parameters = {
    "openai": {"response_format": "srt", "temperature": 0.2},
    "deepgram": {"search": ["keyword"], "numerals": True},
    "google": {"use_enhanced": True}
}

```

The private `_apply_custom_parameters` method merges these provider-specific values into the final payload, with custom parameters taking precedence over default mappings. Unrecognized provider namespaces are safely ignored.

## Implementation Examples

### Mapping to OpenAI Whisper

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

opts = TranscriptionOptions(
    language="en",
    response_format="json",
    temperature=0.0,
    include_word_timestamps=True,
    custom_parameters={"openai": {"response_format": "srt"}}
)

openai_params = ParameterMapper.map_to_openai(opts)

# Result:

# {

#     "language": "en",

#     "response_format": "srt",  # overridden by custom params

#     "temperature": 0.0,

#     "timestamp_granularities": ["word"]

# }

```

### Mapping to Deepgram

```python
deepgram_params = ParameterMapper.map_to_deepgram(opts)

# Result:

# {

#     "language": "en",

#     "punctuate": True,

#     "utterances": True  # derived from timestamp_granularities

# }

```

### Mapping to Google Speech-to-Text

```python
google_params = ParameterMapper.map_to_google(opts)

# Result:

# {

#     "language_code": "en-US",

#     "enable_word_time_offsets": True,

#     "encoding": "LINEAR16"

# }

```

### Provider Wrapper Implementation

Each provider implements a thin wrapper that utilizes the mapper while maintaining clean separation of concerns:

```python
from aisuite.framework.parameter_mapper import ParameterMapper
from aisuite.providers.openai_provider import OpenAIProvider

def transcribe_with_openai(opts: TranscriptionOptions):
    api_params = ParameterMapper.map_to_openai(opts)
    return OpenAIProvider.transcribe(**api_params)

```

This pattern ensures that [`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py), [`aisuite/providers/deepgram_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/deepgram_provider.py), and [`aisuite/providers/google_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/google_provider.py) remain focused on API communication rather than parameter transformation logic.

## Summary

- **Centralized mapping**: All parameter translation logic resides in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) through the `ParameterMapper` class.
- **Static dictionaries**: Provider-specific mappings (`OPENAI_MAPPING`, `DEEPGRAM_MAPPING`, `GOOGLE_MAPPING`) define direct field translations.
- **Semantic conversion**: Helper methods handle complex transformations for timestamps, language codes, and audio encoding formats.
- **Override capability**: The `custom_parameters` dictionary allows provider-specific features while maintaining the unified interface.
- **Clean architecture**: Provider wrappers in `aisuite/providers/` consume mapped parameters without handling translation logic directly.

## Frequently Asked Questions

### How does aisuite handle parameters that exist in one provider but not others?

Provider-specific parameters are supported through the `custom_parameters` dictionary namespaced by provider name. The `_apply_custom_parameters` method merges these into the final API payload only for the relevant provider, ensuring that unique features like Deepgram's keyword search or Google's enhanced models remain accessible without breaking the unified interface.

### Where is the parameter mapping logic implemented in the aisuite codebase?

The core mapping logic is implemented in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py). This file contains the `ParameterMapper` class with static mapping dictionaries and conversion methods (`map_to_openai`, `map_to_deepgram`, `map_to_google`) that transform the unified `TranscriptionOptions` model into provider-specific formats.

### Does aisuite automatically convert language codes for different providers?

Yes, the `ParameterMapper` automatically normalizes language codes for Google Speech-to-Text by expanding two-letter codes like "en" to BCP-47 locale strings such as "en-US". This conversion happens within the `map_to_google` method, ensuring compatibility with Google's API requirements while allowing developers to use standard language codes in their unified configuration.

### Can I override specific parameters for individual providers when using the unified interface?

Absolutely. You can supply a `custom_parameters` dictionary when creating `TranscriptionOptions`, with keys corresponding to provider names ("openai", "deepgram", "google"). These values override the default mappings, allowing you to set provider-specific options like `response_format: "srt"` for OpenAI or `use_enhanced: true` for Google while maintaining a single configuration object for all providers.