60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 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
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
export JOURNAL_MCP_PAT=your_api_key_here
|
||
```
|
||
or set it in your IDE’s environment variables.
|
||
|
||
## Running the Game
|
||
```bash
|
||
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.
|