extremal.online · extremalgames.ai · API · GitHub

Competitive graph search game with leaderboards and generative graph art. Players run search workers that discover high-scoring Ramsey graphs and submit them to a central leaderboard server. Each graph produces a unique deterministic "gem" visualization from its adjacency matrix.

Extremal Games is the overarching project — a blog and landing page covering the math, the AI experiments, and the competitive search game. extremal.online is the live leaderboard server where you can view rankings, explore graphs, and submit your own.

Canary

This is my canary:

This repo contains code entirely generated by agentic coding. Run it at your own risk. If you notice a bug or vulnerability, or bad design, please submit a pull request.

One reason I built this project was to test to see how good AI gets at optimizing closed loop optimization problems. One foundational idea behind Extremal is that it provides an ever increasing complex problem that progress can be made on (higher dimension graphs, high numbers of extremal graphs). Observing how well AI can push that boundary, we can better understand how close we are to achieving a kind of "infinite paperclip machine" kind of capability. --tswedish

What it does

• Workers run combinatorial search strategies (beam search, perturbation) to find graphs with few monochromatic cliques
• Server scores submissions using clique histograms + canonical labeling (nauty), maintains ranked leaderboards per vertex count
• Dashboard shows live worker telemetry: progress, discoveries, and rain visualization of gem art
• Web app displays leaderboards, activity feeds, and identity profiles with SSE real-time updates

Architecture

                  ┌──────────────────┐
                  │  Leaderboard     │
  Workers ──────► │  Server (:3001)  │ ◄──── Web App (:5173)
  (submit graphs) │  PostgreSQL      │       (SvelteKit)
                  └──────────────────┘
                  ┌──────────────────┐
                  │  Dashboard Relay │
  Workers ──WS──► │  (:4000)         │ ◄──WS── Dashboard UI (:5174)
  (telemetry)     │  Ed25519 auth    │        (SvelteKit)
                  └──────────────────┘
                  ┌──────────────────┐
  CLI ──HTTP────► │  Worker HTTP API │
  (control)       │  (:auto-assigned)│
                  └──────────────────┘

12 Rust crates + 2 SvelteKit web apps + shared component package:

Crate	Description
extremal-types	Core newtypes: GraphCid (blake3), KeyId, Verdict
extremal-graph	AdjacencyMatrix, graph6 encode/decode, blake3 CID
extremal-scoring	Clique histogram, Goodman gap, canonical labeling (nauty), GraphScore
extremal-identity	Ed25519 keypair, signing, verification
extremal-store	PostgreSQL data layer (sqlx), advisory locks
extremal-server	Axum REST API + SSE, rate limiting, graceful shutdown
extremal-worker-api	SearchStrategy trait, ConfigParam (adjustable flag)
extremal-strategies	tree2 beam search, Paley graph init
extremal-worker-core	Engine loop, command channel, HTTP API, dashboard telemetry
extremal-worker	Worker CLI binary
extremal-cli	CLI: keygen, submit, score, leaderboard, worker management
extremal-dashboard	Relay server: WebSocket, Ed25519 challenge/response auth

Quick Start

Prerequisites

• Rust stable (via rustup)
• PostgreSQL 14+
• Node.js 24+ (for web apps)

Database setup

sudo -u postgres createuser extremal
sudo -u postgres createdb -O extremal extremal
sudo -u postgres psql -c "ALTER USER extremal WITH PASSWORD 'extremal';"

Environment

cp .env.example .env

Run the server

# First run (creates tables)
cargo run -p extremal-server -- --migrate

# Generate a worker identity and register it
cargo run -p extremal-cli -- keygen --name "my-worker"
cargo run -p extremal-cli -- register-key

Run workers

# Single worker
cargo run -p extremal-worker -- --n 25 --beam-width 80 --max-depth 12

# With dashboard connection
cargo run -p extremal-worker -- --n 25 --beam-width 80 \
  --dashboard ws://localhost:4000/ws/worker

# Fleet of diverse workers
./scripts/experiment.sh 25

Dashboard and web apps

./run dashboard       # Relay server on :4000
./run dashboard-ui    # Dashboard UI on :5174
./run web-dev         # Web app on :5173

CLI

extremal score --n 5 --graph6 'Dhc'           # Score locally
extremal submit --n 5 --graph6 'Dhc'          # Submit to server
extremal leaderboard --n 25                    # View leaderboard
extremal health                                # Server health
extremal workers list                          # List connected workers
extremal workers set fleet-1 beam_width=200    # Adjust worker params
extremal workers pause fleet-1                 # Pause a worker

Docker

docker compose up --build    # Server + Postgres

Scoring System

Golf-style ranking (lower is better). For a graph G on n vertices:

1. k-clique histogram: for each k from max_k down to 3, compare (max(red_k, blue_k), min(red_k, blue_k)) lexicographically
2. Goodman gap: monochromatic triangles minus theoretical minimum
3. Automorphism order: 1/|Aut(G)| via nauty (more symmetric = better)
4. CID: blake3 hash tiebreaker

Server API

Port 3001, prefix /api/. Rate limited (5/s scoring, 100/s global per IP).

Endpoint	Method	Description
/api/health	GET	Health check + pool stats
/api/submit	POST	Score, store, admit, sign receipt
/api/verify	POST	Stateless scoring (no DB write)
/api/leaderboards	GET	List all leaderboards by n
/api/leaderboards/{n}	GET	Paginated leaderboard
/api/leaderboards/{n}/threshold	GET	Admission score threshold
/api/leaderboards/{n}/cids	GET	Incremental CID sync
/api/leaderboards/{n}/graphs	GET	Batch graph6 download
/api/submissions/{cid}	GET	Submission detail + receipt
/api/keys	POST	Register public key
/api/keys/{key_id}	GET	Identity info
/api/events	GET	SSE stream of leaderboard events

Development

./run ci        # Full CI: fmt + clippy + tests
./run test      # Rust tests only
./run clippy    # Lint
./run fmt       # Format

86 tests including property-based tests for graph6 encode/decode.

License

MIT