Quickstart - Alakazam

Everything is bearer-key authenticated. Keys are provisioned per partner; there is no self-serve signup for Train yet. The API lives at https://api.alakazam.gg/train. The serving box wakes on your first request: during boot you get 503 {"status": "waking"} with a phase field; retry the same call until it succeeds (4 to 8 minutes).

1. Submit a smoke job

curl -s -X POST https://api.alakazam.gg/train/jobs \
  -H "Authorization: Bearer $TRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "my-smoke-001",
    "train": {"pop": 6, "gens": 2, "T": 20, "seed": 4242},
    "exam":  {"episodes": 20}
  }'

{"job_id": "my-smoke-001", "status": "spawned",
 "poll": "/jobs/my-smoke-001", "log": "/jobs/my-smoke-001/log"}

The POST returns immediately. Job ids are one-shot: reusing one returns 409, so pick a new id per run.

2. Poll until done

curl -s https://api.alakazam.gg/train/jobs/my-smoke-001 -H "Authorization: Bearer $TRAIN_KEY"

job.json updates after every training generation (per_gen) and every stage transition, so this endpoint doubles as live progress. status walks running → done (or failed). For a human-readable tail:

curl -s "https://api.alakazam.gg/train/jobs/my-smoke-001/log?n=100" -H "Authorization: Bearer $TRAIN_KEY"

3. Read the result

When status is done:

genome6 / genome9: the champion controller,
dream_F: dream fitness (not a capability claim),
oracle.verdict: the frozen exam’s 4-bar verdict,
oracle.worlds.{arena,slalom}: per-episode physics rows + summary.

A smoke champion fails the exam loudly (20/20 contact episodes). That is the anti-exploit machinery working, not a bug. Real training runs warm-started from a good parent achieve 0 contacts in 40/40 episodes. See The exam for how to read verdicts.

4. Scale up with lineage

curl -s -X POST https://api.alakazam.gg/train/jobs \
  -H "Authorization: Bearer $TRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "my-real-001",
    "train": {"pop": 10, "gens": 8, "T": 60, "seed": 61,
              "parent": {"job_id": "my-smoke-001"}},
    "exam":  {"episodes": 20}
  }'

Use T: 60 for dream_F comparable to campaign history (T: 20 scores are not comparable).
parent warm-starts CMA-ES at the prior champion (sigma0 = 2.0); a parent job_id with no champion is refused with 422, never silently cold-started.
Keep episodes: 20. Webots startup dominates the cost, so reduced-episode exams are barely cheaper and their results are not comparable.

Timings

Job	Serving VM (measured)
Smoke (`pop 6, gens 2, T 20`)	12–17 min
Real-scale (`pop 10, gens 8, T 60`)	3–4 h
Exam stage alone	4–6 min

​1. Submit a smoke job

​2. Poll until done

​3. Read the result

​4. Scale up with lineage

​Timings

1. Submit a smoke job

2. Poll until done

3. Read the result

4. Scale up with lineage

Timings