What does this PR do?

Implements #24415 — adds OpenRouter as a first-class STT provider alongside the existing five (local, groq, openai, mistral, xai).

Hermes today supports five STT providers but has no way to reuse OPENROUTER_API_KEY for transcription — users with OpenRouter set up for LLM access have to spin up a separate Groq / OpenAI / xAI account just to transcribe a voice message. OpenRouter exposes an OpenAI-compatible /api/v1/audio/transcriptions endpoint that routes to Whisper-family models (openai/whisper-1, openai/gpt-4o-mini-transcribe, openai/gpt-4o-transcribe) billed through the same credit pool as LLM access. Adding openrouter as a native provider closes that gap with zero new dependencies — the existing openai SDK with a custom base_url handles the wire format.

The implementation lives in tools/transcription_tools.py:

1. Provider detection — explicit stt.provider: openrouter branch + auto-detect chain entry. Auto-detect order is local > groq > openai > xai > openrouter. OpenRouter sits last in the cloud chain because it's a catch-all — if the user also has a dedicated STT key (Groq / OpenAI / xAI), the dedicated provider wins so they keep that provider's pricing and routing.
2. Client routing — _transcribe_openrouter() mirrors the _transcribe_groq() shape: OpenAI(api_key=..., base_url="https://openrouter.ai/api/v1", timeout=30, max_retries=0) then audio.transcriptions.create(model=..., file=..., response_format="text"). Same error envelope, same _extract_transcript_text post-processing.
3. Model selection — default openai/whisper-1, overridable via stt.openrouter.model or the STT_OPENROUTER_MODEL env var. The known-models set is informational only — Hermes does not block other model IDs (OpenRouter routinely adds new ones).
4. Auth — reuses OPENROUTER_API_KEY from .env (no new env var). stt.openrouter.api_key in config wins over the env var so managed deployments can pin per-deployment credentials.
5. No new dependency — the existing openai SDK does the work; the issue's "no new SDK required" promise is honoured.

Related Issue

Closes #24415 — [Feature]: Add OpenRouter as an STT provider.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/transcription_tools.py (+109 / −8):
  • New constants DEFAULT_OPENROUTER_STT_MODEL = "openai/whisper-1", OPENROUTER_STT_BASE_URL = "https://openrouter.ai/api/v1", OPENROUTER_MODELS = {…} (informational only).
  • _get_provider() — explicit openrouter branch (requires OPENROUTER_API_KEY + the openai SDK) + auto-detect chain entry after xai.
  • _transcribe_openrouter() — new function modeled on _transcribe_groq(), with config/env key resolution, base-url override, full error-envelope coverage (PermissionError, APIConnectionError, APITimeoutError, APIError, Exception).
  • transcribe_audio() — new dispatch arm + per-provider model resolution (stt.openrouter.model wins, default openai/whisper-1).
  • Module docstring updated to "seven providers"; the "no provider available" hint mentions OPENROUTER_API_KEY so users discover it without reading source.
• cli-config.yaml.example (+4 / −2) — new commented stt.openrouter block with model / api_key / base_url examples.
• tests/tools/test_transcription_openrouter.py (new, +378 lines) — 18 unit tests across three classes:
  • TestGetProviderOpenRouter (7) — explicit-config and auto-detect resolution, including the precedence rule from the issue (groq / openai / xai win over openrouter in auto-detect).
  • TestTranscribeOpenRouter (7) — env-key resolution, config overrides, OpenAI-SDK call shape (response_format="text" pinned), error-path wrappers.
  • TestTranscribeAudioDispatchOpenRouter (4) — end-to-end transcribe_audio() dispatch + the model-default chain.
• tests/tools/test_transcription_openrouter_feature_anchor.py (new, +208 lines) — 2 feature-shape regression anchors that drive the issue's full "Proposed Solution" contract end-to-end:
  • test_full_user_round_trip_honours_issue_contract — asserts bullets 1–4 (provider routes, base URL, env key, default model) in a single round trip with per-bullet #24415 anchor messages.
  • test_auto_detect_lights_up_with_only_openrouter_key — asserts bullet 5 (auto-detect with only OPENROUTER_API_KEY set must land on openrouter).
• website/docs/user-guide/features/voice-mode.md (+15 / −3) — added OPENROUTER_API_KEY to the API-Keys section with a tip explaining the "reuse your LLM key" value proposition + the auto-detect rationale; troubleshooting bullet updated; Configuration Reference section gets STT_OPENROUTER_MODEL and STT_OPENROUTER_BASE_URL overrides.

No existing files outside the additions above are touched; existing provider code paths (_transcribe_groq, _transcribe_openai, _transcribe_xai, _transcribe_mistral, _transcribe_local, _transcribe_local_command) are byte-identical.

How to Test

1. Check out this branch and ensure .venv is set up: python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[all,dev]"
2. Run the new + adjacent test suites:

   scripts/run_tests.sh \
     tests/tools/test_transcription_openrouter.py \
     tests/tools/test_transcription_openrouter_feature_anchor.py \
     tests/tools/test_transcription_tools.py \
     tests/tools/test_transcription.py \
     tests/tools/test_transcription_dotenv_fallback.py
   

   Expected: 147 passed (20 new + 127 pre-existing).
3. Verify the feature-shape regression anchor really catches the missing feature:

   git checkout upstream/main -- tools/transcription_tools.py
   pytest tests/tools/test_transcription_openrouter_feature_anchor.py -v
   

   Expected: 2 failed with the anchor messages
   #24415 anchor: stt.provider=openrouter with OPENROUTER_API_KEY set must succeed -- got error: 'No STT provider available...'
   and
   #24415 anchor: with only OPENROUTER_API_KEY set and no other STT backend available, auto-detect MUST land on the openrouter provider....
   Restore the fix (git checkout HEAD -- tools/transcription_tools.py) → both pass.
4. (Optional, manual) Drop your real OPENROUTER_API_KEY into ~/.hermes/.env, set stt.provider: openrouter in ~/.hermes/config.yaml, then send a voice message via the gateway:
   • Discord/Telegram: voice-note → Hermes transcribes via https://openrouter.ai/api/v1/audio/transcriptions and replies. OpenRouter dashboard should show a hit on openai/whisper-1.
   • CLI voice mode: hermes → /voice on → push-to-talk; transcript flows through the same code path.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(stt): ..., test(stt): ..., docs(stt): ...)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature (4 commits, all scoped to OpenRouter STT + its tests + its docs)
• I've run scripts/run_tests.sh on the affected test files and all 147 tests pass
• I've added tests for my changes (18 unit tests + 2 feature-shape regression anchors)
• I've tested on my platform: macOS 15.2 (Darwin 24.6.0), Python 3.12

Documentation & Housekeeping

• I've updated relevant documentation — website/docs/user-guide/features/voice-mode.md got an OpenRouter tip, troubleshooting hint, and env-var reference rows
• I've updated cli-config.yaml.example if I added/changed config keys — added a commented stt.openrouter block
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — feature is platform-agnostic; relies only on the openai SDK + OPENROUTER_API_KEY env var, both of which work identically on Windows / macOS / Linux. Tests are hermetic (mocked openai module via patch.dict("sys.modules", ...), no real network or filesystem outside tmp_path).
• I've updated tool descriptions/schemas if I changed tool behavior — N/A (internal STT pipeline; the transcribe_audio public surface keeps the exact same signature and return shape)

Screenshots / Logs

$ scripts/run_tests.sh tests/tools/test_transcription_openrouter.py tests/tools/test_transcription_openrouter_feature_anchor.py tests/tools/test_transcription_tools.py tests/tools/test_transcription.py tests/tools/test_transcription_dotenv_fallback.py
4 workers [147 items]
============================== 147 passed in 1.17s =============================

$ ruff check tools/transcription_tools.py tests/tools/test_transcription_openrouter.py tests/tools/test_transcription_openrouter_feature_anchor.py
All checks passed!

Feature-shape repro on upstream/main (anchor proves the feature is genuinely missing pre-PR):

$ git checkout upstream/main -- tools/transcription_tools.py
$ pytest tests/tools/test_transcription_openrouter_feature_anchor.py -v
FAILED tests/tools/test_transcription_openrouter_feature_anchor.py::TestOpenRouterSttFeatureContract::test_full_user_round_trip_honours_issue_contract
  AssertionError: #24415 anchor: stt.provider=openrouter with OPENROUTER_API_KEY set
    must succeed -- got error: 'No STT provider available. Install faster-whisper for
    free local transcription, ... or set VOICE_TOOLS_OPENAI_KEY or OPENAI_API_KEY for
    the OpenAI Whisper API.'.  This means _get_provider does not recognise
    'openrouter' or the dispatch in transcribe_audio is missing -- the feature is not
    wired.
FAILED tests/tools/test_transcription_openrouter_feature_anchor.py::TestOpenRouterSttFeatureContract::test_auto_detect_lights_up_with_only_openrouter_key
  AssertionError: #24415 anchor: with only OPENROUTER_API_KEY set and no other STT
    backend available, auto-detect MUST land on the openrouter provider...

feat/openrouter-stt-provider