Add Brettapps/trifecta-bro/v1 v1.0.0 trifecta predictor (rule-based)

README.md

@@ -0,0 +1,85 @@
+---
+title: Trifecta-Bro v1 — Australian Gallops Trifecta Predictor
+emoji: 🐎
+colorFrom: green
+colorTo: blue
+sdk: "false"
+tags:
+  - racing
+  - horse-racing
+  - australian-gallops
+  - trifecta
+  - prediction
+  - sports-betting
+license: mit
+library_name: other
+---
+
+# Brettapps/trifecta-bro-v1
+
+**Model id:** `Brettapps/trifecta-bro/v1`
+**Version:** 1.0.0
+**Task:** Australian Gallops **trifecta prediction** (pick the top-3 finishers, in order).
+
+Trifecta-Bro v1 is an open-source, multi-factor trifecta scorer for Australian
+gallops. Given a race's field + form, it assigns each runner a 0–100 score and
+emits a **primary**, **secondary**, and **value** trifecta combination, plus the
+top-3 ranked runners with win/place probabilities.
+
+> **Status:** v1 is a deterministic rule-based scorer. No supervised training
+> was performed because the project has no historical race **results** (labels)
+> yet. v2 will train a gradient-boosted / logistic model on observed outcomes
+> once `data/results/` is populated.
+
+## Method
+
+For each runner, a weighted 0–100 score is computed from:
+
+| Factor | Max weight |
+|--------|-----------|
+| Recent form (last 5 starts: 1/2/3 finishes) | 25 |
+| Career overall win % | 20 |
+| Career overall place % | 10 |
+| Track strike rate (places/starts) | 10 |
+| Distance strike rate | 8 |
+| Condition strike rate (per going) | 8 |
+| Barrier draw | 5 |
+| Career prize money | 5 |
+
+The three highest-scoring runners form the **primary** trifecta. A **secondary**
+and **value** combination are derived from the next-best runners (with an
+outsider angle when a score > 30 exists further down the field).
+
+## Usage
+
+```python
+# Install from the Hub
+# pip install huggingface_hub
+from huggingface_hub import snapshot_download
+path = snapshot_download("Brettapps/trifecta-bro-v1")
+import sys; sys.path.insert(0, path)
+
+from trifecta_bro_v1 import TrifectaPredictor, race_from_payload
+
+payload = {...}  # Trifecta-Bro race payload
+race = race_from_payload(payload)
+prediction = TrifectaPredictor().predict(race)
+print(prediction["primary"], prediction["secondary"], prediction["value"])
+```
+
+Or run the bundled CLI:
+
+```bash
+python -m trifecta_bro_v1.main --data predictions-2026-08-10.json
+```
+
+## Artifact
+
+`model_artifacts/model_artifact.json` documents the model method, feature
+weights, and version — making the published model interpretable and reproducible.
+
+## Backend note
+
+This model is also wired as the `Brettapps/trifecta-bro/v1` identity in the
+Trifecta-Bro LM Studio / Obsidian-vault backend. The HF-published code is the
+canonical, dependency-light inference implementation.

config.json

@@ -0,0 +1,15 @@
+{
+  "model_id": "Brettapps/trifecta-bro/v1",
+  "version": "1.0.0",
+  "task": "trifecta-prediction",
+  "domain": "australian-gallops",
+  "method": "multi-factor-rule-based-scoring",
+  "library_name": "other",
+  "license": "mit",
+  "dependencies": [],
+  "inference_entrypoints": [
+    "trifecta_bro_v1.predictor.TrifectaPredictor",
+    "trifecta_bro_v1.artifact.predict_race"
+  ],
+  "artifact": "model_artifacts/model_artifact.json"
+}

model_artifacts/model_artifact.json

@@ -0,0 +1,16 @@
+{
+  "model_id": "Brettapps/trifecta-bro/v1",
+  "version": "1.0.0",
+  "method": "multi-factor rule-based scoring (0-100)",
+  "feature_weights": {
+    "recent_form": 25.0,
+    "overall_win_pct": 20.0,
+    "overall_place_pct": 10.0,
+    "track_strike": 10.0,
+    "distance_strike": 8.0,
+    "condition_strike": 8.0,
+    "barrier_draw": 5.0,
+    "career_prize": 5.0
+  },
+  "notes": "Open-source multi-factor trifecta scorer. No supervised training (no historical race results available in data/results/). Scores are deterministic given runner form/stat inputs. Future v2 will train a gradient-boosted model on observed outcomes."
+}

push.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Publish Brettapps/trifecta-bro-v1 to the HuggingFace Hub.
+
+Requires a VALID HuggingFace token, supplied via:
+  - HF_ACCESS_TOKEN / HF_TOKEN env var, or
+  - the cached `huggingface_hub` credentials (hf auth login)
+
+This script ONLY uploads; it does not build the package (build is done via
+save_artifact + the committed source files). Run after `hf auth login` succeeds.
+
+Usage:
+    python push.py            # uses cached/ENV token
+    HF_ACCESS_TOKEN=hf_xxx python push.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from huggingface_hub import HfApi, create_repo
+
+REPO_ID = "Brettapps/trifecta-bro-v1"
+REPO_TYPE = "model"
+LOCAL_DIR = Path(__file__).resolve().parents[0]
+ARTIFACT_DIR = LOCAL_DIR / "model_artifacts"
+
+
+def main() -> int:
+    token = os.environ.get("HF_ACCESS_TOKEN") or os.environ.get("HF_TOKEN")
+    api = HfApi(token=token)
+
+    # Fail fast with a clear message if the token is invalid/expired.
+    try:
+        me = api.whoami()
+        print(f"Authenticated as: {me.get('name') or me.get('id')}")
+    except Exception as exc:  # noqa: BLE001
+        print(f"ERROR: HuggingFace authentication failed: {exc}")
+        print("Fix: run `hf auth login` with a valid token, or set HF_ACCESS_TOKEN.")
+        return 1
+
+    # Ensure the repo exists under the authenticated namespace.
+    create_repo(
+        repo_id=REPO_ID,
+        repo_type=REPO_TYPE,
+        token=token,
+        exist_ok=True,
+    )
+
+    print(f"Uploading {LOCAL_DIR} -> {REPO_ID}")
+    api.upload_folder(
+        folder_path=str(LOCAL_DIR),
+        repo_id=REPO_ID,
+        repo_type=REPO_TYPE,
+        commit_message="Add Brettapps/trifecta-bro/v1 v1.0.0 predictor",
+        token=token,
+    )
+    print(f"DONE: https://huggingface.co/{REPO_ID}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trifecta-bro-v1"
+version = "1.0.0"
+description = "Australian Gallops trifecta predictor (Brettapps/trifecta-bro/v1)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["horse-racing", "trifecta", "australian-gallops", "prediction"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["trifecta_bro_v1*"]

trifecta_bro_v1/__init__.py

@@ -0,0 +1,30 @@
+"""Brettapps/trifecta-bro-v1 — Australian Gallops trifecta predictor (v1)."""
+
+from __future__ import annotations
+
+from .artifact import (
+    ARTIFACT,
+    MODEL_ID,
+    ModelArtifact,
+    load_artifact,
+    predict_race,
+    race_from_payload,
+    save_artifact,
+)
+from .predictor import Race, Runner, TrifectaPredictor
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "TrifectaPredictor",
+    "Race",
+    "Runner",
+    "MODEL_ID",
+    "ARTIFACT",
+    "ModelArtifact",
+    "save_artifact",
+    "load_artifact",
+    "predict_race",
+    "race_from_payload",
+    "__version__",
+]

trifecta_bro_v1/artifact.py

@@ -0,0 +1,102 @@
+"""Artifact save/load and model metadata for Brettapps/trifecta-bro-v1."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from .predictor import Race, Runner, TrifectaPredictor
+
+
+MODEL_ID = "Brettapps/trifecta-bro/v1"
+MODEL_CARD_VERSION = "1.0.0"
+
+
+@dataclass
+class ModelArtifact:
+    model_id: str
+    version: str
+    method: str
+    feature_weights: dict[str, float]
+    notes: str
+
+
+# The "learned" configuration of the rule-based model. Documented explicitly so
+# the published artifact is interpretable and reproducible.
+ARTIFACT = ModelArtifact(
+    model_id=MODEL_ID,
+    version=MODEL_CARD_VERSION,
+    method="multi-factor rule-based scoring (0-100)",
+    feature_weights={
+        "recent_form": 25.0,
+        "overall_win_pct": 20.0,
+        "overall_place_pct": 10.0,
+        "track_strike": 10.0,
+        "distance_strike": 8.0,
+        "condition_strike": 8.0,
+        "barrier_draw": 5.0,
+        "career_prize": 5.0,
+    },
+    notes=(
+        "Open-source multi-factor trifecta scorer. No supervised training "
+        "(no historical race results available in data/results/). Scores are "
+        "deterministic given runner form/stat inputs. Future v2 will train a "
+        "gradient-boosted model on observed outcomes."
+    ),
+)
+
+
+def save_artifact(out_dir: str | Path) -> Path:
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / "model_artifact.json"
+    path.write_text(json.dumps(asdict(ARTIFACT), indent=2))
+    return path
+
+
+def load_artifact(path: str | Path) -> ModelArtifact:
+    data = json.loads(Path(path).read_text())
+    return ModelArtifact(**data)
+
+
+def predict_race(race: Race) -> dict[str, Any]:
+    """Convenience: run the packaged predictor on a Race."""
+    return TrifectaPredictor().predict(race)
+
+
+def race_from_payload(payload: dict[str, Any]) -> Race:
+    """Build a Race from the Trifecta-Bro predictions JSON shape."""
+    form = payload.get("form", {})
+    runners = [
+        Runner(
+            number=r.get("number", 0),
+            name=r.get("name", ""),
+            jockey=r.get("jockey", ""),
+            trainer=r.get("trainer", ""),
+            weight=r.get("weight"),
+            barrier=r.get("barrier"),
+            form=r.get("form", ""),
+            last20Starts=r.get("last20Starts", ""),
+            careerPrizeMoney=r.get("careerPrizeMoney", "$0"),
+            scratched=bool(r.get("scratched", False)),
+            stats=r.get("stats", {}),
+        )
+        for r in form.get("runners", [])
+    ]
+    return Race(
+        date=payload.get("date", ""),
+        track=payload.get("track", ""),
+        track_slug=payload.get("track_slug", ""),
+        race_number=str(payload.get("race_number", "")),
+        race_name=payload.get("race_name", ""),
+        distance=payload.get("distance", ""),
+        condition=payload.get("condition", ""),
+        weather=payload.get("weather", ""),
+        race_class=payload.get("race_class", ""),
+        start_time=payload.get("start_time", ""),
+        prize_money=payload.get("prize_money", ""),
+        number_of_runners=int(payload.get("number_of_runners", 0) or 0),
+        runners=runners,
+    )

trifecta_bro_v1/main.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""CLI for Brettapps/trifecta-bro-v1.
+
+Usage:
+    # Run on the bundled sample race
+    python -m trifecta_bro_v1.main
+
+    # Run on a Trifecta-Bro predictions JSON file
+    python -m trifecta_bro_v1.main --data /path/to/predictions-2026-08-10.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .artifact import predict_race, race_from_payload
+from .predictor import TrifectaPredictor
+
+# A tiny self-contained demo race so the package is runnable with no inputs.
+SAMPLE = {
+    "date": "2026-08-10",
+    "track": "Dubbo",
+    "track_slug": "dubbo",
+    "race_number": "3",
+    "race_name": "Aqua West Country Boosted BM58 Handicap",
+    "distance": "1620m",
+    "condition": "Soft 5",
+    "weather": "Showers",
+    "race_class": "BM58",
+    "start_time": "2026-08-10T04:40:00Z",
+    "prize_money": "30000",
+    "number_of_runners": 3,
+    "form": {
+        "runners": [
+            {"number": 1, "name": "Boncapo", "form": "X1241", "stats": {"overall": {"winPercent": 0.25, "placePercent": 0.5}}},
+            {"number": 14, "name": "Bill Peyto", "form": "36412", "stats": {"overall": {"winPercent": 0.07, "placePercent": 0.35}}},
+            {"number": 7, "name": "Casterly Rock", "form": "23939", "stats": {"overall": {"winPercent": 0.06, "placePercent": 0.48}}},
+        ]
+    },
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Brettapps/trifecta-bro/v1 predictor")
+    p.add_argument("--data", help="Path to a Trifecta-Bro predictions JSON file")
+    p.add_argument("--race", type=int, default=0, help="1-based race index when --data is given")
+    args = p.parse_args(argv)
+
+    if args.data:
+        payload = json.loads(Path(args.data).read_text())
+        races = payload.get("races", [payload])
+        idx = max(0, args.race - 1)
+        if idx >= len(races):
+            print(f"Race index {args.race} out of range (have {len(races)})", file=sys.stderr)
+            return 2
+        race = race_from_payload(races[idx])
+    else:
+        race = race_from_payload(SAMPLE)
+
+    pred = TrifectaPredictor().predict(race)
+    print(json.dumps(pred, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trifecta_bro_v1/predictor.py

@@ -0,0 +1,157 @@
+"""Trifecta-Bro v1 — open-source multi-factor trifecta predictor.
+
+Model id: Brettapps/trifecta-bro/v1  (HF repo: Brettapps/trifecta-bro-v1)
+
+This is the standalone inference module for the HuggingFace model repo. It is a
+self-contained, dependency-light implementation of the trifecta prediction logic
+(rule-based multi-factor scoring). It mirrors `src/prediction_model.py` in the
+Trifecta-Bro Space so the published model is directly usable without cloning the
+whole Space.
+
+Load it:
+    from trifecta_bro_v1.predictor import TrifectaPredictor, Race, Runner
+    pred = TrifectaPredictor().predict(race)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Runner:
+    number: int
+    name: str
+    jockey: str = ""
+    trainer: str = ""
+    weight: float | None = None
+    barrier: int | None = None
+    form: str = ""
+    last20Starts: str = ""
+    careerPrizeMoney: str = "$0"
+    scratched: bool = False
+    stats: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Race:
+    date: str
+    track: str
+    track_slug: str
+    race_number: str
+    race_name: str
+    distance: str
+    condition: str
+    weather: str
+    race_class: str
+    start_time: str
+    prize_money: str
+    number_of_runners: int
+    runners: list[Runner] = field(default_factory=list)
+
+
+class TrifectaPredictor:
+    """Open-source trifecta prediction model.
+
+    Scores each runner on a 0-100 scale using recent form, career/overall
+    win & place percentages, track/distance/condition strike rates, barrier
+    draw, and career prize money. The top three by score form the primary
+    trifecta; secondary and value bets are derived from the next-best runners.
+    """
+
+    MODEL_ID = "Brettapps/trifecta-bro/v1"
+
+    def predict(self, race: Race) -> dict[str, Any]:
+        runners = [r for r in race.runners if not r.scratched]
+        if len(runners) < 3:
+            return {"error": "Insufficient runners"}
+
+        scored: list[dict[str, Any]] = []
+        for runner in runners:
+            scored.append({
+                "number": runner.number,
+                "name": runner.name,
+                "score": self._score_runner(runner),
+                "win_prob": self._win_probability(runner),
+                "place_prob": self._place_probability(runner),
+            })
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        top = scored[:3]
+        primary = f"{top[0]['number']}-{top[1]['number']}-{top[2]['number']}"
+
+        secondary = None
+        value = None
+        if len(scored) > 3:
+            secondary = f"{top[0]['number']}-{top[2]['number']}-{scored[3]['number']}"
+            outsiders = [s for s in scored[3:] if s["score"] > 30]
+            if outsiders:
+                value = f"{scored[1]['number']}-{top[0]['number']}-{outsiders[0]['number']}"
+            else:
+                value = f"{scored[1]['number']}-{top[0]['number']}-{top[2]['number']}"
+
+        return {
+            "model_id": self.MODEL_ID,
+            "date": race.date,
+            "track": race.track,
+            "race_number": race.race_number,
+            "race_name": race.race_name,
+            "primary": primary,
+            "secondary": secondary,
+            "value": value,
+            "top3": top,
+            "confidence": "MEDIUM",
+        }
+
+    def _score_runner(self, runner: Runner) -> float:
+        score = 0.0
+        form = str(runner.form or runner.last20Starts or "")
+        recent = form[-5:] if len(form) > 5 else form
+        score += min((recent.count("1") * 8 + recent.count("2") * 4 + recent.count("3") * 4), 25)
+
+        overall = runner.stats.get("overall", {})
+        win_pct = overall.get("winPercent", 0) or 0
+        place_pct = overall.get("placePercent", 0) or 0
+        score += win_pct * 20
+        score += place_pct * 10
+
+        track_stats = runner.stats.get("track", {})
+        track_starts = track_stats.get("starts", 0) or 0
+        track_places = track_stats.get("places", 0) or 0
+        score += min((track_places / max(track_starts, 1)) * 10, 10)
+
+        dist_stats = runner.stats.get("distance", {})
+        dist_starts = dist_stats.get("starts", 0) or 0
+        dist_places = dist_stats.get("places", 0) or 0
+        score += min((dist_places / max(dist_starts, 1)) * 8, 8)
+
+        cond_stats = runner.stats.get("conditions", {})
+        for _key, data in cond_stats.items():
+            c_starts = data.get("starts", 0) or 0
+            c_places = data.get("places", 0) or 0
+            score += min((c_places / max(c_starts, 1)) * 8, 8)
+
+        try:
+            barrier = int(runner.barrier) if runner.barrier else 5
+            score += max(0, 5 - abs(barrier - 5))
+        except Exception:
+            score += 3
+
+        try:
+            prize = float(str(runner.careerPrizeMoney).replace("$", "").replace(",", ""))
+            score += min(prize / 20000, 5)
+        except Exception:
+            pass
+
+        return min(round(score, 1), 100)
+
+    def _win_probability(self, runner: Runner) -> float:
+        overall = runner.stats.get("overall", {})
+        win_pct = overall.get("winPercent", 0) or 0
+        return min(max(round(win_pct * 100, 1), 0), 100)
+
+    def _place_probability(self, runner: Runner) -> float:
+        overall = runner.stats.get("overall", {})
+        place_pct = overall.get("placePercent", 0) or 0
+        return min(max(round(place_pct * 100, 1), 0), 100)