# How the Transcribe Command Routes Between Groq and OpenAI Whisper Providers

> Discover how the transcribe command routes audio to Groq then OpenAI Whisper using a provider catalog and fallback logic for reliable transcription.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-16

---

**The `transcribe` command dynamically routes audio transcription requests to Groq first, then falls back to OpenAI Whisper, using a provider catalog and iterative fallback logic to ensure high availability while validating API keys before processing.**

The Agent-Reach repository implements a sophisticated audio transcription pipeline that abstracts the differences between Groq and OpenAI's Whisper-compatible APIs. By leveraging a static provider configuration and intelligent routing logic in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), the system delivers a seamless experience that prefers cost-effective Groq endpoints while maintaining reliability through automatic fallback handling.

## Provider Catalog and Configuration

At the core of the routing system lies a static **provider catalog** that defines the available transcription endpoints. In [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 30-40), the `PROVIDERS` dictionary maps vendor names to their respective API endpoints, model identifiers, and configuration keys:

- **Groq**: Configured with its Whisper-compatible endpoint and associated API key storage
- **OpenAI**: Mapped to the official Whisper API endpoint with its distinct key configuration

This catalog serves as the single source of truth for all provider-specific metadata, ensuring that routing decisions remain consistent throughout the transcription lifecycle.

## Dynamic Provider Selection and Routing Order

The **`_provider_order`** function (lines 99-104) transforms user input into an ordered execution list. When users specify the `provider` argument as `auto` (the default), the system returns `["groq", "openai"]`, establishing Groq as the primary target with OpenAI as the failover.

Users may bypass automatic routing by explicitly setting `--provider groq` or `--provider openai`, which constrains the system to a single vendor and eliminates fallback attempts. This deterministic mode is useful when compliance or cost constraints mandate a specific provider.

## Pre-Validation and Error Handling

Before downloading or processing audio, the system validates API key availability. The validation logic (lines 22-26) inspects the `Config` object for the presence of tokens corresponding to the selected providers. If neither Groq nor OpenAI keys are configured when needed, the function raises **`NoProviderConfigured`** immediately, preventing wasted computational resources on audiofetching and compression.

This early-exit pattern ensures that transient network errors or missing credentials surface before any heavy I/O operations begin.

## Chunk-Wise Processing and Fallback Strategy

Large audio files undergo a multi-stage pipeline before API transmission:

1. **Fetching**: Remote URLs are retrieved via **yt-dlp**
2. **Compression**: Local files are transcoded to Whisper-friendly formats using **ffmpeg**
3. **Chunking**: Files exceeding the 24 MiB Whisper limit are split into ≤10-minute segments (lines 77-91, 101-112)

The **`_transcribe_with_fallback`** helper (lines 49-61, 63-70) manages the actual API routing. This function iterates over the provider list established by `_provider_order`, skipping any vendors for which API keys are missing. It delegates each chunk to `transcribe_chunk` and returns the first successful response. If all providers fail, the last encountered exception is re-raised as a **`TranscribeError`**.

## Direct API Communication

Individual chunk transmission occurs in **`transcribe_chunk`** (lines 71-89). This function constructs a multipart POST request containing:

- The audio file blob
- The selected Whisper model name (from the `PROVIDERS` catalog)
- An `Authorization: Bearer <API-key>` header

Requests execute with a default 120-second timeout per chunk. HTTP errors and network failures are captured and wrapped in `TranscribeError`, providing a unified exception interface regardless of which provider generated the failure.

## Result Assembly and CLI Integration

Once all chunks complete successfully, the **`transcribe`** function assembles the final output (lines 42-46). Individual segment transcripts are stripped of whitespace, filtered to remove empty strings, and concatenated with newline separators to preserve paragraph boundaries.

The **CLI entry point** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1113-1120) exposes this functionality through the `agent-reach transcribe` command, forwarding user arguments to the library function and handling text output or file writing.

## Practical Usage Examples

### CLI Auto-Routing with Fallback

```bash

# Transcribe a YouTube video; Groq is tried first, OpenAI serves as backup

agent-reach transcribe "https://www.youtube.com/watch?v=example"

```

### Force Specific Provider

```bash

# Use Groq exclusively (fails immediately if Groq key is missing)

agent-reach transcribe "https://example.com/podcast.mp3" --provider groq

```

### Programmatic Usage with Error Handling

```python
from agent_reach.transcribe import transcribe, TranscribeError

try:
    # Auto provider order (Groq → OpenAI)

    text = transcribe("https://youtu.be/example")
    print(text)
except TranscribeError as exc:
    print(f"Transcription failed: {exc}")

```

### Custom Output Directory

```python
from pathlib import Path
from agent_reach.transcribe import transcribe

out_dir = Path("/tmp/my_transcribe")
result = transcribe("local_file.m4a", out_dir=out_dir)
print(result)

```

### Direct Provider Access (Bypassing Fallback)

```python
from agent_reach.transcribe import transcribe_chunk, Config

cfg = Config()                # Loads API keys from config file / env

chunk_path = Path("chunk_001.m4a")
groq_text = transcribe_chunk(chunk_path, "groq", config=cfg)
print(groq_text)

```

## Summary

- **Provider catalog**: The `PROVIDERS` dictionary in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) defines Groq and OpenAI endpoints, models, and configuration keys.
- **Routing logic**: The `_provider_order` function establishes `["groq", "openai"]` as the default execution sequence when `auto` is selected.
- **Early validation**: API keys are verified before audio processing to prevent wasted compute, raising `NoProviderConfigured` if credentials are missing.
- **Chunked fallback**: The `_transcribe_with_fallback` function iterates through providers, skipping unavailable keys and returning the first successful transcription.
- **Error encapsulation**: Network and HTTP errors are normalized into `TranscribeError` regardless of which provider generated them.
- **CLI integration**: The command-line interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) wraps the library function for shell-based workflows.

## Frequently Asked Questions

### Which provider does the transcribe command use by default?

By default, the transcribe command uses **`auto`** routing, which attempts **Groq** first, then falls back to **OpenAI** if Groq fails or is not configured. This prioritization is hardcoded in the `_provider_order` function within [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 99-104).

### How does the system handle audio files larger than 24 MiB?

Files exceeding the Whisper API limit are automatically split into chunks of approximately 10 minutes or less. The system uses **ffmpeg** for compression and segmentation (lines 77-91), then processes each chunk sequentially through the provider fallback chain before concatenating the results with newline separators (lines 42-46).

### What happens if both Groq and OpenAI API keys are missing?

If the user selects `auto` mode or requests a provider whose key is not present in the `Config` object, the system raises a **`NoProviderConfigured`** exception before downloading or processing any audio (lines 22-26). This early validation prevents unnecessary network activity and processing overhead.

### Can I force the transcribe command to use only OpenAI and skip Groq entirely?

Yes. Pass the `--provider openai` flag to the CLI command, or specify `provider="openai"` when calling the `transcribe` function programmatically. This constrains the `_provider_order` to return only `["openai"]`, effectively disabling the Groq fallback and failing fast if the OpenAI key is unavailable.