How the Agent-Reach Transcribe Command Routes Between Groq and OpenAI Providers

The transcribe command routes between Groq and OpenAI via an automatic fallback mechanism that tries Groq first, then OpenAI, based on the --provider flag and available API keys configured in ~/.agent-reach/config.yaml.

Agent-Reach provides a unified transcribe command that converts YouTube links or local audio files into text using OpenAI-compatible Whisper APIs. The command supports both Groq and OpenAI as backend providers, implementing intelligent routing logic that handles provider selection, automatic fallback, and configuration validation. This article explains exactly how the transcribe command routes between Groq and OpenAI providers based on the source code implementation.

Provider Configuration and API Endpoints

The system defines provider-specific endpoints, models, and configuration keys in agent_reach/transcribe.py (lines 30-41). Each provider requires a distinct API key stored in the user's configuration file.

Provider	Endpoint	Model	Config Key
Groq	https://api.groq.com/openai/v1/audio/transcriptions	whisper-large-v3	groq_api_key
OpenAI	https://api.openai.com/v1/audio/transcriptions	whisper-1	openai_api_key

# agent_reach/transcribe.py (lines 30-41)

PROVIDERS = {
    "groq": {
        "endpoint": "https://api.groq.com/openai/v1/audio/transcriptions",
        "model": "whisper-large-v3",
        "key_field": "groq_api_key",
    },
    "openai": {
        "endpoint": "https://api.openai.com/v1/audio/transcriptions",
        "model": "whisper-1",
        "key_field": "openai_api_key",
    },
}

How Provider Selection Works

The routing logic supports three distinct selection modes controlled by the --provider argument parsed in agent_reach/cli.py within the _cmd_transcribe function (lines 1113-1122).

Explicit Provider Selection

Users can force a specific backend by passing --provider groq or --provider openai. When explicitly specified, the command attempts only that provider and fails immediately if the corresponding API key is missing or the request errors.

Automatic Fallback Logic

The default mode --provider auto (or omitting the flag) implements a priority-based fallback. The _provider_order() function in agent_reach/transcribe.py (lines 99-105) returns ["groq", "openai"] for auto mode, ensuring Groq is attempted first.

# agent_reach/transcribe.py (lines 99-105)

def _provider_order(provider: str) -> List[str]:
    if provider == "auto":
        return ["groq", "openai"]
    if provider in PROVIDERS:
        return [provider]
    raise TranscribeError(f"Unknown provider: {provider}")

Configuration-Driven Validation

Before attempting any provider, the system validates API key presence via Config().get() in agent_reach/config.py. Providers without configured keys are skipped entirely. If no valid keys exist for any requested provider, the command raises NoProviderConfigured (tested in tests/test_transcribe.py, lines 22-26).

Internal Routing Implementation

The actual routing between Groq and OpenAI occurs in agent_reach/transcribe.py through the _transcribe_with_fallback() function (lines 49-61). This function receives the ordered provider list from _provider_order() and iterates through it until a successful transcription occurs.

# agent_reach/transcribe.py (lines 49-61)

def _transcribe_with_fallback(chunk, order, config):
    last_err = None
    for p in order:
        if not _provider_key(p, config):
            continue        # skip unconfigured providers

        try:
            return transcribe_chunk(chunk, p, config=config)
        except TranscribeError as e:
            last_err = e
    raise TranscribeError(f"All providers failed: {last_err}")

The transcribe_chunk() function handles the actual HTTP POST to the provider's endpoint, reading the appropriate API key from the config and formatting the request according to the PROVIDERS specification.

Usage Examples

Configure your API keys before running transcription commands:

# Configure Groq API key

agent-reach configure groq-key YOUR_GROQ_API_KEY

# Configure OpenAI API key

agent-reach configure openai-key YOUR_OPENAI_API_KEY

Run transcription with specific routing strategies:

# Explicitly use Groq only

agent-reach transcribe https://youtu.be/abc123 --provider groq

# Explicitly use OpenAI only

agent-reach transcribe ./audio.m4a --provider openai

# Automatic fallback (Groq first, then OpenAI)

agent-reach transcribe https://youtu.be/abc123

# Save output to file

agent-reach transcribe audio.mp3 -o transcript.txt

When using automatic mode, if Groq returns an HTTP error (such as 429 rate limiting), the command automatically retries with OpenAI without user intervention.

Summary

• Provider definitions are hardcoded in agent_reach/transcribe.py with specific endpoints, models, and configuration keys for Groq and OpenAI.
• Routing logic is controlled by the --provider flag, supporting explicit selection (groq or openai) or automatic fallback (auto).
• Auto mode prioritizes Groq first, then falls back to OpenAI if the initial request fails.
• Configuration validation occurs before any API calls, skipping providers lacking API keys in ~/.agent-reach/config.yaml.
• Fallback implementation uses _transcribe_with_fallback() to iterate through the provider order until transcription succeeds or all options are exhausted.

Frequently Asked Questions

What is the default provider for the transcribe command?

The default value is auto. When omitted or set to auto, the command attempts to use Groq first, then automatically falls back to OpenAI if the Groq request fails or is unconfigured.

How do I configure API keys for Groq and OpenAI?

Use the agent-reach configure command to store credentials persistently. Run agent-reach configure groq-key YOUR_KEY and agent-reach configure openai-key YOUR_KEY. These values are saved to ~/.agent-reach/config.yaml and retrieved at runtime via Config().get() in agent_reach/config.py.

What happens if both providers fail?

If all configured providers in the routing order fail to return a successful transcription, the _transcribe_with_fallback() function raises a TranscribeError. The CLI catches this exception in _cmd_transcribe (lines 1113-1122), prints an error message, and exits with status code 1.

Which Whisper model does each provider use?

According to the PROVIDERS dictionary in agent_reach/transcribe.py, Groq uses the whisper-large-v3 model while OpenAI uses the whisper-1 model. These model assignments are hardcoded and cannot be overridden via command-line arguments.

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