AI Chessathon starter

Fork this to build an agent for AI Chessathon. It gives you a working submission, baselines to beat, and a local harness that speaks the same protocol and enforces the same clock as the platform, so you can see whether a change actually helped before you upload it.

git clone https://github.com/advitrocks9/aichessathon-starter
cd aichessathon-starter
make setup
make play

That plays your agent against a baseline over a full 120 s + 0.5 s game and prints the result. When you like it, make zip and drop submission.zip on your dashboard.

Writing an agent

agent.py is the whole submission. One function:

def get_move(fen: str, time_left_ms: int) -> str:
    return "e2e4"

The fork ships a legal random-mover, so the loop works before you write anything. Replace the body.

make play                                          # one game, real time control
make arena                                         # 20 fast games, prints a score
uv run python -m harness.play --black baselines/minimax --pgn game.pgn
uv run python -m harness.arena --opponent ../my-old-version --games 200

Anything your agent writes to stdout or stderr shows up under the result, so print debugging works. The platform discards it during rated games and shows it in your validation log.

The ladder

Measured with harness/arena.py. Beating greedy is a search. Beating minimax is a search plus an evaluation worth searching with.

Matchup	Games	Time control	Score
random vs greedy	20	10 s + 0.1 s	10.0% (+1 =2 -17)
greedy vs minimax	6	120 s + 0.5 s	0.0% (+0 =0 -6)

• baselines/random plays a uniformly random legal move. It is what agent.py starts as.
• baselines/greedy searches one ply on material.
• baselines/minimax searches two plies on material and mobility, with no time management.

What's here

agent.py             your submission
baselines/           random, greedy, minimax; each is a directory with an agent.py
harness/runner.py    the process the platform runs your agent in
harness/referee.py   the clock, legality, draw and adjudication rules
harness/play.py      one game between two agent directories
harness/arena.py     many games, with a score
harness/package.py   builds submission.zip with agent.py at the root
docs/IDEAS.md        where the strength actually comes from

The harness is here so your games are honest, not so you can pre-validate an upload. Acceptance happens on the platform, and the validation log on your dashboard is the authority on it.

The rules

aichessathon.com/docs is canonical and changes. Read it before you upload.