ashishgimekar/commentary-flan-t5

Cricket Commentary Model

Fine-tuned Flan-T5-base to generate ball-by-ball cricket commentary from structured event JSON.

• Hugging Face: ashishgimekar/commentary-flan-t5

Base Model

• Model: google/flan-t5-base
• Type: Seq2Seq (encoder-decoder), text-to-text

Task

• Input: One ball event as JSON (over, teams, striker, bowler, ball length/line, shot, runs, wickets, etc.).
• Output: One or two sentences of commentary; on the last ball of an over, includes score line (e.g. "After 6 overs, Team are 45 for 2.").

Input format used in training and inference:

Generate cricket commentary for this ball: {"ball_in_over": 6, "batting_team": "...", ...}

Event JSON schema

Pass a single event object (as JSON) to the model. The keys must match the schema below.

Full schema

{
  "over_number": 0,
  "ball_in_over": 1,
  "innings": "1",
  "batting_team": "Royal Challengers Bengaluru",
  "bowling_team": "Chennai Super Kings",
  "striker": "V Kohli",
  "non_striker": "F du Plessis",
  "bowler": "DL Chahar",
  "ball_length": "",
  "ball_line": "",
  "shot_played": "",
  "shot_direction": "",
  "runs_off_bat": 0,
  "extras": 0,
  "wides": "",
  "noballs": "",
  "byes": "",
  "legbyes": "",
  "wicket": 0,
  "wicket_type": "",
  "player_dismissed": "",
  "runs_so_far": 0,
  "wickets_so_far": 0,
  "is_last_ball_of_over": false,
  "over_number_completed": null,
  "score_at_end_of_over": ""
}

Field	Type	Description
over_number	int	Over index (0-based).
ball_in_over	int	Delivery in over (1–6).
innings	string	"1" or "2".
batting_team	string	Batting side name.
bowling_team	string	Bowling side name.
striker	string	Batsman on strike (e.g. "V Kohli").
non_striker	string	Non-striker.
bowler	string	Bowler (e.g. "DL Chahar").
ball_length	string	e.g. "good length", "full", "short", "yorker", "bouncer".
ball_line	string	e.g. "outside off", "on off stump", "on leg stump".
shot_played	string	e.g. "drive", "cut", "leave", "defense".
shot_direction	string	e.g. "cover", "midwicket", "straight".
runs_off_bat	int	Runs from bat this ball (0, 1, 4, 6).
extras	int	Extra runs this ball.
wides	string	Wide runs if any (e.g. "1.0"), else "".
noballs	string	No-ball runs if any, else "".
byes	string	Byes if any, else "".
legbyes	string	Leg byes if any, else "".
wicket	int	1 if wicket this ball, else 0.
wicket_type	string	e.g. "caught", "bowled", "lbw", or "".
player_dismissed	string	Dismissed batter or "".
runs_so_far	int	Team total runs after this ball.
wickets_so_far	int	Wickets lost after this ball.
is_last_ball_of_over	bool	true if ball_in_over == 6.
over_number_completed	int | null	Over that just finished (only when last ball), else null.
score_at_end_of_over	string	e.g. "45 for 2" when last ball, else "".

Example 1: First ball (wide)

Input:

{
  "over_number": 0,
  "ball_in_over": 1,
  "innings": "1",
  "batting_team": "Royal Challengers Bengaluru",
  "bowling_team": "Chennai Super Kings",
  "striker": "V Kohli",
  "non_striker": "F du Plessis",
  "bowler": "DL Chahar",
  "ball_length": "",
  "ball_line": "",
  "shot_played": "",
  "shot_direction": "",
  "runs_off_bat": 0,
  "extras": 1,
  "wides": "1.0",
  "noballs": "",
  "byes": "",
  "legbyes": "",
  "wicket": 0,
  "wicket_type": "",
  "player_dismissed": "",
  "runs_so_far": 1,
  "wickets_so_far": 0,
  "is_last_ball_of_over": false,
  "over_number_completed": null,
  "score_at_end_of_over": ""
}

Expected output: "DL Chahar to V Kohli. Wide called by the umpire - that one drifted down the leg side"

Example 2: Last ball of over (boundary)

Input:

{
  "over_number": 0,
  "ball_in_over": 6,
  "innings": "1",
  "batting_team": "Royal Challengers Bengaluru",
  "bowling_team": "Chennai Super Kings",
  "striker": "F du Plessis",
  "non_striker": "V Kohli",
  "bowler": "DL Chahar",
  "ball_length": "good length",
  "ball_line": "outside off",
  "shot_played": "drive",
  "shot_direction": "cover",
  "runs_off_bat": 4,
  "extras": 0,
  "wides": "",
  "noballs": "",
  "byes": "",
  "legbyes": "",
  "wicket": 0,
  "wicket_type": "",
  "player_dismissed": "",
  "runs_so_far": 6,
  "wickets_so_far": 0,
  "is_last_ball_of_over": true,
  "over_number_completed": 0,
  "score_at_end_of_over": "6 for 0"
}

Expected output: "DL Chahar to F du Plessis. good length outside off. FOUR through cover! F du Plessis finds the boundary. After 1 over, Royal Challengers Bengaluru are 6 for 0."

---

Training Data

• Source: dataset/commentary_dataset.csv
• Rows: ~12,600 (one per ball from 50 matches)
• Columns used: Event fields (as in schema above) and one commentary column (commentary or commentary_with_score_line).
• Preprocessing: Each row → input = prompt + JSON(event), target = commentary text. Rows with empty commentary are dropped. Train/val split (e.g. 98% / 2%).

Training (Fine-Tuning)

• Script: scripts/train_commentary_model.py
• Epochs: 3 (default)
• Batch size: 8 per device
• Learning rate: 5e-5
• Warmup: 10% of total steps
• Max input length: 512 tokens
• Max target length: 256 tokens
• Framework: Hugging Face Transformers (Seq2SeqTrainer, AutoModelForSeq2SeqLM, DataCollatorForSeq2Seq)

Optional: use a locally downloaded Flan-T5 when offline:

python scripts/download_flan_t5.py --output-dir models/flan-t5-base
python scripts/train_commentary_model.py --local-model models/flan-t5-base

Output (Prepared Model)

• Saved to: output/commentary_model/ (or --output-dir) — tokenizer and model weights.
• Push to Hub (optional): --push-to-hub --hub-model-id ashishgimekar/commentary-flan-t5

Inference

Load from Hub:

python scripts/generate_commentary.py --model ashishgimekar/commentary-flan-t5 --event-file sample_event.json

Or use a local checkpoint:

python scripts/generate_commentary.py --model output/commentary_model --event-file sample_event.json

Or in code: build the input string "Generate cricket commentary for this ball: " + json.dumps(event, sort_keys=True), tokenize, call model.generate(...), and decode. Your event-detection step should output one JSON object per ball; pass it to the model to get the commentary string.