TaleForge

A framework for building LLM-powered text adventures with directed narratives.

TaleForge combines the infinite input flexibility of large language models with the structured, authored gameplay of classic text adventures. You define rooms, items, puzzles, and narrative paths in simple YAML files. The LLM handles interpreting player input and narrating the results — but the game engine remains the source of truth.

How It Works

Player Input → LLM (interpret) → Game Engine (process) → LLM (narrate) → Player Output
     ↑                                    ↓
     └────────── Game State ←─────────────┘

• Game data is defined in YAML — rooms, items, exits, interactions, and flags
• The engine is a deterministic state machine that processes actions and tracks state
• The LLM translates natural language to structured actions, and engine results to prose
• The LLM cannot invent items, rooms, or paths — it can only work with what you've authored

Quick Start

Install

pip install -e .

Set your API key

export ANTHROPIC_API_KEY="your-key-here"

Play the example adventure

python -m taleforge adventures/example

Creating Adventures

An adventure is a directory with YAML data files:

my_adventure/
  data/
    adventure.yaml   # Title, intro text, tone/style instructions
    rooms.yaml       # Room definitions with exits and interactions
    items.yaml       # Item definitions

See adventures/example/ for a complete working example.

adventure.yaml

Defines metadata and the LLM's narrative tone:

title: "My Adventure"
start_room: starting_room
tone: |
  Write in a suspenseful, noir style...
intro: |
  The text shown when the game starts...

rooms.yaml

Defines rooms, their connections, and what can happen in them:

rooms:
  starting_room:
    name: "The Office"
    description: "A dimly lit office..."
    exits:
      - direction: north
        target: hallway
        description: "A door to the hallway"
      - direction: east
        target: vault
        locked: true
        required_item: vault_key
    items:
      - desk_lamp
    interactions:
      - action: examine
        target: desk
        response: "You find a note..."
        sets_flag: found_note

items.yaml

Defines items the player can find and use:

items:
  vault_key:
    name: "Brass Key"
    description: "A small brass key..."
    portable: true

Architecture

• taleforge/engine.py — The deterministic game state machine
• taleforge/llm.py — LLM integration for input parsing and narration
• taleforge/loader.py — YAML adventure data loader
• taleforge/models.py — Data models (Room, Item, GameState, etc.)
• taleforge/game.py — Main game loop tying everything together

License

MIT