Added crash detection feature and full 2014-2026 prerace dataset

agents/compare_agent.py

@@ -0,0 +1,86 @@
+"""
+KRONECTOR - Compare Agent
+
+Uses Groq's Llama3 to analyze the mathematical SHAP Delta between two drivers
+and synthesize a "Tale of the Tape" style narrative.
+"""
+
+import os
+from groq import Groq
+
+def compare_agent(
+    driver1_name: str,
+    driver1_prob: float,
+    driver1_status: str,
+    driver2_name: str,
+    driver2_prob: float,
+    driver2_status: str,
+    shap_deltas: dict[str, float],
+    race_context: str
+) -> str:
+    """Uses Llama3 to write a head-to-head comparison."""
+    
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        raise RuntimeError("GROQ_API_KEY environment variable is required.")
+        
+    client = Groq(api_key=api_key)
+    
+    # Sort deltas to find biggest advantages for driver 1 (positive) and driver 2 (negative)
+    sorted_deltas = sorted(shap_deltas.items(), key=lambda item: item[1], reverse=True)
+    d1_advantages = [f"{k}: +{v:.2f}" for k, v in sorted_deltas[:3] if v > 0]
+    d2_advantages = [f"{k}: +{abs(v):.2f}" for k, v in reversed(sorted_deltas) if v < 0][:3]
+    
+    system_prompt = f"""
+You are KRONECTOR, an elite Formula 1 Race Strategy AI.
+You have been asked to compare two drivers head-to-head for an upcoming race.
+You have a Machine Learning model that calculates 'SHAP Deltas' — exactly where one driver gains or loses mathematical advantage over the other.
+
+YOUR JOB:
+Write a "Tale of the Tape" style boxing-match breakdown (1-2 paragraphs max).
+Explain who is the overall favorite based on Win Probability, but highlight the specific areas where the underdog might have an edge.
+Make it sound like an expert F1 engineer breaking down a matchup.
+
+IMPORTANT CONCEPTS:
+- 'grid_position' or 'pole_conversion_rate' means track position/qualifying pace.
+- 'career_race_starts' means veteran experience vs rookie volatility.
+- 'driver_form_last3' means recent momentum.
+- 'sector_1_time', etc. means raw track speed.
+- CRASH DETECTION: You are provided with the 'Qualifying Status' for both drivers. If a driver's status indicates an Accident, Collision, or Crash, you MUST dramatically mention it as a major disadvantage or factor! (Note: a driver can still have a good grid position if they crashed in Q3. If so, highlight this loophole!)
+"""
+
+    user_prompt = f"""
+RACE CONTEXT: {race_context}
+
+MATCHUP:
+{driver1_name} (Win Probability: {driver1_prob:.1f}%) | Quali Status: {driver1_status}
+vs
+{driver2_name} (Win Probability: {driver2_prob:.1f}%) | Quali Status: {driver2_status}
+
+MATHEMATICAL ADVANTAGES (SHAP Deltas):
+Biggest edges for {driver1_name}:
+{', '.join(d1_advantages) if d1_advantages else "None"}
+
+Biggest edges for {driver2_name}:
+{', '.join(d2_advantages) if d2_advantages else "None"}
+
+Write the Head-to-Head analysis:
+"""
+
+    chat_completion = client.chat.completions.create(
+        messages=[
+            {
+                "role": "system",
+                "content": system_prompt.strip(),
+            },
+            {
+                "role": "user",
+                "content": user_prompt.strip(),
+            }
+        ],
+        model="llama-3.3-70b-versatile",
+        temperature=0.7,
+        max_tokens=500,
+    )
+    
+    return chat_completion.choices[0].message.content

agents/critique_agent.py

@@ -17,16 +17,26 @@ def critique_agent(prediction: PredictionOutput) -> CritiqueOutput:
     """Critiques the prediction mathematically to safeguard the LLM."""
     prob = prediction["probability"]
     shap_values = prediction["shap_values"]
+    is_prerace = prediction.get("is_prerace", False)
     
     approved = True
     confidence_rating = "Normal"
     critique_notes = ""
     
     # 1. Evaluate Probability Thresholds
-    if prob < 0.20:
+    # Pre-race predictions use a lower threshold (5% = true random chance in a 22-car field)
+    # because features like tires/weather are missing and probabilities are naturally spread thin.
+    # Post-race/historical queries use the stricter 20% threshold.
+    reject_threshold = 0.05 if is_prerace else 0.20
+    
+    if prob < reject_threshold:
         approved = False
         confidence_rating = "Low"
-        critique_notes += f"REJECTED: Win probability is {prob:.1%}, which is below the 20% threshold. The model is guessing. Do not make a definitive prediction.\n\n"
+        context = "pre-race estimate" if is_prerace else "historical query"
+        critique_notes += f"REJECTED: Win probability is {prob:.1%}, below the {reject_threshold:.0%} threshold for a {context}. The model is not confident.\n\n"
+    elif is_prerace and prob < 0.20:
+        confidence_rating = "PreRace"
+        critique_notes += f"PRE-RACE ESTIMATE: Win probability is {prob:.1%}. This is a pre-race prediction using qualifying data only — tires, weather, and race pace data are unavailable. Rankings are meaningful but absolute probabilities are lower than post-race queries.\n\n"
     elif prob > 0.95:
         confidence_rating = "Overconfident"
         critique_notes += f"FLAGGED: Win probability is unusually high ({prob:.1%}). In modern F1, >95% confidence may indicate data leakage or a hyper-dominant driver in the dataset. Proceed with caution.\n\n"

agents/data_agent.py

@@ -159,7 +159,7 @@ def _load_feature_data(data_path: str | Path) -> pd.DataFrame:
     return pd.read_parquet(path)
 
 
-def _filter_by_intent(df: pd.DataFrame, intent: QueryIntent) -> pd.DataFrame:
+def _filter_by_intent(df: pd.DataFrame, intent: QueryIntent, filter_driver: bool = True) -> pd.DataFrame:
     rows = df[df["season"] == intent["season"]].copy()
     
     round_num = intent.get("round")
@@ -188,6 +188,9 @@ def _filter_by_intent(df: pd.DataFrame, intent: QueryIntent) -> pd.DataFrame:
             f"No rows found for season={intent['season']} round={round_num} grand_prix={grand_prix}"
         )
 
+    if not filter_driver:
+        return rows.reset_index(drop=True)
+
     driver_id = _normalize_driver_id(intent.get("driver_id"))
     driver_name = intent.get("driver_name")
 

agents/synthesis_agent.py

@@ -18,12 +18,16 @@ class SynthesisOutput(TypedDict):
 def synthesis_agent(
     query: str, 
     prediction: PredictionOutput, 
-    critique: CritiqueOutput
+    critique: CritiqueOutput,
+    top_contenders: str = ""
 ) -> SynthesisOutput:
     """Uses Llama3 to write the final explanation for the user."""
     
-    # If the mathematical critique rejected the prediction, bypass the LLM
-    if not critique["approved"]:
+    is_prerace = prediction.get("is_prerace", False)
+    
+    # If mathematically rejected AND it's not a pre-race query → hard reject
+    # For pre-race, always call the LLM because the ranking is still meaningful
+    if not critique["approved"] and not is_prerace:
         return {
             "final_response": (
                 "I apologize, but my underlying machine learning model is not confident enough "
@@ -48,20 +52,41 @@ YOUR JOB:
 Synthesize this mathematical data into a clear, confident, and professional answer for the user.
 Speak like an F1 Race Engineer on the pit wall.
 Do NOT hallucinate reasons. Only use the features provided in the Critique Notes.
-Explain what the features mean in a natural way (e.g. if 'grid_position' has a positive impact, say starting on pole is a massive advantage here).
+Explain what the features mean in a natural way. 
+Specifically:
+- If 'grid_position' or 'pole_conversion_rate' has a strong impact, explain that qualifying position is historically crucial at this specific circuit. Note that our model uses a smoothed historical average, so even newer tracks are grounded in global F1 reality.
+- If 'career_race_starts' or 'driver_form_last3' heavily impact a prediction, explain the "experience factor". The model heavily trusts the recent form of proven veterans (100+ starts) but correctly discounts the form of rookies who have a very small sample size of races.
+- IMPORTANT: If the user asks about new engine components, fresh power units, or new car parts/upgrades, you MUST acknowledge that our predictive model operates purely on historical telemetry and lap data, and DOES NOT have access to internal team data regarding unannounced parts upgrades or new engines. 
+- You have been provided the top contenders for this race. If the predicted driver is NOT one of the top favorites, you MUST mention the actual favorites to provide accurate context (e.g., "While Antonelli has a 5% chance, keep in mind Verstappen and Hamilton are the heavy favorites").
+- CRASH DETECTION: You will be provided the driver's 'Qualifying Status'. If it says something like 'Accident', 'Collision', 'Spun off', or anything indicating a crash, you MUST dramatically mention that they crashed in qualifying. Note that a driver can still have a good grid position (e.g. they set a fast lap in Q3 and THEN crashed, which is a known loophole). If they crashed but have a good grid position, explicitly point out this loophole!
+
+IMPORTANT — If Confidence Rating is "PreRace":
+This is a PRE-RACE prediction using only qualifying data. Tire strategy, weather, and pit-stop data are not yet available.
+The model's absolute probabilities are compressed across 22 drivers, so the RANKING matters more than the exact number.
+Frame your response as a pre-race assessment, not a definitive prediction. Mention the key qualifying factors (sector times, grid position, driver form).
 
 Keep it concise (1-2 paragraphs).
 """
 
+    # For pre-race rejected predictions (below 5% threshold), explain it's a long-shot
+    prerace_note = ""
+    if not critique["approved"] and is_prerace:
+        prerace_note = f"\nNOTE: This driver's win probability ({prediction['probability']:.1%}) is very low — they are considered a long-shot for this race based on qualifying data."
+
     user_prompt = f"""
 USER QUERY:
 "{query}"
 
 PREDICTED DRIVER: {prediction.get('driver_name', 'Unknown Driver')}
+Qualifying Status: {prediction.get('quali_status', 'Finished')}
 
 ML PREDICTION:
 Win Probability: {prediction['probability']:.1%}
 Confidence Rating: {critique['confidence_rating']}
+{prerace_note}
+
+OVERALL RACE FAVORITES:
+{top_contenders if top_contenders else "Unknown"}
 
 CRITIQUE AGENT NOTES (SHAP ANALYSIS):
 {critique['critique_notes']}

api/main.py

@@ -26,6 +26,9 @@ from fastapi import FastAPI, HTTPException, Query
 from fastapi.middleware.cors import CORSMiddleware
 
 from agents.data_agent import data_agent, QueryIntent
+from agents.critique_agent import critique_agent
+from agents.synthesis_agent import synthesis_agent
+from agents.compare_agent import compare_agent
 from api.schemas import (
     DriverInfo,
     ErrorResponse,
@@ -34,6 +37,8 @@ from api.schemas import (
     PredictionRequest,
     PredictionResponse,
     RaceInfo,
+    CompareRequest,
+    CompareResponse
 )
 from ml.predict import load_model_and_encoders, predict_dataframe
 
@@ -49,6 +54,7 @@ _model = None
 _encoders = None
 _races_data: pd.DataFrame | None = None
 _drivers_set: set[str] = set()
+_prerace_data: dict[str, pd.DataFrame] = {}  # keyed by "season_round" e.g. "2026_7"
 
 
 def patch_mlruns_paths():
@@ -139,6 +145,22 @@ async def lifespan(app: FastAPI):
         else:
             logger.warning(f"Data not found: {data_path}")
 
+        # Load any pre-race parquet files from data_output/prerace/
+        prerace_dir = Path("data_output/prerace")
+        if prerace_dir.exists():
+            for pf in prerace_dir.glob("*.parquet"):
+                try:
+                    prerace_df = pd.read_parquet(pf)
+                    if not prerace_df.empty:
+                        season = int(prerace_df["season"].iloc[0])
+                        round_num = int(prerace_df["round"].iloc[0])
+                        key = f"{season}_{round_num}"
+                        _prerace_data[key] = prerace_df
+                        circuit = prerace_df["circuit_id"].iloc[0]
+                        logger.info(f"✓ Pre-race data loaded: {key} ({circuit}) — {len(prerace_df)} drivers")
+                except Exception as e:
+                    logger.warning(f"Could not load pre-race file {pf}: {e}")
+
     except Exception as e:
         logger.error(f"Startup error: {e}")
 
@@ -215,28 +237,78 @@ async def predict_f1(request: PredictionRequest) -> PredictionResponse:
             detail="Model not loaded. Set KRONECTOR_MODEL_RUN_ID.",
         )
 
-    if _races_data is None:
+    if _races_data is None and not _prerace_data:
         raise HTTPException(
             status_code=503,
             detail="Race data not loaded. Check data_output/fastf1_races.parquet",
         )
 
     try:
-        # Parse query → intent
-        result = data_agent(request.query)
-        intent = result["intent"]
-        df = result["dataframe"]
+        # Parse query → intent using the main historical parquet
+        # If the round isn't in the main parquet, fall back to pre-race data
+        from agents.data_agent import parse_query_with_groq, _filter_by_intent
+        intent = parse_query_with_groq(request.query)
+
+        df = pd.DataFrame()
+        is_prerace = False
 
-        if len(df) == 0:
+        # 1. Try the main historical parquet first
+        if _races_data is not None:
+            try:
+                df = _filter_by_intent(_races_data, intent, filter_driver=False)
+            except (ValueError, KeyError):
+                df = pd.DataFrame()
+
+        # 2. If not found in historical data, try pre-race data
+        if df.empty and _prerace_data:
+            logger.info(f"Round not in historical data — searching pre-race store for intent: {intent}")
+            for key, prerace_df in _prerace_data.items():
+                try:
+                    df = _filter_by_intent(prerace_df, intent, filter_driver=False)
+                    if not df.empty:
+                        is_prerace = True
+                        logger.info(f"✓ Found match in pre-race data: {key}")
+                        break
+                except (ValueError, KeyError):
+                    continue
+
+        if df.empty:
             raise HTTPException(
                 status_code=400,
-                detail=f"No matching data for query. "
-                f"Season {intent['season']}, round {intent['round']}",
+                detail=(
+                    f"No matching data for query. Season={intent.get('season')}, "
+                    f"GP='{intent.get('grand_prix')}'. "
+                    "If this is an upcoming race, run: "
+                    "python -m scripts.build_prerace_rows --season <year> --round <num>"
+                ),
             )
 
         # Generate predictions
         predictions = predict_dataframe(df, _model, _encoders, explain=True)
         
+        # Get top 3 contenders for context before filtering
+        top_df = predictions.sort_values(by="win_probability", ascending=False).head(3)
+        top_contenders = ", ".join(
+            [f"{r['driver_name']} ({r['win_probability']*100:.1f}%)" for _, r in top_df.iterrows()]
+        )
+        
+        # Now filter down to the requested driver if specified
+        driver_id = intent.get("driver_id")
+        driver_name = intent.get("driver_name")
+        
+        import re
+        if driver_id:
+            d_id = str(driver_id).strip().upper()
+            predictions = predictions[predictions["driver_id"].astype(str).str.upper() == d_id]
+        elif driver_name:
+            d_name = str(driver_name).strip().lower()
+            predictions = predictions[
+                predictions["driver_name"].astype(str).str.lower().str.contains(re.escape(d_name), na=False)
+            ]
+            
+        if predictions.empty:
+            raise HTTPException(status_code=400, detail=f"No predictions matched driver intent: {intent}")
+        
         # If the user asked "Who will win?" and matched multiple drivers,
         # sort by probability to find the most likely winner!
         if len(predictions) > 1:
@@ -244,6 +316,14 @@ async def predict_f1(request: PredictionRequest) -> PredictionResponse:
             
         pred_row = predictions.iloc[0]
         
+        # grid_position is stripped from metadata by predict_dataframe — look it up
+        # directly from the source df using the matched driver_id.
+        matched_driver_id = str(pred_row["driver_id"])
+        grid_pos_series = df.loc[
+            df["driver_id"].astype(str) == matched_driver_id, "grid_position"
+        ]
+        grid_pos = float(grid_pos_series.iloc[0]) if not grid_pos_series.empty else 0.0
+
         # 1. Format raw prediction output
         raw_prob = float(pred_row["win_probability"])
         shap_values = pred_row.get("shap_values", {})
@@ -254,24 +334,26 @@ async def predict_f1(request: PredictionRequest) -> PredictionResponse:
             "feature_names": list(shap_values.keys()) if shap_values else [],
             "model_version": "latest",
             "run_id": "api",
-            "driver_name": str(pred_row["driver_name"])
+            "driver_name": str(pred_row["driver_name"]),
+            "is_prerace": is_prerace,
+            "quali_status": "Crash" if getattr(request, "crashed_in_quali", False) else str(pred_row.get("quali_status", "Finished")),
         }
         
         # 2. Mathematical Critique
         critique = critique_agent(prediction_output)
         
         # 3. LLM Synthesis
-        synthesis = synthesis_agent(request.query, prediction_output, critique)
+        synthesis = synthesis_agent(request.query, prediction_output, critique, top_contenders=top_contenders)
 
         return PredictionResponse(
-            win_probability=raw_prob,
+            win_probability=round(raw_prob * 100, 2),
             metadata=PredictionMetadata(
                 season=int(pred_row["season"]),
                 round=int(pred_row["round"]),
                 driver_id=str(pred_row["driver_id"]),
                 driver_name=str(pred_row["driver_name"]),
                 team=str(pred_row["team"]),
-                grid_position=float(pred_row.get("grid_position", 0.0)),  # Default if missing
+                grid_position=grid_pos,
             ),
             shap_values=shap_values,
             llm_explanation=synthesis["final_response"],
@@ -289,6 +371,151 @@ async def predict_f1(request: PredictionRequest) -> PredictionResponse:
         ) from e
 
 
+@app.post(
+    "/predict/compare",
+    response_model=CompareResponse,
+    description="Compare two drivers head-to-head using mathematical SHAP Deltas",
+    tags=["Prediction"]
+)
+def compare_drivers(request: CompareRequest):
+    """Head-to-head driver matchup endpoint."""
+    if _model is None or _encoders is None:
+        raise HTTPException(
+            status_code=503, detail="Model not loaded. Set KRONECTOR_MODEL_RUN_ID."
+        )
+
+    try:
+        import re
+        import json
+        is_prerace = False
+        df = pd.DataFrame()
+        race_name = "Unknown Race"
+
+        # 1. Season and round specified?
+        if request.season and request.round:
+            prerace_file = Path(f"data_output/prerace/prerace_*_{request.season}.parquet")
+            import glob
+            files = glob.glob(str(prerace_file))
+            
+            found = False
+            for f in files:
+                pdf = pd.read_parquet(f)
+                if not pdf.empty and int(pdf["season"].iloc[0]) == request.season and int(pdf["round"].iloc[0]) == request.round:
+                    df = pdf
+                    is_prerace = True
+                    race_name = f"{request.season} Round {request.round}"
+                    found = True
+                    break
+            
+            if not found:
+                global _races_data
+                if _races_data is not None and not _races_data.empty:
+                    df = _races_data[
+                        (_races_data["season"] == request.season) & 
+                        (_races_data["round"] == request.round)
+                    ]
+                    race_name = f"{request.season} Round {request.round}"
+        
+        # 2. No season/round specified, use latest
+        if df.empty:
+            prerace_dir = Path("data_output/prerace")
+            if prerace_dir.exists():
+                files = list(prerace_dir.glob("*.parquet"))
+                if files:
+                    df = pd.read_parquet(files[0])
+                    is_prerace = True
+                    s = int(df["season"].iloc[0])
+                    r = int(df["round"].iloc[0])
+                    race_name = f"{s} Round {r}"
+            
+            if df.empty and _races_data is not None and not _races_data.empty:
+                latest_season = _races_data["season"].max()
+                latest_round = _races_data[_races_data["season"] == latest_season]["round"].max()
+                df = _races_data[
+                    (_races_data["season"] == latest_season) & 
+                    (_races_data["round"] == latest_round)
+                ]
+                race_name = f"{latest_season} Round {latest_round}"
+
+        if df.empty:
+            raise HTTPException(status_code=400, detail="Could not find race data for comparison.")
+
+        predictions = predict_dataframe(df, _model, _encoders, explain=True)
+
+        d1_str = request.driver1.strip().lower()
+        d1_df = predictions[
+            (predictions["driver_id"].str.lower() == d1_str) | 
+            (predictions["driver_name"].str.lower().str.contains(re.escape(d1_str), na=False))
+        ]
+        if d1_df.empty:
+            raise HTTPException(status_code=400, detail=f"Driver '{request.driver1}' not found in race {race_name}.")
+        d1_row = d1_df.iloc[0]
+
+        d2_str = request.driver2.strip().lower()
+        d2_df = predictions[
+            (predictions["driver_id"].str.lower() == d2_str) | 
+            (predictions["driver_name"].str.lower().str.contains(re.escape(d2_str), na=False))
+        ]
+        if d2_df.empty:
+            raise HTTPException(status_code=400, detail=f"Driver '{request.driver2}' not found in race {race_name}.")
+        d2_row = d2_df.iloc[0]
+
+        d1_prob = float(d1_row["win_probability"]) * 100
+        d2_prob = float(d2_row["win_probability"]) * 100
+
+        d1_shap = d1_row["shap_values"]
+        d2_shap = d2_row["shap_values"]
+        if isinstance(d1_shap, str):
+            d1_shap = json.loads(d1_shap)
+        if isinstance(d2_shap, str):
+            d2_shap = json.loads(d2_shap)
+        
+        deltas = {}
+        for feature in d1_shap.keys():
+            if feature in d2_shap:
+                deltas[feature] = d1_shap[feature] - d2_shap[feature]
+
+        llm_analysis = compare_agent(
+            driver1_name=str(d1_row["driver_name"]),
+            driver1_prob=d1_prob,
+            driver1_status=str(d1_row.get("quali_status", "Finished")),
+            driver2_name=str(d2_row["driver_name"]),
+            driver2_prob=d2_prob,
+            driver2_status=str(d2_row.get("quali_status", "Finished")),
+            shap_deltas=deltas,
+            race_context=f"{race_name} {'(Pre-Race)' if is_prerace else '(Historical)'}"
+        )
+
+        return CompareResponse(
+            driver1=PredictionMetadata(
+                season=int(d1_row["season"]),
+                round=int(d1_row["round"]),
+                driver_id=str(d1_row["driver_id"]),
+                driver_name=str(d1_row["driver_name"]),
+                team=str(d1_row["team"]),
+                grid_position=float(d1_row.get("grid_position", 0.0)),
+            ),
+            driver2=PredictionMetadata(
+                season=int(d2_row["season"]),
+                round=int(d2_row["round"]),
+                driver_id=str(d2_row["driver_id"]),
+                driver_name=str(d2_row["driver_name"]),
+                team=str(d2_row["team"]),
+                grid_position=float(d2_row.get("grid_position", 0.0)),
+            ),
+            driver1_win_probability=round(d1_prob, 2),
+            driver2_win_probability=round(d2_prob, 2),
+            shap_deltas=deltas,
+            llm_analysis=llm_analysis
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Compare prediction error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Comparison failed: {e}")
+
+
 @app.get("/drivers", response_model=list[DriverInfo])
 async def list_drivers(
     season: Optional[int] = Query(None, description="Filter by season"),

api/schemas.py

@@ -16,6 +16,9 @@ class PredictionRequest(BaseModel):
         max_length=500,
         examples=["What's Max's win probability at Monaco 2023?"],
     )
+    crashed_in_quali: bool = Field(
+        False, description="Manually flag if the driver crashed in qualifying"
+    )
 
 
 class PredictionMetadata(BaseModel):
@@ -33,7 +36,7 @@ class PredictionResponse(BaseModel):
     """Win probability prediction with SHAP explanations."""
 
     win_probability: float = Field(
-        ..., ge=0, le=1, description="Probability of winning (0.0-1.0)"
+        ..., ge=0, le=100, description="Win probability as a percentage (0-100)"
     )
     metadata: PredictionMetadata
     shap_values: Optional[dict[str, float]] = Field(
@@ -77,3 +80,34 @@ class ErrorResponse(BaseModel):
 
     detail: str
     error_code: str = Field(..., examples=["INVALID_QUERY", "MODEL_NOT_LOADED"])
+
+
+class CompareRequest(BaseModel):
+    """Request for Head-to-Head Driver Comparison."""
+
+    driver1: str = Field(
+        ...,
+        examples=["Max Verstappen", "VER"],
+        description="First driver to compare (name or 3-letter code)"
+    )
+    driver2: str = Field(
+        ...,
+        examples=["Kimi Antonelli", "ANT"],
+        description="Second driver to compare (name or 3-letter code)"
+    )
+    season: Optional[int] = Field(None, description="Optional year (defaults to latest available)")
+    round: Optional[int] = Field(None, description="Optional round number (defaults to latest available)")
+
+
+class CompareResponse(BaseModel):
+    """Head-to-Head Comparison Response."""
+
+    driver1: PredictionMetadata
+    driver2: PredictionMetadata
+    driver1_win_probability: float
+    driver2_win_probability: float
+    shap_deltas: dict[str, float] = Field(
+        ..., 
+        description="Mathematical difference between driver 1 and driver 2 SHAP values (positive means driver 1 has the edge, negative means driver 2 has the edge)"
+    )
+    llm_analysis: str = Field(..., description="Groq's Head-to-Head tale of the tape")

data/__init__.py

@@ -61,6 +61,85 @@ def _get_track_type(circuit_id: str) -> str:
     return "permanent"
 
 
+def compute_pole_conversion_rate(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute historical pole-to-win conversion rate per circuit.
+
+    For each circuit, calculates what % of races the pole-sitter went on to win.
+    This directly encodes "qualifying matters at this track" — e.g.:
+      - Monaco ~75-80% (almost impossible to overtake)
+      - Monza ~40-45% (long straights, slipstream, DRS)
+
+    Uses only COMPLETED races (requires finish_position data).
+
+    Args:
+        df: Historical race DataFrame with circuit_id, grid_position, finish_position
+
+    Returns:
+        DataFrame with columns (circuit_id, pole_conversion_rate)
+    """
+    if df.empty or "finish_position" not in df.columns:
+        return pd.DataFrame(columns=["circuit_id", "pole_conversion_rate"])
+
+    # Only use rows where we have actual race results
+    completed = df.dropna(subset=["finish_position"]).copy()
+
+    # Get pole-sitters (grid_position == 1) for each race
+    poles = completed[completed["grid_position"] == 1].copy()
+
+    if poles.empty:
+        return pd.DataFrame(columns=["circuit_id", "pole_conversion_rate"])
+
+    poles["pole_won"] = (poles["finish_position"] == 1).astype(int)
+
+    global_mean = poles["pole_won"].mean()
+    C = 3.0  # Confidence weight (pseudo-observations)
+
+    # Calculate wins and total poles per circuit
+    stats = poles.groupby("circuit_id").agg(
+        wins=("pole_won", "sum"),
+        total=("pole_won", "count")
+    ).reset_index()
+
+    # Apply Bayesian smoothing: pulls low-N circuits towards the global average
+    stats["pole_conversion_rate"] = (stats["wins"] + C * global_mean) / (stats["total"] + C)
+    
+    conversion = stats[["circuit_id", "pole_conversion_rate"]]
+
+    logger.info(
+        f"Computed pole_conversion_rate for {len(conversion)} circuits. "
+        f"Range: {conversion['pole_conversion_rate'].min():.1%} – "
+        f"{conversion['pole_conversion_rate'].max():.1%}"
+    )
+
+    return conversion
+
+    return conversion
+
+
+# ---------------------------------------------------------------------------
+# Career Race Starts computation
+# ---------------------------------------------------------------------------
+
+def compute_career_race_starts(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute cumulative career race starts for each driver before each race.
+    This provides an 'experience' feature so the model knows if driver form
+    is based on a veteran's long track record or a rookie's small sample size.
+    """
+    if df.empty or "driver_id" not in df.columns:
+        return pd.DataFrame(columns=["season", "round", "driver_id", "career_race_starts"])
+        
+    # Sort chronologically
+    df_sorted = df.sort_values(by=["driver_id", "season", "round"]).copy()
+    
+    # cumcount() gives 0 for the 1st race, 1 for the 2nd, etc.
+    # This exactly represents 'starts prior to this race'
+    df_sorted["career_race_starts"] = df_sorted.groupby("driver_id").cumcount()
+    
+    return df_sorted[["season", "round", "driver_id", "career_race_starts"]]
+
+
 # ---------------------------------------------------------------------------
 # Safety car probability computation (Correction 2)
 # ---------------------------------------------------------------------------
@@ -298,6 +377,35 @@ def merge_datasets(
             "No lap data — safety_car_probability set to 0 for all rows"
         )
 
+    # -------------------------------------------------------------------
+    # Step 8.3: Compute career_race_starts per driver
+    # -------------------------------------------------------------------
+    starts_df = compute_career_race_starts(merged)
+    if not starts_df.empty:
+        if "career_race_starts" in merged.columns:
+            merged = merged.drop(columns=["career_race_starts"])
+        merged = merged.merge(starts_df, on=["season", "round", "driver_id"], how="left")
+        merged["career_race_starts"] = merged["career_race_starts"].fillna(0)
+        logger.info("Joined career_race_starts from cumulative history")
+    else:
+        merged["career_race_starts"] = 0
+        logger.warning("Could not compute career_race_starts — defaulting to 0")
+
+    # -------------------------------------------------------------------
+    # Step 8.5: Compute pole_conversion_rate per circuit
+    # -------------------------------------------------------------------
+    pcr = compute_pole_conversion_rate(merged)
+    if not pcr.empty:
+        if "pole_conversion_rate" in merged.columns:
+            merged = merged.drop(columns=["pole_conversion_rate"])
+        merged = merged.merge(pcr, on="circuit_id", how="left")
+        # Circuits with no data default to 50% (neutral)
+        merged["pole_conversion_rate"] = merged["pole_conversion_rate"].fillna(0.5)
+        logger.info("Joined pole_conversion_rate from historical data")
+    else:
+        merged["pole_conversion_rate"] = 0.5
+        logger.warning("Could not compute pole_conversion_rate — defaulting to 0.5")
+
     # -------------------------------------------------------------------
     # Step 9: Add target variable
     # -------------------------------------------------------------------

data/fastf1_pipeline.py

@@ -54,7 +54,9 @@ def enable_cache(cache_dir: Optional[str] = None) -> None:
 # ---------------------------------------------------------------------------
 
 def _load_session(
-    season: int, round_num: int, session_type: str
+    season: int, round_num: int, session_type: str,
+    laps: bool = True, telemetry: bool = False,
+    weather: bool = True, messages: bool = False,
 ) -> Optional[fastf1.core.Session]:
     """
     Load a FastF1 session with error handling.
@@ -63,13 +65,17 @@ def _load_session(
         season: F1 season year (2018–2026)
         round_num: Race round number within season
         session_type: One of 'R' (Race), 'Q' (Qualifying), 'FP2', 'FP3'
+        laps: Load lap timing data (default True)
+        telemetry: Load car telemetry (default False — not needed for features)
+        weather: Load weather data (default True)
+        messages: Load race control messages (default False)
 
     Returns:
         Loaded FastF1 Session object, or None if unavailable.
     """
     try:
         session = fastf1.get_session(season, round_num, session_type)
-        session.load()
+        session.load(laps=laps, telemetry=telemetry, weather=weather, messages=messages)
         return session
     except Exception as e:
         logger.warning(

data_output/fastf1_races.parquet

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:8d2fba650f3d5031cd6ac5bf9c3507f471ba4a4ddc59b297e978c0c4fdb045b6
-size 132567
+oid sha256:2849f1eec94e44f124f04f2df23970214fb004aa5ce64080ed5520b3ec666b88
+size 111244

data_output/prerace/prerace_70th_anniversary_gra_2020.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5cd269f7255addee293be9f2edb819a9aee26b922dc13445a7858386fc4797fc
+size 17243

data_output/prerace/prerace_abu_dhabi_grand_prix_2014.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b4edb066e72f51c97af2b827a0372b9537bab50931f1d1a41350203110f0427a
+size 16024

data_output/prerace/prerace_abu_dhabi_grand_prix_2015.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f968dac8035d2a6b98fdd2cb948a2919f67afb82c803e1e8fc00a652c1fdc7e
+size 16086

data_output/prerace/prerace_abu_dhabi_grand_prix_2016.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a5601f3056795c2ece6ef7df44574b6af73ff62585112a432387f4fc1de2695
+size 16184

data_output/prerace/prerace_abu_dhabi_grand_prix_2017.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:502d00fd14943e14cbf616fadb5bc1a425255eee7b4aa5e3bca31f2366ab4491
+size 16121

data_output/prerace/prerace_abu_dhabi_grand_prix_2018.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fee82cb6eb4323b71fec2694d9af9dbd6c83278230d8b46a17fc62e374424fc0
+size 17219

data_output/prerace/prerace_abu_dhabi_grand_prix_2019.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a4297d21fe4c3c53af0efa99d4629cb1712cb617f4d7f3fb9fe4b6a697a3b53
+size 17171

data_output/prerace/prerace_abu_dhabi_grand_prix_2020.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c8f2097399aeca4cc13c1196013b819ca82644a3de9060dd091558e04ad9b0fe
+size 17197

data_output/prerace/prerace_abu_dhabi_grand_prix_2021.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd73c940a2039393c25e4375c3a95d55a81a7337bb2dccd0c96112be8c54804f
+size 17224

data_output/prerace/prerace_abu_dhabi_grand_prix_2022.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b81b44cce7074d8280e7d3cdddf67178e86429d679b8481bb9052e625b95d8a
+size 17173

data_output/prerace/prerace_abu_dhabi_grand_prix_2023.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:808cbab2d0ebf3fd4cdbfc3dff58ed68f98f5ee804041664ca3f530ee40dc283
+size 17197

data_output/prerace/prerace_abu_dhabi_grand_prix_2024.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3385b06f5db6ac54b06d75f87f275865612a678c2a0e72c716031707ed5e6b81
+size 17170

data_output/prerace/prerace_abu_dhabi_grand_prix_2025.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1c6b778ca45dfdd67dfb532cd258910c1b97ee0f894de5484ffbd0854c6df252
+size 17116

data_output/prerace/prerace_australian_grand_pri_2014.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:375f0e17bc001fb25ca6d713b4d60dcb97e4ed836465a53f79fd000f70da8199
+size 15799

data_output/prerace/prerace_australian_grand_pri_2015.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5b5892ff5cdf24d49855631396fdc65c5ab89ff8ec0bc8e028dda87ad4041145
+size 16020

data_output/prerace/prerace_australian_grand_pri_2016.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:163b6ac086ec568316728d6bfa44616e66f8fdccc89022cda5d2790492f7d313
+size 16179

data_output/prerace/prerace_australian_grand_pri_2017.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3bff47910334b98b4785fa55cdcef4ea30936fa63f9c38e9e6ed14fcc05fe97
+size 16120

data_output/prerace/prerace_australian_grand_pri_2018.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b763f2c4b3e5db0d1e732df1598d0452f0ef723352a503fd2538ad35d94e8482
+size 17141

data_output/prerace/prerace_australian_grand_pri_2019.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:933f9ccd3555a89525d451e6988dd5f138fb5b5d908f4ed203a0bd04250e7a41
+size 17176

data_output/prerace/prerace_australian_grand_pri_2022.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb2e8fdeb0e7c937b02ba882d0e289f086010c5f40ada27b69df26b021160ab4
+size 17157

data_output/prerace/prerace_australian_grand_pri_2023.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7d7e04018dfe44b4c19881f2699a5e5aa0534de11b3a4e1a5ff0647447c23841
+size 17158

data_output/prerace/prerace_australian_grand_pri_2024.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:93a9ab6e87502fb12b4e0d74c8d8642f8d9364afb18c1cb1e1afd3153da552d2
+size 17098

data_output/prerace/prerace_australian_grand_pri_2025.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fe70b5ae3c1e4e3a4ae1a7183d3f05b01dcc9202595a1f998be88883ec7fe98e
+size 17084

data_output/prerace/prerace_australian_grand_pri_2026.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:89ab900ac7feea4a1eef01372034f778bb3093f3ac425e0c2897eff4cd07dfd4
+size 17193

data_output/prerace/prerace_austrian_grand_prix_2014.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2b89fd196fde105cdc5c7434932b847c4e72ff30ef1e816a1b87410b8a339b42
+size 16208

data_output/prerace/prerace_austrian_grand_prix_2015.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7c780f2f2d9dc96e289b12b829044bb1f4a0a1c9684aac51711ff9e38f8f60c8
+size 16090

data_output/prerace/prerace_austrian_grand_prix_2016.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d17a96cc7d923b4072d9aaadc452087acc00f040fe61cb4428b55c8fd75e7b36
+size 16198

data_output/prerace/prerace_austrian_grand_prix_2017.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e3671471e0cecbdb8d7d2a8d76f7367ad1fd766e44f91119ba1913f04d98d8dd
+size 16113

data_output/prerace/prerace_austrian_grand_prix_2018.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ec2fba62b991af17cbc38847515e3196dc62f9126c168bbae2a2c7a3eae1713
+size 17193

data_output/prerace/prerace_austrian_grand_prix_2019.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5275dcf00c1580e9c965a018db62d37c2d302505317756c56d6de7d34ad113c2
+size 17180

data_output/prerace/prerace_austrian_grand_prix_2020.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aed36837f04ba4f69a63f0fcdd1e7faa34e1810cc5202048f6dd3381cea1cfd1
+size 17186

data_output/prerace/prerace_austrian_grand_prix_2021.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d890d04b763101f954125f24f77b4650224d5a618b4244ae3689c47834ed1ed0
+size 17194

data_output/prerace/prerace_austrian_grand_prix_2022.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a276394021e03e59b10fcd03c0280df22b3b947d03ccebfd809f95e60f68968d
+size 17180

data_output/prerace/prerace_austrian_grand_prix_2023.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0235cc3b5754c9ad95c8bbc0b14005b463670f416ca85fa52905319c2498e9fb
+size 16910

data_output/prerace/prerace_austrian_grand_prix_2024.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:21ddd483cdd6160159986b984a80336aae7162cb4bed35812fe9dedc827ccbd1
+size 16906

data_output/prerace/prerace_austrian_grand_prix_2025.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b880dbc20428d8c62bf4f2742e8834e7196e73b3f0c677c478c0e8f84d58eca6
+size 17108

data_output/prerace/prerace_azerbaijan_grand_pri_2017.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3991df986866d3b237f2510da2537346ca7b75b86636d0886191aee461a5549b
+size 16079

data_output/prerace/prerace_azerbaijan_grand_pri_2018.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aea98ac4c994c98e4818e105bffdd81a798451ffd2db8bfc53f6dad5a61e215f
+size 17205

data_output/prerace/prerace_azerbaijan_grand_pri_2019.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fdb2c0d9ae8af4fe0afbe35e0fa00b4495d301cc8744cceb8c2b71298cfc2c83
+size 17210

data_output/prerace/prerace_azerbaijan_grand_pri_2021.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:63e61f2415e99646c7d9360479ff0456dcbff83d0efcd530ff74261dd466fd7a
+size 17246

data_output/prerace/prerace_azerbaijan_grand_pri_2022.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5529cc4110424f30674d2c4323a63c273e48b0140d128d1100493d135b4bb919
+size 17180