AIPLAYER/README.md

# MUD AI Player

An autonomous AI player for MUD (Multi-User Dungeon) text-based games.

## Features

- 🤖 **Autonomous Gameplay**: Simulates a human player from character creation to endgame
- 🗺️ **Auto-Mapping**: Builds a complete map of the MUD world with hybrid storage (SQLite + Memvid)
- ⚔️ **Combat AI**: Intelligent combat decisions, target selection, and survival tactics
- 📜 **Quest System**: Automatically detects, plans, and completes quests
- 🔍 **Semantic Search**: Find locations using natural language queries
- 📊 **Progression Optimizer**: Finds optimal grinding spots and equipment upgrades
- 🧠 **LLM Integration**: Context-aware responses to players using local LLMs (Ollama)
- 🌐 **Web Dashboard**: Real-time monitoring dashboard with WebSocket updates
- 👤 **Human Behavior**: Simulates realistic reaction times and behavior patterns

## Architecture

The application is built with a modular architecture:

- **Core**: Telnet client, ANSI parser, text parser, game state
- **Modules**:
  - Character Creator: Stats rolling, class/race selection
  - Auto-Mapper: World mapping with hybrid storage (SQLite + Memvid)
  - Decision Engine: AI decision-making, combat AI, goal management
  - Quest System: Quest detection, planning, execution
  - Progression Optimizer: Grinding optimization, equipment analysis
  - LLM Integration: Ollama/OpenAI-compatible LLM client with memory
  - Web Dashboard: FastAPI-based monitoring with WebSocket support

## Installation

### Using Poetry (Recommended)

```bash
# Install Poetry if not already installed
pip install poetry

# Install dependencies
poetry install

# Activate virtual environment
poetry shell
```

### Using pip

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

## Configuration

1. Copy the example configuration:
   ```bash
   cp examples/config.example.yaml config.yaml
   ```

2. Edit `config.yaml` with your MUD server details:
   ```yaml
   mud:
     host: "your-mud-server.com"
     port: 4000
     username: "your_username"
     password: "your_password"
   ```

## Usage

```bash
# Run the AI player
python -m src.main

# Run with custom config
python -m src.main --config custom_config.yaml

# Run tests
pytest tests/ -v

# Run with coverage
pytest --cov=src --cov-report=html
```

## Project Structure

```
mud-ai-player/
├── src/                    # Source code (~7,500 lines)
│   ├── core/              # Core components
│   │   ├── telnet_client.py    # Async telnet connection
│   │   ├── game_state.py       # Game state management
│   │   ├── ansi_parser.py      # ANSI color code parsing
│   │   └── parsers/            # MUD-specific parsers
│   ├── modules/           # Specialized modules
│   │   ├── mapper/             # World mapping (SQLite + Memvid)
│   │   ├── decision/           # AI decision engine
│   │   ├── llm/                # LLM integration
│   │   ├── character/          # Character creation
│   │   ├── quest/              # Quest management
│   │   ├── progression/        # Grinding optimizer
│   │   └── web/                # Monitoring dashboard
│   ├── utils/             # Utilities
│   └── config/            # Configuration management
├── data/                  # Persistent storage
│   ├── maps/             # World maps (SQLite + Memvid)
│   ├── characters/       # Character saves
│   └── logs/             # Game logs
├── tests/                # Test suite (17 files, ~2,500 lines)
├── docs/                 # Documentation
│   ├── architecture.md   # System architecture
│   ├── configuration.md  # Configuration guide
│   ├── development.md    # Development guide
│   └── api_reference.md  # API reference
```

## Web Dashboard

The AI player includes a real-time web dashboard for monitoring:

```yaml
monitoring:
  enabled: true
  host: "127.0.0.1"
  port: 8080
```

Access the dashboard at `http://127.0.0.1:8080`

**Features:**
- Real-time character vitals (HP/MP/SP)
- Current room information with NPCs and items
- Active goals and AI state
- Map statistics (rooms discovered, exits mapped)
- Event log with game events
- WebSocket updates (no page refresh needed)

## Development

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Run tests with watch
pytest-watch
```

## Documentation

See the `docs/` directory for detailed documentation:

- [Architecture](docs/architecture.md)
- [Configuration Guide](docs/configuration.md)
- [Development Guide](docs/development.md)
- [API Reference](docs/api_reference.md)

## License

MIT License

## Contributing

Contributions are welcome! Please read the development guide before submitting PRs.

## Disclaimer

This is an educational project. Please respect the rules and terms of service of any MUD you connect to. Some MUDs prohibit automated players.