How aisuite Handles Parameter Mapping Across Different LLM Providers

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, 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. 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 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:

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

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

deepgram_params = ParameterMapper.map_to_deepgram(opts)

# Result:

# {

#     "language": "en",

#     "punctuate": True,

#     "utterances": True  # derived from timestamp_granularities

# }

Mapping to Google Speech-to-Text

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:

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, aisuite/providers/deepgram_provider.py, and 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 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. 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.

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