A player's current team can quietly rewrite your historical baseball answers.
You add a profile lookup to your game corpus, join on the player, and hand the enriched text to your assistant. Now a current affiliation sits beside an old matchup, wearing the same air of authority. Nothing crashes. That's the annoying part.
Lab note 122: can we keep useful player context without turning today's roster into historical evidence? The catch comes first: season scopes game retrieval, while a player's team describes their current affiliation. Collecting them together doesn't make them contemporaneous.
Which date does the affiliation belong to?
The tempting join looks harmless:
historical game ─┐
├─ flattened passage → historical answer
current profile ┘
Safer:
historical game → game evidence
current profile → explicitly current profile evidence
matchDate locates a game on the calendar. scrapedAt records collection time. Neither establishes when a player joined or left a team.
That distinction matters before training enters the picture. A retrieval pipeline can supply historically unsupported evidence to a perfectly obedient model.
We'd keep these meanings separate:
| Source field | Meaning in the corpus | What it cannot establish |
|---|---|---|
Game season
|
Season context for the event | A profile's historical affiliation |
Player team
|
Explicitly current affiliation | Membership on the game date |
scrapedAt |
Collection provenance | When an affiliation became valid |
Game homeTeam / awayTeam
|
Participants in the matchup | Which players appeared |
There's another missing edge: the game fields don't establish a relationship between playerId and eventId. A shared team name can't supply that relationship for us.
Make the retrieval boundary part of the record
Our embedding unit is a game record or a player snapshot. We don't concatenate them.
The envelope below is our corpus schema, separate from the source fields. It retains identity, collection provenance, and a reference URL while giving retrieval an explicit scope.
This normalizer accepts only the expected record type and labels current affiliation before text reaches an embedding model.
import hashlib
import json
import os
import re
from pathlib import Path
import tiktoken
from apify_client import ApifyClient
def clean_fields(raw, names):
cleaned = {}
for name in names:
value = raw.get(name)
if isinstance(value, str):
value = re.sub(r"\s+", " ", value).strip()
if value is not None and value != "":
cleaned[name] = value
return cleaned
def normalize(raw, request):
if request["mode"] == "games":
if raw.get("recordType") != "mlb_game":
return None
facts = clean_fields(raw, (
"eventId", "homeTeam", "awayTeam", "matchDate",
"homeScore", "awayScore", "status",
))
required = ("eventId", "homeTeam", "awayTeam", "matchDate")
if any(name not in facts for name in required):
return None
season = request["season"]
if raw.get("season") is not None:
if str(raw["season"]) != season:
raise ValueError("Game season disagrees with request")
facts["season"] = season
scope = "historical_game"
entity_id = str(facts.pop("eventId"))
source = raw.get("eventUrl")
elif request["mode"] == "players":
if raw.get("recordType") != "mlb_player":
return None
facts = clean_fields(raw, ("playerId", "playerName", "team"))
if any(name not in facts for name in ("playerId", "playerName")):
return None
entity_id = str(facts.pop("playerId"))
if "team" in facts:
facts["current_affiliation"] = facts.pop("team")
scope = "player_snapshot"
season = None
source = raw.get("profileUrl")
else:
return None
collected = raw.get("scrapedAt")
return {
"scope": scope,
"entity_id": entity_id,
"season": season,
"facts": facts,
"text": "\n".join(
f"{name}: {value}" for name, value in facts.items()
),
"source_urls": [source] if source else [],
"collected_at": [collected] if collected else [],
}
The required game fields protect the unit of meaning: a matchup with a date. A fragment missing that context goes into the filtered count rather than becoming an ambiguous passage.
We also leave missing scores missing. A scheduled game with no published score must not turn into a scoreless result.
Collect the scopes without inventing a roster join
The acquisition step keeps request context attached during normalization. It also checks run status before treating the dataset as an accepted export.
Example acquisition inputs select a historical schedule and a separate player search:
run_input = {
"mode": "games",
"season": "2023",
"maxItems": 200,
}
player_input = {
"mode": "players",
"searchQuery": "Aaron Judge",
"maxItems": 10,
}
client = ApifyClient(os.environ["APIFY_TOKEN"])
documents = []
audit = {"accepted": 0, "filtered": 0}
for request in (run_input, player_input):
run = client.actor(
"vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup"
).call(run_input=request)
if run["status"] != "SUCCEEDED":
raise RuntimeError(f"Unaccepted run status: {run['status']}")
for raw in client.dataset(run["defaultDatasetId"]).iterate_items():
document = normalize(raw, request)
if document is None:
audit["filtered"] += 1
else:
documents.append(document)
audit["accepted"] += 1
This is a bounded export. maxItems limits returned records, so the request doesn't establish that the corpus covers the entire season.
The player search supplies profile evidence, not a list of participants in those games. We'd rather leave that relationship absent than let a convenient join manufacture it.
Deduplicate content, group evaluation by identity
Hashing the whole envelope would make a new collection timestamp look like new evidence. Instead, we hash identity and normalized facts, then merge provenance for identical content.
Different scores or statuses remain different versions. That matters for games collected while their state changes.
This cell writes separate JSONL files for each retrieval scope and evaluation split.
unique_documents = {}
for document in documents:
content = {
name: document[name]
for name in ("scope", "entity_id", "season", "facts")
}
fingerprint = hashlib.sha256(
json.dumps(
content, sort_keys=True, ensure_ascii=False
).encode("utf-8")
).hexdigest()
if fingerprint not in unique_documents:
unique_documents[fingerprint] = {
**document,
"source_urls": list(document["source_urls"]),
"collected_at": list(document["collected_at"]),
}
else:
existing = unique_documents[fingerprint]
for field in ("source_urls", "collected_at"):
existing[field] = sorted(
set(existing[field]) | set(document[field])
)
corpus = list(unique_documents.values())
for document in corpus:
group = f"{document['scope']}:{document['entity_id']}"
document["split_group"] = group
bucket = hashlib.sha256(group.encode("utf-8")).digest()[0]
document["split"] = "test" if bucket % 5 == 0 else "train"
for scope in ("historical_game", "player_snapshot"):
for split in ("train", "test"):
destination = Path(f"{scope}.{split}.jsonl")
with destination.open("w", encoding="utf-8") as handle:
for document in corpus:
if document["scope"] == scope and document["split"] == split:
handle.write(
json.dumps(document, ensure_ascii=False) + "\n"
)
Grouping by event keeps revisions of the same game together. Grouping by player keeps repeated snapshots together.
This is an identity holdout, not a forecasting evaluation. For questions about predicting future outcomes, use a chronological boundary and audit related entities across it. Randomly separating events can't prevent later knowledge from appearing in training material.
Exact normalized deduplication also won't catch aliases or paraphrases. Team renaming needs an explicit mapping with temporal validity, not aggressive string cleanup.
Can changing today's team change historical context?
The historical context builder filters by scope before spending tokens. It also rejects conflicting versions of an event rather than letting retrieval choose a score by accident.
Each accepted game stays intact. If it exceeds the remaining budget, the builder skips it instead of slicing away its date or matchup.
encoding = tiktoken.get_encoding("cl100k_base")
def historical_context(records, season, token_budget):
by_event = {}
for document in records:
if (
document["scope"] == "historical_game"
and document["season"] == season
):
by_event.setdefault(document["entity_id"], set()).add(
document["text"]
)
if any(len(versions) != 1 for versions in by_event.values()):
raise ValueError("Resolve conflicting game versions first")
chunks = []
for event_id in sorted(by_event):
passage = next(iter(by_event[event_id]))
candidate = "\n\n".join(chunks + [passage])
if len(encoding.encode(candidate)) <= token_budget:
chunks.append(passage)
return "\n\n".join(chunks)
Use the tokenizer that matches your deployed model when adapting the budget. The retrieval boundary matters independently of tokenization.
Example synthetic fixtures below change only the player's current affiliation; the assertions check that historical context remains populated and unchanged.
fixture_game = {
"recordType": "mlb_game",
"eventId": "Example-event",
"homeTeam": "Example Home Club",
"awayTeam": "Example Away Club",
"matchDate": "2023-07-01",
"scrapedAt": "2026-10-01T12:00:00Z",
}
fixture_player = {
"recordType": "mlb_player",
"playerId": "Example-player",
"playerName": "Example Player",
"team": "Example Current Club A",
"scrapedAt": "2026-10-01T12:00:00Z",
}
fixture_before = [
normalize(fixture_game, run_input),
normalize(fixture_player, player_input),
]
fixture_after = [
normalize(fixture_game, run_input),
normalize(
dict(fixture_player, team="Example Current Club B"),
player_input,
),
]
context_before = historical_context(
fixture_before, season=run_input["season"], token_budget=2000
)
context_after = historical_context(
fixture_after, season=run_input["season"], token_budget=2000
)
assert context_before
assert context_before == context_after
assert "current_affiliation" not in context_after
These are counterfactual fixtures, not claims about live records. They exercise the failure we care about: changing unrelated present-day evidence must not alter the historical passage.
What this corpus still can't answer
For the worked source, MLB Teams, Player Search & Season Schedule Lookup supplies useful game and profile records. It doesn't supply the historical player-team relationship needed for roster claims.
Adding season to a player request won't fix that. That input applies only to game retrieval.
Keeping an unrestricted biography in the historical text would reopen the same hole through prose. Our allowlist therefore excludes description, along with birth dates, physical measurements, nationality, and image URLs. Player names and identifiers remain personal data; public availability isn't anonymization.
Reference URLs stay in metadata for traceability. If your distribution policy requires removing identifiers, transform names and IDs consistently and review URLs too. Removing just the obvious name field leaves plenty of breadcrumbs.
The plain verdict: current profiles are useful snapshots, but they're insufficient evidence for historical membership. A historical roster answer needs a source that establishes that relationship for the relevant date or season.
Reproduce the separation
- Install
apify-clientandtiktoken, then setAPIFY_TOKENin your environment. - Execute the Python cells in order. Inspect
auditbefore accepting the JSONL files. - Resolve conflicting game versions before retrieval, and keep split groups intact during indexing.
- Route historical questions exclusively through the game scope. Empty context should produce an evidence gap, not a fallback to current profiles.
Example exact input for the historical game request:
{
"mode": "games",
"season": "2023",
"maxItems": 200
}
Drafted with AI assistance and reviewed for accuracy.
Top comments (0)