The provider system abstracts LLM API calls behind a unified interface. It supports multiple providers (OpenAI, Anthropic, Gemini, Ollama, and OpenAI-compatible services), automatic model discovery, capability-based routing, and usage tracking.
14
15
**Key components:**
16
17
- **`BaseProvider`** -- abstract interface that all providers implement
18
- **`ProviderRegistry`** -- global registry mapping provider names to classes
19
- **`ProviderManager`** -- high-level router that picks the best provider for each task
20
- **`discover_available_models()`** -- scans all configured providers for available models
21
22
---
23
24
## BaseProvider (ABC)
25
26
```python
27
from video_processor.providers.base import BaseProvider
28
```
29
30
Abstract base class that all provider implementations must subclass. Defines the four core capabilities: chat, vision, audio transcription, and model listing.
31
32
**Class attribute:**
33
34
| Attribute | Type | Description |
35
|---|---|---|
36
| `provider_name` | `str` | Identifier for this provider (e.g., `"openai"`, `"anthropic"`) |
from video_processor.providers.base import ProviderRegistry
153
```
154
155
Class-level registry for provider classes. Providers register themselves with metadata on import. This registry is used internally by `ProviderManager` but can also be used directly for introspection.
156
157
### register()
158
159
```python
160
@classmethod
161
def register(
162
cls,
163
name: str,
164
provider_class: type,
165
env_var: str = "",
166
model_prefixes: Optional[List[str]] = None,
167
default_models: Optional[Dict[str, str]] = None,
168
) -> None
169
```
170
171
Register a provider class with its metadata. Called by each provider module at import time.
Return the default models dict for a provider, mapping capability names to model IDs.
209
210
### available()
211
212
```python
213
@classmethod
214
def available(cls) -> List[str]
215
```
216
217
Return names of providers whose required environment variable is set (or providers with no env var requirement, like Ollama).
218
219
### all_registered()
220
221
```python
222
@classmethod
223
def all_registered(cls) -> Dict[str, Dict]
224
```
225
226
Return all registered providers and their metadata dictionaries.
227
228
---
229
230
## OpenAICompatibleProvider
231
232
```python
233
from video_processor.providers.base import OpenAICompatibleProvider
234
```
235
236
Base class for providers using OpenAI-compatible APIs (Together, Fireworks, Cerebras, xAI, Azure). Implements `chat()`, `analyze_image()`, and `list_models()` using the OpenAI client library. `transcribe_audio()` raises `NotImplementedError` by default.
| `api_key` | `Optional[str]` | `None` | API key (falls back to `self.env_var` environment variable) |
247
| `base_url` | `Optional[str]` | `None` | API base URL (falls back to `self.base_url` class attribute) |
248
249
**Subclass attributes to override:**
250
251
| Attribute | Description |
252
|---|---|
253
| `provider_name` | Provider identifier string |
254
| `base_url` | Default API base URL |
255
| `env_var` | Environment variable name for the API key |
256
257
**Usage tracking:** After each `chat()` or `analyze_image()` call, the provider stores token counts in `self._last_usage` as `{"input_tokens": int, "output_tokens": int}`. This is consumed by `ProviderManager._track()`.
258
259
---
260
261
## ProviderManager
262
263
```python
264
from video_processor.providers.manager import ProviderManager
265
```
266
267
High-level router that selects the best available provider and model for each API call. Supports explicit model selection, forced provider, or automatic selection based on discovered capabilities.
268
269
### Constructor
270
271
```python
272
def __init__(
273
self,
274
vision_model: Optional[str] = None,
275
chat_model: Optional[str] = None,
276
transcription_model: Optional[str] = None,
277
provider: Optional[str] = None,
278
auto: bool = True,
279
)
280
```
281
282
| Parameter | Type | Default | Description |
283
|---|---|---|---|
284
| `vision_model` | `Optional[str]` | `None` | Override model for vision tasks (e.g., `"gpt-4o"`) |
285
| `chat_model` | `Optional[str]` | `None` | Override model for chat/LLM tasks |
286
| `transcription_model` | `Optional[str]` | `None` | Override model for transcription |
287
| `provider` | `Optional[str]` | `None` | Force all tasks to a single provider |
288
| `auto` | `bool` | `True` | If `True` and no model specified, pick the best available |
289
290
**Attributes:**
291
292
| Attribute | Type | Description |
293
|---|---|---|
294
| `usage` | `UsageTracker` | Tracks token counts and API costs across all calls |
295
296
### Auto-selection preferences
297
298
When `auto=True` and no explicit model is set, providers are tried in this order:
**Returns:** `dict` -- transcription result with `text`, `segments`, `duration`.
372
373
**Local Whisper:** If `transcription_model` is unset or starts with `"whisper-local"`, the manager tries local Whisper first. Use `"whisper-local:large"` to specify a model size.
374
375
### get_models_used()
376
377
```python
378
def get_models_used(self) -> dict[str, str]
379
```
380
381
Return a dict mapping capability to `"provider/model"` string for tracking purposes.
from video_processor.providers.manager import ProviderManager
393
394
# Auto-select best providers
395
pm = ProviderManager()
396
397
# Force everything through one provider
398
pm = ProviderManager(provider="openai")
399
400
# Explicit model selection
401
pm = ProviderManager(
402
vision_model="gpt-4o",
403
chat_model="claude-haiku-4-5-20251001",
404
transcription_model="whisper-local:large",
405
)
406
407
# Chat completion
408
response = pm.chat([
409
{"role": "user", "content": "Summarize this meeting transcript..."}
410
])
411
412
# Image analysis
413
with open("diagram.png", "rb") as f:
414
analysis = pm.analyze_image(f.read(), "Describe this architecture diagram")
415
416
# Transcription with speaker hints
417
result = pm.transcribe_audio(
418
"meeting.mp3",
419
language="en",
420
speaker_hints=["Alice", "Bob", "Charlie"],
421
)
422
423
# Check usage
424
print(pm.usage.summary())
425
```
426
427
---
428
429
## discover_available_models()
430
431
```python
432
from video_processor.providers.discovery import discover_available_models
433
```
434
435
```python
436
def discover_available_models(
437
api_keys: Optional[dict[str, str]] = None,
438
force_refresh: bool = False,
439
) -> list[ModelInfo]
440
```
441
442
Discover available models from all configured providers. For each provider with a valid API key, calls `list_models()` and returns a unified, sorted list.
443
444
**Parameters:**
445
446
| Parameter | Type | Default | Description |
447
|---|---|---|---|
448
| `api_keys` | `Optional[dict[str, str]]` | `None` | Override API keys (defaults to environment variables) |
449
| `force_refresh` | `bool` | `False` | Force re-discovery, ignoring the session cache |
450
451
**Returns:** `list[ModelInfo]` -- all discovered models, sorted by provider then model ID.
452
453
**Caching:** Results are cached for the session. Use `force_refresh=True` or `clear_discovery_cache()` to refresh.