Apppublic

Forkei/metropolis-chess

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

Metropolis Chess Club

Chess Club is an LLM-driven chess platform built for Metropolis World. The core architecture pairs a personality LLM (Soul) with a real chess engine (Maia-2 for human-like play, Stockfish for high-skill mode) so characters have voice, mood, and memory while moves are genuine engine play. Players can create their own AI agents and deploy them against characters. Phases 1, 2a, 2b, 3a, 3b, and 3c are shipped; Phase 2 feature blocks (agent creation, $CLAY economy, autonomy loop) are flag-gated.

Live demo

URL: https://huggingface.co/spaces/Forkei/metropolis-chess GitHub: https://github.com/Forkei/adaptive-chess-club

Sign up with any username (lowercase letters, digits, underscores; 3–24 chars). No email required on first signup — username-only. On first visit you'll see the character grid; pick Kenji to start a match. Agent creation is available in production. The $CLAY economy and agent autonomy surfaces are hidden until Metropolis platform integration is ready (see feature flags).

Local dev setup

Supported targets: Docker (recommended), or a local venv on macOS/Linux/WSL2. Windows-native is not supported — use WSL2.

Docker

First build takes 10–20 minutes (Maia-2 weights + torch).

bash

cp .env.example .env         # add GEMINI_API_KEY for LLM features
docker compose up --build

App at http://localhost:8000. Presets seed on first boot; memories generate in background if GEMINI_API_KEY is set. Maia-2 weights are cached in a Docker volume.

Local venv (no real engine)

Useful for frontend/backend work without pulling torch/Maia-2.

bash

python -m venv .venv && source .venv/bin/activate   # Windows WSL: same
pip install -e ".[dev]"
cp .env.example .env
uvicorn app.main:app --reload

Character pages, auth, and match creation work fully. Moves run against MockEngine (deterministic first-legal-move — boring, but correct). For real play:

bash

pip install -e ".[dev,engine]"
python scripts/setup_engines.py   # downloads Maia-2 weights (~300 MB)

Git LFS

Binary assets — chess piece PNGs, Kenji's emotion videos, all audio files — are in Git LFS. After cloning:

bash

git lfs pull

Without this, images and videos are 134-byte pointer stubs and the board renders empty squares.

Env vars

Required for LLM features:

Variable	Notes
`GEMINI_API_KEY`	Google Gemini key. Without it the app starts but Kenji is silent and presets seed without memories.

Optional (with defaults):

Variable	Default	Notes
`DATABASE_URL`	`sqlite:///./metropolis_chess.db`	HF Spaces uses `sqlite:////data/metropolis_chess.db` for persistence across restarts
`SESSION_SECRET`	`""`	Cookie integrity secret. Empty = unsigned cookies, fine for dev
`REDIS_URL`	`""`	No Redis → in-process mood/cache state. Single-worker only
`STOCKFISH_PATH`	`/usr/games/stockfish`	Path to Stockfish binary
`MAIA2_CACHE_DIR`	`""`	Maia-2 weights directory
`ALLOW_CHARACTER_API`	`False`	Set `1` to enable character create/edit/clone REST endpoints (required for the character creation web form to work)

Running tests

bash

pytest -m "not live" -q              # 589 passing; 2 known pre-existing failures
RUN_LIVE_LLM_TESTS=1 pytest -m live  # opt-in; needs GEMINI_API_KEY

The 2 failing tests are stale assertions from earlier phases, not regressions. See docs/GOTCHAS.md.

Feature flags

Three env vars gate Phase 2 surfaces. Set to 1 to enable; 0 or absent to disable.

Variable	Production default	What it unlocks
`SHOW_PLAYER_AGENTS`	on	Agent creation, agent rooms, agent-vs-Kenji match flow
`SHOW_CLAY_ECONOMY`	off	$CLAY balance display, wager UI on match/summary pages, transaction history
`SHOW_AGENT_AUTONOMY`	off	Agent goal proposals and autonomy loops (requires `SHOW_PLAYER_AGENTS`)

Flags hide UI entry points only. Backend economy logic and agent data are always active — data written while a flag was on persists and reappears when the flag is re-enabled.

For a Phase 1-only build (community testers, no agent UI):

bash

SHOW_PLAYER_AGENTS=0 uvicorn app.main:app --reload

Where to find more

—`docs/ARCHITECTURE.md` — four-layer runtime, match turn lifecycle, memory model, streaming patterns, and the integration seams for Metropolis platform work
—`docs/GOTCHAS.md` — things that bit us, known test failures, template divergences, and other surprises worth documenting