minecraft-ai-god/README.md

# Minecraft AI God

A Python log-watcher + RCON automation script that gives a vanilla Minecraft server an in-game AI "God".

Players type chat triggers (`pray`, `bible`, `sudo`) and the agent:
- reads context from server state + player state + recent logs,
- calls local LLM(s),
- executes validated commands via RCON,
- and speaks in public chat.

No Bukkit/Paper plugin required.

---

## What Is Included

- **God prayer pipeline** (`pray <message>`)
- **Two-call LLM architecture**
  - command model decides commands (JSON)
  - message model writes divine speech (text)
- **Divine intervention timer** (random unprompted acts)
- **First-login benevolence** (one-time blessing per player)
- **Bundled sudo translator agent** (`sudo <request>`) with whitelist + user lock
- **Bug logging trigger** (`bug_log <optional description>`) with recent context capture
- **Persistent prayer memory**
- **Rolling server event memory** (up to 3 hours / 200 events)
- **Debug command preview** toggle

---

## Trigger Commands (Chat, No Slash)

Vanilla 1.21 rejects unknown slash commands client-side. Use plain chat messages:

- `pray <message>` — prayer flow (God judgment + optional commands + speech)
- `bible` — private usage/help text
- `sudo <request>` — command translator mode (authorized user only)
- `bug_log <optional description>` — append bug report with recent server logs/events

Examples:
- `pray Lord, I need food and shelter`
- `bible`
- `sudo give me 500 wood`
- `bug_log creeper exploded through wall near spawn`

---

## Architecture

```text
chat line -> latest.log tail -> trigger parser

pray path:
  ack player -> gather context -> commands call -> message call -> execute commands -> broadcast message

sudo path:
  auth check -> translate request to commands -> validate/repair -> execute -> private preview

join path:
  login notice -> one-time first-login benevolence event

timer path:
  poisson interval -> if players online -> intervention commands+message
```

### Two-call design (prayer/intervention)

1. **Commands call** (`command_model`)
   - strict JSON output
   - low temp for stable command generation
2. **Message call** (`model`)
   - prose only
   - no token competition with command JSON

This avoids the common failure mode where long speech truncates commands.

---

## Context Passed to LLM

### Prayer / Intervention context

- Online players
- Player positions + distance from spawn
- Time of day, weather, world border
- Scoreboard-derived state where available (deaths, shrink flags)
- Recent server events (chat/death/join/leave), capped by both:
  - last **3 hours**
  - last **200 events**
- Prayer memory (last 10 exchanges)

### Praying player state

- Inventory summary (with rarity annotations)
- Health
- Food level
- XP level
- Death count

### Sudo context

- Requesting player
- Online players
- Current natural-language sudo request
- Last 10 sudo actions:
  - request text
  - translated commands
  - executed commands

This helps sudo correct previous bad translations.

---

## Safety and Validation

- Command-family whitelist enforced (`give`, `effect`, `xp`, `tp`, `time`, `weather`, `execute`, `kill`, `summon`, `tellraw`, `worldborder`)
- Auto-repair for common malformed outputs:
  - transposed `give` args (`give player 64 item`)
  - missing `minecraft:` namespace
  - shorthand aliases (`wood` -> `oak_log`, `door` -> `oak_door`, `bed` -> `white_bed`, etc.)
  - malformed `effect` form corrected to `effect give ...`
- Max commands per response cap
- Per-player prayer cooldown
- First-login benevolence can include many commands but is benevolent by prompt rules
- If kill commands appear in first-login mode, at most one player kill is allowed

---

## Configuration

Main file: `/etc/mc_aigod.json`

| Key | Type | Description |
|---|---|---|
| `server_name` | string | Friendly server name for prompts |
| `log_path` | string | Absolute path to `latest.log` |
| `rcon_host` | string | RCON host |
| `rcon_port` | int | RCON port |
| `rcon_password` | string | RCON password |
| `ollama_url` | string | Ollama API base URL |
| `model` | string | Message model (creative prose) |
| `command_model` | string | Command model (JSON/command generation) |
| `temperature` | float | Message generation temperature |
| `max_tokens` | int | Message call max tokens |
| `cooldown_seconds` | int | Prayer cooldown per player |
| `max_commands_per_response` | int | Max commands in prayer/intervention response |
| `interventions_per_day` | float | Avg random acts/day (Poisson) |
| `god_chat_prefix` | string | Prefix for God speech |
| `debug_commands` | bool | Show `[~]` command preview in chat |
| `god_lore` | string | Optional lore block injected into message system prompt |
| `memory_path` | string | Prayer memory JSON path |
| `sudo_enabled` | bool | Enable/disable sudo agent |
| `sudo_user` | string | Authorized sudo username |
| `sudo_max_commands` | int | Max commands translated from one sudo request |
| `first_login_benevolence_enabled` | bool | Enable one-time first-login blessing |
| `first_login_benevolence_max_commands` | int | Max commands in first-login blessing |
| `first_login_path` | string | Persistent file storing already-blessed players |
| `bug_log_path` | string | File path used for `bug_log` entries |
| `bug_log_event_lines` | int | Number of in-memory interesting events to attach |
| `bug_log_raw_lines` | int | Number of raw tail log lines to attach |

### Current shrink-world example

```json
{
  "server_name": "shrink-world",
  "log_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/logs/latest.log",
  "rcon_host": "127.0.0.1",
  "rcon_port": 25576,
  "rcon_password": "REDACTED_RCON",
  "ollama_url": "http://192.168.0.141:11434",
  "model": "gemma3:12b",
  "command_model": "qwen3-coder:30b",
  "temperature": 0.85,
  "max_tokens": 600,
  "cooldown_seconds": 20,
  "max_commands_per_response": 6,
  "interventions_per_day": 48,
  "god_chat_prefix": "[§6§lGOD§r]",
  "debug_commands": true,
  "sudo_enabled": true,
  "sudo_user": "slingshooter08",
  "sudo_max_commands": 3,
  "first_login_benevolence_enabled": true,
  "first_login_benevolence_max_commands": 10,
  "first_login_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_first_login_seen.json",
  "god_lore": "This is the shrink-world server...",
  "memory_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_memory.json"
}
```

---

## Deployment

```bash
# Dependencies
apt install -y python3-requests

# Install script + config + service
cp mc_aigod.py /usr/local/bin/mc_aigod.py
chmod +x /usr/local/bin/mc_aigod.py
cp mc_aigod_shrink.json /etc/mc_aigod.json
cp mc-aigod.service /etc/systemd/system/mc-aigod.service

# Start service
systemctl daemon-reload
systemctl enable --now mc-aigod.service

# Logs
journalctl -fu mc-aigod.service
tail -f /var/log/mc_aigod.log
tail -f /var/log/mc_aigod_responses.log
```

---

## Debugging Checklist

- No response on trigger?
  - Ensure you typed `pray` / `bible` / `sudo` in chat **without slash**
- Sudo does nothing?
  - Confirm username matches `sudo_user`
  - Check `sudo_enabled`
- Unknown item errors?
  - See `/var/log/mc_aigod.log` for translated command + server error
  - Alias/repair may still need extension for new slang terms
- Long God speech issues?
  - Two-call design is active; commands are decided separately from message text
- Random acts too frequent?
  - Lower `interventions_per_day`

---

## File Map

- `mc_aigod.py` — main script
- `mc_aigod_shrink.json` — real config template
- `mc-aigod.service` — systemd unit
- `Minecraft_Ai_God.md` — deeper design/context notes
- `CONTEXT.md` / `COMMANDS.md` — local infrastructure references

---

## Deployed Reference (Sethpc)

- Host: CT 644 (MCSManager)
- Server: `shrink-world` (RCON `25576`)
- Ollama: `http://192.168.0.141:11434`
- Models:
  - message: `gemma3:12b`
  - commands: `qwen3-coder:30b`
- Service: `mc-aigod.service`