RPG Generator

LLM-powered tabletop RPG content generator. Create campaigns, then generate NPCs, quests, encounters, and loot using AI.

Stack

• FastAPI — async REST API
• PostgreSQL — campaigns, NPCs, quests (structured data)
• MongoDB — encounters, loot, generation audit logs (flexible schema)
• Anthropic Claude / OpenAI — content generation
• Docker Compose — local dev environment

Quick Start

# clone and configure
cp .env.example .env
# add your API key to .env

# start everything
docker compose up --build

# API docs
open http://localhost:8000/docs

API

Campaigns

• POST /api/v1/campaigns/ — create a campaign
• GET /api/v1/campaigns/ — list campaigns
• GET /api/v1/campaigns/{id} — get campaign
• DELETE /api/v1/campaigns/{id} — delete campaign

Generate Content

• POST /api/v1/generate/npc — generate an NPC
• POST /api/v1/generate/quest — generate a quest
• POST /api/v1/generate/encounter — generate a combat encounter
• POST /api/v1/generate/loot — generate loot/treasure

List Generated Content

• GET /api/v1/generate/npcs/{campaign_id} — list NPCs
• GET /api/v1/generate/encounters/{campaign_id} — list encounters
• GET /api/v1/generate/loot/{campaign_id} — list loot

Example

# create a campaign
curl -X POST http://localhost:8000/api/v1/campaigns/ \
  -H "Content-Type: application/json" \
  -d '{"name": "Curse of the Crimson Tide", "setting": "dark fantasy", "description": "A coastal kingdom plagued by a blood-red tide"}'

# generate an NPC for it
curl -X POST http://localhost:8000/api/v1/generate/npc \
  -H "Content-Type: application/json" \
  -d '{"campaign_id": "<id>", "race": "tiefling", "npc_class": "warlock", "level": 7, "context": "tavern owner with a secret"}'

Dev

pip install -e ".[dev]"
ruff check src/
mypy src/
pytest