minecraft-ai-god-paper-fork/LangGraph_Implementation_Idea.md

LangGraph Gateway - Implemented MVP (Paper Fork)

Status

Implemented in this fork as a FastAPI sidecar:

• Script: /usr/local/bin/langgraph_gateway.py
• Service: mc-langgraph-gateway.service
• Config: /etc/mc_langgraph_gateway.json
• Bind: 127.0.0.1:8091

mc_aigod_paper.py can route pray/sudo/system flows through this gateway when:

"use_langgraph_gateway": true

Safety enforcement remains in mc_aigod_paper.py (whitelist, fixups, caps, auth checks).

---

Implemented API

Start session

POST /v1/session/start

Request:

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

Response:

{
  "session_id": "sess_xxxxx"
}

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": "minecraft.wiki_lookup", "ok": true, "results_count": 2}]
}

Close session

POST /v1/session/{session_id}/close

Health

GET /healthz

---

Session + Memory Model

• In-memory sessions keyed by session_id
• mc_aigod_paper.py keeps player+mode -> session_id mapping
• /v1/session/start reuses active session for same player+mode when possible
• Session TTL configurable (session_ttl_seconds, default 6h)
• Last message turns are fed back into gateway model calls
• SQLite persistence enabled by default via session_db_path (survives gateway restarts)

Redis backend is not implemented yet (optional future step).

---

Modes Wired

• god -> prayer flow
• sudo -> translator flow
• god_system -> interventions and first-login system events

---

Tool Loop (MVP)

Bounded tool loop implemented with max step cap:

• minecraft.wiki_lookup
• web.search

Current planner is lightweight heuristic router; this is intentionally bounded and conservative.

---

Runtime Safeguards (still in mc_aigod_paper.py)

Even with gateway enabled, commands are still post-processed by runtime safety:

• command family whitelist
• syntax repair + normalization
• max commands cap
• sudo user authorization
• first-login constraints (e.g. max one player kill)

So gateway/model/tool errors cannot directly bypass execution constraints.

Gateway also applies an early command sanitation pass before returning output:

• strips leading /
• drops prose/non-command payloads
• enforces mode-specific command prefixes
• deduplicates and caps command count

---

Known Current Behavior

• Session state survives gateway restarts when SQLite persistence is enabled.
• Tool traces are logged in mc_aigod_paper.log but not shown in-game.
• Redis persistence backend is not implemented yet.

---

Next Steps

1. Add optional Redis persistence backend
2. Add richer tool planner node (LangGraph proper state machine)
3. Add optional tool trace exposure in debug mode
4. Add stricter command schema output in gateway (model-side)
5. Add MCP-based tool adapters