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 with configurable embedding models (MiniLM, MPNet, Gemma)
- 📊 **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
```

## 🎮 Autonomous Mode

**Modalità completamente autonoma** dove il bot esplora, impara e cresce da solo guidato dall'LLM:

```bash
# Avvia esplorazione autonoma per 60 minuti
python -m src.autonomous_mode --duration 60

# Con config personalizzata
python -m src.autonomous_mode --config my_config.yaml --duration 120
```

**Caratteristiche:**
- 🤖 **LLM-First**: L'LLM prende tutte le decisioni strategiche
- 🗺️ **Auto-Mapping**: Esplora e mappa automaticamente il mondo
- 🧠 **Learning**: Memorizza stanze pericolose, NPC utili, pattern
- 📊 **Session Logging**: Salva tutto in `data/autonomous_sessions/`
- 🎯 **Goal Dinamici**: Obiettivi di esplorazione e crescita
- 🛡️ **Safety First**: Override automatico se HP critici

**Esempio di output:**
```
🚀 Avviata sessione autonoma: session_20240209_143022
🧠 Decisione LLM: [explore] north
   Ragionamento: Uscita non esplorata, pericolo basso
🔍 Scoperta: [room] Village Square: You are standing in...
📄 Log completo: data/autonomous_sessions/session_20240209_143022.json
```

## Configurable Embedding Models

Choose the best embedding model for semantic room search:

```yaml
mapper:
  semantic_search:
    # Available models:
    # - "sentence-transformers/all-MiniLM-L6-v2" (fast, 22MB) - default
    # - "sentence-transformers/all-mpnet-base-v2" (better quality, 418MB)
    # - "google/embeddinggemma-300m" (state-of-the-art, ~300MB)
    model: "google/embeddinggemma-300m"
```

| Model | Size | Speed | Quality | Use Case |
|-------|------|-------|---------|----------|
| **all-MiniLM-L6-v2** | 22MB | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Low resource, fast queries |
| **all-mpnet-base-v2** | 418MB | ⭐⭐⭐ | ⭐⭐⭐⭐ | Better accuracy, balanced |
| **google/embeddinggemma-300m** | ~300MB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Best quality, requires transformers>=4.40 |

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.