# 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:

```json
"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:
```json
{
  "player": "slingshooter08",
  "mode": "god"
}
```

Response:
```json
{
  "session_id": "sess_xxxxx"
}
```

### 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": "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