🐉 AI Dungeon Master Narrator

An intelligent, AI-powered Dungeon Master for immersive text-based tabletop role-playing games. Experience dynamic storytelling where the AI remembers your actions, maintains narrative continuity, and creates a living, breathing game world that responds to your choices.

📋 Table of Contents

• Overview
• Features
• System Architecture
• Prerequisites
• Installation
• Configuration
• Usage
• Demo
• How It Works
• Technical Details

🎯 Overview

This project implements an intelligent AI Dungeon Master (DM) for text-based tabletop RPGs using Large Language Models (LLMs) and vector-based memory systems. The system addresses the core challenge of maintaining narrative continuity and world consistency by combining the power of modern LLMs with intelligent event memory retrieval.

The AI DM:

• Creates immersive narratives with vivid descriptions and interactive storytelling
• Remembers past events using ChromaDB vector database for semantic memory
• Maintains story continuity by referencing relevant past events in its responses
• Responds to player choices with meaningful consequences that shape the game world
• Generates dynamic NPCs and challenges that evolve throughout your adventure

✨ Features

• AI-Powered Storytelling: Uses Groq's LLaMA 3.3 70B model for creative and engaging narratives
• Semantic Memory System: ChromaDB with sentence transformers for intelligent event recall
• Continuous Narrative: Maintains story context across multiple turns
• Character Interaction: Creates responsive NPCs and dynamic encounters
• Concise Responses: Keeps the game paced with 2-4 sentence responses
• Easy Setup: Simple command-line interface for quick game sessions

🏗️ System Architecture

The project is organized into three modular components:

1. main.py - Game Loop & User Interface

• Handles the main game loop and player interactions
• Manages the flow of conversation between player and DM
• Processes player input and coordinates between environment and memory systems
• Exits gracefully when the player types "quit"

2. environment.py - LLM Integration

• Manages all interactions with the Groq API
• Constructs comprehensive prompts combining system instructions with game context
• Handles API calls to the LLaMA 3.3 70B model
• Maintains the system prompt that defines DM behavior

3. bot_db.py - Memory Management

• Implements the vector-based memory system using ChromaDB
• Encodes events using sentence transformers
• Retrieves semantically relevant past events based on player actions
• Maintains persistent game state across sessions

Architecture Flow

Player Input
    ↓
main.py (Game Loop)
    ↓
bot_db.py (Retrieve Relevant Memories)
    ↓
environment.py (Construct Prompt + Call LLM)
    ↓
bot_db.py (Store New Event)
    ↓
Display DM Response

This modular design ensures separation of concerns and makes the system scalable and maintainable.

📦 Prerequisites

• Python 3.8+ (Python 3.10+ recommended)
• pip (Python package installer)
• Groq API Key (Free at https://console.groq.com)
• ~500MB disk space for dependencies and memory database

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/Anuroop128/Dungeon_Master_narrator.ai
cd Dungeon_Master_narrator.ai

Step 2: Create a Memory Directory

mkdir memory

This directory stores the ChromaDB vector database for game events.

Step 3: Install Dependencies

pip install -r requirements.txt

Dependencies:

• groq - Groq API client for LLM inference
• chromadb - Vector database for semantic memory
• sentence-transformers - Embedding model for encoding events

Step 4: Set Up Your Groq API Key

Get your free API key from Groq Console.

For Windows (PowerShell):

$env:GROQ_API_KEY="your_api_key_here"

For Windows (Command Prompt):

set GROQ_API_KEY=your_api_key_here

For Linux/macOS:

export GROQ_API_KEY="your_api_key_here"

Note: Alternatively, you can set the API key directly in environment.py (line 4), though using environment variables is recommended for security.

🎮 Usage

Start your adventure:

python main.py

You'll see:

 ⚔️  AI Dungeon Master is ready  ⚔️
 ⚔️  Your adventure begins now  ⚔️

 START BY INTRODUCING YOUR CHARACTER (eg. name, age, physic, any superpowers)...

Gameplay Instructions

1. Introduce Your Character: Describe your character's name, appearance, abilities, and background

   You: I am Aragorn, a 30-year-old ranger with exceptional archery skills and a mysterious past
   

2. Describe Your Actions: Tell the DM what your character does

   You: I approach the tavern cautiously, looking for clues about the missing artifact
   

3. Interact with the Story: Read the DM's response and continue your adventure

   DM: [Narrative response with world description and consequences]
   

4. End Your Adventure: Type "quit" to exit

   You: quit
    ⚔️  Your adventure has ended. Farewell!  ⚔️
   

📹 Demo

Watch the AI Dungeon Master in action:

🎥 YouTube Demonstration

🧠 How It Works

The Memory System

The AI DM uses a sophisticated memory system to maintain narrative continuity:

1. Event Encoding: Each game turn is summarized and encoded into a vector embedding
2. Semantic Storage: Events are stored in ChromaDB using the all-MiniLM-L12-v2 embedding model
3. Smart Retrieval: When the player takes an action, the system retrieves the 3 most semantically relevant past events
4. Context Injection: Retrieved memories are included in the prompt to the LLM, ensuring consistent storytelling

The Prompt Structure

The system constructs a comprehensive prompt:

[System Instructions - Define DM Behavior]
+ [Relevant Past Events - Retrieved from memory]
+ [Player's Current Action]
= [Complete Context for LLM]

This ensures the AI has full context while keeping responses focused and concise.

Why This Approach?

• Raw LLMs can't remember beyond the current conversation
• Simple prompt concatenation doesn't scale (context limits)
• Vector embeddings enable semantic search - the DM finds relevant memories, not random ones
• Persistent storage means your adventure continues if you restart the script

🔧 Technical Details

Technologies Used

Component	Technology	Purpose
LLM	Groq + LLaMA 3.3 70B	Fast, high-quality text generation
Embeddings	Sentence Transformers (all-MiniLM-L12-v2)	Convert text to semantic vectors
Vector Database	ChromaDB	Store and retrieve game events
API Client	Groq Python SDK	Communicate with LLM service

Memory Database Structure

Collection Name: ttrpg_world_memory

Document Format:

"The player chose to '[action]', and as a result: [DM response]"

Query: Uses cosine similarity on vector embeddings to find 3 most relevant events

System Prompt Details

The DM follows these core instructions:

• Paint vivid pictures of scenes, characters, and events
• Control the story, world, and NPCs
• React meaningfully to player choices with lasting consequences
• Maintain consistency with retrieved past events
• Keep responses to 2-4 sentences
• Never break character
• Stay interactive and responsive

📝 File Structure

Dungeon_Master_narrator.ai/
├── main.py                 # Game loop and player interaction
├── environment.py          # LLM integration and prompt management
├── bot_db.py              # ChromaDB memory system
├── requirements.txt       # Python dependencies
├── memory/                # ChromaDB persistent storage (created on first run)
└── README.md              # This file

🤝 Contributing

Feel free to fork this project and submit pull requests for improvements! Some ideas:

• Multi-player support
• Persistent character/world saves
• Custom DM personality modes
• Advanced combat systems
• Web UI for easier gameplay

⚙️ Troubleshooting

"GROQ_API_KEY not found"

• Make sure you've set the environment variable before running the script
• Verify your API key is valid at Groq Console

"ModuleNotFoundError: No module named 'groq'"

• Ensure all dependencies are installed: pip install -r requirements.txt

"No relevant events have occurred yet"

• This is normal at the start of the game; the memory builds as you play

Slow responses

• Groq's API is optimized for speed; if responses are slow, check your internet connection
• Consider using a shorter memory retrieval window if you experience issues

📄 License

This project is open source and available under the MIT License.

👤 Author

Created by Anuroop128

🔗 Links

• Repository: GitHub
• Demo Video: YouTube
• Groq Console: https://console.groq.com
• ChromaDB Docs: https://docs.trychroma.com

---

May your adventures be legendary! ⚔️🐉