Spaces:
Sleeping
Sleeping
| title: Match Decoded | |
| emoji: ⚽ | |
| colorFrom: indigo | |
| colorTo: blue | |
| sdk: streamlit | |
| sdk_version: "1.52.0" | |
| app_file: frontend/app.py | |
| pinned: false | |
| license: apache-2.0 | |
| # ⚽ Match Decoded | |
| ### AI-powered football match explainability — powered by IBM Granite + LangChain + Docling | |
| **IBM AI Builders Challenge 2026 · June Football Challenge** | |
| [](https://ibm.com/granite) | |
| [](https://python.langchain.com/) | |
| [](https://github.com/IBM/docling) | |
| [](https://bob.ibm.com/) | |
| [](https://python.org) | |
| [](https://streamlit.io) | |
| --- | |
| ## 🏟️ The Problem | |
| **49,000 international football matches. 215 teams. 154 years of data.** | |
| And yet, when a fan watches a match, they hear commentary about *what* happened — but rarely *why*. | |
| > *"Brazil lost to Argentina. But was it because of form? Venue? Historical matchup? Tournament pressure?"* | |
| Fans deserve to understand the invisible forces shaping every match. Teams have million-dollar analytics departments. Fans have bias and guesswork. **Match Decoded bridges that gap.** | |
| --- | |
| ## 🧠 The Solution | |
| Match Decoded is an AI-powered football explainability platform that transforms raw match data into **Granite-generated tactical narratives**, **what-if simulations**, and **fully traceable decision explanations**. | |
| | Fan Experience | Match Decoded | | |
| |---|---| | |
| | "Who do you think will win?" | **"Here's WHY — based on 8 factors from 49K historical matches"** | | |
| | "What if it was a home game?" | **Real-time what-if simulator with AI analysis of the delta** | | |
| | "Was Brazil 1970 better than Spain 2010?" | **Legends Matchup — cross-era Granite-powered comparison** | | |
| | "The pundit says X. Is that right?" | **Full decision trace with feature importance — no black box** | | |
| ### Key Insight: Explainability Over Prediction | |
| This is NOT a score predictor. This is a **match decoder** — an AI that explains *why* outcomes are likely, so every fan understands the game at a deeper level. | |
| --- | |
| ## 🔧 IBM Technologies Used | |
| | # | Technology | How We Use It | Status | | |
| |---|---|---|---| | |
| | 1 | **IBM Granite 3.1-2B** | Core AI engine — generates tactical previews, decision explanations, momentum analysis, legends matchups, and match report analysis via HuggingFace Inference API | ✅ Live | | |
| | 2 | **LangChain** | `ChatPromptTemplate` for all 5 prompt types (preview, explain, momentum, legends, docling analysis) — structured, type-safe prompt engineering | ✅ Live | | |
| | 3 | **IBM Docling** | PDF match report parser — extracts structured text from football report PDFs, feeds parsed data to Granite for AI analysis | ✅ Integrated | | |
| | 4 | **IBM Bob** | AI code assistant used throughout development — architecture design, debugging, deployment setup | ✅ Documented | | |
| ### IBM Granite is the Star | |
| Unlike projects where AI is a wrapper around a deterministic engine, Match Decoded puts Granite at the center: | |
| - Every tactical preview is **Granite-generated**, not templated | |
| - Every decision trace includes **Granite's natural language reasoning** | |
| - Every momentum analysis is **Granite explaining probabilities in context** | |
| - Every legends matchup is **Granite's take on historical football debate** | |
| - Every match report analysis uses **Granite to extract tactical insight from raw text** | |
| --- | |
| ## ✨ Features | |
| ### 🔮 Pre-Match Preview | |
| Select any two teams from 215 international sides. See the predicted outcome with probability breakdown, then read a **Granite-generated tactical preview** explaining WHY one team has the edge. | |
| ### 🔀 What-If Simulator | |
| Change venue (neutral/home) and tournament type (major/friendly). Watch the prediction shift in real time. **Granite explains the delta** — what changed and why. | |
| ### 🏆 Legends Matchup | |
| Cross-era comparisons — Brazil 1970 vs Germany 2014? England 1966 vs France 2018? **Granite settles the debate** with statistical context and passionate football storytelling. | |
| ### 📋 Match Report Analyzer (Docling) | |
| Upload a football match report PDF. **IBM Docling** extracts the text. **Granite + LangChain** analyzes the tactics, key moments, and what decided the match. | |
| ### 🔍 Decision Trace | |
| Every prediction is fully transparent. View: | |
| - **Feature importance** — which factors drove the prediction | |
| - **Granite explanation** — AI-generated narrative of the model's reasoning | |
| - **Model metrics** — accuracy, feature weights, training methodology | |
| ### 🧠 Model Transparency | |
| - **Algorithm**: Random Forest (200 trees, max depth 12) | |
| - **Accuracy**: 55.8% on unseen data (vs 47.2% baseline) | |
| - **Training**: 24,179 matches (pre-2018) | |
| - **Testing**: 7,652 matches (2018+) | |
| - **Features**: 8 factors — win rates, goal averages, recent form, venue, tournament type | |
| --- | |
| ## 🏗️ Architecture | |
| ``` | |
| ┌─────────────────────────────────────────────────────┐ | |
| │ Streamlit Frontend │ | |
| │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │ | |
| │ │ Preview │ │What-If │ │Legends │ │ Docling │ │ | |
| │ │ │ │Simulator │ │Matchup │ │Analyzer │ │ | |
| │ └─────┬─────┘ └────┬─────┘ └───┬────┘ └────┬─────┘ │ | |
| └────────┼─────────────┼───────────┼───────────┼───────┘ | |
| │ │ │ │ | |
| ▼ ▼ ▼ ▼ | |
| ┌─────────────────────────────────────────────────────┐ | |
| │ FastAPI Backend │ | |
| │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │ | |
| │ │/predict │ │/explain/ │ │/explain│ │/docling/ │ │ | |
| │ │ │ │preview │ │/legends│ │analyze │ │ | |
| │ │decision │ │momentum │ │ │ │ │ │ | |
| │ └─────┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘ │ | |
| └────────┼────────────┼───────────┼───────────┼───────┘ | |
| │ │ │ │ | |
| ▼ ▼ ▼ ▼ | |
| ┌────────┐ ┌───────────┐ ┌────────┐ ┌──────────┐ | |
| │ Random │ │ LangChain│ │ IBM │ │ IBM │ | |
| │ Forest │ │ Prompt │ │ Granite│ │ Docling │ | |
| │ Model │ │ Templates │ │via HF │ │ PDFParser│ | |
| └────────┘ └───────────┘ └────────┘ └──────────┘ | |
| ``` | |
| --- | |
| ## 🎯 Judging Criteria Alignment | |
| | Criterion | How Match Decoded Addresses It | | |
| |---|---| | |
| | **Technical Execution** | 5 FastAPI endpoints, Random Forest ML model (55.8% acc), LangChain prompt chains, Docling PDF parsing, Streamlit UI with Plotly charts | | |
| | **Innovation** | Explainability-first approach — not just prediction but WHY. Cross-era Legends Matchup. What-if simulator with AI delta analysis. Docling match report analysis | | |
| | **Challenge Fit** | Direct football theme. "Understand the game. Explain the moments." — every feature is about fan understanding, not pure prediction | | |
| | **Feasibility** | Live prototype with 215 teams, 49K matches, 5 working endpoints. Runs on free HuggingFace Spaces. Zero credit card required | | |
| | **Use of IBM Tech** | 4 IBM technologies: **Granite** (LLM), **LangChain** (prompts), **Docling** (PDF parsing), **Bob** (development assistance) | | |
| | **User Experience** | Polished glassmorphic UI, mobile-friendly, 4 interactive tabs, real-time animations, stadium-themed design | | |
| | **Explainability** | Fully traceable predictions. Feature importance displayed. Granite explains every decision in plain language. No black box | | |
| --- | |
| ## 🚀 Quick Start | |
| ### Prerequisites | |
| - Python 3.11+ | |
| - HuggingFace token (for Granite Inference API — included in code) | |
| ### Installation | |
| ```bash | |
| # Clone | |
| git clone https://github.com/agp-369/match-decoded.git | |
| cd match-decoded | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Start the backend API | |
| python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 | |
| # In a new terminal, start the frontend | |
| streamlit run frontend/app.py | |
| ``` | |
| Open your browser to `http://localhost:8501` | |
| ### Environment Variables | |
| Create a `.env` file in the project root: | |
| ```env | |
| HF_TOKEN=your_huggingface_token_here # Get yours at https://huggingface.co/settings/tokens | |
| API_URL=http://localhost:8000 # Backend URL (auto-detected) | |
| ``` | |
| --- | |
| ## 📁 Project Structure | |
| ``` | |
| match-decoded/ | |
| ├── backend/ | |
| │ ├── main.py # FastAPI (5 endpoints) | |
| │ ├── model.py # Random Forest wrapper | |
| │ ├── granite.py # IBM Granite + LangChain integration | |
| │ ├── langchain_prompts.py # LangChain prompt templates | |
| │ ├── docling_parser.py # IBM Docling PDF parsing | |
| │ └── requirements.txt # Backend deps | |
| ├── frontend/ | |
| │ ├── app.py # Streamlit UI (4 tabs) | |
| │ └── requirements.txt # Frontend deps | |
| ├── models/ | |
| │ ├── match_predictor.pkl # Trained Random Forest | |
| │ └── team_data.pkl # Team statistics | |
| ├── requirements.txt # Combined deps | |
| ├── .huggingface.yaml # HuggingFace Spaces config | |
| └── README.md | |
| ``` | |
| --- | |
| ## 🎬 Demo Video | |
| ### Pitch Script | |
| ``` | |
| "Every football fan has watched a match and wondered: WHY did they win? | |
| Match Decoded answers that question. | |
| Powered by IBM Granite, LangChain, Docling, and built with IBM Bob, | |
| Match Decoded analyzes 49,000 international matches to explain | |
| the invisible forces shaping every game. | |
| Select any two teams. Granite delivers a tactical preview explaining | |
| why one has the edge. Change the venue — watch the prediction shift. | |
| Compare legends across eras — Granite settles the debate. | |
| Upload a match report — Docling extracts the tactics, Granite analyzes them. | |
| Teams have million-dollar analytics. Fans have guesswork. | |
| Match Decoded bridges that gap. | |
| Built with IBM Granite. LangChain. Docling. IBM Bob. | |
| Match Decoded — Every fan deserves to know WHY." | |
| ``` | |
| --- | |
| ## 👨💻 Built With | |
| | Technology | Purpose | | |
| |---|---| | |
| | **IBM Granite 3.1-2B** | AI-powered match explainability | | |
| | **LangChain** | Structured prompt engineering (5 templates) | | |
| | **IBM Docling** | PDF match report parsing | | |
| | **IBM Bob** | AI code assistant | | |
| | **Streamlit** | Interactive web frontend | | |
| | **FastAPI** | High-performance backend API | | |
| | **scikit-learn** | Random Forest prediction model | | |
| | **Plotly** | Interactive data visualizations | | |
| | **HuggingFace Spaces** | Free deployment (zero credit card) | | |
| --- | |
| ## 📊 Training Data | |
| - **Source**: International football results dataset (1872-2026) | |
| - **Total matches**: 49,329 | |
| - **Teams**: 215 international sides | |
| - **Training set**: 24,179 matches (pre-2018) | |
| - **Test set**: 7,652 matches (2018+) | |
| - **Model**: Random Forest (200 trees, max depth 12) | |
| - **Accuracy**: 55.8% (vs 47.2% baseline) | |
| - **Features**: 8 factors — team_a_winrate, team_b_winrate, team_a_goal_avg, team_b_goal_avg, team_a_recent_form, team_b_recent_form, is_neutral, is_major_tournament | |
| --- | |
| ## 📝 License | |
| Apache 2.0 — Built for the IBM AI Builders Challenge 2026 | |
| --- | |
| <div align="center"> | |
| <em>Every fan deserves to understand WHY their team won or lost.</em><br> | |
| <strong>Match Decoded</strong> — IBM AI Builders Challenge 2026 | |
| </div> | |