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:

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