GuardianAI

Inspiration

What it does

💡 Inspiration

Every NBA season, franchise trajectories are derailed by preventable soft-tissue injuries. For coaches and front offices, load management has historically been a double-edged sword: rest players too much and you forfeit seeding; play them too much and you risk season-ending injuries. Most current load management practices rely on subjective "gut feel," generic days-of-rest rules, or proprietary "black-box" analytics tools that lack transparency.

We wanted to build GuardianAI to democratize sports science and bring radical transparency to injury prevention. By pairing the gold-standard sports science metric—the Acute:Chronic Workload Ratio (ACWR)—with state-of-the-art machine learning (XGBoost) and explainable AI (SHAP), we created a tool that doesn't just output a risk percentage, but tells a coach exactly why a player is flagged.

🛠️ How We Built It

We designed and built GuardianAI from scratch using a modular data and ML pipeline:

Data Ingestion (nba_api): We built a robust ingestion pipeline using the official NBA Stats API to download detailed player logs across six seasons (2018–2024).
Feature Engineering & Sports Science Metrics: We engineered features capturing fatigue, schedule density (back-to-backs), and rolling workloads. The core feature is the Acute:Chronic Workload Ratio (ACWR), calculated as:

$$ACWR = \frac{\text{Acute Workload (7-day rolling average minutes)}}{\text{Chronic Workload (28-day rolling average minutes)}}$$

According to sports science literature, keeping a player's workload in the "sweet spot" ($0.8 \le ACWR \le 1.3$) minimizes injury probability, while spiking above $1.5$ puts them in the high-risk "Danger Zone."

Predictive Modeling: We trained an XGBoost Classifier to predict the probability of a player missing $8+$ consecutive days due to injury after any given game.
Explainable AI (XAI): Coaches won't trust a black box. We integrated SHAP (Shapley Additive exPlanations) to extract the exact feature contributions for each individual prediction:

$$f(x) = \phi_0 + \sum_{i=1}^{M} \phi_i$$

Where $\phi_0$ is the base expected risk and $\phi_i$ is the impact (SHAP value) of feature $i$. This translates complex trees into a simple, plain-English explanation (e.g., "LeBron James' risk spiked due to a 35% increase in 7-day workload").

Interactive Dashboard: We wrapped the entire system in a beautiful, responsive dark-themed Streamlit dashboard powered by Plotly to visualize player risks, team workload maps, and model validation metrics.

🚧 Challenges We Faced

The Temporal Split Dilemma (Data Leakage): Standard random train-test splits are dangerous in sports analytics. Randomly shuffling game logs allows information from a player's future games to leak into their past predictions. To prevent this, we implemented a strict temporal split: training on the 2018–2022 seasons and testing on the 2022–2024 seasons, simulating real-world deployment conditions.
Extreme Class Imbalance: Injuries are relatively rare events, occurring in only $5\text{–}8\%$ of our player-game records. A naive model would achieve $92\text{–}95\%$ accuracy by simply predicting "no injury" every time. We resolved this by defining a robust proxy target label, utilizing SMOTE (Synthetic Minority Over-sampling Technique) to balance training distributions, and configuring XGBoost's scale_pos_weight parameter to prioritize Recall over raw accuracy.
NBA API Rate Limits: The NBA Stats API has aggressive, undocumented rate limits. We had to implement exponential backoff mechanisms and asynchronous request batching to reliably download seasons of player data without getting blocked.
Deployment Environment Incompatibilities: Deploying the compiled C-extensions of packages like pandas and pillow on Streamlit Cloud caused build failures due to missing OS-level zlib libraries. We solved this by creating a .python-version file pinning our environment to Python 3.11 to access pre-compiled binary wheels.

🧠 What We Learned

Explainability > Pure Accuracy: In high-stakes sports analytics, a highly accurate model that cannot explain itself is useless. Coaches and trainers need actionable insights they can act on, which makes SHAP values just as important as the model itself.
The Importance of Sports Science Domain Knowledge: Machine learning models are only as good as the features fed into them. Implementing established formulas like ACWR and schedule density gave the XGBoost model the physical context it needed to find true patterns.
Rigorous Validation Safeguards: Evaluating models in sports requires temporal cross-validation. Standard metrics like accuracy are misleading; tracking precision-recall curves and ROC-AUC is crucial for validating rare-event predictive systems.