minecraft-ai-god/LangGraph_Implementation_Idea.md

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

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:

{
  "player": "slingshooter08",
  "mode": "god"
}

Response:

{
  "session_id": "sess_abc123"
}

Send message

POST /v1/session/{session_id}/message

Request:

{
  "role": "user",
  "text": "pray I need wood for shelter",
  "context": {
    "server_state": {},
    "player_state": {},
    "recent_events": []
  },
  "allow_tools": true,
  "max_tool_steps": 4
}

Response:

{
  "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.