QEDSports

Settle arguments about the superior college football team via the transitive property, time travel, and the power of generative AI

What is QEDSports?

College football is rife with heated debates about which team is truly the best. Fans often rely on subjective opinions, biased statistics, or plain supposition to back up their claims. QED (Quasi-Empirical Decisions) Sports was created to provide a clear, objective method for determining team superiority using the transitive property of victories.

How It Works

The Transitive Property

QEDSports relies on advanced elementary school math, namely the transitive property. If Team A beats Team B, and Team B beats Team C, then Team A must be better than Team C. This process can, of course, be repeated indefinitely without issue. QEDSports finds the smallest chain of victories connecting two teams, giving you ample evidence to believe that your team can beat anyone.

The Role of History

The astute reader will likely point out the above approach will fail against undefeated teams. After all, if a team has no losses, there certainly won't be any paths towards them. This is no problem for QEDSports. When no path exists within the current season, the app steps back in time to find games from prior years. Games from past seasons are visually distinguished (faded and muted) so you can quickly see which parts of the chain rely on historical results. This approach, which we call persistence, assumes that if Team A defeated Team B in a previous season, that superiority likely remains. Given the current stability of college rosters, we believe this affirms our conclusions about persistence.

When All Else Fails: Use AI

In the exceedingly rare case where no transitive path can be found, even after applying persistence across multiple seasons, QEDSports leverages the power of generative AI to generate a compelling argument for why Team A should beat Team B. The underlying methodology is irrefutable: which mascot would win in a direct fight? This metric, criminally underutilized by the sports analytics community, has been shown to correlate strongly with team superiority. An angry bulldog will almost certainly best a 2000 pound steer in single combat, and QEDSports gives the detailed justification to prove it.

Setup

1. Python 3.11+ recommended. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables (optional, but required for LLM fallback): Create a .env file in the project root:

   GEMINI_API_KEY=your-gemini-api-key-here

   The LLM fallback is only enabled if this key is set. Obtain a free Gemini API key from Google AI Studio.

4. Ensure data files exist:

   • graph.gexf — the precomputed victory graph (generated by get_games.ipynb)
   • teams.pkl — team metadata including logos (also from the notebook)

Running the App Locally

flask run

Regenerating the Graph

The get_games.ipynb notebook fetches recent seasons from the College Football Data API and generates both graph.gexf and teams.pkl. To refresh the data when new games are available:

1. Obtain an API key from collegefootballdata.com
2. Set your CFB_API_KEY as an environment variable (i.e echo "CFB_API_KEY=your-api-key" >> .env)
3. Run the notebook
4. The precomputed graph will be updated with the latest results

Data Coverage

• Source: College Football Data API
• Seasons: 2020–2025
• Scope: All divisions of college football
• Games: Tens of thousands of results across hundreds of teams