текстовая игра на основе llm + interrupt: README.md

2026-05-27 11:43:47 +00:00
parent 3a2d28bddf
commit 1c344658a6
1 changed files with 133 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Interactive Text Adventure – LLM + Interrupt
+
+A lightweight Python project that turns a large language model (LLM) into an interactive “choose‑your‑own‑adventure” game.  
+The story is generated by the LLM, then paused for user input via a console prompt (`questionary`). After the player selects an option, the graph resumes and the LLM writes a short ending based on that choice.
+
+> **TL;DR** – Run `python game.py`, answer the prompts, and watch the AI craft your story in real time.
+
+---
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Running the Game](#running-the-game)
+- [Example Session](#example-session)
+- [Project Structure](#project-structure)
+
+---
+
+## What It Does
+
+1. **Generate a story hook** – The LLM creates an opening paragraph and three possible actions.
+2. **Pause for user input** – Using `questionary`, the script presents the options and waits for the player to choose one.
+3. **Resume & finish** – The graph resumes, feeding the chosen option back into the LLM, which writes a short ending that reflects the decision.
+
+The whole flow is orchestrated by **LangGraph**, which manages state (`GameState`) and handles the custom `interrupt` node that triggers the human‑in‑the‑loop pause.
+
+---
+
+## Prerequisites
+
+| Component | Minimum Version | Notes |
+|-----------|-----------------|-------|
+| Python    | 3.10+           | Tested on 3.12 |
+| OpenAI API key | – | Set as `OPENAI_API_KEY` environment variable or in a `.env` file. |
+| LangGraph | Latest (pip install) | Handles the graph logic and checkpointing. |
+| LangChain‑OpenAI | Latest | Provides the LLM wrapper (`ChatOpenAI`). |
+| Questionary | Latest | For interactive console prompts. |
+
+> **Optional** – If you want to run locally without an OpenAI key, you can replace `ChatOpenAI` with a local model (e.g., Ollama) and adjust the import accordingly.
+
+---
+
+## Installation
+
+```bash
+# Clone the repo (or copy the files)
+git clone https://github.com/your-username/interactive-adventure.git
+cd interactive-adventure
+
+# Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+`requirements.txt` contains:
+
+```text
+langgraph>=0.1.0
+langchain-openai>=0.2.0
+questionary>=1.10.0
+python-dotenv>=1.0.0   # optional, for .env support
+```
+
+---
+
+## Running the Game
+
+The entire game is contained in a single script: `game.py`.
+
+```bash
+# Make sure your OpenAI key is available:
+export OPENAI_API_KEY="sk-..."
+
+# Run the game
+python game.py
+```
+
+If you prefer to use a `.env` file, create a file named `.env` in the project root with:
+
+```dotenv
+OPENAI_API_KEY=sk-...
+```
+
+The script will automatically load it via `python-dotenv`.
+
+---
+
+## Example Session
+
+Below is a typical console interaction. The AI generates an opening and three actions; you pick one; the AI finishes.
+
+```
+$ python game.py
+Welcome to the Interactive Adventure!
+
+[Story Hook]
+You find yourself in a dimly lit cavern, the air thick with damp stone. A faint glow emanates from a crystal embedded in the wall.
+
+Choose your action:
+1) Inspect the crystal closely.
+2) Search for an exit.
+3) Call out to see if anyone is nearby.
+
+Your choice: 1
+
+[Ending]
+You reach out and touch the crystal. It hums, releasing a burst of light that reveals a hidden passage behind the stone wall. The adventure continues...
+```
+
+Feel free to experiment with different choices – each run will produce a unique narrative!
+
+---
+
+## Project Structure
+
+```text
+interactive-adventure/
+├── game.py          # Main script containing LangGraph logic
+├── requirements.txt
+└── README.md
+```
+
+- **`game.py`** – Defines `GameState`, the graph nodes (`generate_story`, `interrupt_node`, `finish_ending`), and runs the loop.
+- **`requirements.txt`** – Lists all Python dependencies.
+
+---
+
+Happy adventuring! 🚀