# 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

## 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

## 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
│   ├── core/              # Core components
│   ├── modules/           # Specialized modules
│   ├── utils/             # Utilities
│   └── config/            # Configuration management
├── data/                  # Persistent storage
│   ├── maps/             # World maps (SQLite + Memvid)
│   ├── characters/       # Character saves
│   └── logs/             # Game logs
├── tests/                # Test suite
├── docs/                 # Documentation
└── examples/             # Example configurations
```

## 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.