lonpatovaadelina/homework-solutions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
lonpatovaadelina
2026-05-27 12:24:54 +00:00
parent e3929b9005
commit c62ee6a213
1 changed files with 70 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
solutions/69b1a07c67bbf488a1177da4_текстовая_игра_на_основе_llm___interrupt/README.md
+70 -60
View File
@@ -1,9 +1,7 @@
# Interactive Text Adventure – LLM + Interrupt
# Text Adventure with LLM and 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.
A lightweight “choose‑your‑own‑story” game that lets a large language model (LLM) generate the plot while the user makes decisions in real time via the console.
The project demonstrates how to combine **LangGraph** state management, **LangChain** for LLM calls, and **questionary** for interactive prompts.
---
@@ -13,6 +11,8 @@ The story is generated by the LLM, then paused for user input via a console prom
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Game](#running-the-game)
- `client.py` – Interactive CLI
- `agent.py` – Stand‑alone demo (no user input)
- [Example Session](#example-session)
- [Project Structure](#project-structure)
@@ -20,11 +20,16 @@ The story is generated by the LLM, then paused for user input via a console prom
## 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.
1. **LLM generates a hook** – the opening line of an adventure.
2. The graph pauses (`interrupt`) and presents **three options** to the player via `questionary`.
3. Player selects an option; the choice is fed back into the LLM.
4. LLM writes a short continuation based on that choice.
5. The cycle repeats until the story ends or the user quits.
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.
The game showcases:
- LangGraph state nodes and checkpoints
- Human‑in‑the‑loop via custom interrupt handling
- Simple CLI integration with `questionary`
---
@@ -32,102 +37,107 @@ The whole flow is orchestrated by **LangGraph**, which manages state (`GameState
| 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. |
| Python | 3.10+ | Tested on 3.11 |
| Ollama | – | Optional if you use a local LLM; otherwise set `OPENAI_API_KEY` for OpenAI. |
| Qdrant | – | Not required for this demo (only used in advanced setups). |
> **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.
**Environment variables**
```bash
# If using OpenAI
export OPENAI_API_KEY="sk-..."
# If using Ollama locally
export OLLAMA_HOST="http://localhost:11434"
```
---
## 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
git clone https://github.com/yourname/text-adventure.git
cd text-adventure
python -m venv .venv # optional but recommended
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
`requirements.txt` contains:
```text
langgraph>=0.1.0
langchain-openai>=0.2.0
langgraph>=0.1.0
questionary>=1.10.0
python-dotenv>=1.0.0 # optional, for .env support
python-dotenv>=1.0.0
```
---
## Running the Game
The entire game is contained in a single script: `game.py`.
### 1. Interactive CLI (`client.py`)
Launch the game and follow on‑screen prompts.
```bash
# Make sure your OpenAI key is available:
export OPENAI_API_KEY="sk-..."
# Run the game
python game.py
python client.py
```
If you prefer to use a `.env` file, create a file named `.env` in the project root with:
**What happens**
```dotenv
OPENAI_API_KEY=sk-...
- The program asks for a theme (e.g., “fantasy”, “sci‑fi”).
- LLM creates an opening hook.
- Three choices appear; pick one.
- LLM writes a short continuation.
- Repeat until you type `quit` or the story ends.
### 2. Stand‑alone Demo (`agent.py`)
Runs the same logic but without user interaction – useful for quick tests or automated runs.
```bash
python agent.py
```
The script will automatically load it via `python-dotenv`.
It will automatically generate a theme, hook, and options, then print the final story to stdout.
---
## Example Session
Below is a typical console interaction. The AI generates an opening and three actions; you pick one; the AI finishes.
```text
$ python client.py
Enter a theme (or press Enter for random): mystery
```
$ python game.py
Welcome to the Interactive Adventure!
LLM Hook:
"In the dim glow of the lantern, Detective Marlowe stared at the cryptic note left on the desk..."
[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 an action:
1. Inspect the note closely.
2. Call the forensic team.
3. Leave the office and investigate the alley.
Choose your action:
1) Inspect the crystal closely.
2) Search for an exit.
3) Call out to see if anyone is nearby.
> 1
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...
LLM Continuation:
"She unfolded the brittle paper, revealing a series of numbers that seemed to map out the city’s underground tunnels..."
```
Feel free to experiment with different choices – each run will produce a unique narrative!
The game continues until you decide to quit or the story naturally concludes.
---
## Project Structure
```text
interactive-adventure/
├── game.py # Main script containing LangGraph logic
├── requirements.txt
└── README.md
.
├── agent.py # Non‑interactive demo
├── client.py # Interactive CLI with questionary
├── requirements.txt # Dependencies
└── README.md # This file
```
- **`game.py`** – Defines `GameState`, the graph nodes (`generate_story`, `interrupt_node`, `finish_ending`), and runs the loop.
- **`requirements.txt`** – Lists all Python dependencies.
Feel free to tweak `agent.py` or `client.py` to experiment with different LLM prompts, themes, or interrupt handling strategies.
---
Happy adventuring! 🚀
Happy adventuring!