Personalize props model voice

analytics/model_voice.py

@@ -25,49 +25,110 @@ def _dedupe(items: list[str]) -> list[str]:
     return ordered
 
 
-def build_hr_model_voice(row: dict[str, Any]) -> dict[str, str]:
-    positives: list[str] = []
-    negatives: list[str] = []
-
-    if float(row.get("arsenal_hr_adjustment") or 0.0) >= 0.006:
-        positives.append("Crushes this arsenal mix")
-    if float(row.get("zone_hr_adjustment") or 0.0) >= 0.006:
-        positives.append("Gets a favorable zone-shape matchup")
-    if float(row.get("family_zone_hr_adjustment") or 0.0) >= 0.006:
-        positives.append("Family-zone profile boosts the matchup")
-    if float(row.get("weather_hr_adjustment") or 0.0) >= 0.004 or float(row.get("park_hr_adjustment") or 0.0) >= 0.004:
-        positives.append("Park or weather helps carry")
-    if float(row.get("rolling_hr_adjustment") or 0.0) >= 0.004:
-        positives.append("Recent form is trending up")
-    if float(row.get("opportunity_hr_adjustment") or 0.0) >= 0.003:
-        positives.append("Projected lineup slot supports extra opportunities")
-
-    if float(row.get("pitcher_hr_adjustment") or 0.0) <= -0.006:
-        negatives.append("Pitcher profile suppresses home-run damage")
-    if float(row.get("trajectory_hr_adjustment") or 0.0) <= -0.004:
-        negatives.append("Pitch shape and tunneling work against the hitter")
-    if float(row.get("platoon_hr_adjustment") or 0.0) <= -0.004:
-        negatives.append("Platoon split is not in his favor")
-    if float(row.get("rolling_hr_adjustment") or 0.0) <= -0.004:
-        negatives.append("Recent form has cooled")
-    if float(row.get("opportunity_hr_adjustment") or 0.0) <= -0.003:
-        negatives.append("Opportunity projection is light")
-
-    for reason in _listify(row.get("confidence_reasons"))[:2]:
-        negatives.append(reason)
-
-    positives = _dedupe(positives)
-    negatives = _dedupe(negatives)
+def _template_text(template_key: str, template_inputs: dict[str, Any] | None = None) -> str:
+    inputs = dict(template_inputs or {})
+    lineup_slot = inputs.get("lineup_slot_used")
+    lineup_slot_txt = f"No. {int(lineup_slot)} slot" if lineup_slot not in {None, "", "nan", "None"} else "projected slot"
+    venue = str(inputs.get("venue") or "").strip()
+
+    templates = {
+        "pitcher_attackable": "The opposing pitcher profile is giving up HR-friendly contact",
+        "pitcher_suppresses_hr": "The pitcher profile suppresses home-run damage",
+        "trend_up": "Recent batted-ball form is trending up",
+        "trend_down": "Recent batted-ball form has cooled",
+        "zone_favorable": "The zone matchup lines up with his damage areas",
+        "zone_tough": "This zone profile limits his best contact lanes",
+        "family_zone_favorable": "The family-zone matchup boosts his contact shape",
+        "family_zone_tough": "The family-zone matchup works against his usual damage path",
+        "arsenal_favorable": "The arsenal mix fits his power profile",
+        "arsenal_tough": "This pitch mix is a tougher fit for his power profile",
+        "platoon_advantage": "The handedness split helps the matchup",
+        "platoon_disadvantage": "Same-handed conditions trim the HR ceiling",
+        "pulled_contact_strength": "His pulled-air damage keeps the HR ceiling live",
+        "pulled_contact_light": "The pulled-air profile is lighter than ideal for this HR spot",
+        "weather_supportive": "Weather conditions add a little extra carry",
+        "weather_suppressive": "Weather conditions are holding down carry",
+        "park_supportive": f"{venue} plays friendlier for carry" if venue else "The park adds a small carry boost",
+        "park_suppressive": f"{venue} suppresses HR carry" if venue else "The park trims carry",
+        "trajectory_helpful": "Pitch shape is more hittable than usual here",
+        "trajectory_tough": "Pitch shape and tunneling make clean lift harder here",
+        "rolling_up": "Recent form is moving in the right direction",
+        "rolling_down": "Recent form has cooled",
+        "opportunity_strong": f"The {lineup_slot_txt} adds plate-appearance upside",
+        "opportunity_light": "The opportunity projection is lighter than usual",
+        "pitcher_unresolved": "The opposing pitcher is still unresolved",
+        "lineup_unknown": "The lineup slot is still unknown",
+        "lineup_projected": "The lineup slot is projected rather than confirmed",
+        "strikeout_whiff_profile": "The whiff profile supports the strikeout look",
+        "strikeout_price_close": "The price is keeping the strikeout edge tight",
+    }
+    return templates.get(template_key, template_key.replace("_", " ").capitalize())
+
+
+def build_hr_model_voice(row: dict[str, Any]) -> dict[str, Any]:
+    candidates = row.get("model_voice_reason_candidates") or []
+    supportive = [c for c in candidates if str(c.get("direction") or "").strip().lower() == "supportive"]
+    cautions = [c for c in candidates if str(c.get("direction") or "").strip().lower() == "caution"]
+
+    primary = supportive[0] if supportive else candidates[0] if candidates else None
+    caveat = None
+    if primary and str(primary.get("direction") or "").strip().lower() == "caution":
+        caveat = cautions[1] if len(cautions) > 1 else None
+    else:
+        caveat = cautions[0] if cautions else None
+
+    primary_reason = (
+        _template_text(str(primary.get("template_key") or ""), primary.get("template_inputs"))
+        if primary
+        else "His current power baseline is keeping the matchup in range"
+    )
+    caveat_reason = (
+        _template_text(str(caveat.get("template_key") or ""), caveat.get("template_inputs"))
+        if caveat
+        else ""
+    )
+
+    voice = primary_reason
+    if caveat_reason:
+        voice = f"{primary_reason}, but {caveat_reason[:1].lower()}{caveat_reason[1:] if len(caveat_reason) > 1 else ''}"
+
+    tags = _dedupe(
+        [
+            str(candidate.get("template_key") or "").strip()
+            for candidate in candidates
+            if str(candidate.get("template_key") or "").strip()
+        ]
+    )
+
     return {
-        "model_voice_for": " + ".join(positives[:2]) if positives else "Baseline power keeps the play in range",
-        "model_voice_against": " + ".join(negatives[:2]) if negatives else "Market price is the main pushback",
+        "model_voice": voice.rstrip(".") + ".",
+        "model_voice_primary_reason": primary_reason,
+        "model_voice_caveat": caveat_reason or None,
+        "model_voice_tags": tags,
+        "model_voice_for": primary_reason,
+        "model_voice_against": caveat_reason or None,
     }
 
 
-def build_strikeout_model_voice(result: dict[str, Any]) -> dict[str, str]:
+def build_strikeout_model_voice(result: dict[str, Any]) -> dict[str, Any]:
     positives = _dedupe(_listify(result.get("reason_tags_for")))
     negatives = _dedupe(_listify(result.get("reason_tags_against")) + _listify(result.get("confidence_reasons")))
+
+    primary_reason = positives[0] if positives else "The whiff profile supports the strikeout look"
+    caveat = negatives[0] if negatives else ""
+    voice = primary_reason
+    if caveat:
+        voice = f"{primary_reason}, but {caveat[:1].lower()}{caveat[1:] if len(caveat) > 1 else ''}"
+
+    tags = _dedupe(
+        ["strikeout_whiff_profile" if positives else "", "strikeout_price_close" if negatives else ""]
+    )
+
     return {
-        "model_voice_for": " + ".join(positives[:2]) if positives else "Whiff-oriented strikeout profile",
-        "model_voice_against": " + ".join(negatives[:2]) if negatives else "Price and volatility keep this close",
+        "model_voice": voice.rstrip(".") + ".",
+        "model_voice_primary_reason": primary_reason,
+        "model_voice_caveat": caveat or None,
+        "model_voice_tags": [tag for tag in tags if tag],
+        "model_voice_for": primary_reason,
+        "model_voice_against": caveat or None,
     }

analytics/props_view_model.py

@@ -288,6 +288,9 @@ def build_player_prop_detail_map(mapped_df: pd.DataFrame) -> dict[str, dict[str,
             "best_primary": best_primary,
             "best_primary_row": best_primary,
             "best_verdict": best_primary.get("verdict") if best_primary else None,
+            "model_voice": best_primary.get("model_voice") if best_primary else None,
+            "model_voice_primary_reason": best_primary.get("model_voice_primary_reason") if best_primary else None,
+            "model_voice_caveat": best_primary.get("model_voice_caveat") if best_primary else None,
             "model_voice_for": best_primary.get("model_voice_for") if best_primary else None,
             "model_voice_against": best_primary.get("model_voice_against") if best_primary else None,
             "primary_rows": primary_rows.to_dict("records"),
@@ -332,6 +335,9 @@ def build_game_player_props_map(mapped_df: pd.DataFrame) -> dict[str, dict[str,
                     "best_bet_ev": best_primary.get("bet_ev"),
                     "best_confidence_score": best_primary.get("confidence_score"),
                     "best_verdict": best_primary.get("verdict"),
+                    "model_voice": best_primary.get("model_voice"),
+                    "model_voice_primary_reason": best_primary.get("model_voice_primary_reason"),
+                    "model_voice_caveat": best_primary.get("model_voice_caveat"),
                     "model_voice_for": best_primary.get("model_voice_for"),
                     "model_voice_against": best_primary.get("model_voice_against"),
                     "details": detail,

database/db.py

@@ -808,6 +808,10 @@ def ensure_upcoming_hr_props_table(conn) -> None:
             model_hr_prob_source TEXT,
             edge                 DOUBLE PRECISION,
             verdict              TEXT,
+            model_voice          TEXT,
+            model_voice_primary_reason TEXT,
+            model_voice_caveat   TEXT,
+            model_voice_tags     TEXT,
             model_voice_for      TEXT,
             model_voice_against  TEXT
         )
@@ -832,6 +836,10 @@ def ensure_upcoming_hr_props_table(conn) -> None:
         ("confidence_bucket",    "TEXT"),
         ("opportunity_hr_adjustment", "DOUBLE PRECISION"),
         ("verdict",              "TEXT"),
+        ("model_voice",          "TEXT"),
+        ("model_voice_primary_reason", "TEXT"),
+        ("model_voice_caveat",   "TEXT"),
+        ("model_voice_tags",     "TEXT"),
         ("model_voice_for",      "TEXT"),
         ("model_voice_against",  "TEXT"),
     ]:
@@ -854,7 +862,7 @@ def insert_upcoming_hr_props(conn, df: pd.DataFrame) -> None:
         "odds_american", "line", "implied_prob", "raw_hr_prob",
         "calibrated_hr_prob", "model_hr_prob", "fair_prob", "bet_ev", "confidence_score",
         "confidence_bucket", "opportunity_hr_adjustment",
-        "model_hr_prob_source", "edge", "verdict", "model_voice_for", "model_voice_against",
+        "model_hr_prob_source", "edge", "verdict", "model_voice", "model_voice_primary_reason", "model_voice_caveat", "model_voice_tags", "model_voice_for", "model_voice_against",
     ]
     present = [c for c in log_cols if c in df.columns]
     _bulk_insert(conn, "upcoming_hr_props", df[present])

models/hr_probability_engine.py

@@ -94,6 +94,8 @@ def _empty_result(player_name: str, mode: str) -> dict[str, Any]:
         "trajectory_reliability": 0.0,
         "rolling_reliability": 0.0,
         "opportunity_reliability": 0.0,
+        "model_voice_reason_candidates": [],
+        "model_voice_tags": [],
     }
 
 
@@ -109,6 +111,30 @@ def _apply_reliability(raw_adjustment: float, reliability: float) -> float:
     return raw_adjustment * _clamp(reliability, 0.0, 1.0)
 
 
+def _append_reason_candidate(
+    reason_candidates: list[dict[str, Any]],
+    *,
+    category: str,
+    direction: str,
+    magnitude: float,
+    template_key: str,
+    template_inputs: dict[str, Any] | None = None,
+) -> None:
+    mag = abs(_safe_float(magnitude, 0.0))
+    if mag <= 1e-6:
+        return
+    reason_candidates.append(
+        {
+            "category": category,
+            "direction": direction,
+            "magnitude": mag,
+            "signed_magnitude": _safe_float(magnitude, 0.0),
+            "template_key": template_key,
+            "template_inputs": dict(template_inputs or {}),
+        }
+    )
+
+
 def _compute_environment_reliability(game_row: dict[str, Any], weather_row: dict[str, Any] | None) -> float:
     has_venue = bool(str(game_row.get("venue") or "").strip())
     weather_row = dict(weather_row or {})
@@ -346,6 +372,7 @@ def build_hr_probability_result(
 
     applied_layers: list[str] = []
     skipped_layers = result["skipped_layers"].split("|") if result["skipped_layers"] else []
+    reason_candidates: list[dict[str, Any]] = []
 
     pitcher_row = build_pitcher_feature_row(
         statcast_df=pitcher_df,
@@ -368,6 +395,14 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["pitcher_hr_adjustment"], 0.005, 0.25)
     if abs(result["pitcher_hr_adjustment"]) > 1e-6:
         applied_layers.append("pitcher")
+        _append_reason_candidate(
+            reason_candidates,
+            category="pitcher",
+            direction="supportive" if result["pitcher_hr_adjustment"] > 0 else "caution",
+            magnitude=result["pitcher_hr_adjustment"],
+            template_key="pitcher_attackable" if result["pitcher_hr_adjustment"] > 0 else "pitcher_suppresses_hr",
+            template_inputs={"pitcher_name": result["pitcher_name"]},
+        )
 
     reference_date = game_row.get("game_datetime_utc") or game_row.get("game_date")
     batter_trend_row = build_batter_trend_row(
@@ -387,6 +422,13 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["trend_hr_adjustment"], 0.005, 0.25)
     if abs(result["trend_hr_adjustment"]) > 1e-6:
         applied_layers.append("trend")
+        _append_reason_candidate(
+            reason_candidates,
+            category="trend",
+            direction="supportive" if result["trend_hr_adjustment"] > 0 else "caution",
+            magnitude=result["trend_hr_adjustment"],
+            template_key="trend_up" if result["trend_hr_adjustment"] > 0 else "trend_down",
+        )
 
     matchup_multiplier = 1.0
     if result["pitcher_name"]:
@@ -450,8 +492,22 @@ def build_hr_probability_result(
         hr_prob = _clamp(hr_prob + result["family_zone_hr_adjustment"], 0.005, 0.25)
         if abs(result["zone_hr_adjustment"]) > 1e-6:
             applied_layers.append("zone")
+            _append_reason_candidate(
+                reason_candidates,
+                category="zone",
+                direction="supportive" if result["zone_hr_adjustment"] > 0 else "caution",
+                magnitude=result["zone_hr_adjustment"],
+                template_key="zone_favorable" if result["zone_hr_adjustment"] > 0 else "zone_tough",
+            )
         if abs(result["family_zone_hr_adjustment"]) > 1e-6:
             applied_layers.append("family_zone")
+            _append_reason_candidate(
+                reason_candidates,
+                category="family_zone",
+                direction="supportive" if result["family_zone_hr_adjustment"] > 0 else "caution",
+                magnitude=result["family_zone_hr_adjustment"],
+                template_key="family_zone_favorable" if result["family_zone_hr_adjustment"] > 0 else "family_zone_tough",
+            )
 
         arsenal_eff = 0.0
         try:
@@ -476,11 +532,26 @@ def build_hr_probability_result(
         hr_prob = _clamp(hr_prob + result["arsenal_hr_adjustment"], 0.005, 0.25)
         if abs(result["arsenal_hr_adjustment"]) > 1e-6:
             applied_layers.append("arsenal")
+            _append_reason_candidate(
+                reason_candidates,
+                category="arsenal",
+                direction="supportive" if result["arsenal_hr_adjustment"] > 0 else "caution",
+                magnitude=result["arsenal_hr_adjustment"],
+                template_key="arsenal_favorable" if result["arsenal_hr_adjustment"] > 0 else "arsenal_tough",
+            )
 
         result["platoon_hr_adjustment"] = platoon_adj
         hr_prob = _clamp(hr_prob + platoon_adj, 0.005, 0.25)
         if abs(platoon_adj) > 1e-6:
             applied_layers.append("platoon")
+            _append_reason_candidate(
+                reason_candidates,
+                category="platoon",
+                direction="supportive" if platoon_adj > 0 else "caution",
+                magnitude=platoon_adj,
+                template_key="platoon_advantage" if platoon_adj > 0 else "platoon_disadvantage",
+                template_inputs={"matchup_reason": matchup_reason},
+            )
     else:
         skipped_layers.extend(["pitcher_missing", "zone_matchup_unavailable", "arsenal_matchup_unavailable"])
 
@@ -492,6 +563,13 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["pulled_contact_hr_adjustment"], 0.005, 0.30)
     if abs(result["pulled_contact_hr_adjustment"]) > 1e-6:
         applied_layers.append("pulled_contact")
+        _append_reason_candidate(
+            reason_candidates,
+            category="pulled_contact",
+            direction="supportive" if result["pulled_contact_hr_adjustment"] > 0 else "caution",
+            magnitude=result["pulled_contact_hr_adjustment"],
+            template_key="pulled_contact_strength" if result["pulled_contact_hr_adjustment"] > 0 else "pulled_contact_light",
+        )
 
     env_adj = compute_environment_adjustment(game_row=game_row, weather_row=weather_row)
     result["environment_reliability"] = _compute_environment_reliability(game_row, weather_row)
@@ -512,6 +590,16 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["env_hr_adjustment"], 0.005, 0.30)
     if abs(result["env_hr_adjustment"]) > 1e-6:
         applied_layers.append("environment")
+        dominant_env_key = "weather_supportive" if abs(result["weather_hr_adjustment"]) >= abs(result["park_hr_adjustment"]) else "park_supportive"
+        dominant_env_tough_key = "weather_suppressive" if abs(result["weather_hr_adjustment"]) >= abs(result["park_hr_adjustment"]) else "park_suppressive"
+        _append_reason_candidate(
+            reason_candidates,
+            category="environment",
+            direction="supportive" if result["env_hr_adjustment"] > 0 else "caution",
+            magnitude=result["env_hr_adjustment"],
+            template_key=dominant_env_key if result["env_hr_adjustment"] > 0 else dominant_env_tough_key,
+            template_inputs={"venue": game_row.get("venue")},
+        )
 
     trajectory_row = build_trajectory_features(
         statcast_df=pitcher_df,
@@ -527,6 +615,13 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["trajectory_hr_adjustment"], 0.005, 0.25)
     if abs(result["trajectory_hr_adjustment"]) > 1e-6:
         applied_layers.append("trajectory")
+        _append_reason_candidate(
+            reason_candidates,
+            category="trajectory",
+            direction="supportive" if result["trajectory_hr_adjustment"] > 0 else "caution",
+            magnitude=result["trajectory_hr_adjustment"],
+            template_key="trajectory_helpful" if result["trajectory_hr_adjustment"] > 0 else "trajectory_tough",
+        )
 
     pitcher_rolling_row = build_pitcher_rolling_form_row(
         statcast_df=pitcher_df,
@@ -557,6 +652,13 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["rolling_hr_adjustment"], 0.005, 0.30)
     if abs(result["rolling_hr_adjustment"]) > 1e-6:
         applied_layers.append("rolling")
+        _append_reason_candidate(
+            reason_candidates,
+            category="rolling",
+            direction="supportive" if result["rolling_hr_adjustment"] > 0 else "caution",
+            magnitude=result["rolling_hr_adjustment"],
+            template_key="rolling_up" if result["rolling_hr_adjustment"] > 0 else "rolling_down",
+        )
 
     lineup_slot = game_row.get("lineup_slot")
     try:
@@ -598,6 +700,17 @@ def build_hr_probability_result(
     hr_prob = _clamp(hr_prob + result["opportunity_hr_adjustment"], 0.005, 0.30)
     if abs(result["opportunity_hr_adjustment"]) > 1e-6:
         applied_layers.append("opportunity")
+        _append_reason_candidate(
+            reason_candidates,
+            category="opportunity",
+            direction="supportive" if result["opportunity_hr_adjustment"] > 0 else "caution",
+            magnitude=result["opportunity_hr_adjustment"],
+            template_key="opportunity_strong" if result["opportunity_hr_adjustment"] > 0 else "opportunity_light",
+            template_inputs={
+                "lineup_slot_used": lineup_slot,
+                "lineup_slot_source": result["lineup_slot_source"],
+            },
+        )
 
     result["raw_hr_prob"] = hr_prob
     result["adjusted_hr_prob"] = hr_prob
@@ -617,9 +730,40 @@ def build_hr_probability_result(
         applied_layers=applied_layers,
     )
     result.update(confidence)
+    if "Pitcher unresolved" in result.get("confidence_reasons", []):
+        _append_reason_candidate(
+            reason_candidates,
+            category="confidence",
+            direction="caution",
+            magnitude=0.004,
+            template_key="pitcher_unresolved",
+        )
+    if "Lineup slot unavailable" in result.get("confidence_reasons", []):
+        _append_reason_candidate(
+            reason_candidates,
+            category="confidence",
+            direction="caution",
+            magnitude=0.003,
+            template_key="lineup_unknown",
+        )
+    if "Using projected lineup slot" in result.get("confidence_reasons", []):
+        _append_reason_candidate(
+            reason_candidates,
+            category="confidence",
+            direction="caution",
+            magnitude=0.002,
+            template_key="lineup_projected",
+        )
 
     result["applied_layers"] = "|".join(dict.fromkeys(applied_layers))
     result["skipped_layers"] = "|".join(dict.fromkeys([s for s in skipped_layers if s]))
+    ranked_reasons = sorted(
+        reason_candidates,
+        key=lambda item: abs(_safe_float(item.get("signed_magnitude"))),
+        reverse=True,
+    )
+    result["model_voice_reason_candidates"] = ranked_reasons
+    result["model_voice_tags"] = [str(item.get("template_key") or "") for item in ranked_reasons if str(item.get("template_key") or "").strip()]
     result["pregame_context_applied"] = any(
         abs(_safe_float(result.get(key))) > 1e-6
         for key in [

tests/test_model_voice.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from analytics.model_voice import build_hr_model_voice
+
+
+class TestModelVoice(unittest.TestCase):
+    def test_hr_model_voice_uses_ranked_reason_candidates(self) -> None:
+        row = {
+            "model_voice_reason_candidates": [
+                {
+                    "category": "arsenal",
+                    "direction": "supportive",
+                    "magnitude": 0.012,
+                    "signed_magnitude": 0.012,
+                    "template_key": "arsenal_favorable",
+                    "template_inputs": {},
+                },
+                {
+                    "category": "pitcher",
+                    "direction": "caution",
+                    "magnitude": 0.008,
+                    "signed_magnitude": -0.008,
+                    "template_key": "pitcher_suppresses_hr",
+                    "template_inputs": {"pitcher_name": "Ace Arm"},
+                },
+            ]
+        }
+
+        voice = build_hr_model_voice(row)
+
+        self.assertIn("arsenal mix fits his power profile", voice["model_voice"].lower())
+        self.assertIn("pitcher profile suppresses home-run damage", voice["model_voice"].lower())
+        self.assertTrue(voice["model_voice"].endswith("."))
+        self.assertEqual(voice["model_voice_primary_reason"], "The arsenal mix fits his power profile")
+        self.assertEqual(voice["model_voice_caveat"], "The pitcher profile suppresses home-run damage")
+
+    def test_hr_model_voice_changes_with_different_reasons(self) -> None:
+        favorable = build_hr_model_voice(
+            {
+                "model_voice_reason_candidates": [
+                    {
+                        "category": "environment",
+                        "direction": "supportive",
+                        "magnitude": 0.010,
+                        "signed_magnitude": 0.010,
+                        "template_key": "weather_supportive",
+                        "template_inputs": {},
+                    }
+                ]
+            }
+        )
+        caution = build_hr_model_voice(
+            {
+                "model_voice_reason_candidates": [
+                    {
+                        "category": "platoon",
+                        "direction": "caution",
+                        "magnitude": 0.009,
+                        "signed_magnitude": -0.009,
+                        "template_key": "platoon_disadvantage",
+                        "template_inputs": {},
+                    }
+                ]
+            }
+        )
+
+        self.assertNotEqual(favorable["model_voice"], caution["model_voice"])
+        self.assertIn("weather conditions", favorable["model_voice"].lower())
+        self.assertIn("same-handed", caution["model_voice"].lower())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_props_mapper.py

@@ -95,6 +95,8 @@ class TestPropsMapper(unittest.TestCase):
         self.assertAlmostEqual(float(row["model_hr_prob"]), 0.17, places=6)
         self.assertTrue(pd.notna(row["bet_ev"]))
         self.assertEqual(row["confidence_bucket"], "high")
+        self.assertTrue(str(row["model_voice"]).strip())
+        self.assertTrue(str(row["model_voice_primary_reason"]).strip())
         self.assertIn("final_recommendation_score", result.columns)
         self.assertTrue(pd.notna(row["edge"]))
 

visualization/debug_page.py

@@ -650,6 +650,10 @@ def render_debug(
                 "fair_prob",
                 "bet_ev",
                 "verdict",
+                "model_voice",
+                "model_voice_primary_reason",
+                "model_voice_caveat",
+                "model_voice_tags",
                 "model_voice_for",
                 "model_voice_against",
                 "confidence_score",
@@ -725,6 +729,9 @@ def render_debug(
                                     "best_bet_ev": player_entry.get("best_bet_ev"),
                                     "best_confidence_score": player_entry.get("best_confidence_score"),
                                     "best_verdict": player_entry.get("best_verdict"),
+                                    "model_voice": player_entry.get("model_voice"),
+                                    "model_voice_primary_reason": player_entry.get("model_voice_primary_reason"),
+                                    "model_voice_caveat": player_entry.get("model_voice_caveat"),
                                     "model_voice_for": player_entry.get("model_voice_for"),
                                     "model_voice_against": player_entry.get("model_voice_against"),
                                     "best_edge": player_entry.get("best_edge"),

visualization/props_page.py

@@ -211,6 +211,13 @@ def _render_props_ui_styles() -> None:
         .props-voice-line strong {
             color: #f3f8ff;
         }
+        .props-voice-card {
+            display: -webkit-box;
+            -webkit-line-clamp: 3;
+            -webkit-box-orient: vertical;
+            overflow: hidden;
+            min-height: 3.7rem;
+        }
         .props-game-card {
             border: 1px solid rgba(62, 88, 125, 0.32);
             border-radius: 16px;
@@ -473,11 +480,15 @@ def _maybe_log_props(conn, mapped: pd.DataFrame) -> None:
             "odds_american", "line", "implied_prob", "raw_hr_prob",
             "calibrated_hr_prob", "model_hr_prob", "fair_prob", "bet_ev", "confidence_score",
             "confidence_bucket", "opportunity_hr_adjustment", "model_hr_prob_source", "edge",
-            "verdict", "model_voice_for", "model_voice_against",
+            "verdict", "model_voice", "model_voice_primary_reason", "model_voice_caveat", "model_voice_tags", "model_voice_for", "model_voice_against",
         ]
         for col in log_cols:
             if col not in to_log.columns:
                 to_log[col] = None
+        if "model_voice_tags" in to_log.columns:
+            to_log["model_voice_tags"] = to_log["model_voice_tags"].apply(
+                lambda v: "|".join(v) if isinstance(v, list) else v
+            )
         ensure_upcoming_hr_props_table(conn)
         insert_upcoming_hr_props(conn, to_log[log_cols])
     except Exception:
@@ -631,6 +642,7 @@ def render_featured_hr_cards(featured_df: pd.DataFrame) -> None:
             verdict = str(row.get("verdict") or "tracked").strip().lower()
             edge_class = _metric_tone_class("edge", row.get("edge"))
             ev_class = _metric_tone_class("ev", row.get("bet_ev"))
+            model_voice = str(row.get("model_voice") or "Model voice is still being assembled for this matchup.")
             st.markdown(
                 f"""
                 <div class="props-card{' top' if idx == 0 else ''}">
@@ -666,8 +678,7 @@ def render_featured_hr_cards(featured_df: pd.DataFrame) -> None:
                         </div>
                     </div>
                     <div class="props-voice">
-                        <div class="props-voice-line"><strong>Model Voice For:</strong> {str(row.get('model_voice_for') or 'Baseline power keeps this live')}</div>
-                        <div class="props-voice-line"><strong>Model Voice Against:</strong> {str(row.get('model_voice_against') or 'Market price is the main concern')}</div>
+                        <div class="props-voice-line props-voice-card"><strong>Model Voice:</strong> {model_voice}</div>
                     </div>
                 </div>
                 """,
@@ -730,6 +741,11 @@ def render_player_hr_details(player_details: dict[str, Any]) -> None:
         "fair_prob",
         "bet_ev",
         "verdict",
+        "model_voice",
+        "model_voice_primary_reason",
+        "model_voice_caveat",
+        "model_voice_reason_candidates",
+        "model_voice_tags",
         "model_voice_for",
         "model_voice_against",
         "confidence_score",
@@ -773,8 +789,7 @@ def render_player_hr_row(player_entry: dict[str, Any]) -> None:
     best_ev = _format_ev(player_entry.get("best_bet_ev"))
     best_confidence = _format_confidence(player_entry.get("best_confidence_score"))
     verdict = str(player_entry.get("best_verdict") or "tracked").strip().lower()
-    voice_for = str(player_entry.get("model_voice_for") or "")
-    voice_against = str(player_entry.get("model_voice_against") or "")
+    model_voice = str(player_entry.get("model_voice") or "")
 
     details_label = f"{player_name} | {best_label} | {best_book} {best_odds} | {best_ev} EV | {best_edge} | {best_confidence} conf"
     if player_entry.get("has_alt_ladders"):
@@ -794,10 +809,8 @@ def render_player_hr_row(player_entry: dict[str, Any]) -> None:
             value=False,
             key=f"props_player_toggle_{player_entry.get('player_key')}",
         )
-        if voice_for:
-            st.caption(f"For: {voice_for}")
-        if voice_against:
-            st.caption(f"Against: {voice_against}")
+        if model_voice:
+            st.caption(f"Model Voice: {model_voice}")
 
         if details_open:
             st.caption(details_label)
@@ -812,10 +825,19 @@ def render_player_hr_row(player_entry: dict[str, Any]) -> None:
             metric_cols[3].metric("EV", best_ev)
             metric_cols[4].metric("Edge", best_edge)
             metric_cols[5].metric("Confidence", best_confidence)
-            if voice_for:
-                st.caption(f"Model Voice For: {voice_for}")
-            if voice_against:
-                st.caption(f"Model Voice Against: {voice_against}")
+            if model_voice:
+                st.caption(f"Model Voice: {model_voice}")
+            primary_reason = str(player_entry.get("model_voice_primary_reason") or "")
+            caveat = str(player_entry.get("model_voice_caveat") or "")
+            if primary_reason or caveat:
+                why_lines: list[str] = []
+                if primary_reason:
+                    why_lines.append(f"Lead reason: {primary_reason}")
+                if caveat:
+                    why_lines.append(f"Caveat: {caveat}")
+                st.caption("Why this rating")
+                for line in why_lines:
+                    st.write(f"- {line}")
             render_player_hr_details(details)
         st.divider()
 
@@ -880,7 +902,7 @@ def _build_flat_table_rows(display: pd.DataFrame, market_type: str) -> list[dict
                 "Pregame HR%": _format_pct(row.get("model_hr_prob")),
                 "EV": _format_ev(row.get("bet_ev")),
                 "Confidence": _format_confidence(row.get("confidence_score")),
-                "Model Voice": str(row.get("model_voice_for") or "-"),
+                "Model Voice": str(row.get("model_voice") or "-"),
                 "Source": str(row.get("model_hr_prob_source") or "-"),
                 "Edge": _format_edge(row.get("edge")),
             }
@@ -900,7 +922,7 @@ def _build_flat_table_rows(display: pd.DataFrame, market_type: str) -> list[dict
             "Fair%": _format_pct(row.get("fair_prob")),
             "EV": _format_ev(row.get("bet_ev")),
             "Confidence": _format_confidence(row.get("confidence_score")),
-            "Model Voice": str(row.get("model_voice_for") or "-"),
+            "Model Voice": str(row.get("model_voice") or "-"),
             "Edge": _format_edge(row.get("edge")),
         }
         for _, row in display.iterrows()
@@ -940,6 +962,9 @@ def render_probability_diagnostics(display: pd.DataFrame) -> None:
             "sportsbook",
             "display_label",
             "verdict",
+            "model_voice",
+            "model_voice_primary_reason",
+            "model_voice_caveat",
             "model_voice_for",
             "model_voice_against",
             "baseline_hr_prob",