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

Run client.py to start the game.

The AI presents you with a scenario and three options.

Pick an option via the terminal prompt.

The AI finishes the story for you.

What It Does
Prerequisites
Installation
Running the Game
Example Session
Project Structure

What It Does

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.

Prerequisites

Component	Minimum Version	Notes
Python	3.10+	Tested on 3.11
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

Optional: If you want to run the model locally, replace ChatOpenAI with a local LLM provider supported by LangChain.

Installation

# 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:

langgraph>=0.1.0
langchain>=0.2.0
langchain-openai>=0.1.0
questionary>=1.10.0

Running the Game

The entry point is client.py. It builds the graph, starts execution, and handles user interaction.

# From the project root
python client.py

You can also run the graph directly (useful for debugging):

# Run only the graph logic without the CLI wrapper
python graph.py

Example Session

Below is a sample console output when you run client.py:

$ python client.py
Welcome to "Choose Your Own Story"!

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

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

client.py
Initializes the LLM, memory, and graph.
Calls graph.run() which pauses at the interrupt node, then resumes after user input.
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! 🎲✨

README.md Unescape Escape

Interactive Text Adventure – “Choose Your Own Story”

Table of Contents