Verifiable, Accessible, Rule-grounded Soccer Transparency Interpreter for You.

VARSITY is a real-time, screen-reader-native, IFAB-grounded AI explainer of VAR and offside decisions, built as a fan product. When a Video Assistant Referee review happens, VARSITY retrieves the governing Law of the Game, computes the offside geometry, generates a plain-language explanation of why the decision was made, and speaks it through the fan's own screen reader, in their language, before the broadcast picture catches up.

Built for the IBM SkillsBuild AI Builders Challenge (June 2026, Soccer / AI / World Cup).

Watch the 3-minute demo · Try the live demo

A blind football fan is often the last person in the room to understand a VAR call. Audio description is improving and major tournaments increasingly offer it, but even great commentary rarely explains the rule-grounded reason behind a contested VAR or offside decision as it happens. The decision data exists (the applied Law, the offside geometry, the structured outcome) yet it lives only in visual pipelines: stadium screens, broadcast overlays, and officials-only tools. No deployed product turns that into rule-grounded natural language delivered through a blind fan's own accessibility channel in real time. VARSITY adds that layer. It complements audio description and commentary, it does not replace them.

The first system that is all four at once: real-time, screen-reader-native, IFAB-Laws-grounded, and fan-facing, with offside coverage. Prior art (X-VARS, CVPR 2024; SoccerRef-Agents, 2026) is offline, referee-facing, and foul-only. VARSITY is what those would look like if they shipped to the fan who needs it.

The whole product is one loop you can run in five seconds on the live link:

A VAR review fires. VARSITY computes the real offside geometry, retrieves the exact Law, has IBM Granite explain the why, has Granite Guardian check it stays grounded, and your screen reader speaks it, before the broadcast picture catches up.

Everything else is depth behind that one loop, and it groups into five pillars. Read these five, and you have the whole project; the detailed table that follows is the per-capability proof.

1. Grounded, never guessing. Real StatsBomb offside geometry, the exact IFAB Law retrieved (RAG Hit@5 = 1.00), a neuro-symbolic Law-11 proof tree, and a Granite Guardian + multi-critic gate that fails closed. It explains a received decision; it never adjudicates or predicts.
2. Honest about uncertainty. A calibrated "VARSITY's Call" band (ECE 0.34% vs a 4.16% overconfident control), an IPCC-style verbal scale, and a too-close call that withholds the number and defers to the official, audibly. The fan hears the confidence, not just the verdict.
3. Audio-first accessibility. Screen-reader-native aria-live, spatial earcons that move past the offside line (HRTF, ISO 226), five languages, WCAG 2.2 AA enforced in CI, and a full keyboard mode.
4. All-IBM, end to end. Granite reasoning, Granite Guardian, Granite embeddings, Granite Vision, and Docling, federated through Context Forge with an A2A narrator, plus a fully on-device offline mode running Granite Nano in the browser.
5. Provable and resilient. Every claim is a live button on the /judges page, the corpus is SHA-256-signed and fails closed, the oracle survives a 13/13 red-team, and a watsonx outage degrades to a Law-citing floor instead of crashing.

VARSITY is one engine with two surfaces, not a single page. The fan surface is the accessible explainer in this demo: a blind fan presses one button, or a live VAR event fires, and hears the rule-grounded reason through their own screen reader. The operator surface is the same engine's live observability and proof layer that a broadcaster or federation runs in production: the /judges panel of verifiable claims, the OpenTelemetry GET /trace span tree (geometry, law, Granite, Guardian, with per-stage latencies), GET /corpus_integrity (the SHA-256-signed Law corpus), and the Context Forge federation. One surface is for the fan; the other is how an operator monitors, audits, and trusts the why-layer it is shipping.

The Monday test. A federation or broadcaster deploys VARSITY as the why-layer beside the channels they already run. It sits alongside the in-stadium PA announcement of VAR decisions (an option the IFAB approved for 2026/27) and the audio-description feed, and adds the one thing those channels do not carry: the rule-grounded reason a VAR or offside decision was made, delivered in real time through the fan's own accessibility channel. It complements those feeds, it does not replace them. The integration path, the external-service contract, and the partnership-first route are documented in docs/LEGAL.md.

The challenge scores four criteria. Each maps to evidence you can run against the live deployment (web-chi-wine-13.vercel.app) from the in-page "prove it" panel, which calls the live backend (varsity-api.onrender.com) and shows the real result inline.

Every capability here is wired-live and verifiable in this repo: no roadmap-only, aspirational, or "coming soon" entries, and we would rather under-claim than overstate. This is the per-capability proof behind the five pillars, grouped and collapsed so the page stays scannable. Expand a pillar to see its proof.

One VAR offside event flows from a trigger, through the geometry and rule-grounding backends coordinated by the IBM Context Forge MCP gateway, into a Granite explanation that Granite Guardian gates, and out over SSE to the screen reader. See docs/federation.md for the four-backend federation and the VAR-event sequence diagram.

flowchart LR
    subgraph Trigger
      SM["Sportmonks<br/>Goal Under Review"] --> RES{resilient<br/>resolver}
      AF["API-Football<br/>final outcomes"] --> RES
      RB["cached replay<br/>buffer (floor)"] --> RES
      SB["StatsBomb 360<br/>canned frame"] --> RES
    end

    RES --> GEO["match-geometry MCP<br/>offside margin (m)"]

    subgraph Gateway["IBM Context Forge MCP gateway"]
      GEO --> COORD["Granite coordinator"]
      RAG["ifab-rag MCP<br/>Law 11 retrieval"] --> COORD
      A2A["A2A narrator agent"] --> COORD
    end

    COORD --> GRAN["IBM Granite (watsonx)<br/>rule-grounded explanation"]
    GRAN --> GUARD["Granite Guardian<br/>groundedness + Law cite"]
    GUARD --> SSE["FastAPI SSE<br/>/stream"]
    SSE --> LIVE["aria-live region"]
    LIVE --> SR(["Blind fan's<br/>own screen reader"])

    SSE -. decorative, aria-hidden .-> VIZ["SVG offside-line viz<br/>+ spatial-audio cue"]

    OFF["On-device offline mode<br/>Granite Nano · WebGPU"] -. no network .-> LIVE

The canned StatsBomb path is the deterministic floor; the live trigger is a resilient flourish that falls back to a cached replay buffer. The screen-reader layer is always parallel to (and independent of) the decorative visual and audio layers.

See docs/IBM_STACK.md for every IBM component mapped to its file path and how to verify it is running, docs/ACCESSIBILITY.md for the WCAG conformance target, the aria-live design decision, and the screen-reader test matrix, and docs/observability.md for the OpenTelemetry trace of one VAR event with real measured stage timings (~2.8s end to end).

One VAR offside event fans out across four federated backends: the ifab-rag and match-geometry MCP servers, the A2A narrator agent, and the Granite coordinator. There are two ways to see it for real, not just on the diagram:

• Live on the deployed backend: GET /trace returns the real OpenTelemetry span tree for one event (geometry to law to Granite to Guardian) with per-stage durations, runnable from the /judges panel in your own browser.
• Through the IBM Context Forge MCP gateway: bringing up the gateway and registering the backends (steps in docs/federation.md) was verified in a local bring-up, with all four backends reachable, the three federated tools invoked through the gateway over POST /rpc with correct results (Law 11 retrieved, the offside margin computed in metres), and the gateway observability recording, in that local run, 10 tool executions at 100% success and about 27 ms average.

The deployed backend serves the live watsonx Granite, Granite Guardian, IFAB-RAG, and SSE pipeline behind that /trace; the Context Forge gateway federation is brought up and verified as documented in docs/federation.md.

A concept-level view of the project, the companion to the data-flow diagram above. The 18 documentation clusters map onto the five pillars, and the dotted edges are the cross-pillar bridges the graph surfaced: the offside margin and the GUM uncertainty budget couple the geometry and calibration clusters, because the number the geometry computes and the confidence the fan hears are one story, not two.

graph TD
    LOOP["VARSITY · one loop, five pillars<br/>199 concepts and 18 clusters auto-mapped from docs/"]

    subgraph P1["Pillar 1 · Grounded, never guessing"]
      GEO["Offside geometry engine<br/>orient2d · Theil-Sen · convex hull"]
      RAG["IFAB-Laws RAG + SSE pipeline<br/>Docling to FAISS · Context Forge · A2A"]
      PROOF["Law 11 proof tree<br/>+ ASPIC / Dung argumentation"]
      HAP["Safety guardrails<br/>HAP screen · oracle fail-closed"]
    end

    subgraph P2["Pillar 2 · Honest about uncertainty"]
      CAL["Confidence calibration<br/>GUM budget · ECE / Brier · IPCC scale"]
    end

    subgraph P3["Pillar 3 · Audio-first accessibility"]
      A11Y["Accessibility · WCAG 2.2 AA<br/>aria-live · focus · HCM · keyboard"]
      LANG["Multilingual narration<br/>EN / ES / FR / PT / DE · TBX termbase"]
      AUD["Spatial audio + perception<br/>HRTF earcons · ISO 226 · Plomp-Levelt"]
    end

    subgraph P4["Pillar 4 · All-IBM, end to end"]
      APP["App + deployment topology<br/>React / Vite · FastAPI · Render / Vercel"]
      VOICE["On-device voice + ASR<br/>Granite Nano · Whisper · WebGPU"]
    end

    subgraph P5["Pillar 5 · Provable and resilient"]
      RED["Red-team + injection defense<br/>13/13 caught · corpus SHA-256"]
      RAI["Explain-not-adjudicate<br/>+ attribution · non-affiliation"]
      PRIV["Privacy + data minimization"]
      LIC["Licensing + deployment risk"]
    end

    LOOP --> P1
    LOOP --> P2
    LOOP --> P3
    LOOP --> P4
    LOOP --> P5

    GEO -. offside margin .-> CAL
    CAL -. GUM sigma budget .-> GEO
    RAG -. OTel span tree .-> APP
    PROOF --> RAI
    RAG --> HAP

    classDef core fill:#0a0f1c,stroke:#34d399,stroke-width:2px,color:#e2e8f0;
    class LOOP core;

The full graph, 199 concepts and 211 relationships auto-extracted from the 30 documents in docs/ and clustered into 18 communities, lives in docs/knowledge-graph/: an interactive force-directed view (graph.html), a static map (graph.svg), a plain-language analysis (GRAPH_REPORT.md), and a cinematic 3D architecture view (graph-3d.html, glowing orbs and animated data-flow, best opened through a render proxy). Every edge is tagged EXTRACTED / INFERRED / AMBIGUOUS, so the map is as honest as the product.

A Gource visualization of the whole build (197 commits over 4.7 days). The preview loops above; click it for the 10-second cut, and the full 1080p60 render is attached to the v1.0.0 release.

The IFAB retrieval is measured, not asserted. A golden set of 20 VAR/offside questions mapped to the governing Law is run against the real retriever, scored directly (no inflated harness). Full report: docs/benchmarks/rag-eval.md.

Every offside question routes to Law 11 at rank 1, and the two offline near-misses (goal-line to goal-kick, referee to VAR) recover by rank 2-3. CI fails if Hit@5 drops below 1.0. The deterministic BM25 path is the committed, CI-gated artifact (services/evals/scores.json); the online Granite-embeddings figures were measured separately against watsonx and are not persisted in CI (they need live credentials).

Only what is built and running is listed here, and every capability in the table above is wired-live.

• Front end: React 19, Vite 6, TypeScript, Tailwind CSS v4, a multi-section cinematic site (React Three Fiber + GSAP hero, Lenis smooth scroll, scroll-reveals, liquid-glass), an SVG offside-line visualization, a listener-centred Web Audio HRTF spatial-audio engine with a semantic verdict earcon, a broadcast-delay ticker, keyboard power-mode + a stage scrubber + verbosity modes, a shareable on-device audio clip, an on-device offline mode (Transformers.js + WebGPU, Granite 4.0 Nano), a sighted-track read-aloud (Web Speech API + Kokoro-82M), 5-language narration (EN/ES/FR/PT/DE), ARIA live regions.
• Backend: FastAPI + SSE, IBM Context Forge (MCP gateway), IBM Granite + Granite Guardian via watsonx (raw ML REST), Docling to FAISS IFAB-Laws RAG, OpenTelemetry tracing, the official mcp and a2a-sdk SDKs (IFAB-RAG and geometry MCP servers, an A2A narrator agent with a real message/send round-trip), Sportmonks / API-Football triggers with a cached replay buffer, pure-Python offside geometry over StatsBomb 360 data.
• Accessibility: WCAG 2.2 AA, a pre-registered ARIA live region (assertive for the explicitly-requested verdict) with a re-announce-safe fix and verbosity control, screen-reader-native delivery, a lang attribute that switches the spoken voice, full keyboard support, decorative motion gated behind prefers-reduced-motion, axe-core + Playwright accessibility CI.

We are validating VARSITY with blind and low-vision football fans and audio-description users. A first-hand reply from a blind supporter on an audio-description community list confirmed the core need: current match commentary often leaves them unsure what is happening on the pitch, and clear information on the rules during a contested moment would be genuinely helpful. That is exactly the gap VARSITY targets, alongside (not instead of) the audio description and commentary fans already rely on. Outreach records and any personal details are kept private and are not in this repository.

# front end
cd apps/web && npm install && npm run dev
# backend
cd services && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && uvicorn main:app --reload

CI runs lint, typecheck, tests, and build on every push and pull request.

VARSITY is an independent project, not affiliated with FIFA, The IFAB, any league, club, or player. It explains decisions; it does not adjudicate them. Data is StatsBomb Open Data (non-commercial, attributed); the Laws are IFAB's (The IFAB does not permit reproducing the Laws in whole or in part without permission), cited and paraphrased for a non-commercial educational/accessibility purpose, from the attributed 2025/26 edition. The full treatment, including the honest path from this prototype to a partnership-first real deployment, is in docs/LEGAL.md.

Apache-2.0. See LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md. Every shipped model is Apache-2.0; the runtime dependency tree carries no copyleft.