CIPS - Cricket IPL Prediction System

Predicting who's likely to win a cricket match mid-game usually comes down to a commentator's gut feeling. CIPS replaces that guesswork with a live win probability: enter the teams, ground, score, wickets, and overs, and it returns each side's chance of winning in real time. Every prediction is timestamped and saved for later checking. Built and tested like real production software, not a demo.

Under the hood, a FastAPI backend serves an XGBoost classifier inside a scikit-learn Pipeline, so OneHotEncoding and the feature set (runs left, balls left, wickets left, run rates) apply identically at training and inference. Trained on IPL ball-by-ball history (2008–2019) with franchise standardization and Duckworth-Lewis filtering. Every request is persisted via SQLModel into SQLite with a timestamped audit trail. A React/Vite/Tailwind frontend calls the API, backed by Ruff, Mypy, Pytest, and a Docker-based GitHub Actions pipeline — reproducible, tested, containerized: the discipline a company needs before trusting a model in production.

demo.mp4

---

Project Structure

CIPS/
├── .github/                      # CI/CD Workflows
│   └── workflows/
│       └── main.yml
│             
├── backend/                      
│   ├── app/                      # Application Package
│   │   ├── __init__.py
│   │   ├── main.py               # FastAPI Entry Point
│   │   ├── db.py                 # Database Configuration
│   │   ├── models.py             # Data Models (Pydantic & SQLModel)
│   │   ├── api/                  # API Layer
│   │   │   ├── __init__.py
│   │   │   └── endpoints.py      # predict endpoint with logic & logging
│   │   ├── core/                 # Core Infrastructure
│   │   │   ├── __init__.py
│   │   │   ├── config.py         # App Settings & Environment Variables
│   │   │   └── logging_config.py # Structured Logging System
│   │   ├── ml_model/             # Machine Learning Artifacts
│   │   │   └── pipe.pkl          # Serialized ML Pipeline
│   │   ├── services/             # Background & ML Services
│   │   │   ├── __init__.py
│   │   │   ├── data_collection.py # Dataset fetching & loading
│   │   │   ├── model_evaluation.py # Model training & metric reporting
│   │   │   └── preprocessing.py   # Complex data transformation pipelines
│   │   └── utils/                # Utility Functions
│   │       ├── __init__.py
│   │       └── eda.py            # Exploratory Data Analysis & Visualization
│   ├── data/                     # Data Storage
│   │   ├── cips.db               # SQLite Database for Prediction History
│   │   ├── deliveries.csv        # Historical Ball-by-Ball Data
│   │   └── matches.csv           # Historical Match Summaries
│   ├── logs/                     # Application Logs
│   │   └── app.log               
│   ├── notebook/                 # Research & Development
│   │   └── experiment.ipynb      
│   ├── tests/                    # Backend Testing Suite
│   │   ├── __init__.py
│   │   ├── test_api.py           # API Integration Tests
│   │   ├── test_db.py            # Database Logic Tests
│   │   ├── test_endpoints_fail.py # ML Failure Scenario Tests
│   │   ├── test_services.py      # Preprocessing & Service Logic Tests
│   │   └── test_utils.py         # EDA Utility Tests
│   ├── Dockerfile                # Dockerfile
│   ├── pyproject.toml            # Python Tooling Config
│   ├── requirements.txt          # Dependencies
│   └── setup.py                  # Package Metadata
│
├── frontend/                     # Frontend Root (Vite + React)
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   │   ├── Footer.jsx
│   │   │   └── PredictionForm.jsx # Main Prediction Interface
│   │   ├── pages/                # High-level Pages
│   │   │   └── Home.jsx
│   │   ├── services/             # Frontend APIs
│   │   │   └── api.js            
│   │   ├── App.jsx               # Application Layout
│   │   ├── constants.js          
│   │   ├── main.jsx              # React DOM Entry
│   │   └── index.css
│   ├── public/                   # Static Assets
│   ├── Dockerfile                # Frontend Dockerfile
│   ├── package.json              # NPM Dependencies & Scripts
│   ├── tailwind.config.js        # Design System Config
│   └── vite.config.js            # Build Tool Config
│
├── docker-compose.yml            # Multi-container orchestration
├── .gitignore                    
├── demo.png                       # Project Picture
├── demo.mp4                       # Project Video
├── LICENSE                       
├── README.md                     
└── run.py                        # Main Execution Script

---

Model Architecture

graph TD
    A[Raw Data] --> B[Preprocessing]
    B --> C[Feature Engineering]
    C --> D[Model Training]
    D --> E[Evaluation]
    E --> F[Deployment]

Loading

---

Dataset

IPL Match Data (2008-2020) containing:

• 800+ matches
• 10+ features including:
  • Batting/Bowling teams
  • Current score
  • Wickets fallen
  • Overs completed
  • Venue information

Dataset available at: Kaggle IPL Dataset

---

Machine Learning Deep Dive

CIPS utilizes a sophisticated ML pipeline to estimate win probabilities.

1. The Dataset

The model is trained on historical IPL data (2008-2019) containing over 150,000 deliveries.

2. Feature Engineering

Our preprocessing engine transforms raw data into predictive features:

• Batting/Bowling Teams: Categorical encoding of participants.
• City: Venue factor for home/away advantage.
• Runs Left: Continuous metric calculated by subtracting current score from target.
• Balls Left: Remaining balls in the 2nd innings.
• Wickets Left: Crucial factor for chasing team's stability.
• Current Run Rate (CRR): Performance indicator.
• Required Run Rate (RRR): Pressure indicator.

3. Model Architecture

We use an XGBoost Classifier wrapped in a scikit-learn Pipeline. This ensures that preprocessing (like OneHotEncoding) is consistent during both training and inference.

• Success Rate: High R2 and Accuracy on historical test data.
• Resilience: Handles edge cases like missing cities or Duckworth-Lewis matches.

---

Operations Guide

1. Running the Project Locally

The easiest way is using the root run.py script:

# 1. Install Backend Deps
pip install -r backend/requirements.txt

# 2. Setup Frontend
cd frontend && npm install && cd ..

# 3. Start Both
python run.py

2. Testing

Using PowerShell (Windows):

# From the project root (CIPS/)
$env:PYTHONPATH="."; pytest backend/tests/ --cov=backend/app --cov-report=term-missing

Alternative (Recommended): Install the backend in editable mode once, and then you can run pytest from anywhere without setting PYTHONPATH.

pip install -e backend
pytest backend/tests/

3. Docker Deployment

Standard containerized workflow:

# Build & Run via Compose
docker-compose up --build

# Backend only
docker build -t cips-backend -f backend/Dockerfile .
docker run -p 8000:8000 cips-backend

4. CI/CD (GitHub Actions)

Our main.yml automatically performs:

• Linting & Formatting: Using Ruff.
• Type Checking: Using Mypy.
• Integrated Tests: Runs pytest inside the built Docker container.
• Docker Build: Verifies image integrity.

---

Tech Stack

• Backend: Python 3.9, FastAPI, SQLModel, Uvicorn.
• ML: Scikit-learn, Pandas, XGBoost, Numpy.
• Frontend: React 18, Vite, Tailwind CSS, DaisyUI.
• Quality: Ruff (Linter/Formatter), Mypy (Types), Pytest (Testing).
• Environment: Docker, Docker Compose, GitHub Actions.

---

Author

Md Emon Hasan
Email: emon.mlengineer@gmail.com Portfolio: Md-Emon-Hasan WhatsApp: +8801834363533
GitHub: Md-Emon-Hasan
LinkedIn: Md Emon Hasan
Facebook: Md Emon Hasan