An advanced Retrieval-Augmented Generation (RAG) system designed for Dungeon Masters. This tool ingests markdown-based campaign notes, enriches them with AI-generated metadata, and provides an interactive terminal interface to query your world's lore using DSPy and Local LLMs.

Key Features

Parallel Enrichment: Configurable multithreading processes multiple document chunks simultaneously across local LLM slots for high-speed ingestion.
Deep Context Retrieval: Retrieves relevant chunks and "peeks" at the full source file to provide the LLM with broader narrative context.
Local-First: Runs entirely on your hardware using Ollama, keeping your campaign secrets private.

Setup

Prerequisites

UV — Python package manager
Ollama — Running a local server (default localhost:11434)
Local Models — Pull your inference and embedding models with ollama pull

Installation

uv sync

Usage

Ingest & Enrich

Process your markdown campaign files and build the vector database:

uv run src/ingest.py

Query the LLM

Launch the interactive session to ask questions about your campaign:

uv run src/retrieve.py

Example interaction:

Query: Why did the party get free bread at the Golden Grain Inn?

Based on the session notes from 'Session_12.md', the party received free bread because the Rogue intimidated the baker's assistant and the Cleric performed Thaumaturgy to impress the owner.

File Structure

.
├── config.yaml                   # App configuration
├── load_ingestion_llms.sh        # Script to load multiple LLMs (run before ingest)
├── README.md
├── ROADMAP.md
├── src/
│   ├── config_loader.py          # Loads config.yaml
│   ├── embedding.py              # Ollama embedding model client
│   ├── experts/
│   │   ├── ingestion_agent.py    # AI agent for document enrichment
│   │   └── retrieval_agent.py    # AI agent for queries, with tools and DB calls
│   ├── ingest.py                 # Campaign notes ingestion script
│   └── retrieve.py               # Interactive Q&A interface
├── data/                         # Campaign database (gitignored)
│   ├── dmv.db
│   ├── dmv.log
│   └── time_file.txt
├── pyproject.toml
├── LICENSE
└── uv.lock

Configuration

Edit config.yaml to customize:

Inference and embedding models
Campaign notes location (data_dir)
System prompts for ingestion and retrieval agents