ML-powered sports match outcome prediction across Football, Cricket & Basketball.

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Frontend   │────▶│   Backend    │────▶│   ML Service     │
│  (Vite +     │     │  (Express)   │     │  (FastAPI +      │
│   React/TS)  │     │  Port 5000   │     │   XGBoost)       │
│  Port 5173   │     └──────────────┘     │  Port 8001       │
└──────────────┘                          └──────┬───────────┘
                                                 │
                                          ┌──────▼───────────┐
                                          │  Scraper / Data  │
                                          │  Generator       │
                                          └──────────────────┘

• Frontend — React + TypeScript UI (Vite) with prediction forms, analytics dashboard, and history
• Backend — Express.js proxy that routes API calls to the ML service
• ML Service — FastAPI server with XGBoost model, explainability, and match data
• Scraper — Data fetcher and synthetic training data generator

Note: Model files (.pkl, .joblib, model_meta.json), raw Cricsheet data (ipl_json/, t20s_json/), and training_data.csv are generated locally and not tracked in git. See the Data and Setup sections below.

• Python 3.10+
• Node.js 18+
• npm 9+

git clone https://github.com/Nikhil1869/QuantumScore.git
cd QuantumScore

cp .env.example .env
# Edit .env if you need custom ports

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt

python -m ml_service.train

This creates model.pkl and model_meta.json inside ml_service/.

uvicorn ml_service.main:app --port 8001 --reload

cd backend
npm install
npm start

cd frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

The ML models can be trained using real match data from Cricsheet. These JSON files are not included in the repository due to their size.

To download:

# IPL match data
curl -o ipl_json.zip https://cricsheet.org/downloads/ipl_json.zip
unzip ipl_json.zip -d ipl_json/

# T20 International match data
curl -o t20s_json.zip https://cricsheet.org/downloads/t20s_json.zip
unzip t20s_json.zip -d t20s_json/

Once downloaded, train models using the Cricsheet pipeline:

python -m ml_service.parse_cricsheet    # Parse JSON → features
python -m ml_service.train_models       # Train models on parsed data

Alternatively, the default ml_service.train generates 2,000 synthetic training samples that work without any external data download.

All endpoints are available through the backend proxy (localhost:5000) or directly from the ML service (localhost:8001).

POST /api/predict
{
  "sport": "football",
  "homeTeam": "Manchester United",
  "awayTeam": "Liverpool",
  "teamA_form": 0.75,
  "teamB_form": 0.80,
  "teamA_home": 1,
  "teamB_home": 0,
  "teamA_strength": 0.72,
  "teamB_strength": 0.78,
  "teamA_avg_goals": 1.8,
  "teamB_avg_goals": 2.1,
  "teamA_avg_conceded": 0.9,
  "teamB_avg_conceded": 0.8,
  "head_to_head_advantage": 0.55
}

# Regenerate training data (2,000 samples) and retrain
python -m ml_service.train

# Or train on real Cricsheet data
python -m ml_service.train_models

# Or use the auto-retrain script
python -m ml_service.auto_train

# Or trigger via API
curl -X POST http://localhost:8001/retrain

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

This project is licensed under the MIT License — see LICENSE for details.

• Cricsheet — Ball-by-ball cricket match data in JSON format
• XGBoost — Gradient boosting framework
• FastAPI — Modern Python web framework
• Vite — Next-generation frontend build tool