Добавлен README.md

2026-05-28 15:51:49 +00:00
parent 1383d68fb9
commit 1c66078cb2
1 changed files with 106 additions and 81 deletions
@@ -1,95 +1,120 @@
-# Мини‑игра «Выбери свою историю»
+# Текстовая игра «Выбери свою историю»  
+*Интерактивная история с LLM и прерыванием (LangGraph)*  

-## Описание
+---

-Проект реализует интерактивную текстовую игру на основе больших языковых моделей (LLM).  
-Сценарий игры строится следующим образом:
+## 📖 Описание

-1. **LLM** генерирует начальную завязку и несколько вариантов действий для главного героя.
-2. С помощью **LangGraph** выполнение модели ставится в состояние *прерывания* – пользователь получает список вариантов через консольный интерфейс.
-3. Пользователь выбирает один из вариантов при помощи `questionary`.
-4. После выбора LLM дописывает короткую концовку, учитывая выбранный путь.
+Проект реализует мини‑игру **«выбери свою историю»** на основе больших языковых моделей.  
+- LLM генерирует начальную завязку и несколько вариантов действий.  
+- Пользователь выбирает один из них через консольный интерфейс (`questionary`).  
+- После выбора модель дописывает короткую концовку, завершая сцену.

-Таким образом игрок участвует в создании истории в реальном времени, а модель реагирует на его решения.
+Граф выполнения реализован с помощью **LangGraph**:  
+- узел генерации текста → узел прерывания (выбор пользователя) → узел завершения.  
+- Состояние сохраняется в чекпоинтере, чтобы можно было продолжить игру после перезапуска.

-## Предварительные требования
+---
+
+## ⚙️ Предварительные требования

 | Пакет | Версия |
 |-------|--------|
 | Python | 3.10+ |
 | pip | любой актуальный |

-Для работы с OpenAI API понадобится ключ `OPENAI_API_KEY`.  
-Установите переменную окружения:
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
-
-## Установка
-
-1. Клонируйте репозиторий (или скачайте файлы):
-
-   ```bash
-   git clone https://github.com/yourname/text-adventure.git
-   cd text-adventure
-   ```
-
-2. Создайте и активируйте виртуальное окружение:
-
-   ```bash
-   python -m venv .venv
-   source .venv/bin/activate      # Linux/macOS
-   .\.venv\Scripts\activate       # Windows
-   ```
-
-3. Установите зависимости из `requirements.txt` (или вручную):
-
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-   Если файла нет, установите пакеты по отдельности:
-
-   ```bash
-   pip install langgraph langchain langchain-openai questionary rich
-   ```
-
-## Запуск
-
-После установки и настройки переменной окружения просто запустите скрипт:
-
-```bash
-python solution.py
-```
-
-Вы увидите в консоли начальную историю, список вариантов действий и сможете выбрать один из них. После выбора LLM сгенерирует короткую концовку.
-
-## Пример работы
-
-```
-> Запуск игры...
-
-Начальная сцена:
-  Вы просыпаетесь в темном лесу. Вокруг слышен шорох ветвей.
-  Что вы будете делать?
-
-1) Пойти к свету
-2) Остановиться и послушать шумы
-3) Спрятаться за деревом
-
-Выберите номер варианта: 1
-
-Вы выбрали: "Пойти к свету"
-
-Концовка:
-  Вы идёте по тропинке, пока не видите маленькую хижину. Внутри вы находите старую книгу...
-```
-
-> **Важно**  
-> Если при запуске возникнет ошибка `openai.error.AuthenticationError`, проверьте корректность переменной `OPENAI_API_KEY`.
+> **Важно**: Для работы с OpenAI требуется переменная окружения `OPENAI_API_KEY`.  
+> Если вы хотите использовать другую модель, настройте соответствующий провайдер в `solution.py`.

 ---

-*Автор: [Ваше имя]*  
-*Дата: 2026‑05‑28*
+## 📦 Установка
+
+```bash
+# Клонируйте репозиторий (или скачайте архив)
+git clone https://github.com/yourname/text-adventure-llm.git
+cd text-adventure-llm
+
+# Создайте виртуальное окружение (рекомендуется)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# Установите зависимости
+pip install -r requirements.txt
+```
+
+`requirements.txt`:
+
+```text
+langgraph>=0.1.0
+langchain>=0.2.0
+langchain-openai>=0.1.0
+questionary>=1.10.0
+rich>=13.0.0
+```
+
+---
+
+## ▶️ Запуск
+
+```bash
+# Установите переменную окружения с ключом OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Запустите игру
+python solution.py
+```
+
+> **Tip**: Если вы используете Windows PowerShell, команда будет:
+> ```powershell
+> $env:OPENAI_API_KEY = "sk-..."
+> python solution.py
+> ```
+
+---
+
+## 🎮 Пример работы
+
+```text
+$ python solution.py
+Добро пожаловать в интерактивную историю!
+
+Завязка:
+  Вы просыпаетесь в таинственном лесу, окружённом странными светлячками. Вокруг слышен шёпот ветра.
+
+Варианты действий:
+1) Исследовать ближайший домик
+2) Пойти к озеру
+3) Спрятаться за деревом
+
+Выберите действие (1‑3): 2
+
+Вы выбрали: "Пойти к озеру"
+
+Концовка:
+  Вы подходите к зеркальному озеру, и вода начинает светиться. Внезапно из воды выскакивает древний дух, который дарует вам силу видеть будущее. Игра завершена.
+```
+
+---
+
+## 📚 Как это работает
+
+1. **Генерация** – LLM создаёт завязку и варианты действий.  
+2. **Прерывание** – `questionary` выводит список вариантов; пользователь вводит номер.  
+3. **Завершение** – выбранный вариант передаётся в модель, которая генерирует короткую концовку.  
+
+Все состояния сохраняются в чекпоинтере (`checkpoint.json`) – при следующем запуске можно продолжить с того же места.
+
+---
+
+## 🤝 Вклад
+
+Если хотите улучшить игру (добавить новые сценарии, изменить логику выбора, интегрировать другие LLM), откройте Pull Request. Убедитесь, что тесты проходят (`pytest`).
+
+---
+
+## 📄 Лицензия
+
+MIT License – свободно используйте и модифицируйте проект.
+
+---