App logo

Ref — Devpost Submission

Elevator Pitch

Fitness competitions have a fairness problem: a raw head-to-head between two people at different strength levels isn't a contest; it's a foregone conclusion. Most apps ignore this. Ref doesn't.

Ref is a transparent AI referee. Point it at two athletes, and it doesn't just spit out a recommendation — it reasons through the problem live, on screen, in a terminal-style trace console you can actually watch. It pulls real lift history, computes a deterministic handicap, generates a balanced challenge, checks the result for plausibility, and rules on a winner. Every tool call, every number, every piece of reasoning is visible as it happens.

No black box. No "trust the algorithm." Just a referee doing its job in front of you, with math you could verify on a napkin.

We built the whole planner chain — five tools, a capped regeneration loop, a deterministic fairness score — and made the AI's reasoning process the actual hero feature, not a hidden implementation detail.

Ref watches two lifters, levels the playing field with real math, and makes the call — live, out loud, in front of you.

About This Project

🎯 The Problem & Solution

Problem: Competitive fitness apps assume a level playing field that doesn't exist. If one athlete lifts 40% more than another, a straight head-to-head isn't a competition — it's a formality. Existing tools either ignore the gap entirely (static leaderboards, raw number comparisons) or hide their fairness logic behind an opaque recommendation, giving users no reason to trust the result.

Solution: Ref makes the fairness calculation the product. A deterministic planner chain — get_lift_history → compute_handicap → generate_challenge → validate_attempt → adjudicate_result — runs live, streaming every decision to an Agent Trace Console over Server-Sent Events. The handicap and fairness score are real, auditable math, not an LLM guess. The AI's role is to reason through the plan and narrate it in plain English; the numbers underneath are deterministic and reproducible every time.

💡 What Inspired Us

The frustration was simple: fitness "competition" features in most apps are cosmetic. They compare raw totals and call it a leaderboard. None of them ask the obvious question — is this actually a fair fight? We wanted an AI feature where the reasoning itself was the demo, not a hidden step before a result screen. Agent trace consoles are usually a debugging tool built for engineers; we wanted to put one in front of a user and make it the main event, styled like a referee call instead of a stack trace.

🛠️ How We Built It

Stack:

Frontend: Neo-brutalist design system (thick borders, hard-offset drop shadows, high-contrast palette) — locked screen specs sourced from finalized Stitch renders, six core screens from Home hub through Leaderboard
Backend: Lightweight relational schema (athletes, lift_history, matches) so get_lift_history() is a real query against seeded data, not a mock
Streaming: SSE for one-way event push from planner to trace console — no WebSockets, because the console only ever needs to receive, never send
Contract: A single locked JSON event schema (step, status, input, output, reasoning) shared across all five tools, so the frontend renders every trace line off one shape

Where OpenAI tooling did the heavy lifting:

Used Codex to scaffold the five-tool planner chain and the SSE event pipeline quickly enough to leave real build time for the trace console UI — the highest-priority feature per our own standing rule.
Used it to iterate the capped regeneration loop (planner retries at most twice before accepting its best result) without hand-writing the retry/fallback state machine from scratch.
Kept the handicap and fairness math outside the model entirely — deterministic functions, not LLM output — so Codex's job was wiring and orchestration, not number generation. The AI's job is to plan, call tools, and narrate; the arithmetic underneath never touches a prompt.

📐 Technical Math & Architecture

Handicap adjustment, using each athlete's known max lift on the locked exercise:

$$\text{adjustment_ratio} = \frac{\text{rival_max}}{\text{user_max}}$$

$$\text{adjusted_target}(a) = \text{base_target} \times \frac{\text{max}(a)}{\min(\text{user_max}, \text{rival_max})}$$

Fairness score — a real, deterministic calculation, never AI-estimated:

$$\text{fairness_score} = 100 - \left| E_{user} - E_{rival} \right|$$

where $E_a$ is athlete $a$'s adjusted target expressed as a percentage of their historical max. The closer the two expected-effort percentages, the higher the score.

Iteration cap on the generate → evaluate → regenerate loop:

$$\text{attempts} \leq 2 \quad \Rightarrow \quad \text{accept best result, state explicitly in trace}$$

This keeps every number simple enough to explain in one sentence on stage, while remaining a real, auditable calculation rather than a plausible-looking guess.

🚧 Challenges We Faced

Keeping the AI honest: the hardest discipline was resisting the temptation to let the model "estimate" a fairness number — every score had to trace back to a deterministic formula, so trust in the live demo didn't depend on trusting a black box.
Capping the regeneration loop cleanly: a planner loop that looks stuck during a live demo is worse than one that never regenerates at all. We hard-capped at 2 attempts with an explicit on-screen statement when the cap is hit, and kept a single-attempt fallback ready per our own risk plan.
SSE reliability under demo pressure: a dropped or stalled stream mid-trace would be visible to judges. We built a silent single retry with a cached fallback result so a raw error state never surfaces live.
Deterministic vs. generative boundaries: drawing a hard line between "the AI narrates this" and "the AI must never compute this" took more design discipline than the tool-calling code itself.

📚 What We Learned

Agentic tooling shines brightest when it's building the plumbing, not the judgment. Codex accelerated the planner chain and SSE wiring dramatically, but the product's credibility came from not letting the model touch the actual math.
Visible reasoning is a UX feature, not a debug tool. Turning a trace console — normally an engineer-only artifact — into the hero screen taught us that transparency itself can be the differentiator, if it's designed with the same care as any other screen.
Hard caps beat elegant edge-case handling under time pressure. A blunt "2 attempts, then accept and say so" rule was more demo-safe than a more sophisticated tiebreaker system we scoped out for V2.