Avalon

LLM-powered Avalon for local play with bots and remote humans. One game at a time, up to 7 players.

Features

• Hammer rule: 5th proposal auto-approves (no vote).
• Event log in SQLite for replay/debug.
• Human-first turn enforcement with bot catch-up.
• All core Avalon roles supported (choose any subset per game).

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e .

Model defaults to a local MLX Qwen2.5 72B 4-bit build. Override with env:

export QWEN_MODEL="mlx-community/Qwen2.5-72B-Instruct-4bit"

If you want to run without LLM inference:

export AVALON_BOT_MODE="heuristic"

Run

python -m avalon.main

Server runs at http://0.0.0.0:8010.

GUI

Open http://localhost:8010 for the control UI.

Human players should open their link at /play?player_id=... (generated by the control UI).

API (minimal)

Create a game:

curl -X POST http://localhost:8010/game/new \
  -H 'Content-Type: application/json' \
  -d '{
    "players": [
      {"id":"p1","name":"Alice","is_bot":false},
      {"id":"p2","name":"Bot1","is_bot":true},
      {"id":"p3","name":"Bot2","is_bot":true},
      {"id":"p4","name":"Bob","is_bot":false},
      {"id":"p5","name":"Bot3","is_bot":true},
      {"id":"p6","name":"Bot4","is_bot":true},
      {"id":"p7","name":"Carol","is_bot":false}
    ],
    "hammer_auto_approve": true
  }'

Start:

curl -X POST http://localhost:8010/game/start

Submit action:

curl -X POST http://localhost:8010/game/action \
  -H 'Content-Type: application/json' \
  -d '{"player_id":"p1","action_type":"chat","payload":{"message":"hello"}}'

Get public state:

curl http://localhost:8010/game/state

Get private state (role + knowledge):

curl "http://localhost:8010/game/state?player_id=p1"

Notes

• Control UI lets you select # of humans/bots, evil count, and optional roles (Percival enables Morgana).
• Merlin and Assassin are always included; other roles replace Loyal/Minion slots.
• Lady of the Lake is enabled by default (toggle in control UI).
• WebSocket stream (/game/stream) emits periodic state snapshots.