AthleteIQ
Sports Science Intelligence for Coaches and Athletes
Overview & Impact
The Problem & The System Solution
The Problem
Coaches and athletes need rapid access to sports science guidance, but general-purpose language models can hallucinate, perform unreliable calculations, and provide unsafe advice in health-adjacent situations.
The System Solution
Built a LangGraph ReAct agent with four specialized tools: sports-science retrieval, deterministic ACWR calculation, timestamped athlete metric logging, and three-tier safety escalation.
Sports science is a domain where accuracy is non-negotiable. A coach asking for workload ratios for an injured athlete needs exact calculations, not an approximation. Existing AI tools either hallucinate figures or avoid the question entirely.
AthleteIQ was built to solve this precisely. By separating probabilistic LLM reasoning from deterministic Python math tools, every workload calculation is computed programmatically and verifiable, not generated by a language model.
The system uses LangGraph's ReAct loop to decide which tool to call based on query type: vector retrieval for sports science knowledge, Python math for ACWR, a database writer for metric logging, and an immediate safety escalation bypass when emergency language is detected.
Architecture & System Flow
System Design Visualizer
AthleteIQ Hub-and-Spoke Architecture
Emergency language triggers an immediate hard bypass of vector retrieval to prevent hallucinated medical guidance.
Step-by-Step System Execution Payload
OpenRouter Fast-Classifier
Athlete Query + Historical Load Telemetry
Key Engineering Decisions
The LLM does not perform safety-critical workload mathematics. AthleteIQ routes ACWR calculations to deterministic Python logic.
Bypasses retrieval entirely when a medical emergency is detected, instantly routing to immediate human escalation.
Uses a hybrid eval harness combining LLM-as-judge scoring with rule-based checks for safety-critical questions.
Technology Stack
Production Technologies
Core agent logic, math tools, evaluation harness
ReAct agent state machine and multi-step reasoning loop
Tool calling chains and prompt composition
all-MiniLM-L6-v2 embeddings for semantic retrieval
LLM gateway routing to Claude/GPT for agent reasoning
Semantic evaluation of retrieval quality and response accuracy
Local vector store for sports science knowledge base
Features & Capabilities
What It Does
LangGraph ReAct Agent
Multi-step reasoning loop that selects tools based on query intent.
Sports Science RAG
56-entry ChromaDB knowledge base covering ACWR, HRV, RPE, biomechanics, recovery.
Deterministic Math Tools
Python ACWR calculations that bypass LLM for exact, auditable workload ratios.
Safety Escalation
Emergency language triggers immediate human escalation, bypassing all retrieval.
Metric Logging
Timestamped athlete performance data persisted for longitudinal tracking.
Hybrid Evaluation
LLM-as-judge scoring combined with rule-based assertions across 20 ground-truth cases.
Workflow Pipeline
Step-by-Step System Flow
Coach Query
User asks a sports science question or requests workload calculation.
Intent Classification
ReAct agent classifies whether query needs RAG, math tool, metric log, or safety escalation.
Emergency Check
Safety router scans for emergency language. If detected, bypasses all retrieval and routes immediately to human escalation.
Tool Selection
Agent selects the appropriate tool: ChromaDB RAG, ACWR Python tool, or metric logger.
Deterministic Execution
Math tools execute exact Python calculations. RAG retrieves grounded sports science content.
Response Synthesis
Agent combines tool outputs into a structured, grounded response.
Metric Logging
Athlete metrics are timestamped and persisted to the database for longitudinal tracking.
Interface & Dashboard
AthleteIQ Interface
Analytics Dashboard
Conversation View
Engineering Challenges
Hard Problems Solved
The Problem
Language models are unreliable for precise numerical calculations like ACWR ratios. A wrong figure in a training load context could injure an athlete.
Engineering Solution
Routed all workload math to a dedicated Python function tool. The LLM only formats the result — it never generates the numbers.
Results & Evaluation
What Was Achieved
Future Roadmap
What's Next
6 planned features · Active development