alisa_chess

Голосовой шахматный навык для Яндекс.Алисы: игра в шахматы вслепую с озвучиванием ходов.

Возможности

• Голосовая игра в шахматы через Яндекс.Алису
• Шахматный движок Stockfish (локальный бинарь, запускается по UCI через python-chess)
• Распознавание ходов в нескольких форматах: SAN, длинная нотация (e2e4), русскоязычные команды («пешка е4», «конь на эф 3»)
• Превращение пешки (с явным указанием фигуры или ферзём по умолчанию)
• Специальные команды и интенты: помощь, новая игра, сдача, ничья, отмена хода, показать доску, выбор уровня сложности
• Восстановление состояния игры между запросами через user_state_update
• Идемпотентность повторных запросов по message_id
• Поддержка YANDEX.REPEAT через session_state
• Версионируемая схема состояния игры (Pydantic V2) с graceful fallback при ошибках десериализации

Состояния навыка

Перечислены в skill_state.py:

• INITIATED — приветствие, ожидание согласия на игру
• WAITING_CONFIRM — ожидание подтверждения начала игры
• WAITING_COLOR — выбор цвета пользователем
• WAITING_SKILL_LEVEL — выбор уровня сложности
• WAITING_MOVE — ожидание хода пользователя
• WAITING_DRAW_CONFIRM — подтверждение предложения ничьей
• WAITING_RESIGN_CONFIRM — подтверждение сдачи
• WAITING_NEWGAME_CONFIRM — подтверждение начала новой партии
• GAME_OVER — партия завершена

Полная диаграмма переходов: docs/diagrams/state_diagram.md.

Голосовые команды

Доступны в большинстве состояний игры:

• «Помощь» — справка по игре
• «Покажи доску» — текущая позиция в виде FEN/Unicode
• «Новая игра» — начать новую партию
• «Уровень сложности» — изменить уровень игры
• «Повтори» — повтор последнего ответа Алисы (YANDEX.REPEAT)
• «Отмени ход» / «Назад» — откатить последний ход (если доступно)
• «Ничья» — предложить ничью
• «Сдаюсь» — сдаться

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/axtrace/alisa_chess.git
   cd alisa_chess

2. Создайте и активируйте виртуальное окружение:

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Установите Python-зависимости:

   pip install -r requirements.txt

4. Положите бинарь Stockfish в корень проекта рядом с alice_chess.py под именем stockfish (исполняемый файл):

   chmod +x ./stockfish

   Бинарь не входит в репозиторий, его нужно скачать или собрать самостоятельно с официального сайта.

Структура проекта

• alice_chess.py — основной класс AliceChess, точка входа в обработку запроса
• alice_serverless.py — точка входа для Yandex Cloud Functions (handler(event, context))
• game.py — игровая логика, обёртка над chess.Board и UCI-движком Stockfish
• game_state.py — Pydantic-схемы GameStateV1/GameStateV2, миграции и сериализация
• skill_state.py — enum состояний навыка
• handlers/ — обработчики состояний (WaitingMoveHandler, InitiatedHandler, BaseConfirmationHandler и т. д.)
• request_validators/ — валидаторы интентов
• move_extractor.py — парсинг хода пользователя из интентов и текста (включая кириллицу)
• speaker.py, text_preparer.py — построение текста и TTS-ответа
• texts.py — шаблоны фраз
• intents/ — YAML-описания интентов Алисы
• tests/ — юнит-тесты (pytest/unittest)
• docs/ — архитектурная документация и диаграммы

Пример сценария

Алиса: Давайте сыграем в шахматы.
Юзер: Да.
Алиса: За какую сторону играем — белые или чёрные?
Юзер: Белые.
Алиса: Хорошо. Ваш ход.
Юзер: e2 e4.
Алиса: Конь f6. Ваш ход.
Юзер: Покажи доску.
Алиса: [показывает текущую позицию]
...
Алиса: Мат. Спасибо за игру.

Формат состояния

Состояние игры передаётся через state.user.game_state и обновляется через user_state_update. Схема описана в game_state.py (GameStateV2):

{
  "request": {"command": "e2e4", "...": "..."},
  "state": {
    "user": {
      "game_state": {
        "_version": 2,
        "board_state": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
        "skill_state": "WAITING_MOVE",
        "prev_skill_state": "WAITING_CONFIRM",
        "user_color": "WHITE",
        "comp_color": "BLACK",
        "skill_level": 1,
        "time_level": 0.1
      }
    },
    "session": {
      "last_message_id": 3,
      "previous_response": {"text": "...", "tts": "...", "end_session": false}
    }
  }
}

• board_state — FEN текущей позиции.
• skill_state / prev_skill_state — текущее и предыдущее состояния навыка (значения из SkillState).
• _version — версия схемы; при чтении состояний с другой схемой выполняется автоматическая миграция (см. GameState.from_dict).
• session_state.last_message_id — используется для идемпотентности (повторный message_id возвращает предыдущий ответ).
• session_state.previous_response — последний ответ, возвращается при YANDEX.REPEAT.

Тестирование

Запуск всех тестов:

python3 -m pytest tests/ -v

Или через unittest:

python3 -m unittest discover tests

Развёртывание

Поддерживается развёртывание как Yandex Cloud Function. Точка входа — alice_serverless.handler. Workflow для деплоя лежат в .github/workflows/. Подробнее в docs/deployment.md.

Изменения после одобрения модератора: Удалены процессы Manual Deploy to TESTING YaCloud Functions и Manual Deploy to PROD YaCloud Functions, остались только Manual Deploy 2 PROD YaCloud Functions и Auto Deploy 2 TESTING YaCloud Functions. Переменные оставлены с постфиксом _2 для совместимости.

Архитектура

• Основная логика — класс AliceChess; обрабатывает запрос как контекстный менеджер, гарантированно закрывая UCI-движок.
• Игровая обёртка — класс Game с ленивой инициализацией Stockfish и обязательным engine.quit() через __exit__.
• Маршрутизация по состояниям реализована в AliceChess.handle_request на основе SkillState.
• Каждое состояние обрабатывается соответствующим хендлером из handlers/, наследующим BaseHandler.
• Специальные команды (помощь, показ доски, повтор, новая игра и т. д.) обрабатываются в SpecialIntentHandler независимо от текущего состояния.
• Обработка ошибок двухуровневая: BaseHandler.safe_handle возвращает дружелюбное сообщение, а alice_serverless.handler ловит катастрофические исключения и не теряет user_state_update.

Подробности: docs/architecture.md, диаграммы состояний и последовательности в docs/diagrams/.

Планы развития

Два крупных проекта для оптимизации производительности:

• Кэш позиций в Redis (ADR-0004) — ускорение повторных позиций в 50–100x раз
• Stockfish микросервис (ADR-0005) — исключение холодного старта, persistent engine с fallback

Полный roadmap с графиком и задачами: docs/ROADMAP.md.

Технические детали

• Шахматный движок: Stockfish, локальный бинарь, UCI-протокол через python-chess.
• Валидация состояния: Pydantic v2 (requirements.txt).
• Сервер исторически использовал отдельный HTTP-API (axtrace/chessapi) — в текущей версии Stockfish запускается локально внутри функции.

Участие в разработке

PR приветствуются. Перед отправкой — прогоните тесты и убедитесь, что pytest зелёный.

Лицензия

MIT License © 2024 axtrace