0 Fork 0

Files

T

truetype 9a113002d4 feat: make embedding model configurable for semantic search

- Add SemanticSearchConfig to settings.py with embedding model options
- Update WorldMapper to accept embedding_model parameter
- Update main.py to pass model from config to WorldMapper
- Add documentation for available embedding models:
  - sentence-transformers/all-MiniLM-L6-v2 (default, fast)
  - sentence-transformers/all-mpnet-base-v2 (better quality)
  - google/embeddinggemma-300m (state-of-the-art)
- Update config.yaml and config.example.yaml with new options

Users can now choose the best embedding model for their needs.

2026-02-09 11:01:29 +01:00

4.9 KiB

Raw Blame History

Configuration Guide

This guide covers all configuration options for the MUD AI Player.

Configuration File

The main configuration file is config.yaml. An example is provided in examples/config.example.yaml.

Configuration Sections

MUD Connection Settings

mud:
  host: "192.168.0.63"          # MUD server hostname or IP
  port: 6666                     # MUD server port
  mud_type: "dead_souls"         # Parser type: dead_souls, aardwolf, etc.
  username: "your_username"      # Login username
  password: "your_password"      # Login password
  keep_alive_interval: 60        # Seconds between keep-alive commands
  keep_alive_command: ""         # Command to send for keep-alive (empty = no-op)

Character Settings

character:
  name: "AIPlayer"               # Character name
  preferred_class: "warrior"     # warrior, mage, cleric, rogue
  preferred_race: "human"        # human, elf, dwarf, etc.
  play_style: "balanced"         # aggressive, cautious, balanced

AI Engine Settings

ai:
  engine: "hybrid"               # rule_based, llm, hybrid
  llm_model: "llama3.2"          # LLM model name
  decision_delay_ms: [200, 2000] # Min/max reaction time in milliseconds
  exploration_strategy: "depth_first"  # depth_first, breadth_first
  
  llm:
    enabled: true                # Enable/disable LLM features
    base_url: "http://localhost:11434"  # Ollama/OpenAI-compatible endpoint
    model: "llama3.2"            # Model to use
    temperature: 0.3             # Creativity vs consistency (0.0-1.0)
    max_tokens: 512              # Max response length
    timeout_seconds: 30.0        # Request timeout
    max_retries: 2               # Retry attempts on failure
    system_prompt: "You are an AI playing a text-based MUD game..."
    memory_db_path: "data/llm_memory.db"  # Long-term memory storage

Mapper Settings

mapper:
  active_storage:
    db_path: "data/maps/active/world.db"
    graph_cache_size: 10000
  
  historical_storage:
    archive_dir: "data/maps/archive"
    snapshot_triggers:
      room_count: 500            # Trigger snapshot every N rooms
      session_end: true          # Snapshot on disconnect
      time_interval_hours: 24    # Periodic snapshots
    compression:
      fps: 30
      codec: "h264"
  
  semantic_search:
    # Embedding model for semantic room search
    # Available models:
    #   - "sentence-transformers/all-MiniLM-L6-v2" (default, fast, 22MB)
    #   - "sentence-transformers/all-mpnet-base-v2" (better quality, 418MB)
    #   - "google/embeddinggemma-300m" (state-of-the-art, requires transformers>=4.40)
    model: "sentence-transformers/all-MiniLM-L6-v2"
    top_k: 5                     # Number of search results
    similarity_threshold: 0.7    # Minimum similarity score

Behavior Simulation

behavior:
  reaction_time_min_ms: 200      # Minimum delay between actions
  reaction_time_max_ms: 2000     # Maximum delay between actions
  pause_probability: 0.05        # Chance to pause briefly (5%)
  typo_probability: 0.0          # Chance to make typos (0% = disabled)

Logging

logging:
  level: "DEBUG"                 # DEBUG, INFO, WARNING, ERROR
  file: "data/logs/game.log"     # Log file path
  console: true                  # Also log to console
  max_file_size_mb: 10           # Rotate when file reaches this size
  backup_count: 5                # Number of backup files to keep

Web Monitoring Dashboard

monitoring:
  enabled: true                  # Enable/disable web dashboard
  host: "127.0.0.1"             # Bind address
  port: 8080                     # Port for dashboard

Environment Variables

You can override any configuration value using environment variables:

export MUD_HOST="your-mud-server.com"
export MUD_PORT=4000
export MUD_USERNAME="player"
export MUD_PASSWORD="secret"

Multiple Configurations

To use different configurations for different MUDs:

# For Dead Souls MUD
python -m src.main --config config_dead_souls.yaml

# For Aardwolf MUD
python -m src.main --config config_aardwolf.yaml

Security Notes

⚠️ Important: The config.yaml file contains sensitive credentials. It is automatically excluded from Git via .gitignore.

Never commit your config.yaml to version control. Always use the example file as a template.

Configuration Validation

The configuration is validated at startup using Pydantic models. If a required field is missing or invalid, the application will exit with a clear error message.

Troubleshooting

Connection Issues

Verify host and port are correct
Check firewall rules
Ensure mud_type matches your MUD

LLM Not Working

Verify Ollama is running: curl http://localhost:11434/api/tags
Check ai.llm.enabled is set to true
Ensure the model is installed: ollama pull llama3.2

Mapper Not Saving

Check that data/maps/ directory exists and is writable
Verify disk space is available
Check file permissions

4.9 KiB Raw Blame History