Sanctum — Solo RPG Assistant

AI-powered solo play companion. Manages characters, party, session state, and lore. Expands scenes, NPCs, and locations using a local LLM. Integrates with Foundry VTT for maps and tokens, and an Obsidian vault for canon lore.

Systems supported

• Old-School Essentials (OSE) — premium + Carcass Crawler
• Dungeon Crawl Classics (DCC)
• Stars Without Number / Worlds Without Number (SWN/WWN)
• For Gold & Glory (FGG)
• Advanced Roleplay System (ARS)
• OSRIC 3.0 (planned, pending release)

Architecture

browser (Foundry VTT + sanctum module)
        ↕ HTTP / WebSocket
backend (FastAPI on tower.local:8000)
    ├── Ollama (local LLaMA — tower.local:11434)
    └── Obsidian vault (markdown on disk)

Setup

1. Backend

cd backend
cp .env.example .env        # edit paths and model name
pip install .
uvicorn main:app --reload   # dev

Or with Docker:

cp backend/.env.example backend/.env
docker compose up --build

2. Foundry module

Copy foundry-module/ into your Foundry Data/modules/sanctum/ directory, then enable it in your world's module settings.

Configure the API URL under Game Settings → Module Settings → Sanctum.

3. Obsidian vault

Copy vault-template/ to your preferred location and open it in Obsidian. Set VAULT_PATH in backend/.env to point to the live vault.

AI boundaries

The AI is a bounded tool, not a GM oracle. It:

• Expands flavor text within the active system's tone and setting
• Answers rules questions with caveats when uncertain
• Writes lore notes flagged pending_review: true until you approve them

Fate rolls, outcomes, and oracle decisions remain with the player.

API

• GET /health — liveness check
• POST /ai/expand/scene — scene description expansion
• POST /ai/expand/npc — NPC portrait + dialog
• POST /ai/expand/location — location GM note
• POST /ai/query — freeform query with system context
• GET /ai/models — list available Ollama models
• GET /lore/notes — list vault notes
• GET /lore/notes/{path} — read a note
• PUT /lore/notes/{path} — write a note
• GET /lore/search?q= — search vault
• POST /lore/generate — AI-generate a lore note
• POST /rules/roll — roll dice (XdY+Z notation)
• GET /rules/systems — list systems
• POST /rules/query — rules question
• POST /session/start — start session
• GET /session/current — current session state
• GET /session/party — party characters

Full interactive docs: http://localhost:8000/docs