🏏 CricOptima

CricOptima is an advanced, AI-powered fantasy cricket team optimizer. I designed and built this system to move beyond simple heuristics, implementing Gradient Boosting for player performance prediction and mathematical constraint satisfaction for optimal team selection.

🔴 LIVE DEMO - Experience the AI optimizer in action!

---

📚 Documentation

• 📖 Deployment Guide: How to run this on the web or Docker.
• 🏗️ Architecture: Deep dive into the clean, modular design.
• 🤝 Contributing: How to join the project.

---

🚀 Key Features

Build optimal fantasy cricket teams using machine learning predictions and constraint optimization algorithms.

📸 Screenshots

Dashboard	Constraints Setup	Player Analytics
Optimization Results	Head-to-Head	Simulation

✨ Features

Feature	Description
🤖 ML Predictions	Gradient Boosting model predicts player fantasy points
🎯 Smart Optimization	Builds best team within budget and role constraints
📊 Analytics Dashboard	Explore player stats, value scores, and predictions
🔌 REST API	Full-featured FastAPI backend with Swagger docs
🐳 Docker Ready	One-command deployment with docker-compose

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone repository
git clone https://github.com/millenniumsingha/CricOptima.git
cd CricOptima

# Train ML model and start services
docker-compose --profile training up train
docker-compose up -d

# Access:
# - Dashboard: http://localhost:8501
# - API Docs:  http://localhost:8000/docs

Option 2: Local Installation

# Install dependencies
pip install -r requirements.txt

# Train ML model
python -m src.ml.train

# Start API (terminal 1)
uvicorn api.main:app --reload

# Start Dashboard (terminal 2)
streamlit run app/streamlit_app.py

📊 How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Player Data   │────▶│   ML Predictor  │────▶│   Predictions   │
│   (Stats/Form)  │     │ (Gradient Boost)│     │  (Points/Conf)  │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                        ┌─────────────────┐              │
                        │    Optimizer    │◀─────────────┘
                        │  (Constraints)  │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │   Optimal XI    │
                        │ (Best Team)     │
                        └─────────────────┘

ML Features Used

• Recent batting/bowling averages
• Strike rate & economy rate
• Form trend (improving/declining)
• Consistency score
• Matches played (experience)

Optimization Constraints

• Budget limit (default: 1000 points)
• Team size: 11 players
• Min 3 batsmen, 3 bowlers, 1 all-rounder, 1 wicket-keeper
• Max 7 players from same team

🔌 API Reference

Method	Endpoint	Description
GET	/players	List all players with filters
GET	/players/{id}	Get single player details
POST	/optimize	Build optimal team
GET	/predictions	Get ML predictions
POST	/teams/validate	Validate team selection
GET	/health	Health check

Example: Get Optimal Team

curl -X POST "http://localhost:8000/optimize" \
  -H "Content-Type: application/json" \
  -d '{"budget": 1000, "team_name": "My Dream XI"}'

📁 Project Structure

CricOptima/
├── src/
│   ├── models/          # Data models (Player, Team, Match)
│   ├── scoring/         # Fantasy points calculator
│   ├── optimizer/       # Team optimization algorithm
│   ├── ml/              # ML prediction model
│   └── data/            # Data layer & sample data
├── api/                 # FastAPI backend
├── app/                 # Streamlit dashboard
├── tests/               # Test suite
└── ml_models/           # Trained models

🧪 Testing

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=src --cov=api

🎯 Fantasy Scoring Rules

Category	Points
Run	0.5
Four	+1 bonus
Six	+2 bonus
50 runs	+10 bonus
100 runs	+20 bonus
Wicket	10
3-wicket haul	+5 bonus
5-wicket haul	+10 bonus
Catch/Stumping/Run-out	10

✨ What's New in v2.0

• 🔌 Live Integration: Real-time player data fetching via CricAPI.
• 🔐 User Auth: Secure JWT-based authentication with bcrypt hashing.
• 💾 Team Management: Save, load, and manage your optimized teams.
• ⚖️ Smart Comparison: Head-to-Head win probability predictions.
• 🎲 Monte Carlo Simulation: 1000x match simulation for variance analysis.
• 📱 Mobile First: Fully responsive Streamlit UI for all devices.
• 🚀 DevOps Ready: CI/CD pipeline with GitHub Actions.

🗺️ Roadmap (v3.0 & Beyond)

Phase 1: Advanced Analytics (Q1 2026)

• Player Consistency Ratings: New metric based on coefficient of variation.
• ROI Analysis: Cost vs. Points historical trend analysis.
• Venue Impact: Adjust predictions based on pitch conditions.

Phase 2: Social & Real-time (Q2 2026)

• Private Leagues: Compete with friends in custom leaderboards.
• Live Tracking: Real-time point updates via WebSocket during matches.
• Historical Backtesting: Validate model against past 5 years of IPL data.

🙏 Acknowledgments

• Original project from Internshala Python Training
• IPL teams and player data
• scikit-learn, FastAPI, and Streamlit communities

---

Built with ❤️ for cricket fans and data enthusiasts