Midwicket

Cricket Data Infrastructure

20,888+ Matches  ·  9,148,005+ Deliveries  ·  25+ Years of Coverage

       

Ball-by-ball cricket analytics. Local. Fast. No cloud required.

Why Midwicket?

These are real findings — generated in seconds from the IPL corpus using Midwicket's query engine.

See all 10 showcase analyses →

Quick Start

30 seconds. No data download. No account.

pip install midwicket

import midwicket.express as px

# Win probability — works instantly, bundled in-memory data
result = px.predict_win(
    venue="Wankhede Stadium",
    target=180,
    current_score=120,
    wickets_down=5,
    overs_done=15.0,
)
print(f"Win probability: {result['win_prob']:.1%}")
# Win probability: 22.5%

That's it. The model runs locally, no API key, no download.

Open in Colab → — zero-install, browser-based.

Loading Datasets

Midwicket connects to Cricsheet and manages download, extraction, and ingestion automatically.

from midwicket.datasets import load_dataset

# IPL — 1,100+ matches, 2008–present (~50 MB, downloads once)
session = load_dataset("ipl")

# Big Bash League
session = load_dataset("bbl")

# Everything — all formats, all genders, 25+ years
session = load_dataset("all")

Available datasets:

Once loaded, a session gives you a thread-safe DuckDB engine over ball-by-ball events. Query anything:

df = session.engine.execute_sql("""
    SELECT batter,
           SUM(runs_batter) AS runs,
           ROUND(SUM(runs_batter) * 100.0 / COUNT(*), 1) AS strike_rate,
           COUNT(DISTINCT match_id) AS matches
    FROM ball_events
    WHERE over >= 15              -- death overs only
    GROUP BY batter
    HAVING COUNT(*) >= 100
    ORDER BY runs DESC LIMIT 10
""").to_pandas()

Feature Store

Six production-grade metrics, computed from ball-by-ball data:

from midwicket.features import (
    build_pressure_index,
    build_bowler_quality_rating,
    build_match_context_score,
    build_venue_bias_rating,
    build_batter_intent_score,
    build_expected_runs,
)

# Pressure Index — situational leverage per delivery
pi = build_pressure_index(session)
# Returns DataFrame: match_id, inning, over, ball, batter_id, bowler_id, pressure_index

# Bowler Quality Rating — dot balls + wicket rate combined
bqr = build_bowler_quality_rating(session)
# Returns DataFrame: bowler_id, total_balls, dot_balls, wickets, bowler_quality_rating

# Venue Bias Rating — batter-friendly vs bowler-friendly grounds
vbr = build_venue_bias_rating(session)
# VBR > 1.0 = batter-friendly  |  VBR < 1.0 = bowler-friendly
# Venues with < 5 matches default to VBR = 1.0 (stabilised)

# Match Context Score — chase pressure at any moment in the 2nd innings
mcs = build_match_context_score(session)

All features support date filtering — analyse any historical window without leakage:

bqr_2023 = build_bowler_quality_rating(session, start_date="2023-01-01", end_date="2023-12-31")

Scouting Reports

import midwicket as md

session = md.init("./data")          # point at your local dataset
report = md.scouting_report("Virat Kohli")

print(report["role"])                # "Batter"
print(report["strengths"])           # ["Powerplay anchor", "Middle-over accelerator", ...]
print(report["phase_batting"])       # {"Powerplay": {...}, "Middle": {...}, "Death": {...}}
print(report["venue_performance"])   # per-venue batting average and SR
print(report["recent_form"])         # last-N-matches rolling stats

The scouting report resolves name aliases automatically — "V Kohli", "Virat Kohli", "kohli" all resolve to the same entity across 17+ seasons.

Showcase Gallery

Ten analyses built on real IPL data. Click any image to see the full walkthrough.

View all 10 showcases with charts, queries, and walkthroughs →

Five-Minute Tutorial

New to Midwicket? docs/getting_started.md takes you from install to first insight in under 5 minutes — using real data, real outputs.

Examples

The examples/ directory contains 36 runnable scripts organised by complexity:

Start here: examples/28_express_quickstart.py

Architecture

Midwicket separates concerns across five layers. Data flows from raw JSON through a typed ingestion pipeline into a DuckDB analytical store, with a query planner routing between live scans and pre-built feature tables.

Cricsheet JSON
      │
      ▼
┌─────────────────────┐
│  Canonicaliser      │  Strict V1 Arrow schema · retirement fix · int32 upcasting
│  (core/canonicalize)│  Deterministic match_id · venue alias resolution
└──────────┬──────────┘
           │ PyArrow Table
           ▼
┌─────────────────────┐
│  Identity Registry  │  Player / venue / team aliases across 25+ years
│  (storage/registry) │  Temporal-safe: resolves names at match date, not today
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  DuckDB Engine      │  Thread-safe · snapshot management · temporal filtering
│  (storage/engine)   │  ball_events: 9M+ rows · sub-second aggregations
└──────────┬──────────┘
           │
      ┌────┴────┐
      ▼         ▼
 Feature     Express
  Store        API
(features.py) (express.py)
      │         │
      └────┬────┘
           ▼
   FastAPI + Prometheus
   (midwicket/serve/)

Data integrity guarantees:

• Schema version-locked (BALL_EVENT_SCHEMA v1.0.0) — breaking changes are explicit
• over stored as int16, runs as int32 — no silent overflow on aggregation
• Retirements classified correctly: RETIRED_HURT/RETIRED_NOT_OUT → is_wicket=False
• Temporal filters are leak-proof — verified against 4 cutoff dates, 0 leaked rows

Enterprise Deployment

git clone https://github.com/CodersAcademy006/Midwicket.git && cd Midwicket
cp .env.example .env           # set MIDWICKET_SECRET_KEY, MIDWICKET_API_KEYS
docker-compose up -d           # FastAPI + Prometheus + Grafana

The FastAPI service exposes REST endpoints for win probability, player stats, matchups, and scouting reports. Prometheus scrape config and a Grafana dashboard definition are included.

Contributing

Contributions welcome. Areas where help is most needed:

• Additional competition datasets (WBBL scouting, CPL analysis)
• Jupyter notebook tutorials for the showcase analyses
• Performance benchmarks across dataset sizes
• Documentation translations

Read CONTRIBUTING.md before submitting a PR.