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 14:37:56 +00:00
parent a4e68691b7
commit e00a233665
1 changed files with 69 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
solutions/69b1a07c67bbf488a1177da4_текстовая_игра_на_основе_llm___interrupt/README.md
+69 -72
View File
@@ -1,7 +1,13 @@
# Text Adventure with LLM and Interrupt
# Interactive Text Adventure – “Choose Your Own Story”
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.
A lightweight Python project that turns a large language model into an interactive storytelling engine.
The LLM writes the beginning of a story, pauses for user input (a choice), and then continues the narrative based on that choice.
> **TL;DR**
> 1. Run `client.py` to start the game.
> 2. The AI presents you with a scenario and three options.
> 3. Pick an option via the terminal prompt.
> 4. The AI finishes the story for you.
---
@@ -11,8 +17,6 @@ The project demonstrates how to combine **LangGraph** state management, **LangCh
- [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,16 +24,10 @@ The project demonstrates how to combine **LangGraph** state management, **LangCh
## What It Does
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 game showcases:
- LangGraph state nodes and checkpoints
- Human‑in‑the‑loop via custom interrupt handling
- Simple CLI integration with `questionary`
* Generates a short interactive story using an LLM (OpenAI GPT‑4 or any compatible model).
* Uses **LangGraph** to manage state and flow, pausing execution at a custom *interrupt* node.
* Presents the user with three narrative choices via `questionary`.
* Continues the story based on the chosen option.
---
@@ -38,106 +36,105 @@ The game showcases:
| Component | Minimum Version | Notes |
|-----------|-----------------|-------|
| 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). |
| OpenAI API key | – | Set as environment variable `OPENAI_API_KEY` |
| LangGraph | Latest (pip install) | Handles graph execution and checkpoints |
| LangChain | Latest (pip install) | Core LLM integration |
| questionary | Latest (pip install) | Terminal UI for choices |
**Environment variables**
```bash
# If using OpenAI
export OPENAI_API_KEY="sk-..."
# If using Ollama locally
export OLLAMA_HOST="http://localhost:11434"
```
> **Optional**: If you want to run the model locally, replace `ChatOpenAI` with a local LLM provider supported by LangChain.
---
## Installation
```bash
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
# Clone the repo
git clone https://github.com/your-username/interactive-text-adventure.git
cd interactive-text-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
langchain-openai>=0.2.0
langgraph>=0.1.0
langchain>=0.2.0
langchain-openai>=0.1.0
questionary>=1.10.0
python-dotenv>=1.0.0
```
---
## Running the Game
### 1. Interactive CLI (`client.py`)
Launch the game and follow on‑screen prompts.
The entry point is `client.py`. It builds the graph, starts execution, and handles user interaction.
```bash
# From the project root
python client.py
```
**What happens**
- 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.
You can also run the graph directly (useful for debugging):
```bash
python agent.py
# Run only the graph logic without the CLI wrapper
python graph.py
```
It will automatically generate a theme, hook, and options, then print the final story to stdout.
---
## Example Session
```text
$ python client.py
Enter a theme (or press Enter for random): mystery
Below is a sample console output when you run `client.py`:
LLM Hook:
"In the dim glow of the lantern, Detective Marlowe stared at the cryptic note left on the desk..."
Choose an action:
1. Inspect the note closely.
2. Call the forensic team.
3. Leave the office and investigate the alley.
> 1
LLM Continuation:
"She unfolded the brittle paper, revealing a series of numbers that seemed to map out the city’s underground tunnels..."
```
$ python client.py
Welcome to "Choose Your Own Story"!
The game continues until you decide to quit or the story naturally concludes.
The AI has generated the following scenario:
> You find yourself in a dimly lit cavern, the sound of dripping water echoing around you.
>
> What do you do?
1. Explore deeper into the darkness.
2. Search for an exit on the far wall.
3. Call out to see if anyone else is there.
Enter your choice (1‑3): 2
You chose: "Search for an exit on the far wall."
The AI continues the story:
> You move cautiously toward the far wall, feeling the damp stone under your feet...
```
---
## Project Structure
```text
.
├── agent.py # Non‑interactive demo
├── client.py # Interactive CLI with questionary
├── requirements.txt # Dependencies
└── README.md # This file
interactive-text-adventure/
├── client.py # CLI entry point – starts the graph and handles user input
├── graph.py # LangGraph definition: nodes, state, interrupt logic
├── requirements.txt # Dependencies
└── README.md # This file
```
Feel free to tweak `agent.py` or `client.py` to experiment with different LLM prompts, themes, or interrupt handling strategies.
- **client.py**
*Initializes the LLM, memory, and graph.
Calls `graph.run()` which pauses at the interrupt node, then resumes after user input.*
Happy adventuring!
- **graph.py**
*Defines `StoryState` (theme, story text, etc.).
Implements a custom interrupt node that yields control to the CLI for user choice.*
Feel free to extend the game by adding more nodes, richer state, or different LLM providers.
---
Happy storytelling! 🎲✨