README.md

---
title: AI Dungeon Game
emoji: 🎮
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 3.50.2
app_file: app.py
pinned: false
license: mit
---

# AI-Powered Dungeon Adventure Game

## Table of Contents
- [Overview](#overview)
- [Technical Architecture](#technical-architecture)
- [Key Features](#key-features)
- [Game Mechanics](#game-mechanics)
- [AI/ML Implementation](#aiml-implementation)
- [Installation](#installation)
- [Usage](#usage)
- [Project Structure](#project-structure)
- [Technologies Used](#technologies-used)
- [Future Enhancements](#future-enhancements)

## Overview
An advanced text-based adventure game powered by Large Language Models (LLMs) that demonstrates the practical application of AI/ML in interactive entertainment. The game features dynamic quest generation, intelligent NPC interactions, and content safety validation using state-of-the-art language models.

## Technical Architecture
- **Core Engine**: Python-based game engine with modular architecture
- **AI Integration**: Hugging Face Transformers pipeline for text generation
- **UI Framework**: Gradio for interactive web interface
- **Safety Layer**: LLaMA Guard for content moderation
- **State Management**: Dynamic game state handling with quest progression
- **Memory Management**: Optimized for GPU utilization with 8-bit quantization

## Key Features
1. **Dynamic Quest System**
   - Procedurally generated quests based on player progress
   - Multi-chain quest progression
   - Experience-based leveling system

2. **Intelligent Response Generation**
   - Context-aware narrative responses
   - Dynamic world state adaptation
   - Natural language understanding (NLP)

3. **Advanced Safety System**
   - Real-time content moderation
   - Multi-category safety checks
   - Cached response validation

4. **Inventory Management**
   - Dynamic item tracking
   - Automated inventory updates
   - Natural language parsing for item detection

## Game Mechanics
- **Dungeon Generation:** Randomly generated dungeons with obstacles.
- **Player and NPCs:** Players can move, fight NPCs, and use items.
- **Combat System:** Turn-based combat with simple AI decision-making.
- **Inventory Management:** Collect and use items to aid in your adventure.
- **Quest System:** Complete quests to earn rewards and progress through the game.


## AI/ML Implementation
1. **Language Models**
   - Primary: LLaMA-3.2-3B-Instruct
   - Safety: LLaMA-Guard-3-1B
   - Optimized with 8-bit quantization

2. **Natural Language Processing**
   - Context embedding
   - Response generation
   - Content safety validation

3. **Memory Optimization**
   - GPU memory management
   - Response caching
   - Efficient token handling

## Installation
```bash
# Clone repository
git clone https://github.com/prgrmcode/ai-dungeon-game.git
cd ai-dungeon-game

# Create virtual environment
python -m venv dungeon-env
source dungeon-env/Scripts/activate  # Windows
source dungeon-env/bin/activate      # Linux/Mac

# Install dependencies (`pip freeze > requirements.txt` to get requirements)
pip install -r requirements.txt
# Or install libraries directly:
pip install numpy matplotlib pygame
pip install python-dotenv
pip install transformers
pip install gradio
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install psutil
pip install 'accelerate>=0.26.0

# Create a .env file in the root directory of the project and add your environment variables:
HUGGINGFACE_API_KEY=your_api_key_here
```

## Usage
```bash
# Start the game
python main.py

# Access via web browser
http://localhost:7860
# or:
http://127.0.0.1:7860
```

## Project Structure
```
ai_dungeon_game/
├── assets/
│   └── ascii_art.py
├── game/
│   ├── combat.py
│   ├── dungeon.py
│   ├── items.py
│   ├── npc.py
│   └── player.py
├── shared_data/
│   └── Ethoria.json
├── helper.py
└── main.py
```

## Technologies Used
- **Python 3.10+**
- **PyTorch**: Deep learning framework
- **Transformers**: Hugging Face's transformer models
- **Gradio**: Web interface framework
- **CUDA**: GPU acceleration
- **JSON**: Data storage
- **Logging**: Advanced error tracking

## Skills Demonstrated
1. **AI/ML Engineering**
   - Large Language Model implementation
   - Model optimization
   - Prompt engineering
   - Content safety systems

2. **Software Engineering**
   - Clean architecture
   - Object-oriented design
   - Error handling
   - Memory optimization

3. **Data Science**
   - Natural language processing
   - State management
   - Data validation
   - Pattern recognition

4. **System Design**
   - Modular architecture
   - Scalable systems
   - Memory management
   - Performance optimization

## Future Enhancements
1. **Advanced AI Features**
   - Multi-modal content generation
   - Improved context understanding
   - Dynamic difficulty adjustment

2. **Technical Improvements**
   - Distributed computing support
   - Advanced caching mechanisms
   - Real-time model updating

3. **Gameplay Features**
   - Multiplayer support
   - Advanced combat system
   - Dynamic world generation

4. **Visual Enhancements**
   - **Graphical User Interface (GUI):** Implement a GUI using Pygame to provide a more interactive and visually appealing experience.

   - **2D/3D Graphics:** Use libraries like Pygame or Pyglet for 2D graphics.

   - **Animations:** Add animations for player and NPC movements, combat actions, and other in-game events.

   - **Visual Effects:** Implement visual effects such as particle systems for magic spells, explosions, and other dynamic events.

   - **Map Visualization:** Create a visual representation of the dungeon map that updates as the player explores.


## Requirements
- Python 3.10+
- CUDA-capable GPU (recommended)
- 8GB+ RAM
- Hugging Face API key




This project showcases practical implementation of AI/ML in interactive entertainment, 
demonstrating skills in LLM implementation, system design, and performance optimization.