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

> Master ASR parameter mapping with aisuite. Seamlessly translate speech-to-text parameters across OpenAI, Deepgram, and Google using automated renaming and validation. Simplify your ASR integration.

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

---

**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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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.

```python
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`](https://github.com/andrewyng/aisuite/blob/main/deepgram/provider.ts) and [`openai/provider.ts`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/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`](https://github.com/andrewyng/aisuite/blob/main/tests/framework/test_asr_params.py) contains extensive code examples showing expected inputs and outputs for each supported provider and edge case.