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
- Generate a story hook – The LLM creates an opening paragraph and three possible actions.
- Pause for user input – Using
questionary, the script presents the options and waits for the player to choose one. - 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
ChatOpenAIwith a local model (e.g., Ollama) and adjust the import accordingly.
Installation
# 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:
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.
# 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:
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
interactive-adventure/
├── game.py # Main script containing LangGraph logic
├── requirements.txt
└── README.md
game.py– DefinesGameState, the graph nodes (generate_story,interrupt_node,finish_ending), and runs the loop.requirements.txt– Lists all Python dependencies.
Happy adventuring! 🚀