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

json

{
  "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:

json

{
  "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:

json

{
  "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:

bash

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.