AzerothAI/docs/AI_BRAINS.md

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:

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:

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:

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:

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

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:

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:

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:

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:

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.