> ## Documentation Index > Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt > Use this file to discover all available pages before exploring further. # Poll a job (returns job.json verbatim) > Serves the job's `job.json` byte-for-byte, it is the single state store, updated after every training generation and every stage transition, so this endpoint doubles as live progress. ## OpenAPI ````yaml /train-v1.yaml get /jobs/{job_id} openapi: 3.1.0 info: title: Alakazam Train API version: 1.0.0 summary: >- Train policies inside a world model, certify them in a frozen physics oracle. description: > The **Train API** runs the dream-training pipeline as reproducible jobs: 1. TRAIN: CMA-ES evolves a 6-parameter controller *inside the doom world model* (the same public checkpoint as [`alakazamworld/doom-dungeon-hg`](https://huggingface.co/alakazamworld/doom-dungeon-hg) on Hugging Face, byte-identical, sha256-verified). 2. EXAM: the champion is replayed in a frozen Webots oracle (two physical worlds, fixed contract, anti-exploit control arms). The oracle is the sole scoreboard; dream fitness is never a capability claim. One `POST /jobs` does both and leaves a machine-readable `job.json` you can poll at any time, jobs are asynchronous, kill-tolerant, and append-only. ### Honest verdict semantics The exam verdict has four bars per world (contacts, clearance, coverage, path). Warm-started jobs reproduce the historical best-known profile, contact-safe (0 contacts in 40/40 episodes), but no policy in program history has passed all four bars. A `pass: false` verdict with clean contacts is the expected state of the art, not an error. ### Reproducibility Training is bit-deterministic for a given spec seed **on a fixed platform**; champions differ across platforms (macOS-arm64 vs Linux-amd64 float paths). Exam results are deterministic to aggregates (third-decimal physics drift). ### Availability & timings The serving VM runs on-demand (it is started for sessions, not 24/7). Measured wall-times, serving VM (e2-standard-2; CPU generation varies per boot): smoke job (`pop 6, gens 2, T 20`) 12-17 min; real-scale (`pop 10, gens 8, T 60`) 3-4 h; exam alone 4-6 min. Poll `GET /jobs/{job_id}`, never block on the POST. servers: - url: https://api.alakazam.gg/train description: > The Train jobs + exam API. Bearer-key auth; the serving VM behind it is start-on-demand, so coordinate a session window with us before calling. security: - bearerAuth: [] tags: - name: Jobs description: Submit and poll dream-training jobs. - name: Simulation gym description: > **Beta, self-hosted runner.** Drive a world headlessly as a training environment (gym) and stream the SNN-controller observation contract: two virtual proximity sensors, a terminal collision spike, object labels, and an optional square RGB camera. The same schema is emitted offline by the dataset exporter (JSONL episodes), so controllers trained on recorded data plug straight into the live loop. Each session holds a real world-model GPU stream, sessions are metered by wall-time; create only as many parallel environments as your session budget allows, and DELETE them when done. paths: /jobs/{job_id}: get: tags: - Jobs summary: Poll a job (returns job.json verbatim) description: | Serves the job's `job.json` byte-for-byte, it is the single state store, updated after every training generation and every stage transition, so this endpoint doubles as live progress. operationId: getJob parameters: - $ref: '#/components/parameters/jobId' responses: '200': description: Current job state (complete when `status` is `done`). content: application/json: schema: $ref: '#/components/schemas/Job' '401': $ref: '#/components/responses/Unauthorized' '404': description: >- No `job.json` for this id (unknown job, or spawn still initializing). content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Malformed `job_id`. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: jobId: name: job_id in: path required: true schema: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ schemas: Job: type: object description: The job.json state document (single source of truth, atomic writes). required: - job_id - params - status - started - stages - per_gen properties: job_id: type: string params: $ref: '#/components/schemas/JobSpec' status: type: string enum: - running - done - failed started: type: string format: date-time finished: type: - string - 'null' format: date-time restarted_from: type: string format: date-time description: >- Present when the job process was restarted (prior per-gen records kept). parent: oneOf: - type: 'null' - $ref: '#/components/schemas/ResolvedParent' stages: type: object properties: train: $ref: '#/components/schemas/Stage' exam: allOf: - $ref: '#/components/schemas/Stage' - type: object properties: contract: $ref: '#/components/schemas/OracleContract' per_gen: type: array description: One record per completed training generation (streamed live). items: type: object required: - gen - best - mean - best_so_far - gen_wall_s properties: gen: type: integer best: type: number mean: type: number best_so_far: type: number gen_wall_s: type: number rss_mb: type: number genome6: type: - array - 'null' items: type: number description: Champion in compact 6-float form (null until training completes). genome9: type: - array - 'null' items: type: number description: >- Champion expanded to the 9-float controller form the oracle consumes. dream_F: type: - number - 'null' description: >- Champion dream fitness, NOT a capability claim; the oracle is the scoreboard. oracle: oneOf: - type: 'null' - $ref: '#/components/schemas/OracleResult' artifact_paths: type: object description: Server-side artifact locations (raw episode jsonls, verdict, logs). additionalProperties: true Error: type: object properties: detail: type: string description: Human-readable reason. required: - detail JobSpec: type: object required: - job_id - train - exam properties: job_id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ train: type: object required: - pop - gens - T - seed properties: pop: type: integer description: CMA-ES population size (ignored when gens=0). gens: type: integer description: > Number of generations. 0 = exam-only certification of the parent genome (train.parent then REQUIRED). T: type: integer description: Dream episode length (use 60 for history-comparable dream_F). seed: type: integer description: Training seed (bit-deterministic per platform). parent: type: object description: Optional lineage, exactly one of genome6 / job_id. properties: genome6: type: array items: type: number minItems: 6 maxItems: 6 job_id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ note: type: string exam: type: object required: - episodes properties: episodes: type: integer description: >- Episodes per world. Use the full 20, Webots startup dominates, reduced-episode runs are barely cheaper. policy: type: object description: > Optional. Certify a champion you supply instead of training one (requires train.gens=0). The policy replaces ONLY the champion arm's controller; world, spawns, episodes, tick, remap, scoring and the anti-exploit arms stay frozen. required: - format properties: format: type: string enum: - genome9 - python_module genome9: type: array items: type: number minItems: 9 maxItems: 9 description: Required when format=genome9, a raw 9-float controller. module_b64: type: string description: > Required when format=python_module, base64 of a policy `.py` file or a `.zip` bundle, size-capped. The module implements reset(seed)+act(obs); obs matches the local-gym observation dict, action is the wheel-fraction vocabulary. Runs sandboxed (no network egress, resource/time-limited) in the exam container. entry: type: string description: Module name to import (default `policy`). class: type: string description: Policy class name (default `Policy`); a class with reset/act. ResolvedParent: type: object required: - source - genome6 properties: source: type: string enum: - inline - job genome6: type: array items: type: number job_id: type: string parent_dream_F: type: - number - 'null' note: type: string Stage: type: object required: - status - started properties: status: type: string enum: - running - done - failed started: type: string format: date-time finished: type: - string - 'null' format: date-time wall_s: type: - number - 'null' OracleContract: type: object description: The frozen Webots oracle contract (constant across all jobs). properties: DISC: type: string CTRL: type: string RANGE: type: string GATE3_PROX_MAP: type: string EPS: type: integer OracleResult: type: object required: - verdict - worlds properties: verdict: type: object required: - pass - why properties: pass: type: boolean why: type: array items: type: string description: Failed bars, one line each (quotes per-world minima). worlds: type: object properties: arena: $ref: '#/components/schemas/WorldResult' slalom: $ref: '#/components/schemas/WorldResult' contract: $ref: '#/components/schemas/OracleContract' WorldResult: type: object required: - episodes - summary properties: episodes: type: array items: type: object required: - ep - contacts - min_clear - p5_clear - frac_ge_5cm - path_len - steps - webots_phi - mean_imax properties: ep: type: integer contacts: type: integer min_clear: type: number p5_clear: type: number frac_ge_5cm: type: number path_len: type: number steps: type: integer webots_phi: type: number mean_imax: type: number summary: type: object required: - n_eps - contacts_total - min_clear - worst_frac_ge_5cm - path_min - path_mean - cruiser_contacts properties: n_eps: type: integer contacts_total: type: integer min_clear: type: number worst_frac_ge_5cm: type: number path_min: type: number path_mean: type: number cruiser_contacts: type: integer description: >- Anti-exploit control arm, a fixed cruiser policy that MUST rack up contacts; 0 here would mean the exam is vacuous. responses: Unauthorized: description: Bad or missing bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: Single per-partner bearer key, provisioned by Alakazam. ````