How the Transcribe Command Routes Between Groq and OpenAI Whisper Providers

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, 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 (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 (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

# 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

# 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

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

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)

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 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 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 (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.

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