You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Design Goal: Portable Code with Provider Flexibility
4
+
5
+
The ASR parameter system is designed around a core principle: **developers should write portable code that works across providers, while retaining the ability to use provider-specific features when needed**. This document explains the rationale behind our parameter classification and validation approach.
6
+
7
+
---
8
+
9
+
## Mandatory Parameters and Common Mappings
10
+
11
+
### The Foundation: Minimal Requirements
12
+
13
+
Every transcription needs just two things:
14
+
-**`model`**: Which model/provider to use
15
+
-**`file`**: What audio to transcribe
16
+
17
+
By keeping mandatory parameters minimal, we maximize compatibility and reduce the barrier to getting started.
18
+
19
+
### Common Parameters: Write Once, Run Anywhere
20
+
21
+
Beyond the basics, there are concepts that exist across providers but use different names or formats. We handle three common parameters that auto-map to each provider's native API:
22
+
23
+
**Example: Same code, different providers**
24
+
25
+
```python
26
+
# Works with OpenAI
27
+
result = client.audio.transcriptions.create(
28
+
model="openai:whisper-1",
29
+
file="meeting.mp3",
30
+
language="en",
31
+
prompt="discussion about API design"
32
+
)
33
+
34
+
# Exact same code works with Deepgram
35
+
result = client.audio.transcriptions.create(
36
+
model="deepgram:nova-2",
37
+
file="meeting.mp3",
38
+
language="en",
39
+
prompt="discussion about API design"
40
+
)
41
+
```
42
+
43
+
Behind the scenes:
44
+
-**`language`** passes through as `language` for both OpenAI and Deepgram, but expands to `language_code: "en-US"` for Google
45
+
-**`prompt`** passes as `prompt` to OpenAI, transforms to `keywords: ["discussion", "about", "API", "design"]` for Deepgram, and becomes `speech_contexts: [{"phrases": ["discussion about API design"]}]` for Google
46
+
-**`temperature`** passes through to OpenAI (which supports it) and is silently ignored by Deepgram and Google (which don't)
47
+
48
+
**Why auto-mapping?** Developers shouldn't need to remember that Google uses `language_code` while others use `language`, or that Deepgram expects a list of keywords. The framework handles these provider quirks transparently, letting you write portable code.
49
+
50
+
---
51
+
52
+
## Provider-Specific Features: Pass-Through for Power Users
53
+
54
+
Each provider has unique features that give them competitive advantages. We don't limit you to the "lowest common denominator" - if you need provider-specific functionality, it's available:
These provider-specific parameters pass through directly to the provider's SDK. The framework validates them based on your configured mode (see next section), but doesn't block access to unique features.
82
+
83
+
---
84
+
85
+
## Progressive Validation: Safety When You Need It
86
+
87
+
The validation system supports three modes to match different development stages:
88
+
89
+
### Development Mode: `"warn"` (Default)
90
+
```python
91
+
client = Client(extra_param_mode="warn")
92
+
```
93
+
Unknown parameters trigger warnings but continue execution. Perfect for exploration and prototyping. You see *"OpenAI doesn't support 'punctuate'"* but your code keeps running.
94
+
95
+
### Strict Mode: `"strict"`
96
+
```python
97
+
client = Client(extra_param_mode="strict")
98
+
```
99
+
Unknown parameters raise errors immediately. Use in production to catch typos, configuration mistakes, or provider API changes early. Ensures no silent failures.
100
+
101
+
### Permissive Mode: `"permissive"`
102
+
```python
103
+
client = Client(extra_param_mode="permissive")
104
+
```
105
+
All parameters pass through without validation. Use for beta features, experimental parameters, or when providers add new capabilities faster than framework updates.
106
+
107
+
**Progressive workflow:**
108
+
1.**Develop** with `warn` - explore freely, see warnings
109
+
2.**Refactor** - fix warnings to make code portable
110
+
3.**Deploy** with `strict` - ensure production safety
111
+
112
+
---
113
+
114
+
## Developer Experience Benefits
115
+
116
+
### 1. Write Portable Code Naturally
117
+
The same parameter names work across providers. Switch from OpenAI to Deepgram by changing one word: the model identifier.
118
+
119
+
### 2. Progressive Enhancement
120
+
Start with portable common parameters. Add provider-specific features only where you need them. Your core logic remains portable even when using advanced features for specific providers.
121
+
122
+
### 3. Zero Framework Lock-in
123
+
Parameter names come directly from provider APIs, not framework abstractions. If you need to remove the framework, you already know the native API - the names are identical.
124
+
125
+
### 4. Validation That Adapts to You
126
+
Choose your safety level based on context. Strict for production, warn for development, permissive for bleeding-edge features. The framework supports your workflow rather than constraining it.
127
+
128
+
### 5. No Documentation Friction
129
+
Copy parameters from provider docs directly. No need to learn our abstraction layer or figure out mappings - we handle the common cases, you use native names for everything else.
130
+
131
+
---
132
+
133
+
## Alternative Design Considered
134
+
135
+
We considered creating a unified options object (`TranscriptionOptions`) that explicitly defines all parameters with framework-specific names. We chose pass-through instead because:
136
+
137
+
1.**Provider APIs evolve faster than frameworks** - New parameters appear frequently. Pass-through lets developers use them immediately (in permissive mode) without waiting for framework updates.
138
+
139
+
2.**Provider features don't map cleanly** - Deepgram's sentiment analysis, Google's complex speech contexts, OpenAI's timestamp granularities - each is unique. A unified object means either losing functionality or creating complex provider-specific abstractions.
140
+
141
+
3.**Direct API access reduces friction** - Developers already know their provider's API from official docs. They can use parameter names directly rather than learning another abstraction layer.
142
+
143
+
The pass-through approach with progressive validation provides the best of both worlds: portability for common cases, power for advanced features, and safety when you need it.
144
+
145
+
---
146
+
147
+
## Design Principles Summary
148
+
149
+
-**Mandatory Minimal**: Only `model` and `file` required
-**Provider-Specific Pass-Through**: Unique features remain accessible
152
+
-**Progressive Validation**: Three modes for different development stages
153
+
-**Zero Abstraction Tax**: Use provider APIs directly with optional safety nets
154
+
155
+
This design prioritizes developer experience through portability without sacrificing power, validation without blocking experimentation, and simplicity without limiting functionality.
0 commit comments