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. A lightweight Python project that turns a large language model into an interactive storytelling engine.
The project demonstrates how to combine **LangGraph** state management, **LangChain** for LLM calls, and **questionary** for interactive prompts. 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) - [Prerequisites](#prerequisites)
- [Installation](#installation) - [Installation](#installation)
- [Running the Game](#running-the-game) - [Running the Game](#running-the-game)
- `client.py` – Interactive CLI
- `agent.py` – Stand‑alone demo (no user input)
- [Example Session](#example-session) - [Example Session](#example-session)
- [Project Structure](#project-structure) - [Project Structure](#project-structure)
@@ -20,16 +24,10 @@ The project demonstrates how to combine **LangGraph** state management, **LangCh
## What It Does ## What It Does
1. **LLM generates a hook** – the opening line of an adventure. * Generates a short interactive story using an LLM (OpenAI GPT‑4 or any compatible model).
2. The graph pauses (`interrupt`) and presents **three options** to the player via `questionary`. * Uses **LangGraph** to manage state and flow, pausing execution at a custom *interrupt* node.
3. Player selects an option; the choice is fed back into the LLM. * Presents the user with three narrative choices via `questionary`.
4. LLM writes a short continuation based on that choice. * Continues the story based on the chosen option.
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`
--- ---
@@ -38,106 +36,105 @@ The game showcases:
| Component | Minimum Version | Notes | | Component | Minimum Version | Notes |
|-----------|-----------------|-------| |-----------|-----------------|-------|
| Python | 3.10+ | Tested on 3.11 | | Python | 3.10+ | Tested on 3.11 |
| Ollama | – | Optional if you use a local LLM; otherwise set `OPENAI_API_KEY` for OpenAI. | | OpenAI API key | – | Set as environment variable `OPENAI_API_KEY` |
| Qdrant | – | Not required for this demo (only used in advanced setups). | | 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** > **Optional**: If you want to run the model locally, replace `ChatOpenAI` with a local LLM provider supported by LangChain.
```bash
# If using OpenAI
export OPENAI_API_KEY="sk-..."
# If using Ollama locally
export OLLAMA_HOST="http://localhost:11434"
```
--- ---
## Installation ## Installation
```bash ```bash
git clone https://github.com/yourname/text-adventure.git # Clone the repo
cd text-adventure git clone https://github.com/your-username/interactive-text-adventure.git
python -m venv .venv # optional but recommended cd interactive-text-adventure
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 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 pip install -r requirements.txt
``` ```
`requirements.txt` contains: `requirements.txt` contains:
```text ```text
langchain-openai>=0.2.0
langgraph>=0.1.0 langgraph>=0.1.0
langchain>=0.2.0
langchain-openai>=0.1.0
questionary>=1.10.0 questionary>=1.10.0
python-dotenv>=1.0.0
``` ```
--- ---
## Running the Game ## Running the Game
### 1. Interactive CLI (`client.py`) The entry point is `client.py`. It builds the graph, starts execution, and handles user interaction.
Launch the game and follow on‑screen prompts.
```bash ```bash
# From the project root
python client.py python client.py
``` ```
**What happens** You can also run the graph directly (useful for debugging):
- 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 ```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 ## Example Session
```text Below is a sample console output when you run `client.py`:
$ python client.py
Enter a theme (or press Enter for random): mystery
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 ## Project Structure
```text ```text
. interactive-text-adventure/
├── agent.py # Non‑interactive demo ├── client.py # CLI entry point – starts the graph and handles user input
├── client.py # Interactive CLI with questionary ├── graph.py # LangGraph definition: nodes, state, interrupt logic
├── requirements.txt # Dependencies ├── requirements.txt # Dependencies
└── README.md # This file └── 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! 🎲✨