README.md

metadata

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

---

🏟️ 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

# 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:

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

---

Every fan deserves to understand WHY their team won or lost.
Match Decoded — IBM AI Builders Challenge 2026