Balthazar

   

LLM-powered MajorMUD playtest bot that accepts markdown-based skills and a DeepSeek API key to play autonomously.

Architecture

  Telnet Client         ANSI Parser         State Extractor
  (telnetlib3)     ->   (regex strip)   ->  (structured state)
       |                                              |
       v                                              v
  MajorMUD Server                              Agent Memory
                                                     |
       ^                                              v
       |                                        LLM Agent
  Command Executor  <-  Command Validator  <-  (DeepSeek API)

Quick Start

1. Copy .env.example to .env and fill in your credentials:

cp .env.example .env

2. Set DEEPSEEK_API_KEY and your MUD server details.

3. Install dependencies:

pip install -e .

4. Run the bot:

python -m balthazar.main

Skills

Skills are markdown files in skills/ that teach the bot how to play. Each skill has YAML frontmatter:

---
category: combat
priority: 10
triggers: combat, attack, fight
---
# Combat Skill
Rules for fighting monsters...

Create new .md files to add behaviors. Higher priority skills take precedence.

Knowledge Base

Game data (races, classes, commands, quests, maps) lives in knowledge/ as markdown files. These are injected into the LLM's system prompt as reference material.

Configuration

Variable	Default	Description
DEEPSEEK_API_KEY	-	DeepSeek API key (required)
DEEPSEEK_MODEL	deepseek-chat	Model to use
MUD_HOST	localhost	MUD server hostname
MUD_PORT	23	MUD server port
MUD_USERNAME	-	Login username
MUD_PASSWORD	-	Login password
MUD_CHARACTER	-	Character name
MAX_TURNS	1000	Max turns per session
LOG_LEVEL	INFO	Logging verbosity

Project Structure

src/balthazar/
  main.py           # Entry point
  config.py         # .env configuration
  loop.py           # Main agent loop
  telnet/
    client.py       # Async telnet connection & login
  parser/
    ansi.py         # ANSI escape stripping
    output.py       # Prompt detection, regex extraction
    state.py        # State extraction from parsed output
  agent/
    llm.py          # DeepSeek API client
    skills.py       # Markdown skill/knowledge loader
    memory.py       # Short-term & long-term memory
  game/
    state.py        # GameState dataclass
    commands.py     # Command reference & validation
skills/             # Markdown skill files
knowledge/          # Game knowledge base
logs/               # Session transcripts