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

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.