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

> Learn how the Agent-Reach transcribe command routes between Groq and OpenAI providers using a smart fallback mechanism based on your configuration.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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` |

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 99-105) returns `["groq", "openai"]` for auto mode, ensuring Groq is attempted first.

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_transcribe.py), lines 22-26).

## Internal Routing Implementation

The actual routing between Groq and OpenAI occurs in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```python

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.