diff --git a/cli-config.yaml.example b/cli-config.yaml.example index d1ce3b08e2b4..932e99929019 100644 --- a/cli-config.yaml.example +++ b/cli-config.yaml.example @@ -1127,8 +1127,14 @@ stt: local: model: "base" # tiny | base | small | medium | large-v3 | turbo # language: "" # auto-detect; set to "en", "es", "fr", etc. to force + # initial_prompt: "" # Optional faster-whisper prompt, e.g. bias Chinese output to simplified Chinese + # language: "" # GLOBAL language hint for every STT provider (per-provider language wins) + # groq: + # model: "whisper-large-v3-turbo" + # language: "" # blank = stt.language > HERMES_LOCAL_STT_LANGUAGE > auto-detect openai: model: "whisper-1" # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe + language: "" # auto-detect; set to "en", "es", "fr", etc. to force # mistral: # model: "voxtral-mini-latest" # voxtral-mini-latest | voxtral-mini-2602 # deepinfra: diff --git a/contributors/emails/materemias@gmail.com b/contributors/emails/materemias@gmail.com new file mode 100644 index 000000000000..8ad7c212185b --- /dev/null +++ b/contributors/emails/materemias@gmail.com @@ -0,0 +1 @@ +materemias diff --git a/contributors/emails/zombopanda@gmail.com b/contributors/emails/zombopanda@gmail.com new file mode 100644 index 000000000000..2ec1bd83bc8d --- /dev/null +++ b/contributors/emails/zombopanda@gmail.com @@ -0,0 +1 @@ +zombopanda diff --git a/hermes_cli/config.py b/hermes_cli/config.py index 3e8b6e5f07dc..aab86489c4c6 100644 --- a/hermes_cli/config.py +++ b/hermes_cli/config.py @@ -2322,15 +2322,28 @@ def _ensure_hermes_home_managed(home: Path): # Set false to keep STT for the agent while suppressing that user-facing echo. "echo_transcripts": True, "provider": "local", # "local" (free, faster-whisper) | "groq" | "openai" (Whisper API) | "mistral" (Voxtral Transcribe) | "elevenlabs" (Scribe) | "deepinfra" + # Global language hint applied to EVERY provider unless a per-provider + # language overrides it. Empty = auto-detect. ISO-639-1 ("en", "es", ...). + "language": "", "local": { "model": "base", # tiny, base, small, medium, large-v3 "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force + "initial_prompt": "", + }, + "groq": { + "model": "whisper-large-v3-turbo", # whisper-large-v3, whisper-large-v3-turbo, distil-whisper-large-v3-en + "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force }, "openai": { "model": "whisper-1", # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe + "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force }, "mistral": { "model": "voxtral-mini-latest", # voxtral-mini-latest, voxtral-mini-2602 + "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force + }, + "xai": { + "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force }, "elevenlabs": { "model_id": "scribe_v2", # scribe_v2, scribe_v1 diff --git a/tests/tools/test_stt_language_resolution.py b/tests/tools/test_stt_language_resolution.py new file mode 100644 index 000000000000..f7fd535ca372 --- /dev/null +++ b/tests/tools/test_stt_language_resolution.py @@ -0,0 +1,123 @@ +"""Tests for the unified STT language resolution (_resolve_stt_language). + +Class-level contract: EVERY provider resolves its language hint through one +helper with the order: + + stt..language > stt.language (global) > HERMES_LOCAL_STT_LANGUAGE > None + +Regression coverage for the "STT transcribes the wrong language" issue class +(#55551, #50181 and siblings): + - xAI no longer silently forces "en" when nothing is configured + - the global ``stt.language`` key reaches every provider + - per-provider language still wins over the global key +""" + +from unittest.mock import patch + +import pytest + +from tools.transcription_tools import _resolve_stt_language + + +@pytest.fixture(autouse=True) +def _clear_lang_env(monkeypatch): + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + + +class TestResolveSttLanguage: + def test_provider_language_wins(self): + cfg = {"language": "en", "groq": {"language": "he"}} + assert _resolve_stt_language("groq", cfg) == "he" + + def test_global_language_fallback(self): + cfg = {"language": "hu", "groq": {}} + assert _resolve_stt_language("groq", cfg) == "hu" + + def test_global_language_reaches_provider_without_section(self): + cfg = {"language": "uk"} + for provider in ("local", "groq", "openai", "mistral", "xai", "elevenlabs", "deepinfra"): + assert _resolve_stt_language(provider, cfg) == "uk", provider + + def test_env_var_fallback(self, monkeypatch): + monkeypatch.setenv("HERMES_LOCAL_STT_LANGUAGE", "de") + assert _resolve_stt_language("openai", {}) == "de" + + def test_auto_detect_when_nothing_set(self): + assert _resolve_stt_language("xai", {}) is None + + def test_blank_strings_are_skipped(self): + cfg = {"language": " ", "groq": {"language": ""}} + assert _resolve_stt_language("groq", cfg) is None + + def test_extra_keys_alias(self): + cfg = {"elevenlabs": {"language_code": "spa"}} + assert _resolve_stt_language("elevenlabs", cfg, extra_keys=("language_code",)) == "spa" + + def test_null_provider_section(self): + # YAML `stt.groq: null` must not crash + cfg = {"groq": None, "language": "fr"} + assert _resolve_stt_language("groq", cfg) == "fr" + + def test_value_is_stripped(self): + cfg = {"language": " ja "} + assert _resolve_stt_language("local", cfg) == "ja" + + +class TestXaiNoForcedEnglish: + """xAI previously defaulted language to "en" — auto-detect must be the default.""" + + def test_no_language_sent_by_default(self, tmp_path, monkeypatch): + import tools.transcription_tools as tt + audio = tmp_path / "a.ogg" + audio.write_bytes(b"x") + captured = {} + + class _Resp: + status_code = 200 + + @staticmethod + def json(): + return {"text": "hola", "language": "es", "duration": 1.0} + + import requests as _requests + + def fake_post(url, **kwargs): + captured["data"] = kwargs.get("data") + return _Resp() + + monkeypatch.setattr(_requests, "post", fake_post) + with patch.object(tt, "_load_stt_config", return_value={}), \ + patch("tools.xai_http.resolve_xai_http_credentials", + return_value={"api_key": "xai-test", "base_url": "https://api.x.ai/v1"}): + result = tt._transcribe_xai(str(audio), "grok-stt") + + assert result["success"] is True + assert "language" not in (captured["data"] or {}), \ + "xAI must auto-detect when no language is configured (was forced to 'en')" + + def test_global_language_reaches_xai(self, tmp_path, monkeypatch): + import tools.transcription_tools as tt + audio = tmp_path / "a.ogg" + audio.write_bytes(b"x") + captured = {} + + class _Resp: + status_code = 200 + + @staticmethod + def json(): + return {"text": "ok", "language": "he", "duration": 1.0} + + import requests as _requests + + monkeypatch.setattr( + _requests, "post", + lambda url, **kw: captured.update(data=kw.get("data")) or _Resp(), + ) + with patch.object(tt, "_load_stt_config", return_value={"language": "he"}), \ + patch("tools.xai_http.resolve_xai_http_credentials", + return_value={"api_key": "xai-test", "base_url": "https://api.x.ai/v1"}): + result = tt._transcribe_xai(str(audio), "grok-stt") + + assert result["success"] is True + assert captured["data"]["language"] == "he" diff --git a/tests/tools/test_transcription.py b/tests/tools/test_transcription.py index 84f6c9679af6..d5c3903ff130 100644 --- a/tests/tools/test_transcription.py +++ b/tests/tools/test_transcription.py @@ -122,6 +122,27 @@ def test_too_large(self, tmp_path): assert "too large" in result["error"] +# --------------------------------------------------------------------------- +# Config resolution +# --------------------------------------------------------------------------- + + +class TestLoadSttConfig: + + def test_merges_default_local_initial_prompt(self, monkeypatch, tmp_path): + monkeypatch.setenv("HERMES_HOME", str(tmp_path)) + (tmp_path / "config.yaml").write_text( + "stt:\n local:\n model: small\n", + encoding="utf-8", + ) + + from tools.transcription_tools import _load_stt_config + local_config = _load_stt_config()["local"] + + assert local_config["model"] == "small" + assert local_config["initial_prompt"] == "" + + # --------------------------------------------------------------------------- # Local transcription # --------------------------------------------------------------------------- @@ -152,6 +173,72 @@ def test_successful_transcription(self, tmp_path): assert result["success"] is True assert result["transcript"] == "Hello world" + def test_passes_initial_prompt_when_configured(self, tmp_path): + audio_file = tmp_path / "test.ogg" + audio_file.write_bytes(b"fake audio") + + mock_info = MagicMock(language="zh", duration=2.5) + mock_model = MagicMock() + mock_model.transcribe.return_value = ([], mock_info) + + fake_fw = _fake_faster_whisper_module(mock_model) + with patch("tools.transcription_tools._HAS_FASTER_WHISPER", True), \ + patch("tools.transcription_tools._load_stt_config", return_value={ + "local": {"initial_prompt": "以下是普通话的句子,使用简体中文。"}, + }), \ + patch.dict("sys.modules", {"faster_whisper": fake_fw}), \ + patch("tools.transcription_tools._local_model", None): + from tools.transcription_tools import _transcribe_local + result = _transcribe_local(str(audio_file), "base") + + assert result["success"] is True + assert mock_model.transcribe.call_args.kwargs["initial_prompt"] == ( + "以下是普通话的句子,使用简体中文。" + ) + + def test_omits_blank_initial_prompt(self, tmp_path): + audio_file = tmp_path / "test.ogg" + audio_file.write_bytes(b"fake audio") + + mock_info = MagicMock(language="en", duration=2.5) + mock_model = MagicMock() + mock_model.transcribe.return_value = ([], mock_info) + + fake_fw = _fake_faster_whisper_module(mock_model) + with patch("tools.transcription_tools._HAS_FASTER_WHISPER", True), \ + patch("tools.transcription_tools._load_stt_config", return_value={ + "local": {"initial_prompt": " "}, + }), \ + patch.dict("sys.modules", {"faster_whisper": fake_fw}), \ + patch("tools.transcription_tools._local_model", None): + from tools.transcription_tools import _transcribe_local + result = _transcribe_local(str(audio_file), "base") + + assert result["success"] is True + assert "initial_prompt" not in mock_model.transcribe.call_args.kwargs + + def test_accepts_null_local_config(self, monkeypatch, tmp_path): + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + audio_file = tmp_path / "test.ogg" + audio_file.write_bytes(b"fake audio") + + mock_info = MagicMock(language="en", duration=2.5) + mock_model = MagicMock() + mock_model.transcribe.return_value = ([], mock_info) + + fake_fw = _fake_faster_whisper_module(mock_model) + with patch("tools.transcription_tools._HAS_FASTER_WHISPER", True), \ + patch("tools.transcription_tools._load_stt_config", return_value={ + "local": None, + }), \ + patch.dict("sys.modules", {"faster_whisper": fake_fw}), \ + patch("tools.transcription_tools._local_model", None): + from tools.transcription_tools import _transcribe_local + result = _transcribe_local(str(audio_file), "base") + + assert result["success"] is True + assert mock_model.transcribe.call_args.kwargs == {"beam_size": 5} + def test_not_installed(self): with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False): from tools.transcription_tools import _transcribe_local @@ -190,6 +277,44 @@ def test_successful_transcription(self, monkeypatch, tmp_path): assert result["success"] is True assert result["transcript"] == "Hello from OpenAI" + def test_configured_language_is_forwarded(self, monkeypatch, tmp_path): + monkeypatch.setenv("VOICE_TOOLS_OPENAI_KEY", "sk-test") + audio_file = tmp_path / "test.ogg" + audio_file.write_bytes(b"fake audio") + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "Привіт" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("tools.transcription_tools._load_stt_config", return_value={ + "openai": {"language": "uk"}, + }), \ + patch("openai.OpenAI", return_value=mock_client): + from tools.transcription_tools import _transcribe_openai + result = _transcribe_openai(str(audio_file), "whisper-1") + + assert result["success"] is True + assert mock_client.audio.transcriptions.create.call_args.kwargs["language"] == "uk" + + def test_unset_language_omits_argument(self, monkeypatch, tmp_path): + monkeypatch.setenv("VOICE_TOOLS_OPENAI_KEY", "sk-test") + audio_file = tmp_path / "test.ogg" + audio_file.write_bytes(b"fake audio") + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "Hello" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("tools.transcription_tools._load_stt_config", return_value={ + "openai": {"language": ""}, + }), \ + patch("openai.OpenAI", return_value=mock_client): + from tools.transcription_tools import _transcribe_openai + result = _transcribe_openai(str(audio_file), "whisper-1") + + assert result["success"] is True + assert "language" not in mock_client.audio.transcriptions.create.call_args.kwargs + # --------------------------------------------------------------------------- # Main transcribe_audio() dispatch diff --git a/tests/tools/test_transcription_tools.py b/tests/tools/test_transcription_tools.py index 0997872c69fd..1674e0383aa2 100644 --- a/tests/tools/test_transcription_tools.py +++ b/tests/tools/test_transcription_tools.py @@ -311,6 +311,116 @@ def test_permission_error(self, monkeypatch, sample_wav): assert result["success"] is False assert "Permission denied" in result["error"] + def test_language_hint_omitted_when_unset(self, monkeypatch, sample_wav): + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "hi" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch("tools.transcription_tools._load_stt_config", return_value={}): + from tools.transcription_tools import _transcribe_groq + _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert "language" not in kwargs + + def test_language_hint_from_config(self, monkeypatch, sample_wav): + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "hola" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch( + "tools.transcription_tools._load_stt_config", + return_value={"groq": {"language": "es"}}, + ): + from tools.transcription_tools import _transcribe_groq + _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert kwargs["language"] == "es" + + def test_language_hint_from_env_when_config_missing(self, monkeypatch, sample_wav): + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.setenv("HERMES_LOCAL_STT_LANGUAGE", "hu") + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "szia" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch("tools.transcription_tools._load_stt_config", return_value={}): + from tools.transcription_tools import _transcribe_groq + _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert kwargs["language"] == "hu" + + def test_language_config_overrides_env(self, monkeypatch, sample_wav): + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.setenv("HERMES_LOCAL_STT_LANGUAGE", "hu") + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "hello" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch( + "tools.transcription_tools._load_stt_config", + return_value={"groq": {"language": "en"}}, + ): + from tools.transcription_tools import _transcribe_groq + _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert kwargs["language"] == "en" + + def test_language_whitespace_treated_as_unset(self, monkeypatch, sample_wav): + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "hi" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch( + "tools.transcription_tools._load_stt_config", + return_value={"groq": {"language": " "}}, + ): + from tools.transcription_tools import _transcribe_groq + _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert "language" not in kwargs + + def test_null_groq_subsection_is_safe(self, monkeypatch, sample_wav): + """`stt.groq: null` in YAML yields None; must not raise, auto-detect stays intact.""" + monkeypatch.setenv("GROQ_API_KEY", "gsk-test") + monkeypatch.delenv("HERMES_LOCAL_STT_LANGUAGE", raising=False) + + mock_client = MagicMock() + mock_client.audio.transcriptions.create.return_value = "hi" + + with patch("tools.transcription_tools._HAS_OPENAI", True), \ + patch("openai.OpenAI", return_value=mock_client), \ + patch( + "tools.transcription_tools._load_stt_config", + return_value={"groq": None}, + ): + from tools.transcription_tools import _transcribe_groq + result = _transcribe_groq(sample_wav, "whisper-large-v3-turbo") + + assert result["success"] is True + kwargs = mock_client.audio.transcriptions.create.call_args.kwargs + assert "language" not in kwargs + # ============================================================================ # _transcribe_openai — additional tests diff --git a/tools/transcription_tools.py b/tools/transcription_tools.py index dd8c60275ad6..d8418dae878b 100644 --- a/tools/transcription_tools.py +++ b/tools/transcription_tools.py @@ -136,6 +136,38 @@ def is_stt_enabled(stt_config: Optional[dict] = None) -> bool: return is_truthy_value(enabled, default=True) +def _resolve_stt_language( + provider_key: str, + stt_config: Optional[Dict[str, Any]] = None, + *, + extra_keys: tuple = (), +) -> Optional[str]: + """Resolve the language hint for an STT provider (class-level, all providers). + + Resolution order (first non-empty wins): + 1. ``stt..language`` (plus any *extra_keys* aliases, e.g. + ElevenLabs' historical ``language_code``) + 2. ``stt.language`` — global default for every provider + 3. ``HERMES_LOCAL_STT_LANGUAGE`` env var (legacy escape hatch) + 4. ``None`` — let the provider auto-detect + + Returns a stripped ISO-639-1-ish code or None. Never returns "". + """ + if stt_config is None: + stt_config = _load_stt_config() + provider_cfg = _get_stt_section(stt_config, provider_key) + candidates = [provider_cfg.get("language")] + for key in extra_keys: + candidates.append(provider_cfg.get(key)) + if isinstance(stt_config, dict): + candidates.append(stt_config.get("language")) + candidates.append(os.getenv(LOCAL_STT_LANGUAGE_ENV)) + for candidate in candidates: + if isinstance(candidate, str) and candidate.strip(): + return candidate.strip() + return None + + def _has_openai_audio_backend() -> bool: """Return True when OpenAI audio can use config credentials, env credentials, or the managed gateway.""" try: @@ -672,7 +704,7 @@ def _transcribe_command_stt( output_format = _get_command_stt_output_format(config) language = ( config.get("language") - or stt_config.get("language") + or _resolve_stt_language(provider_name, stt_config) or DEFAULT_COMMAND_STT_LANGUAGE ) model = model_override or config.get("model") or "" @@ -1154,15 +1186,16 @@ def _transcribe_local(file_path: str, model_name: str) -> Dict[str, Any]: _local_model = _load_local_whisper_model(model_name) _local_model_name = model_name - # Language: config.yaml (stt.local.language) > env var > auto-detect. - _forced_lang = ( - (_load_stt_config().get("local") or {}).get("language") - or os.getenv(LOCAL_STT_LANGUAGE_ENV) - or None - ) + # Language: stt.local.language > stt.language > env var > auto-detect. + stt_config = _load_stt_config() + local_config = stt_config.get("local") or {} + _forced_lang = _resolve_stt_language("local", stt_config) transcribe_kwargs = {"beam_size": 5} if _forced_lang: transcribe_kwargs["language"] = _forced_lang + initial_prompt = local_config.get("initial_prompt") + if isinstance(initial_prompt, str) and initial_prompt.strip(): + transcribe_kwargs["initial_prompt"] = initial_prompt try: segments, info = _local_model.transcribe(file_path, **transcribe_kwargs) @@ -1237,12 +1270,8 @@ def _transcribe_local_command(file_path: str, model_name: str) -> Dict[str, Any] ), } - # Language: config.yaml (stt.local.language) > env var > "en" default. - language = ( - (_load_stt_config().get("local") or {}).get("language") - or os.getenv(LOCAL_STT_LANGUAGE_ENV) - or DEFAULT_LOCAL_STT_LANGUAGE - ) + # Language: stt.local.language > stt.language > env var > "en" default. + language = _resolve_stt_language("local") or DEFAULT_LOCAL_STT_LANGUAGE normalized_model = _normalize_local_command_model(model_name) try: @@ -1302,7 +1331,13 @@ def _transcribe_local_command(file_path: str, model_name: str) -> Dict[str, Any] def _transcribe_groq(file_path: str, model_name: str) -> Dict[str, Any]: - """Transcribe using Groq Whisper API (free tier available).""" + """Transcribe using Groq Whisper API (free tier available). + + Honours an optional ISO-639-1 language hint resolved from + ``stt.groq.language`` > ``stt.language`` (config.yaml) > + ``HERMES_LOCAL_STT_LANGUAGE`` (env). When none is set, Groq + Whisper auto-detects. + """ api_key = get_env_value("GROQ_API_KEY") if not api_key: return {"success": False, "transcript": "", "error": "GROQ_API_KEY not set"} @@ -1315,20 +1350,27 @@ def _transcribe_groq(file_path: str, model_name: str) -> Dict[str, Any]: logger.info("Model %s not available on Groq, using %s", model_name, DEFAULT_GROQ_STT_MODEL) model_name = DEFAULT_GROQ_STT_MODEL + language = _resolve_stt_language("groq") + try: from openai import OpenAI, APIError, APIConnectionError, APITimeoutError client = OpenAI(api_key=api_key, base_url=GROQ_BASE_URL, timeout=30, max_retries=0) try: + create_kwargs = { + "model": model_name, + "response_format": "text", + } + if language: + create_kwargs["language"] = language with open(file_path, "rb") as audio_file: transcription = client.audio.transcriptions.create( - model=model_name, file=audio_file, - response_format="text", + **create_kwargs, ) transcript_text = str(transcription).strip() - logger.info("Transcribed %s via Groq API (%s, %d chars)", - Path(file_path).name, model_name, len(transcript_text)) + logger.info("Transcribed %s via Groq API (%s, lang=%s, %d chars)", + Path(file_path).name, model_name, language or "auto", len(transcript_text)) return {"success": True, "transcript": transcript_text, "provider": "groq"} finally: @@ -1376,6 +1418,10 @@ def _transcribe_openai( return {"success": False, "transcript": "", "error": str(exc)} base_url = base_url or fallback_base + # Language: stt..language > stt.language > env > auto-detect. + # Explicit language hint improves accuracy for non-English languages. + language = _resolve_stt_language(provider_label) + if not _HAS_OPENAI: return {"success": False, "transcript": "", "error": "openai package not installed"} @@ -1391,11 +1437,16 @@ def _transcribe_openai( client = OpenAI(api_key=api_key, base_url=base_url, timeout=30, max_retries=0) try: with open(file_path, "rb") as audio_file: - transcription = client.audio.transcriptions.create( - model=model_name, - file=audio_file, - response_format="text" if model_name == "whisper-1" else "json", - ) + create_kwargs = { + "model": model_name, + "file": audio_file, + "response_format": "text" if model_name == "whisper-1" else "json", + } + if language: + create_kwargs["language"] = language + logger.debug("Using language hint '%s' for OpenAI STT", language) + + transcription = client.audio.transcriptions.create(**create_kwargs) transcript_text = _extract_transcript_text(transcription) logger.info( @@ -1446,10 +1497,15 @@ def _transcribe_mistral(file_path: str, model_name: str) -> Dict[str, Any]: with Mistral(api_key=api_key) as client: with open(file_path, "rb") as audio_file: - result = client.audio.transcriptions.complete( - model=model_name, - file={"content": audio_file, "file_name": Path(file_path).name}, - ) + complete_kwargs: Dict[str, Any] = { + "model": model_name, + "file": {"content": audio_file, "file_name": Path(file_path).name}, + } + # Language: stt.mistral.language > stt.language > env > auto. + language = _resolve_stt_language("mistral") + if language: + complete_kwargs["language"] = language + result = client.audio.transcriptions.complete(**complete_kwargs) transcript_text = _extract_transcript_text(result) logger.info( @@ -1496,11 +1552,7 @@ def _transcribe_xai(file_path: str, model_name: str) -> Dict[str, Any]: or creds.get("base_url") or XAI_STT_BASE_URL ).strip().rstrip("/") - language = str( - xai_config.get("language") - or os.getenv("HERMES_LOCAL_STT_LANGUAGE") - or DEFAULT_LOCAL_STT_LANGUAGE - ).strip() + language = _resolve_stt_language("xai", stt_config) or "" # .get("format", True) already defaults to True when the key is absent; # is_truthy_value only normalizes truthy/falsy strings from config. use_format = is_truthy_value(xai_config.get("format", True)) @@ -1591,7 +1643,9 @@ def _transcribe_elevenlabs(file_path: str, model_name: str) -> Dict[str, Any]: or get_env_value("ELEVENLABS_STT_BASE_URL") or ELEVENLABS_STT_BASE_URL ).strip().rstrip("/") - language_code = str(elevenlabs_config.get("language_code") or "").strip() + language_code = _resolve_stt_language( + "elevenlabs", stt_config, extra_keys=("language_code",) + ) or "" tag_audio_events = is_truthy_value(elevenlabs_config.get("tag_audio_events", False)) diarize = is_truthy_value(elevenlabs_config.get("diarize", False)) @@ -1768,7 +1822,8 @@ def transcribe_audio(file_path: str, model: Optional[str] = None) -> Dict[str, A return _transcribe_local_command(file_path, model_name) if provider == "groq": - model_name = model or DEFAULT_GROQ_STT_MODEL + groq_cfg = stt_config.get("groq") or {} + model_name = model or groq_cfg.get("model") or DEFAULT_GROQ_STT_MODEL return _transcribe_groq(file_path, model_name) if provider == "openai": @@ -1827,7 +1882,7 @@ def transcribe_audio(file_path: str, model: Optional[str] = None) -> Dict[str, A # forwards ``language`` from there. Top-level ``model`` argument # overrides any config-set model. plugin_cfg = stt_config.get(provider, {}) if isinstance(stt_config.get(provider), dict) else {} - plugin_language = plugin_cfg.get("language") + plugin_language = _resolve_stt_language(provider, stt_config) plugin_model = model or plugin_cfg.get("model") plugin_result = _dispatch_to_plugin_provider( file_path, diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 362652974035..ec99660fd783 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -102,7 +102,7 @@ Hermes reads environment variables from the process environment and, for user-ma | `HERMES_MODEL` | Override model name at process level (used by cron scheduler; prefer `config.yaml` for normal use) | | `VOICE_TOOLS_OPENAI_KEY` | Preferred OpenAI key for OpenAI speech-to-text and text-to-speech providers | | `HERMES_LOCAL_STT_COMMAND` | Optional local speech-to-text command template. Supports `{input_path}`, `{output_dir}`, `{language}`, and `{model}` placeholders | -| `HERMES_LOCAL_STT_LANGUAGE` | Default language passed to `HERMES_LOCAL_STT_COMMAND` or auto-detected local `whisper` CLI fallback (default: `en`) | +| `HERMES_LOCAL_STT_LANGUAGE` | Default language hint for STT. Used by the `local` (faster-whisper) provider, `HERMES_LOCAL_STT_COMMAND`, the local `whisper` CLI fallback (default: `en`), Groq, and xAI when no per-provider `language` is set in `config.yaml` | | `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`). Also scopes the gateway PID file and systemd service name, so multiple installations can run concurrently | | `HERMES_GIT_BASH_PATH` | **Windows only.** Override `bash.exe` discovery for the terminal tool. Points at any bash — full Git-for-Windows install, WSL bash via symlink, MSYS2, Cygwin. The installer sets this automatically to the PortableGit it provisioned. See the [Windows (Native) Guide](../user-guide/windows-native.md#how-hermes-runs-shell-commands-on-windows) | | `HERMES_DISABLE_WINDOWS_UTF8` | **Windows only.** Set to `1` to disable the UTF-8 stdio shim (`configure_windows_stdio()`) and fall back to the console's locale code page. Useful for bisecting encoding bugs; rarely the right setting in normal operation | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 4a773b30d53a..c1981b0130de 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -1713,19 +1713,27 @@ stt: enabled: true # Auto-transcribe inbound voice messages (default: true) echo_transcripts: true # Post raw transcripts back to the chat as 🎙️ "..." (default: true) provider: "local" # "local" | "groq" | "openai" | "mistral" + language: "" # GLOBAL language hint for every provider (ISO-639-1, e.g. "en", "he", "uk"); blank = auto-detect local: model: "base" # tiny, base, small, medium, large-v3 + language: "" # per-provider override of stt.language + initial_prompt: "" # optional whisper prompt to bias vocabulary/script (e.g. Simplified Chinese) + groq: + language: "" # per-provider override of stt.language openai: model: "whisper-1" # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe + language: "" # per-provider override of stt.language # model: "whisper-1" # Legacy fallback key still respected ``` +Language resolution is the same for **every** STT provider (local, groq, openai, mistral, xai, elevenlabs, deepinfra, command providers, and plugins): `stt..language` → `stt.language` → `HERMES_LOCAL_STT_LANGUAGE` env var → provider auto-detect. Setting `stt.language` once fixes the common "my voice notes get transcribed in the wrong language" problem regardless of which provider is active. + Set `stt.echo_transcripts: false` when the gateway should transcribe voice notes for the agent but must not post the raw transcript back to the chat (for example, customer-facing WhatsApp bots). Provider behavior: - `local` uses `faster-whisper` running on your machine. Install it separately with `pip install faster-whisper`. -- `groq` uses Groq's Whisper-compatible endpoint and reads `GROQ_API_KEY`. +- `groq` uses Groq's Whisper-compatible endpoint and reads `GROQ_API_KEY`. Pass `stt.groq.language` (or the global `HERMES_LOCAL_STT_LANGUAGE` env var) to skip auto-detection and reduce latency. - `openai` uses the OpenAI speech API and reads `VOICE_TOOLS_OPENAI_KEY`. If the requested provider is unavailable, Hermes falls back automatically in this order: `local` → `groq` → `openai`. diff --git a/website/docs/user-guide/features/tts.md b/website/docs/user-guide/features/tts.md index 726a43c7724e..920f360f7a35 100644 --- a/website/docs/user-guide/features/tts.md +++ b/website/docs/user-guide/features/tts.md @@ -429,12 +429,16 @@ stt: provider: "local" # "local" | "groq" | "openai" | "mistral" | "xai" local: model: "base" # tiny, base, small, medium, large-v3 + language: "" # optional ISO-639-1 hint; blank = use HERMES_LOCAL_STT_LANGUAGE if set, else auto-detect + groq: + language: "" # optional ISO-639-1 hint; blank = use HERMES_LOCAL_STT_LANGUAGE if set, else auto-detect openai: model: "whisper-1" # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe mistral: model: "voxtral-mini-latest" # voxtral-mini-latest, voxtral-mini-2602 xai: model: "grok-stt" # xAI Grok STT + language: "" # optional ISO-639-1 hint; blank = use HERMES_LOCAL_STT_LANGUAGE if set, else "en" ``` ### Provider Details @@ -449,7 +453,7 @@ stt: | `medium` | ~1.5 GB | Slower | Great | | `large-v3` | ~3 GB | Slowest | Best | -**Groq API** — Requires `GROQ_API_KEY`. Good cloud fallback when you want a free hosted STT option. +**Groq API** — Requires `GROQ_API_KEY`. Good cloud fallback when you want a free hosted STT option. Set `stt.groq.language` (or the global `HERMES_LOCAL_STT_LANGUAGE` env var) to skip Whisper's auto-detect and reduce latency on known-language audio. **OpenAI API** — Accepts `VOICE_TOOLS_OPENAI_KEY` first and falls back to `OPENAI_API_KEY`. Supports `whisper-1`, `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`. diff --git a/website/docs/user-guide/features/voice-mode.md b/website/docs/user-guide/features/voice-mode.md index 7c3222b6438a..a4f64be3f3a4 100644 --- a/website/docs/user-guide/features/voice-mode.md +++ b/website/docs/user-guide/features/voice-mode.md @@ -414,6 +414,9 @@ stt: provider: "local" # "local" (free) | "groq" | "openai" | "mistral" | "xai" local: model: "base" # tiny, base, small, medium, large-v3 + language: "" # optional ISO-639-1 hint; blank = use HERMES_LOCAL_STT_LANGUAGE if set, else auto-detect + groq: + language: "" # optional ISO-639-1 hint; blank = use HERMES_LOCAL_STT_LANGUAGE if set, else auto-detect # model: "whisper-1" # Legacy: used when provider is not set # Text-to-Speech