Interactive Story Game with LLM and Interrupts

A lightweight “choose‑your‑own‑adventure” text game that uses a large language model (LLM) to generate story snippets, pauses for user input, then continues the narrative based on the chosen option. The project demonstrates how to build a LangGraph pipeline with human‑in‑the‑loop interruptions and checkpoints.

📖 Overview

LLM generates an opening scene – a short paragraph describing the setting and presenting several possible actions.
Interrupt – the graph pauses, displaying the options in the console via questionary.
User selects an option – the choice is stored in the graph state.
LLM writes a brief ending that follows the chosen path.

The result is a chain of prompts:
LLM → pause & user input → LLM (ending).

🚀 Getting Started

Prerequisites

Python 3.10+
An OpenAI API key (or any other model supported by LangChain)

Tip: If you prefer not to use OpenAI, replace the OpenAI wrapper with another LangChain LLM provider in main.py.

Installation

# Clone the repo
git clone https://github.com/your-username/interactive-story-game.git
cd interactive-story-game

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate   # On Windows: .\.venv\Scripts\activate

# Install dependencies
pip install langgraph==0.1.2 \
           langchain==1.2.10 \
           langchain-openai==1.1.9 \
           questionary

Environment variable
Set your OpenAI key before running the game:
export OPENAI_API_KEY="sk-..."
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

📁 Project Structure

File	Purpose
`main.py`	Entry point – builds the graph, runs it, and handles user interaction.
`graph.py`	Defines the LangGraph nodes, state schema, and interrupt logic.
`utils.py`	Helper functions (e.g., prompt templates).
`requirements.txt`	List of dependencies (for reproducibility).

🛠️ Running the Game

python main.py

You will see something like:

=== Interactive Story ===
Topic: A mysterious forest

Scene:
  You find yourself at the edge of a dark, misty forest. The trees loom overhead, their branches tangled like fingers.

Options:
1) Step into the forest.
2) Walk along the clearing's edge.
3) Call out for help.

Enter your choice (1‑3):

After you type 1, the game will ask the LLM to finish the story based on that choice and print a short ending.

🔧 Customization

Changing the Prompt

Edit utils.py:

def generate_scene_prompt(topic: str) -> str:
    return f"Topic: {topic}\nWrite a short opening scene with 3 possible actions."

Adding More Nodes

You can split the graph into separate nodes for “generate scene” and “write ending”, or add additional decision points.

🎮 Example Session

$ python main.py
=== Interactive Story ===
Topic: A forgotten laboratory

Scene:
  The lab is dimly lit, with humming machines and a faint smell of ozone. In the center lies an ancient console flickering with static.

Options:
1) Approach the console.
2) Inspect the surrounding equipment.
3) Leave the lab immediately.

Enter your choice (1‑3): 2

Ending:
You carefully examine the equipment, discovering a hidden panel that opens to reveal a secret passage. The adventure continues...

📜 License

This project is released under the MIT License – feel free to adapt and expand it for your own experiments with LLMs and human‑in‑the‑loop systems.

README.md Unescape Escape