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

```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.