fix(stt): better error logging and smarter DM when STT install fails

Three improvements to the voice-transcription setup flow:

1. tools/transcription_tools.py - Log lazy-install failures at WARNING
   instead of DEBUG, and include actionable guidance about venv
   permission issues (the most common cause of silent STT failures).

2. gateway/run.py - Smart DM message: check the actual stt config
   before sending setup instructions. If stt.enabled is already true
   and provider is 'local', skip the redundant 'set stt.enabled'
   advice and show a permission-aware install hint instead.

3. gateway/run.py - Agent note now includes a config-aware hint
   about why STT is unavailable (e.g. 'provider is local but
   faster-whisper failed to install').
This commit is contained in:
Damian Kluk 2026-06-14 12:12:39 +00:00
parent ab22317d09
commit d3e07bdaaa
2 changed files with 79 additions and 10 deletions

View file

@ -223,8 +223,20 @@ def _try_lazy_install_stt() -> bool:
import importlib.util as _iu
if _iu.find_spec("faster_whisper"):
return True
logger.warning(
"faster-whisper was installed but importlib still cannot find it "
"(may require Python restart)"
)
except Exception as exc:
logger.debug("Lazy install of faster-whisper failed: %s", exc)
logger.warning(
"Lazy install of faster-whisper failed: %s. "
"This is often a permission issue: the Hermes process user cannot "
"write to the virtual environment. Try running manually as the "
"venv owner: `stat -c '%%u' '$(dirname $(dirname $(which python3)))'` "
"then `su - <owner> -c 'VIRTUAL_ENV=/opt/hermes/.venv "
"uv pip install faster-whisper==1.2.1'`",
exc,
)
return False