How amrit-sarker/bpl-win-probability-predictor works
1. What this repository is
- A small machine-learning project for ball-by-ball win probability prediction in the Bangladesh Premier League (BPL).
- It is split into two clear phases: offline model training and online/scripted inference.
2. Core runtime boundary
- The only executable runtime component in the repo is predict.py.
- The trained model is stored separately in bpl_predictor.pkl, so inference does not retrain anything at runtime.
3. Training subsystem
- bpl_win_predictor.ipynb contains the full data cleaning, feature engineering, and model training workflow.
- This notebook is the source of the model artifact and is where the architecture’s learning logic lives.
4. Model artifact
- bpl_predictor.pkl is the serialized trained model, described as the project’s “brain.”
- The README indicates the model is a Logistic Regression classifier with about 82.28% accuracy.
5. Data source and preprocessing boundary
- Historical match data was collected from Cricsheet JSON files.
- The training set spans 2012–2025 and includes 435 matches.
- The raw source data is not stored as JSON in the repo; instead, the repo keeps a processed CSV artifact.
6. Prepared dataset artifact
- bpl_all_matches.csv appears to be the consolidated dataset used for analysis/training.
- This file likely represents the boundary between raw external match feeds and the cleaned modeling dataset.
7. Inference flow
- predict.py takes match-state inputs such as:
- batting team
- bowling team
- venue
- target
- current runs
- wickets lost
- current over and ball
- These inputs are passed into the loaded pickle model to produce the chasing team’s win probability.
8. Input normalization constraint
- The model expects city-based labels only, not full franchise or venue names.
- This is an important architectural constraint because it means the inference layer depends on the exact categorical encoding used during training.
9. Key feature shape
- The prediction problem is ball-by-ball and state-based, meaning the model is driven by the current match situation rather than a full sequence model.
- The critical state variables are score, wickets, overs, target, teams, and venue.
10. External dependencies
- The repo’s functional dependencies are lightweight: pandas and scikit-learn.
- The trained artifact and inference script together imply a standard Python ML deployment pattern, not a web service or API server.
11. Validation context
- The README mentions informal comparison against ESPN Cricinfo during live matches.
- That is validation context only; it is not part of the repo’s runtime architecture.
12. Best way to draw the architecture
- Draw three main blocks:
- Data ingestion/prep from Cricsheet into a cleaned dataset
- Training notebook producing the pickle model
- Prediction script consuming user inputs plus the pickle model to output win probability
- The central boundary is the transition from offline training artifacts to runtime inference.
Main entry points: predict.py Predict script · bpl_win_predictor.ipynb Training notebook · bpl_all_matches.csv Match CSV · bpl_predictor.pkl Logistic model
Components 9
Data prep
Raw match feeds are consolidated into the training dataset.
- Cricsheet data · Historical BPL match feeds used to build the dataset.
Training
Offline model-building workflow.
- Training notebook · Data cleaning, feature engineering, and model fitting workflow.
bpl_win_predictor.ipynb - Feature logic · Encodes match-state variables such as teams, venue, target, runs, wickets, and over/ball.
- Dependencies · pandas and scikit-learn support data handling and model training/inference.
Runtime
Scripted prediction path used for inference.
- Predict script · Loads the trained model and produces win probabilities from live match inputs.
predict.py - Match inputs · Batting team, bowling team, venue, target, runs, wickets, overs, and ball.
- Win probability · Chasing team win probability returned by the inference script.
Artifacts
Persisted dataset and serialized model.
- Match CSV · Consolidated ball-by-ball dataset used for analysis and training.
bpl_all_matches.csv - Logistic model · Trained win-probability model saved as a pickle artifact.
bpl_predictor.pkl
Connections 9
- Cricsheet data → Match CSV: consolidate · Historical JSON feeds are transformed into the prepared CSV dataset.
- Match CSV → Training notebook: train from · The notebook consumes the consolidated dataset.
- Training notebook → Feature logic: engineer · Training builds the state-based features used by the classifier.
- Feature logic → Logistic model: fit model · Feature set is used to train the logistic regression model.
- Dependencies → Training notebook: support · Training relies on the Python ML stack.
- Dependencies → Predict script: support · Inference relies on the same lightweight Python dependencies.
- Match inputs → Predict script: feed · User-supplied match state is passed into the prediction script.
- Logistic model → Predict script: load · The script loads the serialized model artifact at runtime.
- Predict script → Win probability: emit · Script outputs the chasing team's win probability.