Improve AI module comments and README

README.md

@@ -18,6 +18,8 @@
 `Alexander Smart Speaker` слушает ключевое слово `Alexandr`, распознает речь, маршрутизирует команду в нужный модуль и озвучивает ответ.
 Проект оптимизирован под русский язык, но поддерживает RU/EN сценарии (включая перевод и mixed-language TTS).
 
+Проект собран как локальная голосовая колонка под Linux: активация по wake word, распознавание речи, маршрутизация команд, ответ через AI или встроенные модули и затем озвучка результата.
+
 ## Возможности
 
 - Активация по wake word `Alexandr` (Porcupine).
@@ -45,6 +47,13 @@ flowchart TD
     F --> G[Follow-up режим или ожидание wake word]
 ```
 
+## Что Важно В Этой Реализации
+
+- Контекст диалога хранится в памяти текущей сессии, поэтому после первого вопроса можно продолжать разговор без потери нити.
+- Системная роль ассистента и `ROLE_JSON` сохраняются для всех поддерживаемых AI-провайдеров.
+- Для AI используется строго один активный API key. Если в `.env` оставить несколько ключей, ассистент покажет ошибку конфигурации вместо случайного выбора.
+- Поддержка провайдеров сделана внутри одного модуля, но с разным форматом запросов для OpenAI-compatible API и Anthropic.
+
 ## Быстрый старт
 
 ### 1) Системные зависимости (Ubuntu/Debian)
@@ -86,6 +95,19 @@ PORCUPINE_ACCESS_KEY=...
 
 Если одновременно оставить несколько AI API key, ассистент вернет ошибку: он не будет выбирать провайдера наугад.
 
+Пример:
+
+```ini
+# правильно
+OPENAI_API_KEY=sk-...
+# GEMINI_API_KEY=...
+# ANTHROPIC_API_KEY=...
+
+# неправильно
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=AIza...
+```
+
 ### 4) Запуск
 
 ```bash
@@ -146,6 +168,15 @@ python run.py
 
 Память текущего диалога, история сообщений и `ROLE_JSON` системной роли сохраняются для всех поддерживаемых AI-провайдеров.
 
+## Как Выбирается AI-Провайдер
+
+1. Приложение проверяет, какие AI API key реально активны в `.env`.
+2. Если активен ровно один ключ, используется именно он.
+3. Если активны несколько ключей, ассистент возвращает ошибку конфигурации.
+4. Если активных ключей нет, приложение ориентируется на `AI_PROVIDER`, но без ключа работать не сможет.
+
+Такое поведение сделано специально, чтобы конфигурация была предсказуемой и при демонстрации не возникало скрытого переключения между сервисами.
+
 ## Полезные команды
 
 | Команда | Что делает |
@@ -179,6 +210,7 @@ alexander_smart-speaker/
 | STT не распознает речь | `DEEPGRAM_API_KEY`, сетевой доступ, выбранный микрофон |
 | Нет звука | корректное аудиоустройство и доступность `pactl`/`amixer` |
 | Будильник/таймер не звонит | наличие `mpg123` в системе |
+| Ошибка про несколько AI API | в `.env` должен остаться только один незакомментированный AI ключ |
 | Spotify не управляется | заполнены `SPOTIFY_*`, есть активное устройство, Premium-аккаунт |
 
 ## Лицензия