Parameter Mapping for ASR: Translating Speech-to-Text Parameters Across Providers in aisuite

aisuite normalizes ASR parameters across OpenAI, Deepgram, and Google through a centralized validation layer that automatically renames, transforms, and validates keys using provider-specific mapping tables.

Working with multiple speech-to-text providers traditionally forces developers to maintain separate parameter dictionaries for each API. The aisuite library eliminates this friction by implementing a unified parameter mapping system for ASR that translates OpenAI-style inputs into native formats for Deepgram, Google Cloud Speech-to-Text, and other back-ends. This architecture lives primarily in aisuite/framework/asr_params.py and handles the complexity of divergent naming conventions, value formats, and validation rules behind a single, provider-agnostic interface.

How aisuite Normalizes ASR Parameters

The parameter mapping system operates through three distinct stages orchestrated by the ParamValidator class. Each stage ensures that logical parameters like language or prompt arrive at the target provider in the exact structure and nomenclature required by its SDK.

Common Parameter Auto-Mapping

At the core of the translation layer is the COMMON_PARAMS dictionary defined in aisuite/framework/asr_params.py (lines 19-33). This table maps universal parameter names to their provider-specific equivalents. When you pass a standard OpenAI-style parameter dictionary, the validator automatically rewrites keys according to the target provider's schema.

Key translations include:

• language becomes language_code when routing to Google
• prompt becomes keywords for Deepgram (split into a list of strings)
• prompt becomes speech_contexts for Google (wrapped in a structured object with phrases and boost values)
• temperature and other OpenAI-native parameters pass through unchanged when the provider supports them directly

Provider-Specific Validation

After mapping common parameters, the validator checks every remaining key against the PROVIDER_PARAMS whitelist (lines 43-87). Each supported ASR provider maintains a defined set of valid parameters—such as Deepgram's punctuate, diarize, and sentiment flags. The validate_and_map method enforces these constraints based on the configured extra_param_mode:

• strict – Raises an error immediately when encountering unknown parameters
• warn – Logs a warning but proceeds with the request
• permissive – Forwards unknown keys unchanged to the provider (useful for testing beta features)

Value Transformations and Localization

Raw values often require structural reshaping beyond simple key renaming. The GOOGLE_LANGUAGE_MAP (lines 32-55) handles the expansion of two-letter ISO codes into full BCP-47 locales. For example, the input "es" automatically becomes "es-ES" when validated for Google Cloud Speech-to-Text.

Deepgram receives special handling for contextual prompts: the validator splits the prompt string into individual keywords, while Google receives the same data wrapped in a speech_contexts array containing phrase objects with optional boost scores.

Implementing Parameter Validation in Code

The ParamValidator class exposes a single entry point for all ASR parameter processing. Instantiate the validator with your preferred error handling mode, then call validate_and_map with the provider name and parameter dictionary.

from aisuite.framework.asr_params import ParamValidator

# Initialize with strict validation

validator = ParamValidator(extra_param_mode="strict")

# OpenAI: Parameters pass through natively

openai_params = validator.validate_and_map(
    "openai",
    {"language": "en", "prompt": "meeting minutes", "temperature": 0.7}
)

# Result: {'language': 'en', 'prompt': 'meeting minutes', 'temperature': 0.7}

# Deepgram: Common params converted, specific flags preserved

deepgram_params = validator.validate_and_map(
    "deepgram",
    {"language": "en", "prompt": "team sync", "punctuate": True}
)

# Result: {'language': 'en', 'keywords': ['team', 'sync'], 'punctuate': True}

# Google: Language expanded, prompt becomes speech_contexts

google_params = validator.validate_and_map(
    "google",
    {"language": "es", "prompt": "technical review", "enable_automatic_punctuation": True}
)

# Result: {

#     'language_code': 'es-ES',

#     'speech_contexts': [{'phrases': ['technical review']}],

#     'enable_automatic_punctuation': True

# }

For experimental workflows or newly released provider features not yet in the whitelist, instantiate the validator with extra_param_mode="permissive" to bypass key validation and forward parameters directly.

Architecture and Testing

The mapping logic is fully decoupled from provider-specific implementations. Consumer adapters located in aisuite/js/src/asr-providers/ (such as deepgram/provider.ts and openai/provider.ts) receive the validated, mapped dictionaries produced by ParamValidator.validate_and_map().

Comprehensive test coverage exists in tests/framework/test_asr_params.py, which validates edge cases including invalid language codes, malformed speech contexts, and behavior across all three extra_param_mode settings. The examples/asr_example.ipynb notebook demonstrates end-to-end transcription workflows using the normalized parameter interface.

Summary

• aisuite/framework/asr_params.py contains the complete parameter mapping implementation, including COMMON_PARAMS, PROVIDER_PARAMS, and GOOGLE_LANGUAGE_MAP.
• The ParamValidator class normalizes inputs through the validate_and_map method, handling key translation, value transformation, and strictness configuration.
• Three operational modes (strict, warn, permissive) control how the system handles unknown or non-standard parameters.
• Language codes automatically expand to full BCP-47 locales for Google Cloud, while prompts convert to keywords for Deepgram and speech contexts for Google.
• All mapping logic is verified by the unit test suite in tests/framework/test_asr_params.py.

Frequently Asked Questions

What ASR providers does aisuite support for parameter mapping?

The framework currently supports OpenAI (Whisper), Deepgram, Google Cloud Speech-to-Text, and Hugging Face. Each provider maintains a distinct parameter whitelist in PROVIDER_PARAMS that defines which keys are valid for that specific back-end.

How does aisuite handle language code differences between providers?

The validator uses GOOGLE_LANGUAGE_MAP to translate two-letter ISO codes (like "en" or "es") into full BCP-47 locale strings (like "en-US" or "es-ES") required by Google's API. OpenAI and Deepgram generally accept standard ISO codes without expansion.

What happens if I pass a parameter that isn't in the provider's whitelist?

Behavior depends on the extra_param_mode setting passed to ParamValidator. In strict mode, an exception is raised immediately. In warn mode, the system logs a warning but continues. In permissive mode, the unknown key is forwarded to the provider unchanged, allowing immediate use of new API features before official framework updates.

Where can I find examples of the parameter mapping in action?

The repository includes examples/asr_example.ipynb, an interactive notebook demonstrating real-world transcription workflows. Additionally, tests/framework/test_asr_params.py contains extensive code examples showing expected inputs and outputs for each supported provider and edge case.

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