Mortdecai/CLAUDE.md

Mortdecai — Agent Context

Single source of truth for AI agents working on this project. When docs disagree, trust this file > implementation > historical docs.

Project Identity

Mortdecai is a fine-tuned Qwen3.5-9B (and upcoming 14B) language model for Minecraft server operations. It runs inside a Paper 1.21 server via a LangGraph-style gateway, responding to player prayers (god mode) and commands (sudo mode) using 24 tools. The model is trained via QLoRA on curated + Claude-distilled + RCON-validated data.

This is NOT a chatbot, NOT a general assistant. It is a domain-specific Minecraft operations agent.

Current State (2026-03-22)

• Current model: mortdecai:0.5.0 (Qwen3.5-9B, QLoRA fine-tune)
• Base model: Qwen/Qwen3.5-9B (HuggingFace)
• Known issue: 30% empty god-mode responses (think-block token drain, no freeform text training)
• Next version: 0.6.0 (9B + 14B, training on rented H100)
• Tool count: 24 (all deployed and wired into gateway)

Canonical Files (trust these)

File	Domain	Trust
agent/tools/tool_schemas.py	Tool capability inventory	Canonical — 24 tools
langgraph_gateway.py (in Sethpc-Minecraft-PaperFork repo)	Runtime orchestrator	Canonical — production code
mc_aigod_paper.py (in Sethpc-Minecraft-PaperFork repo)	Server-side AI handler	Canonical
training/scripts/validate_all_training.py	Data quality validator	Current
training/scripts/merge_datasets.py	Training data merge	Current
training/scripts/train_lora.py	Training script	Current

Historical Files (useful but potentially stale)

File	Note
PLAN.md	Reflects 0.4.0→0.5.0 era planning. Not current deployment truth.
SESSION.md	Historical session log. May reference old architecture.
README.md	Public-facing. Tool count may lag behind tool_schemas.py.
MODEL_CARD.md	Reflects 0.5.0 release. Update on each version bump.
data/schema.json	LEGACY — does not validate current data. Use validate_all_training.py instead.
data/validate_dataset.py	LEGACY — replaced by training/scripts/validate_all_training.py.
agent/serve.py	Reference only — not the production runtime. Production runs in PaperFork repo.

Runtime Architecture

Player chat → Paper server (mc_aigod_paper.py) → LangGraph Gateway (langgraph_gateway.py)
                                                      ↓
                                               Mortdecai model (Ollama)
                                                      ↓
                                               Tool loop (24 tools, max 50 steps)
                                                      ↓
                                               RCON execution → Minecraft server

• Production entrypoint: mc_aigod_paper.py watches server log, dispatches to gateway
• Gateway: langgraph_gateway.py on port 8091 (internal to CT 644)
• Model inference: Ollama on steel141 (3090 Ti F16 for dev, RTX 4000 Q4 for prod)
• This repo contains: tools, schemas, training data, training scripts, eval harness
• The PaperFork repo contains: runtime (gateway + server handler)

24 Tools (all deployed, all wired into gateway)

Tool	Status	In Training Data
rcon.execute	Production	Yes (heavy)
minecraft.lookup	Production	Partial (was wiki_lookup)
plugin.docs_lookup	Production	Yes
world.player_info (+ inventory)	Production	Yes
world.server_state	Production	Yes
world.nearby_entities	Production	Yes
world.scan_area	Production	Needs 0.6.0 examples
world.redstone_trace	Production	Needs 0.6.0 examples
world.render	Production	Needs 0.6.0 examples
server.config	Production	Needs 0.6.0 examples
memory.read	Production	Yes
memory.write	Production	Yes
journal.read	Production	120 multitool examples
journal.write	Production	120 multitool examples
log.query	Production	Needs more examples
user.ask	Production	Needs more examples
script.write	Production	Yes
script.validate	Production	Yes
script.execute	Production	Yes
script.read	Production	Minimal
script.list	Production	Minimal
script.delete	Production	Minimal
script.schedule (tick/load/delay)	Production	Minimal
training.save	Dev only (config toggle)	Needs 0.6.0 examples

Data Map

Raw data: data/raw/ — individual JSONL files from various sources Processed data: data/processed/ — merged, filtered, validated Quarantine: data/quarantine/ — failed validation, some salvageable External: data/external/ — IGLU Microsoft Research dataset (nested git repo)

Known data issues (from validator run):

• 2,891 commands use @s (should be player name)
• 2,633 commands use enchantment syntax Paper RCON rejects
• 24,476 examples in old dict format (need conversion to messages[] chat)
• 7,647 examples have outdated system prompts (missing new tools)

Ignore List

• __pycache__/ — committed by accident, not meaningful
• USER_NOTES_IGNORE_ME/ — private notes, not project context
• data/external/iglu-repo/ — external dataset, read-only
• eval/results/ — historical eval outputs, may be stale
• data/processed/pipeline_output.jsonl — 7,032 examples with RCON connection failures marked as success. Do NOT trust.
• data/raw/scraped_*.jsonl — empty files
• web/ — admin/community tools, not model-related

Known Problems

1. Secrets in tracked files — RCON passwords, API keys hardcoded. Should be env vars.
2. README/MODEL_CARD tool count lag — says 17, reality is 24. Update on release.
3. agent/serve.py misleads — looks like main entrypoint but isn't. Real runtime is in PaperFork repo.
4. data/schema.json is legacy — doesn't validate current data. Replaced by validate_all_training.py.
5. pipeline_output.jsonl is poisoned — connection failures marked as success.

Working Rules for AI Agents

1. agent/tools/tool_schemas.py is the tool inventory. Not README, not PLAN.md.
2. The production runtime is NOT in this repo. It's in Sethpc-Minecraft-PaperFork/.
3. Paper RCON cannot give enchanted items. Use plain give + effect combos.
4. @s does not work via RCON (no executor context). Training data uses @p as a pragmatic fix, but @p selects nearest player — not always the requester. Prefer explicit player names in new training data.
5. Dev world is named devworld, not world. WorldGuard needs -w devworld.
6. When in doubt about a command, RCON-validate it on dev (192.168.0.244:25578, pass REDACTED_RCON).
7. Keep seed_dataset dominant in training mix to prevent fill_build regression.
8. The model (0.5.0) cannot produce freeform text in sudo mode — it only outputs JSON. Training 0.6.0 fixes this.
9. data/processed/pipeline_output.jsonl is poisoned (7,032 examples with RCON connection failures marked success). Excluded from training.