# Dungeon Masters Vault: Local RAG Assistant

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](https://docs.astral.sh/uv/)** — Python package manager
* **Ollama** — Running a local server (default `localhost:11434`)
* **Local Models** — Pull your inference and embedding models with `ollama pull`

### Installation

```bash
uv sync
```

---

## Usage

### Ingest & Enrich

Process your markdown campaign files and build the vector database:

```bash
uv run src/ingest.py
```

### Query the LLM

Launch the interactive session to ask questions about your campaign:

```bash
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

---