How AISuite Manages Provider-Specific Parameters Through Parameter Mapping

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 (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 (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, 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 and 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

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

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

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

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 defines a single, provider-agnostic configuration object.
• Centralized translation: ParameterMapper in 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 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. 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. 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, lines 197–254.

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