# D&D Helpers

D&D Helpers is designed to solve the "missing notes" problem. It focuses on the automatic extraction of game-relevant data from live conversation, turning spoken dialogue into structured records.

## Core Objective: Automated Data Capture

The primary goal is to listen to game sessions and automatically identify and record critical information into structured files, while ignoring the "noise" of out-of-character (OOC) conversation.

### The Pipeline

1. **Listen**: Capture audio and convert it to text via Speech-to-Text (STT).
2. **Filter**: An LLM analyzes the transcript to strip away OOC nonsense and non-game-relevant chatter.
3. **Extract**: The system identifies key events and routes them to the appropriate destination:
   - **Lore**: Narrative details, NPC introductions, and world-building are appended to Markdown files.
   - **Character State & Inventory**: Changes to health, status effects, and loot are updated in JSON files.
4. **Confirm**: A human-in-the-loop system suggests these updates via a CLI tool, allowing the user to confirm, edit, or reject the change before it is committed.

## Features

### Data Trackers

- **Lore Tracker**: A personal wiki for your campaign's lore, NPCs, and locations. Stored in Markdown for rich text and easy version control.
- **Character & Inventory Tracker**: A centralized record of character identity, stats, effects, and gear. Stored in JSON for portability and VTT compatibility.

### Summarizer

Distill long sessions into concise highlights. Use LLMs to summarize recorded transcripts into a brief "The Story So Far" document.

## Interface & Usage

- **CLI**: The primary interface for confirming automated updates and querying current game state.
- **Text Editors**: Since data is stored in Markdown and JSON, you can use any editor (VS Code, Vim, Obsidian) to manually refine your campaign data.

## Technical Stack

- **Language**: Python 3.10+
- **Data Persistence**: Local JSON and Markdown files.
- **AI Backend**: vLLM / OpenAI API compatible endpoints (via `openai` Python library).
- **STT Engine**: OpenAI Whisper (local) for high-accuracy transcription.
- **Audio Capture (Linux)**:
  - `sounddevice` or `PyAudio` for microphone and system audio capture.
  - `ffmpeg` for audio stream processing and format conversion.
- **Interface**:
  - `Textual` or `Rich` for a modern, intuitive Terminal User Interface (TUI).
  - `Click` or `Typer` for command-line argument parsing.