How to Configure the Groq API Key for Podcast Transcription in Agent Reach

Agent Reach stores the Groq API key in ~/.agent-reach/config.yaml under the groq_api_key field and automatically falls back to OpenAI's Whisper service only when Groq's whisper-large-v3 model is unavailable.

The Panniantong/Agent-Reach repository provides a seamless podcast transcription pipeline that prioritizes Groq's free Whisper API for speed and cost efficiency. To enable this functionality, you must configure the Groq API key for podcast transcription in Agent Reach before processing audio files. This guide covers the exact file locations, validation logic, and command-line methods used by the transcription engine.

Configuration Storage and Validation

Agent Reach persists sensitive credentials outside the repository using a YAML-based configuration system. The transcription engine validates these credentials before attempting API calls to avoid unnecessary network failures.

The Configuration File Structure

In agent_reach/config.py, the Config class manages the groq_api_key value within the user’s home directory at ~/.agent-reach/config.yaml. When you save a key, the system writes it to this file under the exact field name groq_api_key, ensuring consistent retrieval across CLI and programmatic interfaces.

Environment Variable Fallback

As a secondary source, Agent Reach checks the GROQ_API_KEY environment variable. If the YAML configuration lacks the key but the environment variable is present, the transcription pipeline uses the environment value without modifying the config file.

Validation via is_configured

The Config.is_configured("groq_whisper") helper (lines 90‑94 in agent_reach/config.py) verifies that a valid Groq API key exists in either the config file or the environment. This check runs before any transcription attempt to ensure the provider order can be established correctly.

Setting the Groq API Key

You can populate the credential store using the CLI convenience command or direct Python instantiation.

CLI Configuration Command

The agent_reach/cli.py file implements a dedicated configure sub-command that writes the key safely:

agent-reach configure groq-key gsk_YourGroqKeyHere

This command invokes config.set("groq_api_key", …) (lines 104‑107), persisting the value to ~/.agent-reach/config.yaml with proper file permissions.

Programmatic Configuration

For automated setups or testing environments, instantiate the Config class directly:

from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "gsk_YourGroqKeyHere")

This approach writes immediately to the YAML file and makes the key available for subsequent transcription calls within the same process.

Transcription Pipeline Architecture

Once configured, the transcription engine routes audio through Groq’s infrastructure using a provider-agnostic abstraction layer.

Provider Mapping in transcribe.py

The agent_reach/transcribe.py file defines a PROVIDERS mapping (lines 30‑36) that specifies the Groq endpoint (https://api.groq.com/openai/v1/audio/transcriptions), the model name (whisper-large-v3), and the config field to read (groq_api_key). This mapping decouples the transcription logic from specific vendor implementations.

Key Extraction and HTTP Requests

The internal _provider_key() method (lines 57‑61) extracts the key from the Config instance, while transcribe_chunk() (lines 63‑71) constructs the multipart HTTP POST request to Groq’s API. The function sends the audio chunk along with the stored API key in the Authorization header.

Automatic Fallback Logic

The transcribe() function (lines 107‑118) builds a provider order list ["groq", "openai"] when the user specifies provider="auto". It first validates that at least one key is configured (lines 22‑25), then delegates to _transcribe_with_fallback() (lines 49‑61), which attempts Groq first and catches errors to retry with OpenAI’s whisper-1 model if necessary.

Practical Usage Examples

With the Groq API key configured, you can process podcast URLs immediately.

Transcribe with automatic provider selection (Groq first):

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

Force Groq only (fails fast if the key is missing):

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

Use the Python API directly:

from agent_reach.transcribe import transcribe
from agent_reach.config import Config

cfg = Config()
text = transcribe(
    "https://example.com/podcast.mp3",
    provider="auto",
    config=cfg,
)
print(text)

Troubleshooting and Verification

If transcription fails immediately with a configuration error, verify the setup using the built-in diagnostics.

Checking Configuration Status

Run a quick Python check to confirm the key is recognized:

from agent_reach.config import Config

cfg = Config()
print(f"Groq configured: {cfg.is_configured('groq_whisper')}")

A True result indicates that agent_reach/config.py successfully located the groq_api_key in ~/.agent-reach/config.yaml or the GROQ_API_KEY environment variable.

Installation Reminders

The _install_xiaoyuzhou_deps() function in agent_reach/cli.py (lines 71‑78) prints a helpful reminder if the Groq key is missing during channel setup, explicitly suggesting the agent-reach configure groq-key command format. This ensures users discover the configuration requirement during initial setup rather than at runtime.

Summary

• Agent Reach stores the Groq API key in ~/.agent-reach/config.yaml under the field groq_api_key, with fallback support for the GROQ_API_KEY environment variable.
• Use agent-reach configure groq-key <key> to persist credentials via the CLI, or call Config().set("groq_api_key", …) programmatically.
• The transcription pipeline in agent_reach/transcribe.py routes audio to https://api.groq.com/openai/v1/audio/transcriptions using the whisper-large-v3 model.
• When provider="auto" is selected, the system automatically falls back to OpenAI’s whisper-1 only if Groq requests fail or the key is absent.
• Validation occurs via Config.is_configured("groq_whisper") before any network requests are attempted.

Frequently Asked Questions

Where does Agent Reach store the Groq API key?

Agent Reach writes the key to a YAML file located at ~/.agent-reach/config.yaml under the field name groq_api_key. This path is hardcoded in agent_reach/config.py to keep credentials outside version-controlled directories.

Can I use environment variables instead of the config file?

Yes. The Config class checks for the GROQ_API_KEY environment variable as a fallback when the groq_api_key field is missing from the YAML file. You can export this variable in your shell profile to avoid writing the key to disk.

What happens if my Groq API key is invalid or rate-limited?

The _transcribe_with_fallback() function in agent_reach/transcribe.py catches errors from Groq and automatically retries the request using OpenAI’s Whisper API, provided you have configured an OpenAI key. If you force Groq with --provider groq, the command raises an error immediately instead of falling back.

How do I force Agent Reach to use OpenAI instead of Groq?

Pass the --provider openai flag to the CLI command, or set provider="openai" in the Python API. This bypasses the default provider order of ["groq", "openai"] and skips the Groq validation check entirely.

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