feat: refine assistant logic and update docs

app/core/config.py

@@ -7,15 +7,49 @@ Loads environment variables from .env file.
 # Он загружает настройки из файла .env (переменные окружения) и определяет константы.
 
 import os
+import re
 import time
+from io import StringIO
 from pathlib import Path
-from dotenv import load_dotenv
+from dotenv import dotenv_values
 
 # Базовая директория проекта (корневая папка, где лежит .env)
 BASE_DIR = Path(__file__).resolve().parents[2]
 
-# Загружаем переменные из файла .env в корневом каталоге
-load_dotenv(BASE_DIR / ".env")
+def _load_project_env(env_path: Path) -> None:
+    """
+    Загружает .env, игнорируя строковый "шум" без формата KEY=VALUE.
+    Это делает конфиг устойчивым к человеческим комментариям без символа '#'.
+    """
+    if not env_path.exists():
+        return
+
+    raw_text = env_path.read_text(encoding="utf-8")
+    sanitized_lines = []
+
+    for line in raw_text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            sanitized_lines.append(line)
+            continue
+
+        if "=" in line:
+            key = line.split("=", 1)[0].strip()
+            if re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", key):
+                sanitized_lines.append(line)
+                continue
+
+        # Игнорируем невалидные строки, чтобы dotenv не шумел warning'ами.
+        sanitized_lines.append(f"# ignored invalid env line: {line}")
+
+    parsed = dotenv_values(stream=StringIO("\n".join(sanitized_lines)))
+    for key, value in parsed.items():
+        if key and value is not None and os.getenv(key) is None:
+            os.environ[key] = value
+
+
+# Загружаем переменные из .env в корневом каталоге
+_load_project_env(BASE_DIR / ".env")
 
 # --- Настройки AI ---
 # AI_PROVIDER опционален. Приоритет у единственного активного AI API key.
@@ -29,6 +63,22 @@ OPENROUTER_API_URL = os.getenv(
     "OPENROUTER_API_URL", "https://openrouter.ai/api/v1/chat/completions"
 )
 
+
+def _read_clamped_float_env(name: str, default: str, minimum: float, maximum: float) -> float:
+    try:
+        value = float(os.getenv(name, default))
+    except Exception:
+        value = float(default)
+    return max(minimum, min(maximum, value))
+
+
+def _read_clamped_int_env(name: str, default: str, minimum: int, maximum: int) -> int:
+    try:
+        value = int(os.getenv(name, default))
+    except Exception:
+        value = int(default)
+    return max(minimum, min(maximum, value))
+
 # OpenAI
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
 OPENAI_MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
@@ -65,6 +115,13 @@ OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "llama3.1:8b")
 OLLAMA_API_URL = os.getenv(
     "OLLAMA_API_URL", "http://localhost:11434/v1/chat/completions"
 )
+AI_CHAT_TEMPERATURE = _read_clamped_float_env("AI_CHAT_TEMPERATURE", "0.9", 0.0, 2.0)
+AI_CHAT_MAX_TOKENS = _read_clamped_int_env("AI_CHAT_MAX_TOKENS", "220", 80, 700)
+AI_CHAT_MAX_CHARS = _read_clamped_int_env("AI_CHAT_MAX_CHARS", "320", 120, 1200)
+AI_INTENT_TEMPERATURE = _read_clamped_float_env("AI_INTENT_TEMPERATURE", "0.0", 0.0, 1.0)
+AI_TRANSLATION_TEMPERATURE = _read_clamped_float_env(
+    "AI_TRANSLATION_TEMPERATURE", "0.2", 0.0, 1.0
+)
 
 # --- Настройки распознавания речи (Deepgram) ---
 # Ключ для облачного STT (Speech-to-Text)
@@ -86,6 +143,42 @@ WAKE_WORD_ALIASES = (
 PORCUPINE_KEYWORD_PATH = BASE_DIR / "assets" / "models" / "Waltron_en_linux_v4_0_0.ppn"
 # Чувствительность wake word (0..1). Выше = ловит легче, но больше ложных срабатываний.
 PORCUPINE_SENSITIVITY = float(os.getenv("PORCUPINE_SENSITIVITY", "0.8"))
+# Антифантомный фильтр wake word по RMS-сигналу.
+# Чем выше WAKEWORD_MIN_RMS / WAKEWORD_RMS_MULTIPLIER, тем меньше ложных срабатываний,
+# но тем выше риск не распознать очень тихую активацию.
+try:
+    WAKEWORD_MIN_RMS = float(os.getenv("WAKEWORD_MIN_RMS", "120"))
+except Exception:
+    WAKEWORD_MIN_RMS = 120.0
+WAKEWORD_MIN_RMS = max(0.0, WAKEWORD_MIN_RMS)
+try:
+    WAKEWORD_RMS_MULTIPLIER = float(os.getenv("WAKEWORD_RMS_MULTIPLIER", "1.7"))
+except Exception:
+    WAKEWORD_RMS_MULTIPLIER = 1.7
+WAKEWORD_RMS_MULTIPLIER = max(1.0, WAKEWORD_RMS_MULTIPLIER)
+try:
+    WAKEWORD_HIT_COOLDOWN_SECONDS = float(
+        os.getenv("WAKEWORD_HIT_COOLDOWN_SECONDS", "1.2")
+    )
+except Exception:
+    WAKEWORD_HIT_COOLDOWN_SECONDS = 1.2
+WAKEWORD_HIT_COOLDOWN_SECONDS = max(0.0, WAKEWORD_HIT_COOLDOWN_SECONDS)
+try:
+    WAKEWORD_REOPEN_GRACE_SECONDS = float(
+        os.getenv("WAKEWORD_REOPEN_GRACE_SECONDS", "0.45")
+    )
+except Exception:
+    WAKEWORD_REOPEN_GRACE_SECONDS = 0.45
+WAKEWORD_REOPEN_GRACE_SECONDS = max(0.0, WAKEWORD_REOPEN_GRACE_SECONDS)
+WAKEWORD_ENABLE_FALLBACK_STT = (
+    os.getenv("WAKEWORD_ENABLE_FALLBACK_STT", "0").strip().lower()
+    in {"1", "true", "yes", "on"}
+)
+# При активации wake word музыка приглушается до указанного процента от текущего уровня.
+WAKEWORD_MUSIC_DUCK_PERCENT = _read_clamped_int_env(
+    "WAKEWORD_MUSIC_DUCK_PERCENT", "20", 1, 100
+)
+WAKEWORD_MUSIC_DUCK_RATIO = WAKEWORD_MUSIC_DUCK_PERCENT / 100.0
 
 # --- Параметры аудио ---
 # Частота дискретизации для микрофона (стандарт для распознавания речи)
@@ -134,17 +227,17 @@ _stt_sfx_default = BASE_DIR / "assets" / "sounds" / "alisa-golosovoj-pomoschnik.
 if not _stt_sfx_default.exists():
     _stt_sfx_default = Path.home() / "Music" / "alisa-golosovoj-pomoschnik.mp3"
 STT_START_SOUND_PATH = os.getenv("STT_START_SOUND_PATH", "").strip() or str(_stt_sfx_default)
-try:
-    STT_START_SOUND_VOLUME = float(os.getenv("STT_START_SOUND_VOLUME", "0.25"))
-except Exception:
-    STT_START_SOUND_VOLUME = 0.25
-STT_START_SOUND_VOLUME = max(0.0, min(1.0, STT_START_SOUND_VOLUME))
+# Звук старта STT всегда на 100% громкости, чтобы по уровню был как обычный TTS-ответ.
+STT_START_SOUND_VOLUME = 1.0
 # Голос для русского языка (eugene - мужской голос)
 TTS_SPEAKER = "eugene"  # Доступные (ru): aidar, baya, kseniya, xenia, eugene
 # Голос для английского языка
 TTS_EN_SPEAKER = os.getenv("TTS_EN_SPEAKER", "en_0")
 # Частота дискретизации для воспроизведения (качество звука)
 TTS_SAMPLE_RATE = 48000
+# Скорость TTS: 1.0 = обычная, <1.0 = медленнее, >1.0 = быстрее.
+# По умолчанию чуть медленнее для более разборчивой речи.
+TTS_SPEED = _read_clamped_float_env("TTS_SPEED", "0.96", 0.85, 1.15)
 
 # --- Настройки погоды ---
 WEATHER_LAT = os.getenv("WEATHER_LAT")