Add teleport border guard, dimension-aware TP, fully enchanted context, enchantment guidance for god

2026-03-16 19:28:51 -04:00
parent 83b9037a94
commit fe36ae3739
3 changed files with 367 additions and 5 deletions
@@ -0,0 +1,180 @@
+# LangGraph Implementation Idea
+
+## Goal
+
+Add a session-based agent gateway in front of Ollama so the Minecraft AI system can:
+- keep per-player/session memory,
+- run multi-step tool calls (MCP/web search),
+- return a final `message + commands` payload to the existing plugin.
+
+This is a future enhancement. Current system is working and remains the source of truth for command execution safety.
+
+---
+
+## Why This Exists
+
+Current `mc_aigod.py` calls Ollama directly. That is effectively stateless unless full history is re-sent every call.
+
+A LangGraph sidecar can provide:
+- persistent sessions/threads,
+- tool loop orchestration,
+- model routing,
+- better observability of intermediate reasoning steps.
+
+---
+
+## Proposed Architecture
+
+```text
+Minecraft chat -> mc_aigod.py -> LangGraph Gateway API -> Ollama
+                                      |                \
+                                      |                 -> MCP tools (web search/wiki/etc)
+                                      -> Session store (SQLite/Redis)
+```
+
+`mc_aigod.py` remains responsible for:
+- trigger parsing (`pray`, `bible`, `sudo`),
+- RCON command execution,
+- whitelist/validation/fixups,
+- hard safety rules (e.g. first-login kill limits).
+
+LangGraph gateway is responsible for:
+- session state,
+- tool calls,
+- composing final JSON output.
+
+---
+
+## API Contract Sketch
+
+### Start session
+`POST /v1/session/start`
+
+Request:
+```json
+{
+  "player": "slingshooter08",
+  "mode": "god"
+}
+```
+
+Response:
+```json
+{
+  "session_id": "sess_abc123"
+}
+```
+
+### Send message
+`POST /v1/session/{session_id}/message`
+
+Request:
+```json
+{
+  "role": "user",
+  "text": "pray I need wood for shelter",
+  "context": {
+    "server_state": {},
+    "player_state": {},
+    "recent_events": []
+  },
+  "allow_tools": true,
+  "max_tool_steps": 4
+}
+```
+
+Response:
+```json
+{
+  "message": "Divine response text",
+  "commands": [
+    "give slingshooter08 minecraft:oak_log 64"
+  ],
+  "tool_trace": [
+    {
+      "tool": "web.search",
+      "input": "minecraft oak log item id",
+      "ok": true
+    }
+  ]
+}
+```
+
+### End session (optional)
+`POST /v1/session/{session_id}/close`
+
+---
+
+## LangGraph Flow (Draft)
+
+1. Load session state by `session_id`
+2. Add user message + context
+3. Call command model
+4. If tool requested:
+   - execute MCP tool
+   - append tool result
+   - loop until final commands or step limit reached
+5. Call message model with chosen commands
+6. Return final `{message, commands}`
+7. Persist updated session state
+
+---
+
+## Tooling Plan
+
+Primary tools to add first:
+- `web.search` (general search)
+- `minecraft.wiki_lookup` (targeted page fetch/search)
+
+Potential later tools:
+- local documentation lookup,
+- server analytics lookup,
+- schematic index lookup.
+
+---
+
+## Modes to Support
+
+- `god` (prayer flow, tool-enabled)
+- `sudo` (translator flow, likely tool-disabled or very limited)
+- `god_system` (intervention/first-login internal events)
+
+---
+
+## Safety Model (Keep in mc_aigod.py)
+
+Even after LangGraph is added, keep hard enforcement in plugin runtime:
+- whitelist command families,
+- syntax repair + normalization,
+- max commands cap,
+- per-flow constraints (e.g. first-login benevolence restrictions),
+- unauthorized sudo user rejection.
+
+This ensures model/tool errors cannot directly bypass execution safeguards.
+
+---
+
+## MVP Steps (Later)
+
+1. Build FastAPI LangGraph gateway with in-memory sessions
+2. Add `/session/start` + `/session/{id}/message`
+3. Mirror current two-call behavior (no tools yet)
+4. Switch `mc_aigod.py` to gateway endpoint
+5. Add one MCP search tool and bounded tool loop
+6. Add persistence (SQLite/Redis)
+7. Add structured logs + tool traces
+
+---
+
+## Open Questions
+
+- Session lifetime policy (per player, per login, time-based expiry?)
+- Whether `sudo` should ever be tool-enabled
+- How much tool trace to expose in-game vs log-only
+- Which MCP stack to standardize on for web search
+
+---
+
+## Notes
+
+This document is a planning scratchpad for future implementation. It is intentionally practical and API-first so a coder bot can pick it up and implement directly.