docs(voice): use `uv pip install faster-whisper` in STT install hints by briandevans · Pull Request #29800 · NousResearch/hermes-agent

briandevans · 2026-05-21T12:16:55Z

What does this PR do?

Three runtime messages tell users to pip install faster-whisper to enable local STT. Reported in #29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit bash: pip: command not found because the Hermes Docker image is built on ghcr.io/astral-sh/uv with a uv-managed venv that doesn't ship pip on PATH. Users on modern uv tool install / uv venv installs see the same problem.

The canonical install command in this repo is uv pip install (see tools/lazy_deps.py:509 feature_install_command(), which generates uv pip install ... for every lazy backend including stt.faster_whisper). uv pip install works in Docker (uv image), in uv tool install venvs, and in pip-based venvs that already have uv on PATH.

Audited siblings: grepped pip install faster-whisper across gateway/, cli.py, tools/ — exactly three runtime message strings emit this hint and all three are updated by this PR. Docs (website/docs/, README.md, skills) intentionally left alone — those are read in browser context where the user can copy whichever variant fits their install, and changing them is a separate scope.

Related Issue

Fixes #29782

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

gateway/run.py — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Now suggests `uv pip install faster-whisper` in the Hermes venv and notes that `pip install faster-whisper` also works if pip is on PATH.
tools/voice_mode.py — /voice status line for missing STT now says uv pip install faster-whisper.
cli.py — Voice-mode startup error "Option 1" now says uv pip install faster-whisper (free, local).

Before/after on the gateway message reported in the issue:

Before: To enable voice: install faster-whisper (`pip install faster-whisper` in the Hermes venv) and set `stt.enabled: true` ...
After:  To enable voice: install faster-whisper (`uv pip install faster-whisper` in the Hermes venv; `pip install faster-whisper` also works if pip is on PATH) and set `stt.enabled: true` ...

How to Test

Reproduce the original failure on origin/main:

docker run --rm ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie bash -lc 'pip install faster-whisper'
# bash: pip: command not found

Verify uv pip install works in the same env:

docker run --rm ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie bash -lc 'uv venv && source .venv/bin/activate && uv pip install faster-whisper'
# Resolved + installed

Existing test pass:

uv run --with pytest --with pytest-xdist --with pytest-asyncio --with pytest-timeout python3 -m pytest tests/tools/test_voice_mode.py -v
# 45 passed, 15 skipped

Trigger the gateway STT hint by sending a voice message to a Telegram bot with stt.enabled: false (or no STT configured), and confirm the new copy is rendered.

Checklist

Code

I've read the Contributing Guide
My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
I searched for existing PRs to make sure this isn't a duplicate
My PR contains only changes related to this fix/feature (no unrelated commits)
I've run focused tests for the touched code and all pass
I've added tests for my changes (required for bug fixes, strongly encouraged for features) — N/A: cosmetic copy change in user-facing message strings; a string-equality test would be brittle without protecting against a real regression class.
I've tested on my platform: macOS 15.x

Documentation & Housekeeping

I've updated relevant documentation (README, docs/, docstrings) — or N/A (in-product hints updated; web docs intentionally left alone)
I've updated cli-config.yaml.example if I added/changed config keys — N/A (no config keys)
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 — uv is cross-platform; the new hint is correct on macOS, Linux, Windows.
I've updated tool descriptions/schemas if I changed tool behavior — N/A

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates voice-mode user guidance to prefer uv pip when installing the faster-whisper STT dependency.

Changes:

Swaps pip install faster-whisper → uv pip install faster-whisper in voice requirement checks and CLI error text.
Expands gateway user-facing message to mention both uv pip and plain pip as options.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
tools/voice_mode.py	Updates missing-STT provider hint to recommend `uv pip`.
gateway/run.py	Updates user message to recommend `uv pip`, while noting `pip` can also work.
cli.py	Updates RuntimeError guidance to recommend `uv pip` for installing `faster-whisper`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@@ -10120,7 +10120,7 @@ def _voice_start_recording(self):
        if not reqs.get("stt_available", reqs.get("stt_key_set")):
            raise RuntimeError(
                "Voice mode requires an STT provider for transcription.\n"
-                "Option 1: pip install faster-whisper  (free, local)\n"
+                "Option 1: uv pip install faster-whisper  (free, local)\n"


@@ -966,7 +966,7 @@ def check_voice_requirements() -> Dict[str, Any]:
        details_parts.append("STT provider: OK (OpenAI)")
    else:
        details_parts.append(
-            "STT provider: MISSING (pip install faster-whisper, "
+            "STT provider: MISSING (uv pip install faster-whisper, "


                                "🎤 I received your voice message but can't transcribe it — "
                                "no speech-to-text provider is configured.\n\n"
                                "To enable voice: install faster-whisper "
-                                "(`pip install faster-whisper` in the Hermes venv) "
+                                "(`uv pip install faster-whisper` in the Hermes venv; "
+                                "`pip install faster-whisper` also works if pip is on PATH) "
                                "and set `stt.enabled: true` in config.yaml, "
                                "then /restart the gateway."
                            )


briandevans · 2026-05-21T13:15:17Z

@copilot Findings 1 & 2 addressed in ec4e2ef3a — both cli.py and tools/voice_mode.py now mention pip install faster-whisper as a fallback when uv isn't on PATH, matching the existing gateway/run.py wording.

On finding 3 (centralizing the install hint across the three files): leaving as-is for now. The strings differ by surface (multi-line raised RuntimeError, single-line status detail, multi-line user-facing chat message), so a shared helper would have to take enough format knobs that it would not reduce the drift it tries to prevent. Happy to revisit if a clearer centralization shape becomes obvious. Also worth noting: #29815 wires lazy-install into the transcription pipeline, which means the gateway/run.py message becomes a fallback-only diagnostic once that lands — further reducing the need to centralize.

Three runtime messages told users to `pip install faster-whisper` (reported in NousResearch#29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit `bash: pip: command not found`). The Hermes Docker image is built on `ghcr.io/astral-sh/uv` with a uv-managed venv that doesn't ship `pip` on PATH; users on modern `uv tool install` / `uv venv` installs see the same problem. The canonical install command in this repo is `uv pip install` (see `tools/lazy_deps.py:509` `feature_install_command()`), which works in Docker (uv image), in `uv tool install` venvs, and in pip-based venvs that already have uv on PATH. Changed three locations to match: - `gateway/run.py` — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Suggests `uv pip install faster-whisper` and notes that `pip install faster-whisper` also works if `pip` is on PATH. - `tools/voice_mode.py` — `/voice` status line for missing STT. - `cli.py` — Voice-mode startup error, "Option 1". No behavior change beyond the user-facing text. No production code path was touched.

Copilot flagged that cli.py and tools/voice_mode.py recommend `uv pip install faster-whisper` without a fallback for environments where uv isn't on PATH. The gateway/run.py message already lists `pip install faster-whisper` as an alternative; this commit aligns the two remaining call sites to match. Addresses inline Copilot review on NousResearch#29800.

…NousResearch#29800) * docs(voice): use `uv pip install faster-whisper` in STT install hints Three runtime messages told users to `pip install faster-whisper` (reported in NousResearch#29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit `bash: pip: command not found`). The Hermes Docker image is built on `ghcr.io/astral-sh/uv` with a uv-managed venv that doesn't ship `pip` on PATH; users on modern `uv tool install` / `uv venv` installs see the same problem. The canonical install command in this repo is `uv pip install` (see `tools/lazy_deps.py:509` `feature_install_command()`), which works in Docker (uv image), in `uv tool install` venvs, and in pip-based venvs that already have uv on PATH. Changed three locations to match: - `gateway/run.py` — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Suggests `uv pip install faster-whisper` and notes that `pip install faster-whisper` also works if `pip` is on PATH. - `tools/voice_mode.py` — `/voice` status line for missing STT. - `cli.py` — Voice-mode startup error, "Option 1". No behavior change beyond the user-facing text. No production code path was touched. * docs(voice): add pip fallback to cli + voice_mode STT hints Copilot flagged that cli.py and tools/voice_mode.py recommend `uv pip install faster-whisper` without a fallback for environments where uv isn't on PATH. The gateway/run.py message already lists `pip install faster-whisper` as an alternative; this commit aligns the two remaining call sites to match. Addresses inline Copilot review on NousResearch#29800. --------- Co-authored-by: briandevans <252620095+briandevans@users.noreply.github.com>

…NousResearch#29800) * docs(voice): use `uv pip install faster-whisper` in STT install hints Three runtime messages told users to `pip install faster-whisper` (reported in NousResearch#29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit `bash: pip: command not found`). The Hermes Docker image is built on `ghcr.io/astral-sh/uv` with a uv-managed venv that doesn't ship `pip` on PATH; users on modern `uv tool install` / `uv venv` installs see the same problem. The canonical install command in this repo is `uv pip install` (see `tools/lazy_deps.py:509` `feature_install_command()`), which works in Docker (uv image), in `uv tool install` venvs, and in pip-based venvs that already have uv on PATH. Changed three locations to match: - `gateway/run.py` — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Suggests `uv pip install faster-whisper` and notes that `pip install faster-whisper` also works if `pip` is on PATH. - `tools/voice_mode.py` — `/voice` status line for missing STT. - `cli.py` — Voice-mode startup error, "Option 1". No behavior change beyond the user-facing text. No production code path was touched. * docs(voice): add pip fallback to cli + voice_mode STT hints Copilot flagged that cli.py and tools/voice_mode.py recommend `uv pip install faster-whisper` without a fallback for environments where uv isn't on PATH. The gateway/run.py message already lists `pip install faster-whisper` as an alternative; this commit aligns the two remaining call sites to match. Addresses inline Copilot review on NousResearch#29800. --------- Co-authored-by: briandevans <252620095+briandevans@users.noreply.github.com> #AI commit#

…NousResearch#29800) * docs(voice): use `uv pip install faster-whisper` in STT install hints Three runtime messages told users to `pip install faster-whisper` (reported in NousResearch#29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit `bash: pip: command not found`). The Hermes Docker image is built on `ghcr.io/astral-sh/uv` with a uv-managed venv that doesn't ship `pip` on PATH; users on modern `uv tool install` / `uv venv` installs see the same problem. The canonical install command in this repo is `uv pip install` (see `tools/lazy_deps.py:509` `feature_install_command()`), which works in Docker (uv image), in `uv tool install` venvs, and in pip-based venvs that already have uv on PATH. Changed three locations to match: - `gateway/run.py` — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Suggests `uv pip install faster-whisper` and notes that `pip install faster-whisper` also works if `pip` is on PATH. - `tools/voice_mode.py` — `/voice` status line for missing STT. - `cli.py` — Voice-mode startup error, "Option 1". No behavior change beyond the user-facing text. No production code path was touched. * docs(voice): add pip fallback to cli + voice_mode STT hints Copilot flagged that cli.py and tools/voice_mode.py recommend `uv pip install faster-whisper` without a fallback for environments where uv isn't on PATH. The gateway/run.py message already lists `pip install faster-whisper` as an alternative; this commit aligns the two remaining call sites to match. Addresses inline Copilot review on NousResearch#29800. --------- Co-authored-by: briandevans <252620095+briandevans@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 21, 2026 12:16

Copilot AI reviewed May 21, 2026

View reviewed changes

briandevans force-pushed the fix/voice-stt-install-hint-uv-29782 branch from ec4e2ef to 1ee1208 Compare May 24, 2026 01:15

briandevans added 2 commits May 26, 2026 00:08

briandevans force-pushed the fix/voice-stt-install-hint-uv-29782 branch from 1ee1208 to ba33133 Compare May 26, 2026 07:10

benbarclay mentioned this pull request May 28, 2026

fix(stt): lazy-install faster-whisper on first voice message (#29782) #29815

Closed

benbarclay merged commit 3ad4693 into NousResearch:main May 28, 2026
21 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(voice): use `uv pip install faster-whisper` in STT install hints#29800

docs(voice): use `uv pip install faster-whisper` in STT install hints#29800
benbarclay merged 2 commits into
NousResearch:mainfrom
briandevans:fix/voice-stt-install-hint-uv-29782

briandevans commented May 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

briandevans commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

briandevans commented May 21, 2026

What does this PR do?

Related Issue

Type of Change

Changes Made

How to Test

Checklist

Code

Documentation & Housekeeping

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

briandevans commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants