AzerothAI/README.md

# AzerothAI — Living Realm prototype

A working private web control plane for an AI-populated, self-hosted realm. The real player is the center of the experience: the Realm Director sets the tone, bot identities provide continuity, and the GM console lets the operator stage the world.

**Boundary:** AzerothCore handles movement, combat, inventory, progression, and game rules. AzerothAI owns identity, personality, high-level goals, memory, and relationships. No model gets GM access.

## What runs today

- Dark navy/gold dashboard inspired by the supplied Living Realm mockup.
- Persistent bot creation, spawn, pause, resume, despawn, and retirement.
- Versioned recipes with per-bot snapshots; explicit recipe reapplication.
- Operator memories, generated observation memories, and directed relationships.
- Realm Director updates goals around a named player and focus zone.
- Manual decision loop: observe → assemble context → decide → validate → connector acknowledgment → memory/event.
- Reconnectable SSE event feed with sequence replay and a 500-event retention window.
- Deterministic personality simulator, Ollama provider, and OpenAI-compatible local model provider.
- GM terminal with history and simulated or confirmed live SOAP commands.
- Durable D1/SQLite state with optimistic revision checks and bounded operation leases.
- Modular TypeScript interfaces for additional game connectors and inference providers.
- Live World Monitor for Zaku, population bands, zones, Hardcore deaths, ALE pulse, and system health.
- Disposable playable realm profile for AzerothCore + Playerbots + ALE.
- Temporary Windows-PC/Ubuntu-VM lab profile with Windows-hosted Ollama/Qwen and migration export.

The default demo contains six sample identities and four recipes. **It is not connected to an actual game server or LLM.** Simulation acknowledgments do not mean a character was created in WoW.

## Source layout

```text
app/page.tsx                  Dashboard and all management views
app/globals.css               Navy/gold visual theme and responsive layout
app/api/state/route.ts        Persistent realm snapshot
app/api/actions/route.ts      Validated commands
app/api/events/route.ts       Reconnectable SSE batches
app/api/health/route.ts       Configuration availability (no secrets)
core/types.ts                 Game-neutral contracts and domain types
core/service.ts               Lifecycle, recipes, memory, director, audit
core/validation.ts            Zod input and decision validation
core/connectors/index.ts      Simulation and AzerothCore HTTP bridge adapters
core/llm/index.ts             Deterministic, Ollama, compatible providers
core/gm.ts                    Human-only allowlisted SOAP command channel
core/store.ts                 D1 repository and optimistic concurrency
core/seed.ts                  Explicit demo data
 db/schema.ts                 Drizzle schema
 drizzle/                    Generated schema migrations
 docs/CONNECTORS.md           Bridge contract and extension guide
 docs/OPERATIONS.md           Local setup, credentials, limitations
 tests/core.test.cjs          Core behavior and failure tests
 scripts/test-core.mjs        Compile/run tests
 deploy/playable/              Private playable-realm bootstrap
 deploy/pc-lab/                Temporary Windows + Ubuntu VM lab
```

## Local quick start

Use Node 22.13+ and the pnpm version pinned in `package.json`. The project runs locally with Cloudflare's Worker emulator and SQLite; no paid cloud account or model is required for simulation.

```bash
corepack enable
pnpm install --frozen-lockfile
pnpm build
node --import ./scripts/sites-env.mjs ./node_modules/wrangler/bin/wrangler.js d1 execute DB --local --config dist/server/wrangler.json --persist-to .wrangler/state --file drizzle/0000_old_deathbird.sql
pnpm start
```

Open the loopback URL printed by Wrangler (normally http://127.0.0.1:8787). `pnpm start` is local, not a deployment. Preserve `.wrangler/state` for persistence. The managed Work environment uses its supervised preview instead.

For live integrations, copy `.env.example` to `.dev.vars`, populate the needed settings, and restart the local runtime. Do not commit that file. Hosted settings are supplied separately through the hosting platform. A cloud-hosted app cannot reach your home server's `localhost`.

## Fastest path to a playable temporary lab

For a Windows gaming PC with an Ubuntu VM, use `deploy/pc-lab/README.md`. It keeps WoW and Qwen/Ollama on Windows while AzerothCore, Playerbots, ALE, MySQL, and AzerothAI run inside the VM.

For a dedicated Linux host, use `deploy/playable/README.md`.

## Try the intended flow

1. Open Realm Director. Pick the experience, enter your character and zone, and apply your brief.
2. Create an offline bot with a recipe. Open its profile and spawn it in simulation.
3. Add a memory and a relationship. Run a decision and inspect the resulting intent.
4. Edit its recipe. Notice that the bot keeps its old snapshot until explicitly updated.
5. Open GM Console and try `.announce Welcome to the realm!`. The response is labeled simulated.
6. Watch Event Stream and reload the app to verify state persists.

## Checks

```bash
node node_modules/typescript/bin/tsc --noEmit
node scripts/test-core.mjs
pnpm build
```

## Integration status

The GM SOAP client is implemented against AzerothCore's documented remote-access protocol; live execution needs your server and credentials. The bot HTTP connector is an implemented client for **our bridge contract**, not an assertion that stock AzerothCore exposes those endpoints. A game-side adapter for your actual core/Playerbots branch still needs implementation and end-to-end testing.

AzerothCore version/client selection must be settled before that adapter is written; a Classic-style experience does not establish compatibility with the modern WoW Classic client. This prototype deliberately stores no client-version assumption in its domain model.

See [operations](docs/OPERATIONS.md) for operational limits and [connectors](docs/CONNECTORS.md) for API contracts.