AI Arena Recap

Code behind aiarenarecap.com, a website that aggregates and displays StarCraft 2 bot-vs-bot match data from aiarena.net. It syncs competitive match results to a local SQLite database and serves a dashboard with rankings, per-bot analytics, and match details.

Features

• Ladder rankings with ELO ratings, division placement, and win/loss stats
• Bot detail pages with match history, head-to-head matchup records, and performance trends
• Match pages with game details and replay downloads
• Season archive -- finished seasons stay browsable at /s/<slug>/ (e.g. /s/2026-season-1/), with their own ladder, rankings and bot pages
• Background sync periodically fetches updates from the aiarena.net API
• Offline-capable -- local caching means the site stays up even if the upstream API is unavailable

Setup

Requires Python 3.11+.

pip install -e .

Create a .env file:

aiarena_api_token=YOUR_TOKEN

Optional settings:

Variable	Default	Description
competition_id	38	Competition served at the un-prefixed URLs ("this season")
archive_refresh_seconds	86400	How often to re-check archived seasons
sync_interval_seconds	600	Background sync frequency
db_path	ai_arena_recap.db	SQLite database path

Usage

# Initialize the database
ai-arena-recap init-db

# Sync match data (use --max-rounds to limit initial import)
ai-arena-recap sync
ai-arena-recap sync --max-rounds 50

# Import a past season's final standings into the archive (seconds).
# Browsable at /s/<slug>/ afterwards: full ladder, no match history.
ai-arena-recap sync --competition 36 --max-rounds 0

# Import a past season in full, match history included (tens of minutes).
# Pass several at once — that pages each bot's history once instead of once
# per season. Safe to interrupt; re-running resumes.
# Always pace it: aim for ~3 requests/min, which means hours, not minutes.
# Faster degrades aiarena.net's participation endpoint (see AGENTS.md).
# Safe to interrupt — re-running resumes.
ai-arena-recap backfill --competition 30 --spread-hours 8

# Several at once pages each bot's career once instead of once per season.
ai-arena-recap backfill -c 30 -c 28 -c 27 --spread-hours 12

# Start the web server (http://127.0.0.1:8000)
ai-arena-recap serve

Tech Stack

FastAPI, SQLite/SQLModel, Jinja2, APScheduler, httpx