Quick Start

This guide will help you get QuestFoundry up and running.

Installation

Prerequisites

  • Python 3.11 or later

  • uv package manager

Install from Source

# Clone repository
git clone https://github.com/pvliesdonk/questfoundry.git
cd questfoundry

# Install with uv
uv sync

# Verify installation
uv run qf version

Basic Usage

Compile Domain to Code

QuestFoundry uses MyST files as the source of truth. Compile them to Python:

qf compile

This generates:

  • Pydantic models from ontology/

  • Role configurations from roles/

  • LangGraph definitions from loops/

Run a Workflow

Start an interactive story creation session:

qf ask "Create a mystery story set in a Victorian mansion"

The Showrunner will orchestrate the 8 roles to create your story.

Configure LLM Provider

QuestFoundry supports multiple LLM providers. Configure in your project:

# Use Ollama (local)
qf config set provider ollama
qf config set model qwen3:8b

# Use OpenAI
qf config set provider openai
qf config set model gpt-4o

Example Project

See examples/mystery_manor/ for a complete example:

cd examples/mystery_manor

# Inspect the cold store
sqlite3 project.qfdb "SELECT anchor, title FROM sections;"

# Read a scene
sqlite3 project.qfdb "SELECT content FROM sections WHERE anchor='scene_1';"

Next Steps