Text Adventure Game with LLM and Interrupt

Overview

This repository implements a text‑based choose‑your‑story game that demonstrates how to combine LangGraph, LangChain and the BroJS LLM for interactive storytelling.

The key concepts showcased are:

• A stateful graph that pauses for user input via interrupt().
• Two LLM calls: one generates an opening paragraph with three actions; the second writes a short ending based on the chosen action.
• Human‑in‑the‑loop (HITL) using questionary to present a menu and capture the user's choice.

The game is intentionally lightweight so you can run it locally with minimal setup.

File Structure

Path	Purpose
main.py	Entry point – defines state, nodes, graph and runs the game.
requirements.txt	Exact dependencies with pinned versions.
README.md	Project description, installation and usage instructions.

Installation

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

# Install dependencies
pip install -r requirements.txt

Important: The BroJS LLM requires an API key. Export it as:

export JOURNAL_MCP_PAT=your_api_key_here

or set it in your IDE’s environment variables.

Running the Game

python main.py

You will be prompted to enter a theme for the adventure (e.g., "a lonely astronaut on a deserted moon"). The game proceeds as follows:

1. Intro generation – The LLM writes a short opening paragraph and three numbered actions.
2. Interrupt – The graph pauses, displaying the intro and asking you to choose an action via a console menu.
3. Ending generation – After you select an option, the LLM produces a concluding paragraph that reflects your choice.
4. Final output – The complete story (intro, chosen action, ending) is printed to the console.

Customization

• Change the theme: Edit main.py or provide a different prompt when running.
• Adjust LLM temperature: Modify the temperature parameter in the ChatOpenAI initialization.
• Add more options: Update the prompt to request more than three actions and adjust parsing logic accordingly.

Troubleshooting

Symptom	Likely Cause	Fix
No output after running	API key missing or invalid	Ensure JOURNAL_MCP_PAT is set correctly.
LLM returns unexpected format	Prompt not strict enough	Tighten the prompt to enforce a predictable response structure.
Errors in parsing options	Options list contains extra text	Verify that each option line starts with "1)" / "2)" / "3)".

License & Credits

This project is released under the MIT license. The LLM model used is provided by BroJS and is subject to their terms of service.