# How AISuite Manages Provider-Specific Parameters Through Parameter Mapping

> Learn how AISuite uses parameter mapping to normalize disparate ASR provider API requirements. Understand its unified schema and central mapper for seamless integration.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-07-27

---

**AISuite normalizes disparate API requirements across ASR providers by funneling every request through a unified `TranscriptionOptions` schema and a central `ParameterMapper` that translates those options into provider-native payloads.**

The `andrewyng/aisuite` repository eliminates the need for developers to memorize each provider's unique parameter names by offering a single source of truth for configuration. Instead of manually reformatting payloads for OpenAI, Deepgram, or Google Speech-to-Text, you define high-level options once and let the framework handle the rest. This article walks through the exact source files and mapping logic as implemented in `andrewyng/aisuite`.

## The Core Architecture of AISuite Parameter Mapping

The system relies on two components: a provider-agnostic dataclass that captures intent, and a mapper that turns that intent into concrete API fields.

### TranscriptionOptions: The Unified Schema

All high-level transcription settings live in the **TranscriptionOptions** dataclass defined in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py) (lines 197–254). This structure aggregates common concepts such as **language**, **audio format**, **sample rate**, **timestamps**, **speaker diarization**, and **maximum speaker count** into one standardized object. By centralizing these fields, AISuite ensures that adding a new provider never requires changes to user-facing configuration code.

### ParameterMapper: The Central Translation Layer

The **ParameterMapper** class in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) (lines 12–100) houses the static mapping dictionaries and conversion methods for each supported service. It exposes class methods such as `map_to_openai`, `map_to_deepgram`, and `map_to_google` that accept a single `TranscriptionOptions` instance and return a dictionary ready for the provider's SDK. The mapper intentionally omits `None` values, so only explicitly configured parameters reach the downstream API.

### Provider-Specific Mapping Tables

Inside [`parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/parameter_mapper.py), each provider has its own translation table. The OpenAI mapping occupies lines 15–23, the Deepgram mapping spans lines 25–45, and the Google mapping sits at lines 50–72. These tables define simple key renames—such as mapping the unified `language` field to `language_code` for Google—while the surrounding methods handle structural transformations like building `timestamp_granularities` arrays or converting boolean flags into provider-specific enums.

## How the AISuite Mapping Flow Works

When a request leaves your application, the parameter translation happens in four discrete stages.

1. **Create `TranscriptionOptions`** — Instantiate the dataclass with the desired settings, leaving any irrelevant fields unset.

2. **Invoke the provider mapper** — Call `ParameterMapper.map_to_<provider>(options)` to target a specific backend.

3. **Translate and filter** — The mapper iterates over the provider's mapping table, copies only non-`None` values, applies specialized logic (for example, expanding `"en"` into `"en-US"` for Google or collapsing timestamp preferences into Deepgram's `utterances` and `paragraphs` flags), and prunes empty keys.

4. **Merge custom overrides** — The private `_apply_custom_parameters` helper merges any user-supplied `custom_parameters` directly into the final payload, allowing raw provider arguments to pass through untouched.

The resulting dictionary is forwarded straight to the provider's client—such as the OpenAI Whisper client, the Deepgram SDK, or Google Speech-to-Text—without further manipulation. Provider implementations like [`aisuite/providers/xai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/xai_provider.py) and [`aisuite/providers/watsonx_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/watsonx_provider.py) consume these mapped dictionaries directly.

## Code Examples: From Unified Options to Provider Payloads

The following snippets demonstrate how identical `TranscriptionOptions` instances produce different payloads for each backend.

### Building a Unified Options Object

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

options = TranscriptionOptions(
    language="en",
    audio_format="wav",
    sample_rate=16000,
    include_word_timestamps=True,
    enable_speaker_diarization=True,
    max_speakers=2,
    custom_parameters={"model": "whisper-1"}  # Provider-specific override

)

```

### Mapping to OpenAI Whisper

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

openai_params = ParameterMapper.map_to_openai(options)

# openai_params now contains:

# {

#   "language": "en",

#   "response_format": None,

#   "temperature": None,

#   "prompt": None,

#   "stream": None,

#   "timestamp_granularities": ["word"],

#   "model": "whisper-1"

# }

```

Notice how `include_word_timestamps=True` is transformed into the `timestamp_granularities` list expected by OpenAI's Whisper API.

### Mapping to Deepgram

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

# deepgram_params includes Deepgram-specific keys such as:

# {

#   "language": "en",

#   "diarize": True,

#   "utterances": True,

#   "sample_rate": 16000,

#   "channels": None,

#   "model": "whisper-1"

# }

```

Here, speaker diarization and word-level timestamps are translated into Deepgram's native `diarize` and `utterances` flags.

### Mapping to Google Speech-to-Text

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

# google_params now holds:

# {

#   "language_code": "en-US",

#   "sample_rate_hertz": 16000,

#   "encoding": "LINEAR16",

#   "enable_speaker_diarization": True,

#   "diarization_speaker_count": 2,

#   "enable_word_time_offsets": True,

#   "model": "whisper-1"

# }

```

The mapper automatically converts the generic `language` value into Google's `language_code` and bumps `"en"` to `"en-US"` while renaming `sample_rate` to `sample_rate_hertz`.

## Extending Mappings with Custom Parameters

Even though the mapper covers common fields, AISuite does not lock you into predefined translations. The `_apply_custom_parameters` helper allows arbitrary key-value pairs supplied through `TranscriptionOptions.custom_parameters` to override or augment the generated payload. Because these values are merged last, they take precedence over mapped defaults, giving developers an escape hatch for provider-specific beta features or niche configuration flags.

## Summary

- **Unified schema**: `TranscriptionOptions` in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py) defines a single, provider-agnostic configuration object.
- **Centralized translation**: `ParameterMapper` in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) converts that object into provider-specific payloads via static mapping tables.
- **Clean payloads**: The mapper strips `None` values, so only explicitly set parameters reach the API.
- **Override support**: The `_apply_custom_parameters` helper merges raw provider arguments from `custom_parameters` without requiring framework changes.

## Frequently Asked Questions

### What is TranscriptionOptions used for in AISuite?

`TranscriptionOptions` is a dataclass defined in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py) that acts as the single source of truth for all transcription-related settings. It collects provider-agnostic fields such as language, audio format, and diarization preferences so that developers can configure one object regardless of which ASR backend they target.

### How does ParameterMapper handle different field names across providers?

`ParameterMapper` maintains a separate dictionary for each provider inside [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py). These dictionaries map unified option names to the exact strings the provider expects—for example, translating the generic `language` key into `language_code` for Google Speech-to-Text—while dedicated class methods handle structural changes like turning booleans into arrays or renaming nested keys.

### Can I send provider-specific parameters that are not in TranscriptionOptions?

Yes. Any additional arguments placed in the `custom_parameters` dictionary of a `TranscriptionOptions` instance are merged into the final payload by the private `_apply_custom_parameters` helper. This lets you pass raw, provider-specific flags straight through the mapper without modifying the core library code.

### Where are the actual mapping tables located in the source code?

The mapping tables and conversion logic reside in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py). According to the source, the OpenAI mapping is found at lines 15–23, the Deepgram mapping at lines 25–45, and the Google mapping at lines 50–72. The unified schema itself is defined earlier in the same repository at [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py), lines 197–254.