Handling Provider-Specific Parameters with extra_param_mode in aisuite

aisuite uses the extra_param_mode parameter to control how unknown transcription arguments are handled, offering three behaviors: "strict" (raise an error), "warn" (emit a warning but continue), or "permissive" (silently forward the parameters).

The aisuite library normalizes audio transcription requests across multiple AI providers through a centralized validation system. When you call client.audio.transcriptions.create(), your arguments pass through the ParamValidator class in aisuite/framework/asr_params.py before reaching the provider's API. This validator automatically maps common parameters to provider-specific names and uses extra_param_mode to govern how it treats unrecognized keys.

How aisuite Categorizes Transcription Parameters

The validation logic in aisuite/framework/asr_params.py organizes incoming parameters into three distinct groups. This classification determines whether a parameter is transformed, passed through directly, or flagged as unknown.

Common Parameters and Automatic Mapping

Common parameters follow OpenAI's naming convention (e.g., language, prompt, temperature) and are automatically translated to provider-specific equivalents. The COMMON_PARAMS table defined at lines 19-38 maps these standardized names to each provider's internal schema.

For example, when you pass language="en" to Google, the validator's _transform_value method (lines 58-61) converts it to language_code="en-US". This ensures cross-provider compatibility without requiring you to memorize different naming conventions for each service.

Provider-Specific Parameter Whitelists

Each provider defines a whitelist of supported arguments in the PROVIDER_PARAMS dictionary (lines 43-129). Provider-specific parameters appearing in this set bypass the common mapping logic and pass directly to the API unchanged.

If you use Deepgram-specific features like punctuate=True or diarize=True, the validator recognizes these as valid provider parameters and forwards them without transformation or warnings.

Controlling Unknown Parameters with extra_param_mode

When the validator encounters a parameter that exists in neither the common set nor the provider whitelist, it triggers the extra_param_mode logic implemented in the _handle_unknown method (lines 74-97). You set this mode when constructing a Client instance, and it propagates to the validator via self.param_validator = ParamValidator(extra_param_mode).

The three supported modes behave as follows:

• "strict" – Raises a ValueError immediately with a descriptive message (lines 90-92). Use this in production environments to catch typos or unsupported arguments before they reach the provider.
• "warn" – Emits a UserWarning but continues execution (lines 93-96). This is the default behavior, providing visibility into potential issues without breaking the request.
• "permissive" – Silently passes unknown keys through to the provider (lines 33-36). Use this when testing beta features or provider-specific arguments not yet whitelisted in aisuite.

Configuring Strict Mode for Parameter Validation

In strict mode, any unrecognized parameter triggers an exception. This is enforced in aisuite/client.py at line 528 where the validator is invoked.

from aisuite import Client

# Initialize client with strict validation

client = Client(
    provider_configs={"openai": {"api_key": "sk-test"}},
    extra_param_mode="strict",
)

# This raises ValueError because 'foobar' is not a recognized parameter

client.audio.transcriptions.create(
    model="openai:whisper-1",
    file=open("sample.wav", "rb"),
    language="en",
    foobar=True,  # Unknown parameter triggers exception

)

Using Warn Mode to Surface Parameter Issues

Warn mode allows the request to proceed while alerting you to potential problems. The test suite verifies this behavior in tests/client/test_client.py (lines 124-152).

import warnings
from aisuite import Client

client = Client(extra_param_mode="warn")

# Capture the warning but still get results

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    result = client.audio.transcriptions.create(
        model="openai:whisper-1",
        file=open("sample.wav", "rb"),
        language="en",
        foobar=True,  # Emits warning but request succeeds

    )
    

# w[-1] contains the UserWarning about 'foobar'

Forwarding Experimental Parameters with Permissive Mode

Permissive mode bypasses validation entirely for unknown keys, forwarding them directly to the provider. This is useful for accessing beta features or provider-specific extensions not yet supported by the common interface.

from aisuite import Client

client = Client(extra_param_mode="permissive")

# Unknown parameters are forwarded verbatim to the provider

result = client.audio.transcriptions.create(
    model="openai:whisper-1",
    file=open("sample.wav", "rb"),
    language="en",
    experimental_feature=True,  # Silently passed through

)

Passing Provider-Specific Arguments Safely

Provider-specific parameters are not treated as "unknown" when they appear in the whitelist. According to the test test_provider_specific_params_passthrough (lines 221-246 in tests/client/test_client.py), these arguments flow directly to the provider without triggering extra_param_mode logic.

from aisuite import Client

# Deepgram-specific parameters pass through regardless of extra_param_mode

client = Client(provider_configs={"deepgram": {"api_key": "dg-test"}})

result = client.audio.transcriptions.create(
    model="deepgram:nova-2",
    file=open("sample.wav", "rb"),
    punctuate=True,  # Deepgram-specific, validated against PROVIDER_PARAMS

    diarize=True,    # Also Deepgram-specific

)

Summary

• Parameter validation in aisuite occurs in the ParamValidator class (aisuite/framework/asr_params.py), which distinguishes between common parameters, provider-specific whitelisted parameters, and unknown parameters.
• extra_param_mode controls how unknown parameters are handled, with options for "strict" (raise ValueError), "warn" (emit UserWarning), or "permissive" (silent forwarding).
• Common parameters are automatically mapped to provider-specific names using the COMMON_PARAMS table (lines 19-38), while provider-specific parameters listed in PROVIDER_PARAMS (lines 43-129) pass through unchanged.
• The validation is triggered at line 528 of aisuite/client.py, and behaviors are verified in tests/client/test_client.py and tests/framework/test_asr_params.py.

Frequently Asked Questions

What happens if I pass a misspelled parameter to aisuite?

If you pass a parameter like temperatur=0.5 instead of temperature, the validator treats it as an unknown parameter. Depending on your extra_param_mode, it will either raise a ValueError (strict), emit a warning but continue (warn), or forward it to the provider (permissive). The default mode is "warn".

Can I use provider-specific features not listed in the aisuite documentation?

Yes. If the feature is listed in the provider's PROVIDER_PARAMS whitelist (lines 43-129 of aisuite/framework/asr_params.py), you can use it directly. If it is a brand-new or experimental parameter not yet whitelisted, set extra_param_mode="permissive" to forward it directly to the provider's API without validation.

Where is the extra_param_mode logic implemented in the source code?

The logic is implemented in the _handle_unknown method of the ParamValidator class, located at lines 74-97 of aisuite/framework/asr_params.py. The mode is set when instantiating a Client and stored in the validator instance, which is then called at line 528 of aisuite/client.py during transcription request processing.

Does strict mode reject all parameters not in the OpenAI format?

No. Strict mode only rejects parameters that are neither in the COMMON_PARAMS mapping nor the provider's PROVIDER_PARAMS whitelist. Provider-specific parameters like Deepgram's punctuate or diarize are always allowed because they are explicitly whitelisted, regardless of whether they follow OpenAI's naming convention.

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