From c8ee83466043d1b810187a211d03da5b8bd4734d Mon Sep 17 00:00:00 2001
From: charles <charles@tipsy.codes>
Date: Mon, 25 May 2026 20:41:40 -0700
Subject: [PATCH] Add README.md

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..298b21e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# 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.