The Conductor
Formula Analytics / Conductor ← Back to About

System reference · not marketing copy

One dispatcher.
No agent that decides its own turn.

The race weekend runs through five machine phases. A single Conductor decides which of ~20 registered agents fire in each one, in a fixed order, gated by what's required and what already exists. Nothing here is invented — every name, order, and rule below is read straight from scripts/conductor.py's live default_registry() and f1analytics/conductor.py's dispatch loop.

How the Conductor wakes up

GitHub Actions cron drifts 50–60+ minutes — too imprecise for session-timed dispatch — so the clock lives outside GitHub entirely.

01 · WRITE

Trigger plan

conductor.py --plan-week reads the real FastF1 session schedule and writes exact fire times to data/state/triggers_<season>_r<round>.json.

02 · WATCH

Cloudflare Worker

A cron every 15 minutes reads the latest trigger plan from the repo. Stateless — no KV, no Durable Object. Duplicate firings are safe by design.

03 · WAKE

repository_dispatch

Any trigger inside the lookback window POSTs a conductor-phase event to GitHub with {season, round} as payload.

04 · RUN

conductor.yml

The hosted runner calls schedule.detect_phase(), then dispatches every agent registered for that phase, in order.

The five phases, in real dispatch order

requireda failure here halts the phase. optionalfailures are logged and the phase advances — retried on the next firing.

PHASE 1 / 5

EARLY

Before any session has run. Pre-weekend research and the gate's earliest non-blocking checkpoint.

event_context
Once-per-round context artifact, gated on its own output existing.
detoptional
gate_pulse
Multi-stage human gate's non-blocking pulse — trackfit/upgrades readiness. Re-fires every dispatch until pulses run out; not idempotency-marked done like a normal agent.
detoptional
weather
No output artifact by design — each phase's firing appends a fresher read rather than gating on one file.
detoptional
upgrade_set
Polls for the official FIA upgrade set; no-ops internally once it lands.
detoptional
PHASE 2 / 5

PRE_QUALI

Practice is running. The single hard stop in the whole week — nothing past this phase moves without a human.

human_gate
Registered FIRST, on purpose — its halt blocks every other PRE_QUALI agent below it. Opens a review issue, polls for a decision, and raises while pending. 48h auto-accept if nobody responds; the loop never stalls unattended.
detrequired
gate_pulse
Continues from EARLY — post-P1/P2/P3 checkpoints as sessions land.
detoptional
weather
Same no-artifact refresh pattern as EARLY.
detoptional
upgrade_set
Keeps polling until the set is official.
detoptional
upgrade_analysis
LLM read of the official upgrade set once it's available — the three-part contract: a versioned prompt file, a built input record, one output artifact.
llmoptional
PHASE 3 / 5

POST_QUALI

Grid is set. A shorter blocking checkpoint before race day — 12 hours to decide, not 48.

weather
One more refresh ahead of the race-day forecast window.
detoptional
gate_post_qualy
Multi-stage gate's blocking checkpoint — 12h auto-accept.
detrequired
PHASE 4 / 5

PRE_RACE

The quiet phase — one last weather read ahead of lights out.

weather
Final refresh before the race-start forecast is locked in.
detoptional
PHASE 5 / 5

POST_RACE

The long chain. Eleven optional agents run in sequence so each can see the last one's output, then one blocking gate closes the round.

results_ingest
Pulls the classified result set first — everything below depends on it existing.
detoptional
race_log
Read-only check that the PC fetch landed the Race laps + weather in R2; alerts once if it has not (after a short grace).
detoptional
settlement
Realizes paper-ledger P&L from the classified results. Raises (retried next firing) if results haven't landed yet.
detoptional
ratings_reset
Advances base driver/team ratings one round with an auditable delta trail. Gated on its own per-round snapshot artifact.
detoptional
ratings_pages
Re-renders the public driver/team ratings pages from the advance that just ran. Deliberately NOT output-gated — it's a fixed path overwritten every round, not one file per round.
detoptional
race_context
LLM agent with live web search — builds the narrative context the write-up below cites.
llmoptional
wow_report
The week-over-week write-up itself — an LLM agent, cites race_context's output as its input.
llmoptional
wow_delivery
Renders and delivers the report once it exists.
detoptional
handoff
Writes the session handoff artifact for the next round.
detoptional
loop_restart
Re-arms the loop for the next round.
detoptional
base_evolution_kickoff
Kicks off the slower, separate base-model review track.
detoptional
gate_post_race
Registered LAST on purpose — every agent above gets a chance to run before this can halt further progress. 48h auto-accept.
detrequired

The rules underneath

ARTIFACT = DONE

Files are the only handoff

An agent is never asked "did you run." Its declared output file existing IS the completion signal. A re-fire that finds the artifact already there just skips — no separate "already ran" bookkeeping to drift out of sync with reality.

data/state/conductor_state.json
key: "{season}:{round}:{phase}:{agent}"
DEGRADE, DON'T BLOCK

Most agents are optional

FastF1 and Jolpica publish on their own clocks after a session flag — the first firing routinely finds a source not ready yet. An optional agent failing gets logged into the report and retried next firing; nothing else waits on it.

TWO KINDS, ONE SEAM

det vs. llm

A det agent is a direct Python call — no subprocess. An llm agent carries a fixed three-part contract: a provider-neutral prompt file, a built input record the Conductor writes before calling it, and one pre-agreed output artifact the result lands at.