Agent Reach Transcribe Command: Whisper with Groq and OpenAI Fallback

Agent Reach's transcribe command automatically routes audio and video transcription requests to Groq's free whisper-large-v3 model, falling back to OpenAI's whisper-1 when Groq fails, while handling large files through intelligent chunking and SSRF-protected downloads.

Agent Reach is a Python-based CLI tool that provides AI agents with unified access to internet platforms. The transcribe command leverages Whisper-compatible APIs to convert audio and video content into text, implementing a robust Groq to OpenAI fallback mechanism. This architecture ensures reliable transcription even when primary rate limits or service interruptions occur.

How the Transcribe Command Works

The transcription pipeline is orchestrated across several modules with clear separation of concerns between CLI parsing, provider selection, and media processing.

CLI Entry Point and Provider Selection

Command-line arguments are parsed in agent_reach/cli.py by the _cmd_transcribe function, which forwards user inputs to the transcription engine. Users can specify --provider auto|groq|openai to control backend selection.

When provider="auto" is used (the default), the _provider_order function in agent_reach/transcribe.py expands this to ["groq", "openai"], establishing the fallback sequence. The _transcribe_with_fallback method iterates through this list until transcription succeeds or all providers are exhausted.

Provider Configuration and API Models

Provider definitions are centralized in the PROVIDERS dictionary at the top of agent_reach/transcribe.py. This configuration maps:

• Groq: Uses whisper-large-v3 via Groq's fast inference endpoint
• OpenAI: Uses whisper-1 as the secondary option

The actual HTTP requests occur in transcribe_chunk, which uses requests.post with the appropriate endpoint, model name, and bearer token retrieved from the configuration.

Secure Media Processing Pipeline

The pipeline handles both local files and remote URLs through distinct phases:

1. Safety Validation: The _assert_safe_public_url function prevents SSRF attacks by validating that URLs are public-only before download.
2. Download: For remote sources, download_audio utilizes yt-dlp to fetch media after safety checks pass.
3. Compression: compress_audio re-encodes media to mono 16 kHz, 32 kbps m4a to ensure the final size fits Whisper's 25 MiB limit.
4. Chunking: Files exceeding SIZE_LIMIT_BYTES (24 MiB) are split into ≤10-minute segments via ffmpeg to comply with API constraints.

Configuration and Error Handling

API Key Management

Credentials are retrieved from ~/.agent-reach/config.yaml through the Config.get method in agent_reach/config.py. The system validates that at least one provider key exists; otherwise, it raises NoProviderConfigured.

Exception Hierarchy

The module defines granular exceptions near the top of agent_reach/transcribe.py to provide clear failure modes:

• TranscribeError: Base exception for transcription failures
• MissingDependency: When yt-dlp or ffmpeg are not installed
• NoProviderConfigured: When no API keys are present in the config file

Usage Examples

Basic CLI Transcription with Automatic Fallback

agent-reach transcribe "https://youtu.be/dQw4w9WgXcQ"

This command downloads the YouTube video, compresses it, splits it if necessary, contacts Groq first, and automatically falls back to OpenAI if Groq returns an error. The transcript prints to stdout.

Explicit Provider Selection

# Force OpenAI only when Groq quota is exhausted

agent-reach transcribe "https://example.com/podcast.mp3" --provider openai -o transcript.txt

The transcript is written to transcript.txt.

Python Library Integration

from agent_reach.transcribe import transcribe, TranscribeError

try:
    text = transcribe(
        "https://v.redd.it/abcd1234",      # any public media URL

        provider="auto",                   # default – Groq → OpenAI fallback

    )
    print(text)
except TranscribeError as exc:
    print(f"Transcription failed: {exc}")

Custom Chunk Processing (Advanced)

from pathlib import Path
from agent_reach.transcribe import (
    download_audio,
    compress_audio,
    chunk_audio,
    transcribe_chunk,
)

src = download_audio("https://example.com/long-audio.mp3", Path("/tmp"))
compressed = compress_audio(src, Path("/tmp"))
chunks = chunk_audio(compressed, Path("/tmp"), segment_seconds=300)  # 5‑min chunks

texts = [transcribe_chunk(c, "groq") for c in chunks]
full_transcript = "\n".join(texts)
print(full_transcript)

Summary

• Agent Reach provides a transcribe command with automatic Groq to OpenAI fallback for Whisper transcription, preferring whisper-large-v3 over whisper-1
• The implementation in agent_reach/transcribe.py handles media download via yt-dlp, compression, and intelligent chunking for files exceeding 24 MiB
• Security is enforced through _assert_safe_public_url to prevent SSRF attacks before downloading remote content
• Supports both CLI usage via _cmd_transcribe in agent_reach/cli.py and direct Python library calls with granular exception handling
• Processes large files by splitting into ≤10-minute chunks using ffmpeg to comply with API size limits

Frequently Asked Questions

What is the default provider order for Agent Reach's transcribe command?

The default order prioritizes Groq using the whisper-large-v3 model, then falls back to OpenAI's whisper-1 when Groq fails. This is determined by the _provider_order function in agent_reach/transcribe.py, which expands the auto setting to ["groq", "openai"] and guides the _transcribe_with_fallback logic.

How does Agent Reach handle large audio files that exceed API size limits?

Files exceeding SIZE_LIMIT_BYTES (24 MiB) are automatically compressed to mono 16 kHz, 32 kbps m4a and split into ≤10-minute chunks using ffmpeg. Each chunk is transcribed individually by transcribe_chunk and concatenated with newline separators to form the complete transcript.

Where does Agent Reach store API keys for Groq and OpenAI?

API keys are read from the user's ~/.agent-reach/config.yaml file through the Config.get method in agent_reach/config.py. If neither provider is configured, the system raises a NoProviderConfigured exception before attempting any transcription.

What security measures prevent malicious URL attacks when transcribing remote content?

The _assert_safe_public_url function in agent_reach/transcribe.py validates that supplied URLs are public-only before the download_audio function invokes yt-dlp. This prevents Server-Side Request Forgery (SSRF) attacks by ensuring agents cannot access internal network resources.

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