https://github.com/buzz/llm-gamebook
An interactive storytelling framework using LLMs to generate dynamic narratives along predefined, graph-based story paths.
https://github.com/buzz/llm-gamebook
ai game-engine gamebook interactive-fiction llm narrative-generation python storytelling
Last synced: about 2 months ago
JSON representation
An interactive storytelling framework using LLMs to generate dynamic narratives along predefined, graph-based story paths.
- Host: GitHub
- URL: https://github.com/buzz/llm-gamebook
- Owner: buzz
- License: agpl-3.0
- Created: 2025-10-14T14:54:33.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-23T16:58:00.000Z (6 months ago)
- Last Synced: 2025-10-23T18:31:29.018Z (6 months ago)
- Topics: ai, game-engine, gamebook, interactive-fiction, llm, narrative-generation, python, storytelling
- Language: Python
- Homepage:
- Size: 360 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# LLM Gamebook
This project is an **interactive storytelling framework** that uses Large Language Models (LLMs) to generate dynamic narratives along predefined story paths. Here's a comprehensive overview:
## Core Concept
`llm-gamebook` is a Python application that creates interactive, branching stories where the narrative follows predefined graph-based paths while being dynamically generated by an LLM. It's essentially a sophisticated choose-your-own-adventure system with AI-powered narration.
## Key Features
1. **Dynamic Narrative Generation**: The LLM creates contextually appropriate responses based on the current story state
2. **Predefined Story Arcs**: Ensures narrative coherence while allowing branching paths
3. **Entity State Management**: Tracks character relationships, locations, and other story elements
4. **Time Tracking**: Variable time progression that can speed up or slow down based on narrative needs
5. **Modular Design**: Stories can be broken into reusable components
6. **Streaming Responses**: Real-time display of the LLM's thinking and response generation
## How It Works
This project represents an innovative approach to interactive storytelling, combining the idea of traditional gamebooks with the dynamic capabilities of modern LLMs to create rich, branching narratives.
1. A story is defined in a YAML file with entity types, nodes, and transitions
2. The StoryEngine loads the story and initializes the state
3. The LLM generates narrative content based on the current state and predefined paths
4. Users interact with the story through the TUI
5. The system maintains state and triggers appropriate transitions and updates based on conditions and user input
## Technology Stack
- **Python** for the application logic
- **Pydantic** for data validation and schema definition
- **Pydantic AI** for LLM integration and tool calling
- **Textual** for the terminal user interface
- **Jinja2** for templating prompts and narrative elements
- **YAML** for story definitions
## Development
Run FastAPI web server.
```
$ cd backend
$ uv run uvicorn llm_gamebook.web.app:create_app --reload --factory --log-level debug
```
Run Vite dev server.
```
$ cd frontend
$ pnpm dev
```