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:

Intro generation – The LLM writes a short opening paragraph and three numbered actions.
Interrupt – The graph pauses, displaying the intro and asking you to choose an action via a console menu.
Ending generation – After you select an option, the LLM produces a concluding paragraph that reflects your choice.
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.

2.8 KiB Raw Blame History Unescape Escape