Import verified AzerothAI snapshot from GitHub

Source branch: feature/ai-brain-router
Source commit: c2a09e0460465201a58aaab56c71424e9a96405e

docs/AI_BRAINS.md

@@ -0,0 +1,179 @@
+# AzerothAI Brain Architecture
+
+AzerothAI separates **who a character is** from **which model thinks for them**.
+
+Character identity, memories, relationships, housing, goals, mortality history, and possessions remain in AzerothAI. The model is replaceable compute.
+
+## Default
+
+The configured local-model default is:
+
+```text
+qwen3.5:4b
+```
+
+The seed realm remains on the deterministic provider until a local LLM endpoint is configured, so a fresh development install never fails just because Ollama is absent.
+
+For the mini-PC deployment, enable Ollama after installation and point:
+
+```text
+LLM_URL=http://ollama:11434
+```
+
+or the equivalent LAN/container address.
+
+Then select **Ollama** in Server & Models.
+
+## Router
+
+The router has separate profiles:
+
+### Resident brain
+
+Default:
+
+```text
+model: qwen3.5:4b
+memory retrieval: 8 memories
+generation budget: 220 tokens
+```
+
+Foreground residents use the configured LLM.
+
+Background residents default to deterministic utility logic so the server does not spend CPU asking every distant character for a language-model decision.
+
+### Hero brain
+
+Zaku currently uses:
+
+```text
+model: qwen3.5:4b
+memory retrieval: 16 memories
+generation budget: 420 tokens
+```
+
+The model can later be changed independently to a larger local model or remote OpenAI-compatible model without changing Zaku's identity.
+
+## Runtime routing
+
+```text
+decision requested
+      |
+      v
+Is provider deterministic?
+  yes -> utility brain
+  no
+      |
+      v
+Is character background + ordinary resident?
+  yes -> utility brain by default
+  no
+      |
+      +---- resident -> resident model profile
+      |
+      +---- hero/Zaku -> hero model profile
+```
+
+This makes compute scale with story importance rather than population count.
+
+## Character prompt boundary
+
+The LLM is told that the character lives in Azeroth and should remain in character.
+
+The prompt intentionally does not expose:
+
+- ALE credentials
+- GM commands
+- database access
+- Lua execution
+- packets
+- server administration
+- plot armor
+- simulation/runtime implementation details
+
+Zaku therefore does not know that the runtime protects him at 1 HP.
+
+## Installing the default local model
+
+On a machine running Ollama:
+
+```bash
+ollama pull qwen3.5:4b
+ollama run qwen3.5:4b
+```
+
+Verify Ollama is reachable from AzerothAI before switching the decision provider from deterministic to Ollama.
+
+## Swapping models
+
+Changing:
+
+```text
+brains.residentModel
+brains.heroModel
+```
+
+changes only inference.
+
+It does not reset:
+
+- memories
+- relationships
+- housing
+- inventory/world history
+- personality recipes
+- goals
+- death records
+
+This allows future model upgrades without "replacing" the character.
+
+## Benchmarking
+
+Run:
+
+```bash
+MODELS=qwen3.5:4b,<another-model> OLLAMA_URL=http://127.0.0.1:11434 pnpm bench:brains
+```
+
+The benchmark records:
+
+- response latency
+- valid JSON rate
+- allowed-action compliance
+- approximate response length
+- raw in-character rationale for manual review
+
+The benchmark scenarios focus on AzerothAI-specific situations rather than generic academic benchmarks.
+
+The eventual evaluation set should include at least:
+
+- friend permanently dies
+- near-death experience
+- dungeon invitation
+- stranger enters home
+- low money
+- dangerous travel
+- betrayal
+- gift from a friend
+- argument
+- rumor
+- late-night fatigue
+- conflicting goals
+- player behaving strangely
+- seeing a GM-like supernatural event without knowing its cause
+
+## Future provider routing
+
+The router is provider-independent.
+
+Possible later policy:
+
+```text
+background residents -> deterministic utility brain
+foreground residents -> Qwen3.5 4B
+major NPCs -> larger local model
+Zaku routine decisions -> local model
+Zaku rare deep reflection -> optional stronger local/cloud endpoint
+```
+
+Cloud providers are optional. Character identities never belong to the provider.