clarkkitchen22/MLB-2025-ChatML-Matchups

MLB 2025 ChatML Matchups

MLB 2025 ChatML Matchups is a compact instruction-tuning dataset built from the public MLB Stats API for the 2025 Major League Baseball regular season. It converts structured game, team offense, and team pitching information into ChatML-style rows that are ready for supervised fine-tuning, retrieval-augmented evaluation, sports analytics prototypes, or prompt engineering tests.

Each row is written from one team's perspective for one completed MLB regular-season game. A single game produces two examples: the away team's view and the home team's view. The assistant answer is a compact JSON payload containing the matchup facts needed to discuss the game without relying on hidden knowledge.

What This Dataset Is For

Use this dataset when you want a language model to learn how to read structured baseball context and produce grounded matchup analysis. It is especially useful for:

• —Training chat models to answer MLB matchup questions from supplied facts
• —Building sports analytics assistants that explain offense-versus-pitching context
• —Evaluating whether a model can preserve structured sports statistics in an answer
• —Prototyping retrieval flows where the retrieved record is converted into a concise analyst response
• —Creating baseball examples for ChatML ingestion pipelines

This is not a betting dataset, odds dataset, or projection model output. It contains official-style game and team statistics from MLB API endpoints, not market prices or gambling recommendations.

Dataset Summary

The schedule loader excludes postponed placeholders and deduplicates suspended or continued games that appear on multiple schedule dates by MLB gamePk.

Data Sources

The builder uses these MLB Stats API endpoints:

• —https://statsapi.mlb.com/api/v1/schedule
• —https://statsapi.mlb.com/api/v1/teams/stats
• —https://statsapi.mlb.com/api/v1/game/{gamePk}/boxscore

The included script uses a local disk cache, sequential requests, configurable request throttling, retry/backoff, and explicit handling for HTTP 429 responses.

Row Format

Each example contains a messages column formatted as a list of ChatML-style messages:

[
  {
    "role": "system",
    "content": "You are an MLB matchup analyst. Use only the supplied 2025 MLB Stats API facts and answer in compact JSON."
  },
  {
    "role": "user",
    "content": "Build a pitching and offense matchup brief for Los Angeles Dodgers vs Chicago Cubs on 2025-03-18."
  },
  {
    "role": "assistant",
    "content": "{\"game_date\":\"2025-03-18T10:10:00Z\", ... }"
  }
]

The assistant content is JSON. It contains the team, opponent, final score, game-level batting and pitching lines, and season-level hitting and pitching context for both clubs.

Columns

How To Use

Hugging Face Datasets

from datasets import load_dataset

ds = load_dataset("clarkkitchen22/MLB-2025-ChatML-Matchups", split="train")
example = ds[0]

messages = example["messages"]
print(messages[0]["role"], messages[0]["content"])

Pandas

import pandas as pd

df = pd.read_parquet(
    "hf://datasets/clarkkitchen22/MLB-2025-ChatML-Matchups/data/train-00000-of-00001.parquet"
)

print(df[["team_name", "opponent_name", "team_runs", "opponent_runs", "result"]].head())

Fine-Tuning

Most chat fine-tuning stacks can consume the messages column directly or after a small adapter. The dataset is designed for supervised fine-tuning where:

• —system defines the analyst behavior and grounding rule
• —user asks for a matchup brief
• —assistant returns a structured JSON answer

If your trainer expects plain text, serialize each row with your model's chat template before training.

Why This Format

Baseball data is highly structured, but baseball questions are usually conversational. This dataset bridges those two modes. The model sees natural user requests while the target response preserves exact facts in a predictable JSON structure. That makes it useful for teaching:

• —Grounded sports explanations
• —Matchup framing
• —Team offense versus team pitching context
• —Score-aware summaries
• —Structured-output discipline

The dataset intentionally keeps the assistant response compact. It is easier to inspect, easier to validate, and less likely to reward unsupported narrative claims.

Reproducibility

The repository includes:

• —scripts/build_dataset.py: source scraper and Parquet builder
• —scripts/verify_dataset.py: verifier for row counts, teams, unique row ids, ChatML roles, and pitching fields
• —mlb_2025_chatml_matchups.manifest.json: build manifest with row count, source, and scraper metrics

The local build was verified with:

python3 scripts/verify_dataset.py --parquet data/processed/mlb_2025_chatml_matchups.parquet

Verification result:

• —rows: 4,850
• —games: 2,425
• —teams: 30
• —rows_match_schedule_x2: true
• —unique_row_ids: true
• —all_games_present: true
• —all_30_teams_present: true
• —chatml_roles_valid: true
• —pitching_fields_present: true

Limitations

• —The dataset reflects the public MLB Stats API responses available at build time.
• —Team season stats are full-season 2025 totals, not pregame rolling statistics.
• —The assistant targets are structured JSON records, not prose scouting reports.
• —The dataset does not include player-level pitch-by-pitch events, betting odds, injuries, weather, umpire data, or park factors.
• —Commercial usage and redistribution should be evaluated against MLB's applicable data terms and policies.

Responsible Use

This dataset is intended for sports analytics, education, retrieval, and model-development workflows. Do not present model outputs trained on this data as official MLB commentary, real-time predictions, medical/injury guidance, or wagering advice.

Attribution

Data was collected from the public MLB Stats API. This dataset is not affiliated with, endorsed by, or sponsored by Major League Baseball or its clubs.