FUT-HEROS match mode: SAM3 goal detection + RF-DETR ball tracking + goal events + per-strike coaching (ZeroGPU)

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

README.md

@@ -1,14 +1,35 @@
 ---
-title: Fut Heros
-emoji: 💻
-colorFrom: indigo
+title: FUT-HEROS
+emoji: ⚽
+colorFrom: green
 colorTo: yellow
 sdk: gradio
 sdk_version: 6.18.0
 python_version: '3.12'
 app_file: app.py
 pinned: false
+license: apache-2.0
 short_description: check if you have the skill to make it the worldcup
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ⚽ FUT-HEROS
+
+**They measure your shot. You fix it.**
+
+Upload a match or highlight clip. FUT-HEROS:
+
+1. **Finds the goal post** — zero-shot, SAM3 with the text prompt "goal post"
+2. **Tracks the ball** — RF-DETR Nano (30M params, Apache-2.0), every frame
+3. **Detects your goals** — football-rules event logic: the ball's path crossing the
+   goal plane, with kickoff-return suppression (you can't score twice in 5 seconds —
+   there's a kickoff in between)
+4. **Finds your scoring kick** — tracks the ball backwards from each goal to the
+   leg-ball contact
+5. **Coaches the strike** — biomechanics scorecard (knee bend, trunk lean, plant foot,
+   hip drive, follow-through, launch angle) + cues and drills
+
+Everything is tiny + open: SAM3 (one image call), RF-DETR Nano, MediaPipe Pose.
+The numbers are coaching-grade bands, not lab degrees — honest by design.
+
+Built for the **Build Small Hackathon** (Backyard AI track) by a Sunday-league player
+who wanted to know if his strikes have World Cup form.

app.py

@@ -0,0 +1,216 @@
+"""FUT-HEROS — upload your match clip, it finds your goals and coaches your strikes.
+
+ZeroGPU Space: heavy vision (SAM3 goal detection + RF-DETR ball tracking) runs inside
+the @spaces.GPU window; pose, event logic, coaching and rendering run on CPU.
+"""
+from __future__ import annotations
+
+import os
+import time
+
+import cv2
+import gradio as gr
+import numpy as np
+import spaces
+
+from futheros.adapters.pose_mediapipe import MediaPipePose
+from futheros.adapters.renderer_opencv import OpenCvRenderer
+from futheros.adapters.video_opencv import OpenCvVideoSink, OpenCvVideoSource
+from futheros.adapters.coach_rule import RuleCoach
+from futheros.domain import biomechanics, goal as goal_mod, trajectory as trajectory_mod
+from futheros.domain.goal import GoalRegion
+from futheros.domain.models import Box, ContactResult
+
+
+# --- startup asset: CLIP BPE vocab for SAM3 (downloaded once, cached) ---
+import urllib.request
+_BPE_LOCAL = "/tmp/bpe_simple_vocab_16e6.txt.gz"
+if not os.path.exists(_BPE_LOCAL):
+    urllib.request.urlretrieve(
+        "https://github.com/openai/CLIP/raw/main/clip/bpe_simple_vocab_16e6.txt.gz", _BPE_LOCAL)
+os.environ["SAM3_BPE_PATH"] = _BPE_LOCAL
+
+MAX_FRAMES = 900          # ~30-40s of footage per analysis (ZeroGPU time budget)
+
+_DETECTOR = None
+_GOAL_DET = None
+_POSE = MediaPipePose()
+_COACH = RuleCoach()
+_RENDER = OpenCvRenderer()
+
+
+def _get_models():
+    """Create the GPU models lazily inside the GPU context (ZeroGPU pattern)."""
+    global _DETECTOR, _GOAL_DET
+    if _DETECTOR is None:
+        from futheros.adapters.detector_rfdetr import RFDetrDetector
+        _DETECTOR = RFDetrDetector(model_cls="nano")
+    if _GOAL_DET is None:
+        try:
+            from futheros.adapters.goal_detector_sam3 import Sam3GoalDetector
+            _GOAL_DET = Sam3GoalDetector(prompt="goal post")
+            _GOAL_DET._ensure_loaded()
+        except Exception as e:  # noqa: BLE001
+            print("SAM3 goal detector unavailable:", e)
+            _GOAL_DET = False
+    return _DETECTOR, _GOAL_DET
+
+
+@spaces.GPU(duration=120)
+def gpu_detect(frames: list[np.ndarray]):
+    """Everything that needs the GPU, in one allocation window:
+    goal boxes (SAM3, 3 frames) + per-frame ball/person detections (RF-DETR)."""
+    det, goal_det = _get_models()
+    goal_boxes = []
+    if goal_det:
+        for fi in {len(frames) // 4, len(frames) // 2, (3 * len(frames)) // 4}:
+            try:
+                goal_boxes.extend(goal_det.detect_goals(frames[fi], conf=0.45))
+            except Exception as e:  # noqa: BLE001
+                print("goal det err:", e)
+    dets = det.detect(frames)
+    ball = [[d.ball.cx, d.ball.cy, d.ball.conf, d.ball.radius] if d.ball else None for d in dets]
+    return goal_boxes, ball
+
+
+def analyze(video_path, progress=gr.Progress()):
+    if not video_path:
+        raise gr.Error("Upload a clip of your match / highlights first.")
+    t0 = time.time()
+
+    progress(0.05, desc="Loading video…")
+    clip = OpenCvVideoSource().load(video_path, max_frames=MAX_FRAMES)
+    fps = clip.fps
+
+    progress(0.15, desc="GPU: locating goal + tracking ball…")
+    goal_boxes, ball_raw = gpu_detect(clip.frames)
+
+    # goal regions (dedupe by location, keep top-2)
+    kept = []
+    for b in sorted(goal_boxes, key=lambda x: -x.conf):
+        if all(abs(b.cx - k.cx) > 40 or abs(b.cy - k.cy) > 40 for k in kept):
+            kept.append(b)
+    regions = [GoalRegion.from_box(b) for b in kept[:2]]
+    if not regions:
+        raise gr.Error("No goal post found in this clip — film so a goal is visible.")
+
+    # rebuild Detection stream
+    from futheros.domain.models import Detection
+    dets = []
+    for bb in ball_raw:
+        ball = None
+        if bb is not None:
+            x, y, c, r = bb
+            ball = Box(x - r, y - r, x + r, y + r, c)
+        dets.append(Detection(person=None, ball=ball))
+
+    progress(0.55, desc="Finding your goals…")
+    cuts = goal_mod.detect_cuts(clip.frames)
+    per_region = [goal_mod.find_goal_events(dets, r, min_gap=int(fps * 2), cuts=cuts, fps=fps)
+                  for r in regions]
+    events = goal_mod.merge_goal_events(per_region, fps=fps, refractory_s=5.0)
+    if not events:
+        raise gr.Error("No goals detected in this clip. Tip: include the moment the ball "
+                       "crosses the line, filmed from behind/side of the attack.")
+
+    progress(0.65, desc=f"{len(events)} goal(s)! Analyzing your strikes…")
+    poses = _POSE.estimate(clip.frames)
+
+    cards = []
+    kick_frames = []
+    for gi, e in enumerate(events):
+        ge = goal_mod.attribute_scorer(dets, poses, e, lookback=int(fps * 4), cuts=cuts)
+        head = f"### ⚽ GOAL #{gi + 1} — at {clip.time_of(e):.1f}s"
+        if ge is None:
+            cards.append(head + "\n\n*Couldn't isolate the kick for this one.*")
+            continue
+        ci = ge.contact_frame
+        kick_frames.append(ci)
+        contact = ContactResult(frame_idx=ci, kicking_side=ge.kicking_side,
+                                method="goal_backtrack", confidence=ge.confidence,
+                                ball_track=ge.ball_track)
+        fs = biomechanics.compute_features(poses, dets, contact)
+        traj = trajectory_mod.compute_trajectory(dets, contact)
+        if traj.valid:
+            fs.features.append(trajectory_mod.launch_angle_feature(traj))
+        rep = _COACH.coach(fs)
+        rows = "\n".join(
+            f"| {f.label} | {'—' if f.value is None else f'{f.value:.0f} {f.unit}'} | "
+            f"{ {'good':'🟢','amber':'🟡','poor':'🔴','na':'⚪'}[f.band] } {f.band.upper()} |"
+            for f in fs.features)
+        cards.append(
+            f"{head} · kick at {clip.time_of(ci):.1f}s · **{rep.score}/100**\n\n"
+            f"**{rep.summary}**\n\n"
+            f"| Feature | Measured | Band |\n|---|---|---|\n{rows}\n\n"
+            f"**Cues:** " + " · ".join(rep.cues[:3]) + "\n\n"
+            f"**Drills:** " + " · ".join(rep.drills[:2]))
+
+    progress(0.9, desc="Rendering your highlight video…")
+    out_path = _render(clip, dets, regions, events, kick_frames, fps)
+
+    md = (f"## 🏆 {len(events)} goal(s) found in {time.time()-t0:.0f}s\n\n"
+          + "\n\n---\n\n".join(cards)
+          + "\n\n<sub>FUT-HEROS · zero-shot vision (SAM3 goal + RF-DETR ball) + "
+            "football logic + biomechanics. Bands not lab-degrees — honest coaching.</sub>")
+    return out_path, md
+
+
+def _render(clip, dets, regions, events, kick_frames_list, fps):
+    kick_frames = set()
+    for c in kick_frames_list:
+        kick_frames.update(range(max(0, c - int(fps * 0.15)), c + int(fps * 0.35)))
+    H, W = clip.frames[0].shape[:2]
+    banner = int(fps * 1.6)
+    max_jump = 90.0 * max(1.0, 60.0 / fps)
+    ball_xy = np.array([[d.ball.cx, d.ball.cy] if d.ball else [np.nan, np.nan]
+                        for d in dets], np.float32)
+    frames_out = []
+    trail = []
+    for i, f in enumerate(clip.frames):
+        v = f.copy()
+        for r in regions:
+            cv2.polylines(v, [r.poly.astype(np.int32)], True, (0, 0, 255), 2)
+        if not np.isnan(ball_xy[i][0]):
+            if trail and (i - trail[-1][0] > 5 or np.linalg.norm(ball_xy[i] - trail[-1][1]) > max_jump):
+                trail = []
+            trail.append((i, ball_xy[i]))
+        trail = [(j, q) for j, q in trail if i - j <= int(fps)]
+        for k in range(1, len(trail)):
+            cv2.line(v, tuple(trail[k - 1][1].astype(int)), tuple(trail[k][1].astype(int)),
+                     (0, 255, 255), 2)
+        if not np.isnan(ball_xy[i][0]):
+            cv2.circle(v, tuple(ball_xy[i].astype(int)), 10, (0, 255, 0), 2)
+        if i in kick_frames:
+            cv2.putText(v, "KICK", (W // 2 - 70, 90), cv2.FONT_HERSHEY_SIMPLEX, 1.6, (0, 140, 255), 4)
+        for gidx, e in enumerate(events):
+            if e <= i < e + banner:
+                cv2.rectangle(v, (0, 0), (W - 1, H - 1), (0, 200, 0), 10)
+                cv2.putText(v, f"GOAL #{gidx + 1}", (W // 2 - 130, 60),
+                            cv2.FONT_HERSHEY_SIMPLEX, 1.6, (0, 230, 0), 4)
+        frames_out.append(v)
+    out = f"/tmp/futheros_{int(time.time())}.mp4"
+    OpenCvVideoSink().write(frames_out, out, fps)
+    return out
+
+
+with gr.Blocks(title="FUT-HEROS", theme=gr.themes.Soft(primary_hue="green")) as demo:
+    gr.Markdown(
+        "# ⚽ FUT-HEROS\n"
+        "**Upload your match or highlight clip → it finds the goal post, tracks the ball, "
+        "detects YOUR goals, and coaches every scoring strike.**\n\n"
+        "Zero-shot vision (SAM3 + RF-DETR Nano) · football-rules event logic · "
+        "biomechanics scorecard. Do you have World Cup form?"
+    )
+    with gr.Row():
+        with gr.Column(scale=1):
+            vid_in = gr.Video(label="Your clip (≤ ~40s analyzed)", sources=["upload"])
+            go = gr.Button("⚽ Find my goals & coach me", variant="primary", size="lg")
+            gr.Markdown("*Works best when the goal and the ball are visible — side or corner "
+                        "view, fixed camera. Highlight montages with cuts are fine.*")
+        with gr.Column(scale=2):
+            report = gr.Markdown()
+    out_vid = gr.Video(label="Your annotated highlights (ball trail · KICK · GOAL)", autoplay=True)
+
+    go.click(analyze, inputs=[vid_in], outputs=[out_vid, report])
+
+demo.queue().launch()

futheros/__init__.py

@@ -0,0 +1,18 @@
+"""FUT-HEROS — football kick form coach (hexagonal architecture).
+
+Layers:
+  domain/       pure analysis (geometry, contact, biomechanics, coaching rules) — no I/O
+  ports/        abstract interfaces (Protocols) the application depends on
+  adapters/     concrete backends (RF-DETR, YOLO, MediaPipe, llama.cpp, OpenCV)
+  application/  the use-case service + composition root (wires adapters to ports)
+
+Public API:
+  from futheros import build_service, Settings
+  svc = build_service(Settings(detector="rfdetr", use_llm=True))
+  result = svc.analyze("clip.mp4")
+"""
+from .application import AnalyzeKickService, build_service
+from .application.factory import Settings
+
+__version__ = "0.2.0"
+__all__ = ["AnalyzeKickService", "build_service", "Settings"]

futheros/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Adapters — concrete implementations of ports (driven side of the hexagon).
+
+Each adapter wraps one external dependency (RF-DETR, YOLO, MediaPipe, llama.cpp,
+OpenCV) behind a port. Imports are kept inside constructors so a missing optional
+backend doesn't break the package import; the composition root handles fallback.
+"""

futheros/adapters/coach_llamacpp.py

@@ -0,0 +1,79 @@
+"""llama-cpp-python coach adapter — runs a tiny GGUF (Nemotron-3-Nano-4B primary,
+Qwen3-4B fallback). The LLM only ever sees the feature numbers, never the video.
+On malformed output it falls back to the pure rule-based report.
+"""
+from __future__ import annotations
+
+import json
+
+from ..domain.biomechanics import overall_score
+from ..domain.coaching import SYSTEM_PROMPT, build_user_prompt, rule_based_report
+from ..domain.models import CoachReport, FeatureSet
+from .infra_config import LLM_CANDIDATES, LLM_N_CTX, LLM_N_GPU_LAYERS
+
+
+class LlamaCppCoach:
+    def __init__(self, llm, name: str):
+        self._llm = llm
+        self.name = name
+
+    @classmethod
+    def load(cls, candidates=LLM_CANDIDATES) -> "LlamaCppCoach":
+        """Try each GGUF candidate in order; raise if none load."""
+        from llama_cpp import Llama
+        last_err: Exception | None = None
+        for c in candidates:
+            try:
+                llm = Llama.from_pretrained(
+                    repo_id=c["repo_id"], filename=c["filename"],
+                    n_gpu_layers=LLM_N_GPU_LAYERS, n_ctx=LLM_N_CTX, verbose=False,
+                )
+                return cls(llm, c["name"])
+            except Exception as e:  # noqa: BLE001
+                last_err = e
+        raise RuntimeError(f"No coaching LLM could be loaded: {last_err}")
+
+    def coach(self, feature_set: FeatureSet) -> CoachReport:
+        score = overall_score(feature_set)
+        try:
+            out = self._llm.create_chat_completion(
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": build_user_prompt(feature_set)},
+                ],
+                temperature=0.4, max_tokens=512,
+                response_format={"type": "json_object"},
+            )
+            data = _parse_json(out["choices"][0]["message"]["content"])
+        except Exception:
+            data = None
+
+        if not data or "summary" not in data:
+            rep = rule_based_report(feature_set)
+            rep.engine = f"{self.name}+rule-fallback"
+            return rep
+
+        return CoachReport(
+            summary=str(data.get("summary", "")).strip(),
+            cues=[str(c).strip() for c in data.get("cues", []) if str(c).strip()][:4],
+            drills=[str(d).strip() for d in data.get("drills", []) if str(d).strip()][:3],
+            score=score, engine=self.name,
+        )
+
+
+def _parse_json(text: str):
+    text = (text or "").strip()
+    if text.startswith("```"):
+        text = text.strip("`")
+        if text.lower().startswith("json"):
+            text = text[4:]
+    try:
+        return json.loads(text)
+    except Exception:
+        a, b = text.find("{"), text.rfind("}")
+        if a != -1 and b > a:
+            try:
+                return json.loads(text[a:b + 1])
+            except Exception:
+                return None
+    return None

futheros/adapters/coach_rule.py

@@ -0,0 +1,12 @@
+"""Rule-based coach adapter — wraps the pure domain coaching logic. Always available."""
+from __future__ import annotations
+
+from ..domain.coaching import rule_based_report
+from ..domain.models import CoachReport, FeatureSet
+
+
+class RuleCoach:
+    name = "rule"
+
+    def coach(self, feature_set: FeatureSet) -> CoachReport:
+        return rule_based_report(feature_set)

futheros/adapters/detector_base.py

@@ -0,0 +1,79 @@
+"""Shared detection post-processing: pick the subject person, pick the ball, and
+temporally interpolate the ball track. Concrete backends supply only raw per-frame
+boxes; this module turns them into the Detection stream the domain expects.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from ..domain.config import BALL_MAX_INTERP_GAP
+from ..domain.models import Box, Detection
+
+
+def pick_person(persons: list[Box], prev: Box | None) -> Box | None:
+    if not persons:
+        return None
+    if prev is not None:
+        return min(persons, key=lambda b: (b.cx - prev.cx) ** 2 + (b.cy - prev.cy) ** 2)
+    return max(persons, key=lambda b: b.area)
+
+
+def pick_ball(balls: list[Box], person: Box | None) -> Box | None:
+    if not balls:
+        return None
+    if person is not None:
+        diag = ((person.x2 - person.x1) ** 2 + (person.y2 - person.y1) ** 2) ** 0.5 + 1e-6
+
+        def score(b: Box) -> float:
+            d = ((b.cx - person.cx) ** 2 + (b.cy - person.cy) ** 2) ** 0.5
+            return b.conf - 0.15 * (d / diag)
+        return max(balls, key=score)
+    return max(balls, key=lambda b: b.conf)
+
+
+def interpolate_balls(dets: list[Detection], max_gap: int = BALL_MAX_INTERP_GAP) -> None:
+    idxs = [i for i, d in enumerate(dets) if d.ball is not None]
+    for a, b in zip(idxs, idxs[1:]):
+        gap = b - a
+        if 1 < gap <= max_gap + 1:
+            ba, bb = dets[a].ball, dets[b].ball
+            for k in range(1, gap):
+                t = k / gap
+                dets[a + k].ball = Box(
+                    ba.x1 + t * (bb.x1 - ba.x1), ba.y1 + t * (bb.y1 - ba.y1),
+                    ba.x2 + t * (bb.x2 - ba.x2), ba.y2 + t * (bb.y2 - ba.y2),
+                    min(ba.conf, bb.conf) * 0.5,
+                )
+                dets[a + k].ball_interpolated = True
+
+
+def assemble(per_frame_boxes, track: bool = True) -> list[Detection]:
+    """per_frame_boxes: iterable of (persons:list[Box], balls:list[Box]).
+
+    When `track`, lock onto the kicker via ByteTrack (robust to crowds); otherwise
+    fall back to greedy nearest/largest person selection.
+    """
+    frames = [(list(p), list(b)) for p, b in per_frame_boxes]
+    # best ball per frame, independent of person (needed before subject selection)
+    best_balls = [max(b, key=lambda x: x.conf) if b else None for _, b in frames]
+
+    subject_boxes = None
+    if track:
+        try:
+            from .subject_tracking import lock_subject
+            subject_boxes = lock_subject([p for p, _ in frames], best_balls)
+        except Exception:
+            subject_boxes = None
+
+    dets: list[Detection] = []
+    prev_person: Box | None = None
+    for i, (persons, balls) in enumerate(frames):
+        if subject_boxes is not None:
+            person = subject_boxes[i]
+        else:
+            person = pick_person(persons, prev_person)
+        if person is not None:
+            prev_person = person
+        dets.append(Detection(person=person, ball=pick_ball(balls, person)))
+    interpolate_balls(dets)
+    return dets

futheros/adapters/detector_null.py

@@ -0,0 +1,14 @@
+"""Null detector — used when no detection backend is available. The pipeline then
+runs pose-only; ball-dependent features degrade to 'na' (honest, not crashing)."""
+from __future__ import annotations
+
+import numpy as np
+
+from ..domain.models import Detection
+
+
+class NullDetector:
+    name = "none"
+
+    def detect(self, frames_bgr: list[np.ndarray]) -> list[Detection]:
+        return [Detection() for _ in frames_bgr]

futheros/adapters/detector_rfdetr.py

@@ -0,0 +1,54 @@
+"""RF-DETR detector adapter (primary). COCO person+ball, Apache-2.0, DINOv2.
+
+RF-DETR emits 91-class COCO label ids (person=1, sports ball=37) — NOT the 80-class
+contiguous ids YOLO uses (person=0, ball=32). We resolve the ids from RF-DETR's own
+label map by name so the adapter is correct regardless of the indexing convention.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from ..domain.config import BALL_CONF, PERSON_CONF
+from ..domain.models import Box, Detection
+from .detector_base import assemble
+
+
+def _resolve_ids():
+    """Map 'person' and 'sports ball' -> RF-DETR class ids via its COCO label map."""
+    from rfdetr.util.coco_classes import COCO_CLASSES
+    items = COCO_CLASSES.items() if isinstance(COCO_CLASSES, dict) else enumerate(COCO_CLASSES)
+    name_to_id = {n: i for i, n in items}
+    return name_to_id.get("person", 1), name_to_id.get("sports ball", 37)
+
+
+class RFDetrDetector:
+    name = "rfdetr"
+
+    def __init__(self, model_cls: str = "nano", resolution: int | None = None):
+        import rfdetr
+        registry = {"nano": rfdetr.RFDETRNano, "small": rfdetr.RFDETRSmall,
+                    "medium": rfdetr.RFDETRMedium, "large": rfdetr.RFDETRLarge}
+        if model_cls in ("xlarge", "2xlarge"):
+            # XL/2XL ship in the rfdetr-plus extra (PML 1.0 license, not Apache)
+            import rfdetr_plus
+            registry["xlarge"] = rfdetr_plus.RFDETRXLarge
+            registry["2xlarge"] = rfdetr_plus.RFDETR2XLarge
+        cls = registry[model_cls]
+        self._model = cls(resolution=resolution) if resolution else cls()
+        self._person_id, self._ball_id = _resolve_ids()
+        self.name = f"rfdetr-{model_cls}"
+
+    def _frame_boxes(self, frame_rgb: np.ndarray):
+        det = self._model.predict(frame_rgb, threshold=BALL_CONF)
+        persons, balls = [], []
+        for box, c, cf in zip(det.xyxy, det.class_id, det.confidence):
+            b = Box(float(box[0]), float(box[1]), float(box[2]), float(box[3]), float(cf))
+            if int(c) == self._person_id and cf >= PERSON_CONF:
+                persons.append(b)
+            elif int(c) == self._ball_id and cf >= BALL_CONF:
+                balls.append(b)
+        return persons, balls
+
+    def detect(self, frames_bgr: list[np.ndarray]) -> list[Detection]:
+        # contiguous copy: torchvision.to_tensor rejects the negative stride from [..., ::-1]
+        return assemble(self._frame_boxes(np.ascontiguousarray(f[:, :, ::-1])) for f in frames_bgr)

futheros/adapters/detector_yolo.py

@@ -0,0 +1,33 @@
+"""Ultralytics YOLO11 detector adapter (fallback). COCO person+ball."""
+from __future__ import annotations
+
+import numpy as np
+
+from ..domain.config import BALL_CONF, COCO_PERSON, COCO_SPORTS_BALL, PERSON_CONF
+from ..domain.models import Box, Detection
+from .detector_base import assemble
+
+
+class YoloDetector:
+    name = "yolo"
+
+    def __init__(self, weights: str = "yolo11n.pt"):
+        from ultralytics import YOLO
+        self._model = YOLO(weights)
+
+    def _frame_boxes(self, frame_rgb: np.ndarray):
+        res = self._model.predict(frame_rgb, conf=BALL_CONF,
+                                  classes=[COCO_PERSON, COCO_SPORTS_BALL], verbose=False)[0]
+        persons, balls = [], []
+        for box in res.boxes:
+            c = int(box.cls[0]); cf = float(box.conf[0])
+            xy = box.xyxy[0].tolist()
+            b = Box(xy[0], xy[1], xy[2], xy[3], cf)
+            if c == COCO_PERSON and cf >= PERSON_CONF:
+                persons.append(b)
+            elif c == COCO_SPORTS_BALL:
+                balls.append(b)
+        return persons, balls
+
+    def detect(self, frames_bgr: list[np.ndarray]) -> list[Detection]:
+        return assemble(self._frame_boxes(f[:, :, ::-1]) for f in frames_bgr)

futheros/adapters/goal_annotations.py

@@ -0,0 +1,47 @@
+"""Persistent goal-mouth annotations.
+
+The cameras are fixed, so the goal mouth is annotated ONCE per video (a 4-point
+polygon = the goal plane as projected in the image) and recorded in
+annotations/goals.json keyed by the video's basename. Every later run reuses it —
+no re-annotation, no SAM3 dependency for annotated videos.
+
+Schema:
+{
+  "<video basename>": [
+     {"name": "goal-1", "polygon": [[x,y],[x,y],[x,y],[x,y]]},
+     ...
+  ]
+}
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+
+ANNOT_FILE = Path(__file__).resolve().parents[2] / "annotations" / "goals.json"
+
+
+def _load_all() -> dict:
+    if ANNOT_FILE.exists():
+        return json.loads(ANNOT_FILE.read_text())
+    return {}
+
+
+def load_goal_polygons(video_path: str) -> list[np.ndarray]:
+    """Polygons annotated for this video (possibly empty)."""
+    key = os.path.basename(video_path)
+    entries = _load_all().get(key, [])
+    return [np.array(e["polygon"], dtype=np.float32) for e in entries]
+
+
+def save_goal_polygons(video_path: str, polygons: list[np.ndarray]) -> str:
+    key = os.path.basename(video_path)
+    data = _load_all()
+    data[key] = [{"name": f"goal-{i+1}", "polygon": np.asarray(p).astype(float).tolist()}
+                 for i, p in enumerate(polygons)]
+    ANNOT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    ANNOT_FILE.write_text(json.dumps(data, indent=2))
+    return str(ANNOT_FILE)

futheros/adapters/goal_detector_sam3.py

@@ -0,0 +1,71 @@
+"""SAM3 zero-shot goal detector (facebook/sam3 via Meta's `sam3` package).
+
+Text-prompted: prompt "goal post" returns the goal-mouth box(es) with no annotation
+or fine-tuning. Validated on indoor (0.72) and outdoor (0.65–0.87) footage. The model
+is heavy (~1.3GB, slow first load) so we load it lazily and, since the match camera is
+fixed, the caller runs it once per clip.
+
+Weights download from HF — needs HUGGINGFACE_TOKEN in the environment / .env.
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+from PIL import Image
+
+from ..domain.models import Box
+
+def _find_bpe() -> str | None:
+    """Locate the CLIP BPE vocab SAM3 needs (its own default asset path is missing).
+    Order: SAM3_BPE_PATH env -> assets/ next to the package root -> `clip` package."""
+    p = os.environ.get("SAM3_BPE_PATH")
+    if p and os.path.exists(p):
+        return p
+    here = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    p = os.path.join(here, "assets", "bpe_simple_vocab_16e6.txt.gz")
+    if os.path.exists(p):
+        return p
+    try:
+        import clip
+        p = os.path.join(os.path.dirname(clip.__file__), "bpe_simple_vocab_16e6.txt.gz")
+        return p if os.path.exists(p) else None
+    except Exception:
+        return None
+
+
+class Sam3GoalDetector:
+    name = "sam3-goal"
+
+    def __init__(self, prompt: str = "goal post", device: str = "cuda"):
+        self.prompt = prompt
+        self._device = device
+        self._processor = None
+
+    def _ensure_loaded(self):
+        if self._processor is not None:
+            return
+        # surface HF token for the weight download
+        tok = os.environ.get("HUGGINGFACE_TOKEN") or os.environ.get("HF_TOKEN")
+        if tok:
+            os.environ.setdefault("HF_TOKEN", tok)
+            os.environ.setdefault("HUGGING_FACE_HUB_TOKEN", tok)
+        from sam3.model_builder import build_sam3_image_model
+        from sam3.model.sam3_image_processor import Sam3Processor
+        model = build_sam3_image_model(bpe_path=_find_bpe(), device=self._device, load_from_HF=True)
+        self._processor = Sam3Processor(model)
+
+    def detect_goals(self, frame_bgr: np.ndarray, conf: float = 0.4) -> list[Box]:
+        self._ensure_loaded()
+        image = Image.fromarray(frame_bgr[:, :, ::-1])
+        state = self._processor.set_image(image)
+        out = self._processor.set_text_prompt(state=state, prompt=self.prompt)
+        boxes = out["boxes"]; scores = out["scores"]
+        boxes = boxes.cpu().numpy() if hasattr(boxes, "cpu") else np.asarray(boxes)
+        scores = scores.cpu().numpy() if hasattr(scores, "cpu") else np.asarray(scores)
+        result: list[Box] = []
+        for b, s in zip(boxes, scores):
+            if float(s) >= conf:
+                result.append(Box(float(b[0]), float(b[1]), float(b[2]), float(b[3]), float(s)))
+        result.sort(key=lambda bx: bx.conf, reverse=True)
+        return result

futheros/adapters/infra_config.py

@@ -0,0 +1,25 @@
+"""Infrastructure config — model repos, download URLs, GPU settings.
+
+Kept in the adapters layer (not the domain) because these are deployment concerns.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+MODELS_DIR = Path(__file__).resolve().parents[2] / "models"
+
+# MediaPipe Pose Landmarker (Tasks API) .task bundle
+POSE_TASK_URL = (
+    "https://storage.googleapis.com/mediapipe-models/pose_landmarker/"
+    "pose_landmarker_full/float16/latest/pose_landmarker_full.task"
+)
+POSE_TASK_FILE = MODELS_DIR / "pose_landmarker_full.task"
+
+# Coaching LLM GGUF candidates (tried in order). Primary = Nemotron (Quest+Tiny Titan).
+LLM_CANDIDATES = [
+    {"repo_id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF", "filename": "*Q4_K_M.gguf", "name": "Nemotron-3-Nano-4B"},
+    {"repo_id": "unsloth/Qwen3-4B-Instruct-2507-GGUF", "filename": "*Q4_K_M.gguf", "name": "Qwen3-4B-Instruct"},
+    {"repo_id": "Qwen/Qwen2.5-3B-Instruct-GGUF", "filename": "*q4_k_m.gguf", "name": "Qwen2.5-3B-Instruct"},
+]
+LLM_N_CTX = 4096
+LLM_N_GPU_LAYERS = -1     # offload all layers to the GPU

futheros/adapters/pose_mediapipe.py

@@ -0,0 +1,65 @@
+"""MediaPipe Pose adapter using the current Tasks API (PoseLandmarker).
+
+mediapipe >=0.10.x dropped the legacy `mp.solutions.pose` module in favour of the
+Tasks API, which needs a `.task` model bundle. We auto-download it once to models/.
+We use only the 2D (x,y) image-plane landmarks + visibility — never the Z axis.
+"""
+from __future__ import annotations
+
+import urllib.request
+
+import numpy as np
+
+from ..domain.models import FramePose
+from .infra_config import POSE_TASK_FILE, POSE_TASK_URL
+
+
+def _ensure_model() -> str:
+    if not POSE_TASK_FILE.exists():
+        POSE_TASK_FILE.parent.mkdir(parents=True, exist_ok=True)
+        urllib.request.urlretrieve(POSE_TASK_URL, POSE_TASK_FILE)
+    return str(POSE_TASK_FILE)
+
+
+class MediaPipePose:
+    name = "mediapipe-pose"
+
+    def __init__(self):
+        import mediapipe as mp
+        from mediapipe.tasks import python
+        from mediapipe.tasks.python import vision
+
+        self._mp = mp
+        model_path = _ensure_model()
+        options = vision.PoseLandmarkerOptions(
+            base_options=python.BaseOptions(model_asset_path=model_path),
+            running_mode=vision.RunningMode.IMAGE,
+            num_poses=1,
+            min_pose_detection_confidence=0.5,
+            min_pose_presence_confidence=0.5,
+            min_tracking_confidence=0.5,
+            output_segmentation_masks=False,
+        )
+        self._landmarker = vision.PoseLandmarker.create_from_options(options)
+
+    def estimate(self, frames_bgr: list[np.ndarray]) -> list[FramePose]:
+        out: list[FramePose] = []
+        for f in frames_bgr:
+            h, w = f.shape[:2]
+            rgb = np.ascontiguousarray(f[:, :, ::-1])
+            mp_image = self._mp.Image(image_format=self._mp.ImageFormat.SRGB, data=rgb)
+            res = self._landmarker.detect(mp_image)
+            if not res.pose_landmarks:
+                out.append(FramePose(None, None))
+                continue
+            lms = res.pose_landmarks[0]
+            xy = np.array([[lm.x * w, lm.y * h] for lm in lms], dtype=np.float32)
+            vis = np.array([lm.visibility for lm in lms], dtype=np.float32)
+            out.append(FramePose(xy=xy, vis=vis))
+        return out
+
+    def close(self) -> None:
+        try:
+            self._landmarker.close()
+        except Exception:
+            pass

futheros/adapters/renderer_opencv.py

@@ -0,0 +1,130 @@
+"""OpenCV renderer adapter: skeleton overlay, ball marker, contact flash, hero
+freeze-frame, scorecard. Pure cv2/numpy — no extra deps.
+
+A SAM 3D Body mesh (optional "wow" hero shot) composites in via hero(..., mesh_img=).
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from ..domain.config import LM
+from ..domain.models import (Clip, ContactResult, Detection, FeatureSet, FramePose,
+                             Trajectory)
+
+_EDGES = [
+    ("l_shoulder", "r_shoulder"), ("l_shoulder", "l_hip"), ("r_shoulder", "r_hip"),
+    ("l_hip", "r_hip"),
+    ("l_shoulder", "l_elbow"), ("r_shoulder", "r_elbow"),
+    ("l_hip", "l_knee"), ("l_knee", "l_ankle"), ("l_ankle", "l_foot"),
+    ("r_hip", "r_knee"), ("r_knee", "r_ankle"), ("r_ankle", "r_foot"),
+]
+_BAND_BGR = {"good": (90, 200, 90), "amber": (40, 190, 240),
+             "poor": (60, 60, 235), "na": (150, 150, 150)}
+
+
+def _p(pose: FramePose, name: str):
+    if pose.xy is None:
+        return None
+    i = LM[name]
+    if pose.vis is not None and pose.vis[i] < 0.2:
+        return None
+    return tuple(int(v) for v in pose.xy[i])
+
+
+class OpenCvRenderer:
+    def _draw(self, frame, pose, det, kicking_side, is_contact=False):
+        img = frame.copy()
+        if pose.ok():
+            for a, b in _EDGES:
+                pa, pb = _p(pose, a), _p(pose, b)
+                if pa and pb:
+                    on_kick = a.startswith(kicking_side) or b.startswith(kicking_side)
+                    cv2.line(img, pa, pb, (0, 215, 255) if on_kick else (235, 235, 235), 2, cv2.LINE_AA)
+            for name in LM:
+                pt = _p(pose, name)
+                if pt:
+                    cv2.circle(img, pt, 3, (0, 140, 255), -1, cv2.LINE_AA)
+        if det.ball is not None:
+            c = (int(det.ball.cx), int(det.ball.cy))
+            r = max(4, int(det.ball.radius))
+            cv2.circle(img, c, r, (0, 255, 0) if not det.ball_interpolated else (0, 200, 120), 2, cv2.LINE_AA)
+        if is_contact:
+            h, w = img.shape[:2]
+            cv2.rectangle(img, (0, 0), (w - 1, h - 1), (0, 0, 255), 6)
+            cv2.putText(img, "CONTACT", (12, 40), cv2.FONT_HERSHEY_SIMPLEX, 1.1, (0, 0, 255), 3, cv2.LINE_AA)
+        return img
+
+    def _draw_trajectory(self, img, trajectory: Trajectory | None, upto: int | None = None):
+        """Draw the ball path as a fading polyline. `upto` limits to frames <= upto
+        (so the trail grows over the video); None draws the whole post-contact arc."""
+        if trajectory is None or not trajectory.valid:
+            return
+        pts = [(i, x, y) for (i, x, y) in trajectory.post_points if upto is None or i <= upto]
+        if len(pts) < 2:
+            return
+        for j in range(1, len(pts)):
+            p0 = (int(pts[j - 1][1]), int(pts[j - 1][2]))
+            p1 = (int(pts[j][1]), int(pts[j][2]))
+            t = j / len(pts)
+            col = (0, int(120 + 135 * t), 255)        # orange→yellow trail
+            cv2.line(img, p0, p1, col, max(2, int(2 + 3 * t)), cv2.LINE_AA)
+        cv2.circle(img, (int(pts[-1][1]), int(pts[-1][2])), 5, (0, 255, 255), -1, cv2.LINE_AA)
+
+    def annotate(self, clip: Clip, poses, dets, fs: FeatureSet, contact: ContactResult,
+                 trajectory: Trajectory | None = None):
+        out = []
+        for i, f in enumerate(clip.frames):
+            img = self._draw(f, poses[i], dets[i], fs.kicking_side, is_contact=(i == contact.frame_idx))
+            if i >= contact.frame_idx:
+                self._draw_trajectory(img, trajectory, upto=i)
+            out.append(img)
+        return out
+
+    def hero(self, clip: Clip, poses, dets, fs: FeatureSet, contact: ContactResult,
+             trajectory: Trajectory | None = None, mesh_img: np.ndarray | None = None):
+        ci = contact.frame_idx
+        base = self._draw(clip.frames[ci], poses[ci], dets[ci], fs.kicking_side, is_contact=True)
+        self._draw_trajectory(base, trajectory, upto=None)
+        if trajectory is not None and trajectory.valid:
+            cv2.putText(base, f"Launch: {trajectory.launch_angle_deg:.0f} deg {trajectory.direction}",
+                        (12, base.shape[0] - 18), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 0), 4, cv2.LINE_AA)
+            cv2.putText(base, f"Launch: {trajectory.launch_angle_deg:.0f} deg {trajectory.direction}",
+                        (12, base.shape[0] - 18), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 255), 1, cv2.LINE_AA)
+        y0 = 70
+        for f in fs.features[:3]:
+            col = _BAND_BGR.get(f.band, (200, 200, 200))
+            txt = f"{f.label}: {f.band.upper()}"
+            if f.value is not None:
+                txt += f" ({f.value:.0f}{'' if f.unit in ('shank', 'leg') else 'deg'})"
+            cv2.putText(base, txt, (12, y0), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 4, cv2.LINE_AA)
+            cv2.putText(base, txt, (12, y0), cv2.FONT_HERSHEY_SIMPLEX, 0.6, col, 1, cv2.LINE_AA)
+            y0 += 28
+        if mesh_img is not None:
+            h = base.shape[0]
+            mesh_r = cv2.resize(mesh_img, (int(mesh_img.shape[1] * h / mesh_img.shape[0]), h))
+            base = np.hstack([base, mesh_r])
+        return base
+
+    def scorecard(self, fs: FeatureSet, score: int, width: int = 720):
+        rows, row_h, head_h = len(fs.features), 64, 110
+        h = head_h + rows * row_h + 24
+        img = np.full((h, width, 3), 250, np.uint8)
+        cv2.rectangle(img, (0, 0), (width, head_h), (38, 28, 22), -1)
+        cv2.putText(img, "FUT-HEROS  Form Scorecard", (24, 46),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (255, 255, 255), 2, cv2.LINE_AA)
+        sc_col = (90, 200, 90) if score >= 80 else (40, 190, 240) if score >= 55 else (60, 60, 235)
+        cv2.putText(img, f"{score}", (width - 150, 64), cv2.FONT_HERSHEY_SIMPLEX, 1.8, sc_col, 4, cv2.LINE_AA)
+        cv2.putText(img, "/100", (width - 70, 64), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (200, 200, 200), 2, cv2.LINE_AA)
+        y = head_h + 12
+        for f in fs.features:
+            col = _BAND_BGR.get(f.band, (150, 150, 150))
+            cv2.putText(img, f.label, (24, y + 24), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (40, 40, 40), 1, cv2.LINE_AA)
+            fill = {"good": 1.0, "amber": 0.55, "poor": 0.2, "na": 0.0}[f.band]
+            bx, bw = 24, width - 48
+            cv2.rectangle(img, (bx, y + 34), (bx + bw, y + 50), (225, 225, 225), -1)
+            cv2.rectangle(img, (bx, y + 34), (bx + int(bw * fill), y + 50), col, -1)
+            label = f.band.upper() if f.band != "na" else "NOT VISIBLE"
+            cv2.putText(img, label, (bx + bw - 130, y + 47), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (30, 30, 30), 1, cv2.LINE_AA)
+            y += row_h
+        return img

futheros/adapters/subject_tracking.py

@@ -0,0 +1,69 @@
+"""Subject lock via ByteTrack (supervision).
+
+In a crowded frame, "which person is the kicker?" can't be answered by size alone.
+We give every person a stable track id with ByteTrack, then lock onto the track whose
+foot gets *closest to the ball* across the whole clip — that's the striker. The chosen
+track's box is returned per frame, so pose/features follow one person, not whoever is
+biggest. Falls back cleanly if supervision is unavailable.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from ..domain.models import Box
+
+
+def lock_subject(persons_per_frame: list[list[Box]],
+                 balls_per_frame: list[Box | None]) -> list[Box | None] | None:
+    """Return the subject's Box per frame (or None where absent). None if tracking
+    can't run (caller then falls back to greedy selection)."""
+    import supervision as sv
+
+    n = len(persons_per_frame)
+    tracker = sv.ByteTrack()
+    frame_tracks: list[dict[int, Box]] = []
+
+    for persons in persons_per_frame:
+        if persons:
+            det = sv.Detections(
+                xyxy=np.array([[b.x1, b.y1, b.x2, b.y2] for b in persons], dtype=float),
+                confidence=np.array([b.conf for b in persons], dtype=float),
+                class_id=np.zeros(len(persons), dtype=int),
+            )
+        else:
+            det = sv.Detections.empty()
+        det = tracker.update_with_detections(det)
+
+        tracks: dict[int, Box] = {}
+        if det.tracker_id is not None:
+            for k in range(len(det)):
+                tid = int(det.tracker_id[k])
+                x1, y1, x2, y2 = det.xyxy[k]
+                cf = float(det.confidence[k]) if det.confidence is not None else 0.0
+                tracks[tid] = Box(float(x1), float(y1), float(x2), float(y2), cf)
+        frame_tracks.append(tracks)
+
+    # subject = track whose foot (box bottom-centre) gets nearest the ball
+    track_min: dict[int, float] = {}
+    for i, tracks in enumerate(frame_tracks):
+        ball = balls_per_frame[i]
+        if ball is None:
+            continue
+        for tid, box in tracks.items():
+            foot = np.array([(box.x1 + box.x2) / 2, box.y2])
+            d = float(np.linalg.norm(foot - ball.center))
+            track_min[tid] = min(track_min.get(tid, 1e18), d)
+
+    if track_min:
+        subject_tid = min(track_min, key=track_min.get)
+    else:
+        # no ball anywhere -> the track closest to camera (largest cumulative area)
+        area: dict[int, float] = {}
+        for tracks in frame_tracks:
+            for tid, box in tracks.items():
+                area[tid] = area.get(tid, 0.0) + box.area
+        if not area:
+            return None
+        subject_tid = max(area, key=area.get)
+
+    return [frame_tracks[i].get(subject_tid) for i in range(n)]

futheros/adapters/tracker_sam3_video.py

@@ -0,0 +1,142 @@
+"""SAM3 VIDEO tracker — text-prompted, zero-shot, with temporal memory.
+
+Prompt once (e.g. "ball"); SAM3 segments matching objects and TRACKS each with a
+stable object id across the whole clip, surviving blur/occlusion via its memory.
+This natively provides what per-frame detectors need heuristics for: identity over
+time. The real match ball is then simply the object that moves the most.
+
+Heavy model: built lazily, weights from HF (needs HUGGINGFACE_TOKEN).
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+
+def _find_bpe() -> str | None:
+    try:
+        import clip
+        p = os.path.join(os.path.dirname(clip.__file__), "bpe_simple_vocab_16e6.txt.gz")
+        return p if os.path.exists(p) else None
+    except Exception:
+        return None
+
+
+class Sam3VideoTracker:
+    name = "sam3-video"
+
+    def __init__(self):
+        self._predictor = None
+
+    def _ensure_loaded(self):
+        if self._predictor is not None:
+            return
+        tok = os.environ.get("HUGGINGFACE_TOKEN") or os.environ.get("HF_TOKEN")
+        if tok:
+            os.environ.setdefault("HF_TOKEN", tok)
+            os.environ.setdefault("HUGGING_FACE_HUB_TOKEN", tok)
+        from sam3.model_builder import build_sam3_video_predictor
+        self._predictor = build_sam3_video_predictor(bpe_path=_find_bpe())
+
+    # SAM3 (this release) copies the WHOLE video to GPU regardless of its
+    # offload_video_to_cpu flag (_construct_initial_input_batch sends the full
+    # img_batch to device). ~1000 frames ≈ 12GB+, OOMing a 24GB card. So long
+    # clips are tracked in CHUNKS with overlap: SAM3 suppresses unconfirmed
+    # objects for its first ~1-2s (hotstart), so each chunk overlaps the previous
+    # one and the warm-up region is discarded.
+    CHUNK = 600
+    OVERLAP = 100
+
+    def track(self, video_path: str, prompt: str = "ball",
+              prompt_frame: int = 0) -> np.ndarray:
+        """Track all objects matching `prompt` through the video.
+
+        Returns an (N, 7) float32 array: [frame_idx, obj_id, cx, cy, prob, w, h]
+        (cx, cy, w, h normalized 0..1).
+        """
+        import cv2
+        cap = cv2.VideoCapture(str(video_path))
+        n = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+        cap.release()
+
+        if n <= self.CHUNK + self.OVERLAP:
+            return self._track_one(str(video_path), prompt, prompt_frame, frame_offset=0,
+                                   keep_from=0)
+
+        import subprocess
+        import tempfile
+        rows_all = []
+        with tempfile.TemporaryDirectory(prefix="sam3chunks_") as tmp:
+            for s in range(0, n, self.CHUNK):
+                cs = max(0, s - self.OVERLAP) if s > 0 else 0
+                ce = min(n, s + self.CHUNK)
+                chunk_path = os.path.join(tmp, f"chunk_{s}.mp4")
+                subprocess.run(
+                    ["ffmpeg", "-y", "-loglevel", "error",
+                     "-ss", f"{cs / fps:.4f}", "-i", str(video_path),
+                     "-frames:v", str(ce - cs),
+                     "-c:v", "libx264", "-preset", "veryfast", "-crf", "18",
+                     "-pix_fmt", "yuv420p", chunk_path],
+                    check=True)
+                part = self._track_one(chunk_path, prompt, prompt_frame=0,
+                                       frame_offset=cs, keep_from=s)
+                if len(part):
+                    rows_all.append(part)
+        return (np.concatenate(rows_all, axis=0) if rows_all
+                else np.zeros((0, 7), dtype=np.float32))
+
+    def _track_one(self, video_path: str, prompt: str, prompt_frame: int,
+                   frame_offset: int, keep_from: int) -> np.ndarray:
+        self._ensure_loaded()
+        p = self._predictor
+        resp = p.handle_request(request=dict(type="start_session", resource_path=video_path))
+        sid = resp["session_id"]
+        try:
+            p.handle_request(request=dict(type="add_prompt", session_id=sid,
+                                          frame_index=prompt_frame, text=prompt))
+            rows = []
+            for item in p.handle_stream_request(dict(type="propagate_in_video", session_id=sid)):
+                out = item["outputs"]
+                if out is None:
+                    continue
+                fi = frame_offset + item["frame_index"]
+                if fi < keep_from:
+                    continue          # warm-up overlap region, covered by previous chunk
+                for oid, prob, box in zip(out["out_obj_ids"], out["out_probs"], out["out_boxes_xywh"]):
+                    x, y, w, h = [float(v) for v in box]
+                    rows.append([fi, int(oid), x + w / 2, y + h / 2, float(prob), w, h])
+        finally:
+            try:
+                p.handle_request(request=dict(type="close_session", session_id=sid))
+            except Exception:
+                pass
+        return np.array(rows, dtype=np.float32) if rows else np.zeros((0, 7), dtype=np.float32)
+
+
+def pick_moving_object(track: np.ndarray, top_k: int = 1) -> list[int]:
+    """Object id(s) with the largest total displacement — the real ball moves,
+    static lookalikes (pitch logos, goal frames) do not."""
+    scores = {}
+    for oid in set(track[:, 1].astype(int)) if len(track) else []:
+        sub = track[track[:, 1] == oid]
+        if len(sub) < 2:
+            continue
+        scores[oid] = float(np.abs(np.diff(sub[:, 2])).sum() + np.abs(np.diff(sub[:, 3])).sum())
+    return [oid for oid, _ in sorted(scores.items(), key=lambda kv: -kv[1])[:top_k]]
+
+
+def to_ball_xy(track: np.ndarray, n_frames: int, obj_ids: list[int] | None = None) -> np.ndarray:
+    """Collapse the multi-object track to a per-frame ball position (n_frames, 2).
+    If obj_ids given, only those objects are considered; highest prob wins per frame."""
+    ball = np.full((n_frames, 2), np.nan, dtype=np.float32)
+    best = np.full(n_frames, -1.0, dtype=np.float32)
+    for r in track:
+        fi, oid, cx, cy, prob = int(r[0]), int(r[1]), r[2], r[3], r[4]
+        if obj_ids is not None and oid not in obj_ids:
+            continue
+        if 0 <= fi < n_frames and prob > best[fi]:
+            best[fi] = prob
+            ball[fi] = [cx, cy]
+    return ball

futheros/adapters/video_opencv.py

@@ -0,0 +1,132 @@
+"""OpenCV/ffmpeg video I/O adapter: load+auto-rotate to upright frames, write mp4.
+
+Phone clips often carry a rotation in container metadata (and WhatsApp re-encodes
+sideways). We read the rotation via ffprobe and apply it so the pose math sees an
+upright person; a UI control can override it.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from ..domain.config import MAX_FRAMES
+from ..domain.models import Clip
+
+
+class OpenCvVideoSource:
+    def load(self, path: str, force_rotation: int | None = None,
+             window: tuple[float, float] | None = None,
+             max_frames: int = MAX_FRAMES) -> Clip:
+        """Load a clip into upright BGR frames.
+
+        window=(start_s, end_s) loads only that time span at FULL fps (used when the
+        user pins their kick moment) — accurate and fast. Without a window we load the
+        whole clip, subsampling only if it exceeds max_frames.
+        """
+        path = str(path)
+        rot = force_rotation if force_rotation is not None else _ffprobe_rotation(path)
+
+        cap = cv2.VideoCapture(path)
+        if not cap.isOpened():
+            raise RuntimeError(f"Could not open video: {path}")
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+        total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+
+        if window is not None:
+            start_s, end_s = max(0.0, window[0]), window[1]
+            start_idx = int(start_s * fps)
+            end_idx = int(end_s * fps)
+            cap.set(cv2.CAP_PROP_POS_FRAMES, start_idx)
+            frames: list[np.ndarray] = []
+            idx = start_idx
+            while idx <= end_idx and len(frames) < max_frames:
+                ok, frame = cap.read()
+                if not ok:
+                    break
+                frames.append(_apply_rotation(frame, rot))
+                idx += 1
+            cap.release()
+            if not frames:
+                raise RuntimeError(f"No frames decoded from {path} in window {window}")
+            h, w = frames[0].shape[:2]
+            return Clip(frames=frames, fps=fps, width=w, height=h, t0_s=start_idx / fps)
+
+        step = int(np.ceil(total / max_frames)) if total and total > max_frames else 1
+        frames = []
+        idx = 0
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+            if idx % step == 0:
+                frames.append(_apply_rotation(frame, rot))
+            idx += 1
+            if len(frames) >= max_frames:
+                break
+        cap.release()
+        if not frames:
+            raise RuntimeError(f"No frames decoded from {path}")
+        h, w = frames[0].shape[:2]
+        return Clip(frames=frames, fps=fps / step, width=w, height=h)
+
+
+class OpenCvVideoSink:
+    def write(self, frames_bgr: list[np.ndarray], out_path: str, fps: float) -> str:
+        out_path = str(out_path)
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        h, w = frames_bgr[0].shape[:2]
+
+        if shutil.which("ffmpeg"):
+            cmd = ["ffmpeg", "-y", "-loglevel", "error", "-f", "rawvideo",
+                   "-pix_fmt", "bgr24", "-s", f"{w}x{h}", "-r", f"{fps:.4f}", "-i", "-",
+                   "-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart", out_path]
+            try:
+                proc = subprocess.Popen(cmd, stdin=subprocess.PIPE)
+                for f in frames_bgr:
+                    proc.stdin.write(np.ascontiguousarray(f).tobytes())
+                proc.stdin.close()
+                proc.wait()
+                if proc.returncode == 0 and Path(out_path).exists():
+                    return out_path
+            except Exception:
+                pass
+
+        vw = cv2.VideoWriter(out_path, cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
+        for f in frames_bgr:
+            vw.write(f)
+        vw.release()
+        return out_path
+
+
+def _ffprobe_rotation(path: str) -> int:
+    if not shutil.which("ffprobe"):
+        return 0
+    try:
+        out = subprocess.run(
+            ["ffprobe", "-v", "quiet", "-print_format", "json",
+             "-show_streams", "-select_streams", "v:0", path],
+            capture_output=True, text=True, timeout=20).stdout
+        st = (json.loads(out).get("streams") or [{}])[0]
+        rot = int((st.get("tags") or {}).get("rotate", 0) or 0)
+        for sd in st.get("side_data_list", []) or []:
+            if "rotation" in sd:
+                rot = int(sd["rotation"])
+        return rot % 360
+    except Exception:
+        return 0
+
+
+def _apply_rotation(frame: np.ndarray, rot: int) -> np.ndarray:
+    rot = rot % 360
+    if rot in (90, -270):
+        return cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+    if rot in (180, -180):
+        return cv2.rotate(frame, cv2.ROTATE_180)
+    if rot in (270, -90):
+        return cv2.rotate(frame, cv2.ROTATE_90_COUNTERCLOCKWISE)
+    return frame

futheros/application/__init__.py

@@ -0,0 +1,5 @@
+"""Application layer: the use-case service + the composition root that wires it."""
+from .factory import build_service
+from .service import AnalyzeKickService
+
+__all__ = ["AnalyzeKickService", "build_service"]

futheros/application/factory.py

@@ -0,0 +1,65 @@
+"""Composition root — the only place that knows about concrete adapters.
+
+Picks backends from settings, handles graceful fallback (RF-DETR→YOLO→null,
+LLM→rule), and injects everything into AnalyzeKickService. The rest of the app
+talks to ports only.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from .service import AnalyzeKickService
+
+log = logging.getLogger("futheros")
+
+
+@dataclass
+class Settings:
+    detector: str = "rfdetr"     # rfdetr | yolo
+    use_llm: bool = True
+    out_dir: str | None = None
+
+
+def _build_detector(prefer: str):
+    order = ["rfdetr", "yolo"] if prefer == "rfdetr" else ["yolo", "rfdetr"]
+    for name in order:
+        try:
+            if name == "rfdetr":
+                from ..adapters.detector_rfdetr import RFDetrDetector
+                return RFDetrDetector()
+            from ..adapters.detector_yolo import YoloDetector
+            return YoloDetector()
+        except Exception as e:  # noqa: BLE001
+            log.warning("detector %s unavailable: %s", name, e)
+    from ..adapters.detector_null import NullDetector
+    log.warning("no detector available — running pose-only")
+    return NullDetector()
+
+
+def _build_coach(use_llm: bool):
+    if use_llm:
+        try:
+            from ..adapters.coach_llamacpp import LlamaCppCoach
+            return LlamaCppCoach.load()
+        except Exception as e:  # noqa: BLE001
+            log.warning("LLM coach unavailable, using rule coach: %s", e)
+    from ..adapters.coach_rule import RuleCoach
+    return RuleCoach()
+
+
+def build_service(settings: Settings | None = None) -> AnalyzeKickService:
+    s = settings or Settings()
+    from ..adapters.pose_mediapipe import MediaPipePose
+    from ..adapters.renderer_opencv import OpenCvRenderer
+    from ..adapters.video_opencv import OpenCvVideoSink, OpenCvVideoSource
+
+    return AnalyzeKickService(
+        source=OpenCvVideoSource(),
+        sink=OpenCvVideoSink(),
+        detector=_build_detector(s.detector),
+        pose=MediaPipePose(),
+        coach=_build_coach(s.use_llm),
+        renderer=OpenCvRenderer(),
+        out_dir=s.out_dir,
+    )

futheros/application/match_service.py

@@ -0,0 +1,231 @@
+"""Match-mode use case: a match/highlight clip in → goals found → each scoring kick
+analyzed and coached.
+
+The validated detection recipe (8/8 on the test clips):
+  RF-DETR ball+player per frame → static-FP cleaning → cut-aware continuous runs →
+  goal planes (user annotation if present, else SAM3 zero-shot) → path-crossing +
+  flight-extrapolation → kickoff-return suppression → goal events →
+  backward walk to the leg-ball contact → pose on a BALL-CENTERED CROP at contact
+  (so the skeleton lands on the kicker, not the most prominent player) →
+  biomechanics features → coaching report per goal.
+"""
+from __future__ import annotations
+
+import logging
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+from ..domain import biomechanics, goal as goal_mod, trajectory as trajectory_mod
+from ..domain.goal import GoalRegion
+from ..domain.models import (Box, CoachReport, ContactResult, FeatureSet, FramePose)
+
+log = logging.getLogger("futheros")
+Progress = Callable[[float, str], None]
+
+
+@dataclass
+class GoalAnalysis:
+    goal_time_s: float
+    kick_time_s: float | None
+    feature_set: FeatureSet | None
+    report: CoachReport | None
+    kick_frame_img: np.ndarray | None = None     # annotated contact frame (BGR)
+
+
+@dataclass
+class MatchResult:
+    n_goals: int
+    goals: list[GoalAnalysis] = field(default_factory=list)
+    annotated_video_path: str | None = None
+    diagnostics: dict = field(default_factory=dict)
+
+
+class MatchAnalysisService:
+    """Composed like AnalyzeKickService but for whole-match/highlight clips."""
+
+    def __init__(self, *, source, sink, detector, pose, coach, renderer,
+                 goal_detector=None, out_dir: str | None = None):
+        self.source = source
+        self.sink = sink
+        self.detector = detector
+        self.pose = pose
+        self.coach = coach
+        self.renderer = renderer
+        self.goal_detector = goal_detector      # SAM3 image-mode (optional)
+        self.out_dir = Path(out_dir or tempfile.mkdtemp(prefix="futheros_match_"))
+        self.out_dir.mkdir(parents=True, exist_ok=True)
+
+    # ---------- goal regions ----------
+    def _goal_regions(self, clip, video_path: str) -> list[GoalRegion]:
+        from ..adapters.goal_annotations import load_goal_polygons
+        polys = load_goal_polygons(video_path)
+        if polys:
+            return [GoalRegion(p) for p in polys]
+        if self.goal_detector is None:
+            return []
+        boxes: list[Box] = []
+        for fi in {clip.n // 4, clip.n // 2, (3 * clip.n) // 4}:
+            try:
+                boxes.extend(self.goal_detector.detect_goals(clip.frames[fi], conf=0.45))
+            except Exception as e:  # noqa: BLE001
+                log.warning("goal detection failed on frame %s: %s", fi, e)
+        # dedupe by IoU-ish proximity, keep best-conf per location
+        kept: list[Box] = []
+        for b in sorted(boxes, key=lambda x: -x.conf):
+            if all(abs(b.cx - k.cx) > 40 or abs(b.cy - k.cy) > 40 for k in kept):
+                kept.append(b)
+        return [GoalRegion.from_box(b) for b in kept[:2]]
+
+    # ---------- kicker pose on ball-centered crop ----------
+    def _kicker_pose(self, frame: np.ndarray, ball: Box | None) -> FramePose:
+        """Run pose on a crop around the ball so the skeleton lands on the kicker.
+        Falls back to full-frame pose when no ball is known."""
+        h, w = frame.shape[:2]
+        if ball is None:
+            return self.pose.estimate([frame])[0]
+        half = int(max(120, ball.radius * 14))
+        x0 = max(0, int(ball.cx) - half); x1 = min(w, int(ball.cx) + half)
+        y0 = max(0, int(ball.cy) - int(half * 1.3)); y1 = min(h, int(ball.cy) + half // 2)
+        crop = np.ascontiguousarray(frame[y0:y1, x0:x1])
+        if crop.size == 0:
+            return self.pose.estimate([frame])[0]
+        p = self.pose.estimate([crop])[0]
+        if p.xy is not None:
+            p.xy[:, 0] += x0
+            p.xy[:, 1] += y0
+        return p
+
+    # ---------- main ----------
+    def analyze(self, clip_path: str, *, progress: Progress = lambda f, m: None,
+                max_frames: int = 2400) -> MatchResult:
+        t0 = time.time()
+        diag = {"detector": getattr(self.detector, "name", "?")}
+
+        progress(0.05, "Loading video…")
+        clip = self.source.load(clip_path, max_frames=max_frames)
+        fps = clip.fps
+        diag["n_frames"], diag["fps"] = clip.n, round(fps, 1)
+
+        progress(0.12, "Locating the goal…")
+        regions = self._goal_regions(clip, clip_path)
+        diag["goal_regions"] = len(regions)
+        if not regions:
+            return MatchResult(n_goals=0, diagnostics={**diag, "error": "no goal found"})
+
+        progress(0.2, f"Tracking ball + players ({diag['detector']})…")
+        dets = self.detector.detect(clip.frames)
+        diag["ball_frames"] = sum(1 for d in dets if d.ball is not None)
+
+        progress(0.55, "Finding your goals…")
+        cuts = goal_mod.detect_cuts(clip.frames)
+        per_region = [goal_mod.find_goal_events(dets, r, min_gap=int(fps * 2),
+                                                cuts=cuts, fps=fps) for r in regions]
+        events = goal_mod.merge_goal_events(per_region, fps=fps, refractory_s=5.0)
+        diag["goals"] = [round(e / fps, 1) for e in events]
+
+        progress(0.65, "Analyzing each scoring kick…")
+        # full-frame pose pass once (for kick attribution along the timeline)
+        poses = self.pose.estimate(clip.frames)
+
+        goals: list[GoalAnalysis] = []
+        for e in events:
+            ge = goal_mod.attribute_scorer(dets, poses, e, lookback=int(fps * 4), cuts=cuts)
+            ga = GoalAnalysis(goal_time_s=clip.time_of(e), kick_time_s=None,
+                              feature_set=None, report=None)
+            if ge is not None:
+                ci = ge.contact_frame
+                ga.kick_time_s = clip.time_of(ci)
+                contact = ContactResult(frame_idx=ci, kicking_side=ge.kicking_side,
+                                        method="goal_backtrack", confidence=ge.confidence,
+                                        ball_track=ge.ball_track)
+                # precise pose on the kicker (ball-centered crop) for the features
+                kick_pose = self._kicker_pose(clip.frames[ci], dets[ci].ball)
+                poses_for_features = list(poses)
+                poses_for_features[ci] = kick_pose
+                fs = biomechanics.compute_features(poses_for_features, dets, contact)
+                traj = trajectory_mod.compute_trajectory(dets, contact)
+                if traj.valid:
+                    fs.features.append(trajectory_mod.launch_angle_feature(traj))
+                ga.feature_set = fs
+                ga.report = self.coach.coach(fs)
+                ga.kick_frame_img = self.renderer.hero(clip, poses_for_features, dets, fs, contact)
+            goals.append(ga)
+
+        progress(0.9, "Rendering annotated video…")
+        ann = self._render_match(clip, dets, regions, events,
+                                 [int(g.kick_time_s * fps) for g in goals
+                                  if g.kick_time_s is not None], fps)
+        out_video = str(self.out_dir / f"match_{int(t0)}.mp4")
+        self.sink.write(ann, out_video, fps)
+
+        diag["elapsed_s"] = round(time.time() - t0, 1)
+        progress(1.0, "Done")
+        return MatchResult(n_goals=len(events), goals=goals,
+                           annotated_video_path=out_video, diagnostics=diag)
+
+    def _render_match(self, clip, dets, regions, events, kick_frames_list, fps):
+        import cv2
+        kick_frames = set()
+        for c in kick_frames_list:
+            kick_frames.update(range(max(0, c - int(fps * 0.15)), c + int(fps * 0.35)))
+        H, W = clip.frames[0].shape[:2]
+        banner = int(fps * 1.6)
+        max_jump = 90.0 * max(1.0, 60.0 / fps)
+        ball_xy = np.array([[d.ball.cx, d.ball.cy] if d.ball else [np.nan, np.nan]
+                            for d in dets], np.float32)
+        out = []
+        trail: list[tuple[int, np.ndarray]] = []
+        for i, f in enumerate(clip.frames):
+            v = f.copy()
+            for r in regions:
+                cv2.polylines(v, [r.poly.astype(np.int32)], True, (0, 0, 255), 2)
+            if not np.isnan(ball_xy[i][0]):
+                if trail and (i - trail[-1][0] > 5 or
+                              np.linalg.norm(ball_xy[i] - trail[-1][1]) > max_jump):
+                    trail = []
+                trail.append((i, ball_xy[i]))
+            trail = [(j, q) for j, q in trail if i - j <= int(fps)]
+            for k in range(1, len(trail)):
+                cv2.line(v, tuple(trail[k - 1][1].astype(int)),
+                         tuple(trail[k][1].astype(int)), (0, 255, 255), 2)
+            if not np.isnan(ball_xy[i][0]):
+                cv2.circle(v, tuple(ball_xy[i].astype(int)), 10, (0, 255, 0), 2)
+            if i in kick_frames:
+                cv2.putText(v, "KICK", (W // 2 - 70, 90), cv2.FONT_HERSHEY_SIMPLEX,
+                            1.6, (0, 140, 255), 4)
+            for gidx, e in enumerate(events):
+                if e <= i < e + banner:
+                    cv2.rectangle(v, (0, 0), (W - 1, H - 1), (0, 200, 0), 10)
+                    cv2.putText(v, f"GOAL #{gidx + 1}", (W // 2 - 130, 60),
+                                cv2.FONT_HERSHEY_SIMPLEX, 1.6, (0, 230, 0), 4)
+            out.append(v)
+        return out
+
+
+def build_match_service(detector_cls: str = "nano", use_llm: bool = False,
+                        use_sam3_goal: bool = True, out_dir: str | None = None) -> MatchAnalysisService:
+    """Composition root for match mode."""
+    from ..adapters.pose_mediapipe import MediaPipePose
+    from ..adapters.renderer_opencv import OpenCvRenderer
+    from ..adapters.video_opencv import OpenCvVideoSink, OpenCvVideoSource
+    from .factory import _build_coach, _build_detector
+
+    goal_detector = None
+    if use_sam3_goal:
+        try:
+            from ..adapters.goal_detector_sam3 import Sam3GoalDetector
+            goal_detector = Sam3GoalDetector(prompt="goal post")
+        except Exception as e:  # noqa: BLE001
+            log.warning("SAM3 goal detector unavailable: %s", e)
+
+    return MatchAnalysisService(
+        source=OpenCvVideoSource(), sink=OpenCvVideoSink(),
+        detector=_build_detector("rfdetr"), pose=MediaPipePose(),
+        coach=_build_coach(use_llm), renderer=OpenCvRenderer(),
+        goal_detector=goal_detector, out_dir=out_dir,
+    )

futheros/application/service.py

@@ -0,0 +1,104 @@
+"""AnalyzeKickService — the core use case.
+
+Depends ONLY on ports (DetectorPort, PosePort, CoachPort, VideoSource/Sink,
+RendererPort) and the pure domain logic. It contains no knowledge of RF-DETR,
+MediaPipe, llama.cpp, OpenCV, or Gradio — those are injected adapters. This is the
+hexagon's inside; swapping any backend never touches this file.
+"""
+from __future__ import annotations
+
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+from ..domain import biomechanics, contact as contact_mod, trajectory as trajectory_mod
+from ..domain.models import AnalysisResult, Clip
+from ..ports import (CoachPort, DetectorPort, PosePort, RendererPort,
+                     VideoSinkPort, VideoSourcePort)
+
+Progress = Callable[[float, str], None]
+
+
+class AnalyzeKickService:
+    def __init__(self, *, source: VideoSourcePort, sink: VideoSinkPort,
+                 detector: DetectorPort, pose: PosePort, coach: CoachPort,
+                 renderer: RendererPort, out_dir: str | None = None):
+        self.source = source
+        self.sink = sink
+        self.detector = detector
+        self.pose = pose
+        self.coach = coach
+        self.renderer = renderer
+        self.out_dir = Path(out_dir or tempfile.mkdtemp(prefix="futheros_"))
+        self.out_dir.mkdir(parents=True, exist_ok=True)
+
+    def analyze(self, clip_path: str, *, force_rotation: int | None = None,
+                kick_time_s: float | None = None, window_s: float = 2.0,
+                progress: Progress = lambda f, m: None) -> AnalysisResult:
+        t0 = time.time()
+        diag = {"detector": getattr(self.detector, "name", "?"),
+                "pose": getattr(self.pose, "name", "?"),
+                "coach": getattr(self.coach, "name", "?")}
+
+        progress(0.05, "Loading video…")
+        # If the user pins their kick time, load a tight full-fps window around it so we
+        # analyse THEIR kick (and lock onto the player making that contact), not whatever
+        # other touch happens elsewhere in a multi-player clip.
+        window = (kick_time_s - window_s, kick_time_s + window_s) if kick_time_s is not None else None
+        clip = self.source.load(clip_path, window=window)
+        if force_rotation:
+            clip = _rotate_clip(clip, (-(int(force_rotation) // 90)) % 4)
+            diag["rotation"] = f"{int(force_rotation)}°"
+        if kick_time_s is not None:
+            diag["window_s"] = f"{max(0.0, kick_time_s - window_s):.1f}–{kick_time_s + window_s:.1f}s"
+        diag["n_frames"], diag["fps"] = clip.n, round(clip.fps, 1)
+
+        progress(0.25, f"Detecting player + ball ({diag['detector']})…")
+        dets = self.detector.detect(clip.frames)
+        diag["ball_frames"] = sum(1 for d in dets if d.ball is not None)
+        diag["person_frames"] = sum(1 for d in dets if d.person is not None)
+
+        progress(0.5, "Extracting body pose…")
+        poses = self.pose.estimate(clip.frames)
+        diag["pose_frames"] = sum(1 for p in poses if p.ok())
+
+        progress(0.65, "Finding ball-contact frame…")
+        contact = contact_mod.detect_contact(poses, dets)
+        diag.update(contact_idx=contact.frame_idx, contact_method=contact.method,
+                    kicking_leg="right" if contact.kicking_side == "r" else "left")
+
+        progress(0.75, "Measuring technique…")
+        fs = biomechanics.compute_features(poses, dets, contact)
+        traj = trajectory_mod.compute_trajectory(dets, contact)
+        if traj.valid:
+            fs.features.append(trajectory_mod.launch_angle_feature(traj))
+            diag["launch_angle_deg"] = round(traj.launch_angle_deg, 1)
+        score = biomechanics.overall_score(fs)
+
+        progress(0.85, f"Coaching ({diag['coach']})…")
+        report = self.coach.coach(fs)
+
+        progress(0.92, "Rendering annotated video…")
+        ann = self.renderer.annotate(clip, poses, dets, fs, contact, traj)
+        out_video = str(self.out_dir / f"annotated_{int(t0)}.mp4")
+        self.sink.write(ann, out_video, clip.fps)
+        hero = self.renderer.hero(clip, poses, dets, fs, contact, traj)
+        scorecard = self.renderer.scorecard(fs, score)
+
+        diag["elapsed_s"] = round(time.time() - t0, 1)
+        progress(1.0, "Done")
+        return AnalysisResult(
+            feature_set=fs, report=report, contact=contact, score=score, fps=clip.fps,
+            diagnostics=diag, trajectory=traj, annotated_video_path=out_video,
+            hero_image=hero, scorecard_image=scorecard,
+        )
+
+
+def _rotate_clip(clip: Clip, k: int) -> Clip:
+    """Rotate every frame by k×90° (np.rot90) and return a new Clip."""
+    frames = [np.ascontiguousarray(np.rot90(f, k)) for f in clip.frames]
+    h, w = frames[0].shape[:2]
+    return Clip(frames=frames, fps=clip.fps, width=w, height=h)

futheros/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain core: pure analysis logic with no I/O or model-library dependencies."""

futheros/domain/biomechanics.py

@@ -0,0 +1,133 @@
+"""Biomechanics feature extraction + banded scoring — pure domain logic.
+
+Computes the 5-feature shortlist at/after the contact frame from 2D landmarks and
+the ball box, then scores each into good/amber/poor/na bands. Reports bands rather
+than exact degrees because a 3/4 view foreshortens angles — honest coaching.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .config import FEATURE_SPEC
+from .geometry import angle_at, angle_to_vertical
+from .models import ContactResult, Detection, Feature, FeatureSet, FramePose
+
+
+def _band(key: str, value: float | None) -> tuple[str, str]:
+    spec = FEATURE_SPEC[key]
+    if value is None:
+        return "na", ""
+    lo, hi = spec["good"]
+    pad = spec["amber_pad"]
+    if lo <= value <= hi:
+        return "good", ""
+    note = spec["help_low"] if value < lo else spec["help_high"]
+    if (lo - pad) <= value <= (hi + pad):
+        return "amber", note
+    return "poor", note
+
+
+def make_feature(key: str, value: float | None) -> Feature:
+    spec = FEATURE_SPEC[key]
+    band, note = _band(key, value)
+    return Feature(key=key, label=spec["label"], value=value, unit=spec["unit"],
+                   band=band, confidence=spec["confidence"], note=note)
+
+
+_mk = make_feature  # internal alias
+
+
+def _shank_len(pose: FramePose, side: str) -> float | None:
+    knee = pose.pt(f"{side}_knee"); ankle = pose.pt(f"{side}_ankle")
+    if knee is None or ankle is None:
+        return None
+    return float(np.linalg.norm(knee - ankle))
+
+
+def _leg_len(pose: FramePose, side: str) -> float | None:
+    hip = pose.pt(f"{side}_hip"); knee = pose.pt(f"{side}_knee"); ankle = pose.pt(f"{side}_ankle")
+    if hip is None or knee is None or ankle is None:
+        return None
+    return float(np.linalg.norm(hip - knee) + np.linalg.norm(knee - ankle))
+
+
+def compute_features(poses: list[FramePose], dets: list[Detection],
+                     contact: ContactResult) -> FeatureSet:
+    side = contact.kicking_side
+    plant = "l" if side == "r" else "r"
+    ci = contact.frame_idx
+    n = len(poses)
+    cp = poses[ci]
+    fs = FeatureSet(kicking_side=side, contact_idx=ci)
+
+    hip = cp.pt(f"{side}_hip"); knee = cp.pt(f"{side}_knee"); ankle = cp.pt(f"{side}_ankle")
+
+    # 1. knee flexion at strike (180 - interior angle)
+    knee_flex = None
+    if hip is not None and knee is not None and ankle is not None:
+        knee_flex = 180.0 - angle_at(hip, knee, ankle)
+    fs.features.append(_mk("knee_flexion_strike", knee_flex))
+
+    # 2. trunk lean
+    trunk = None
+    ls, rs = cp.pt("l_shoulder"), cp.pt("r_shoulder")
+    lh, rh = cp.pt("l_hip"), cp.pt("r_hip")
+    if ls is not None and rs is not None and lh is not None and rh is not None:
+        trunk = angle_to_vertical((ls + rs) / 2, (lh + rh) / 2)
+    fs.features.append(_mk("trunk_lean_strike", trunk))
+
+    # 3. plant-foot distance to ball / shank length
+    plant_dist = None
+    pf = cp.foot(plant)
+    ball = dets[ci].ball if ci < len(dets) else None
+    shank = _shank_len(cp, plant) or _shank_len(cp, side)
+    if pf is not None and ball is not None and shank:
+        plant_dist = float(np.linalg.norm(pf - ball.center)) / (shank + 1e-6)
+    fs.features.append(_mk("plant_foot_dist", plant_dist))
+
+    # 4. hip flexion (shoulder, hip, knee)
+    hip_flex = None
+    sh = cp.pt(f"{side}_shoulder")
+    if sh is not None and hip is not None and knee is not None:
+        hip_flex = angle_at(sh, hip, knee)
+    fs.features.append(_mk("hip_flexion_strike", hip_flex))
+
+    # 5. follow-through peak foot height after contact / leg length
+    ft_height = None
+    leg = _leg_len(cp, side)
+    contact_foot = cp.foot(side)
+    if leg and contact_foot is not None:
+        base_y = contact_foot[1]
+        rises = []
+        for j in range(ci, min(n, ci + 25)):
+            fp = poses[j].foot(side)
+            if fp is not None:
+                rises.append(base_y - fp[1])
+        if rises:
+            ft_height = float(max(rises)) / (leg + 1e-6)
+    fs.features.append(_mk("follow_through_height", ft_height))
+
+    return fs
+
+
+def overall_score(fs: FeatureSet) -> int:
+    pts = {"good": 1.0, "amber": 0.5, "poor": 0.0}
+    vals = [pts[f.band] for f in fs.features if f.band in pts]
+    return int(round(100 * sum(vals) / len(vals))) if vals else 0
+
+
+def features_to_dict(fs: FeatureSet) -> dict:
+    """Serialise for the LLM coach (numbers + targets + bands)."""
+    return {
+        "kicking_leg": "right" if fs.kicking_side == "r" else "left",
+        "overall_score_0_100": overall_score(fs),
+        "features": [
+            {
+                "name": f.label, "key": f.key,
+                "value": None if f.value is None else round(f.value, 1),
+                "unit": f.unit, "band": f.band, "confidence": f.confidence,
+                "target_good_range": list(FEATURE_SPEC[f.key]["good"]),
+            }
+            for f in fs.features
+        ],
+    }

futheros/domain/coaching.py

@@ -0,0 +1,66 @@
+"""Rule-based coaching — pure domain logic shared as the always-available coach
+and as the fallback when the LLM misbehaves. No external deps.
+
+The LLM prompt strings also live here so the domain owns the coaching contract;
+the llama-cpp adapter just executes them.
+"""
+from __future__ import annotations
+
+from .biomechanics import features_to_dict, overall_score
+from .config import DRILL_BANK
+from .models import CoachReport, FeatureSet
+
+SYSTEM_PROMPT = (
+    "You are FUT-HEROS, a concise football (soccer) kicking-technique coach. "
+    "You are given MEASURED biomechanics from a single side/three-quarter phone clip "
+    "of one kick, already converted to good/amber/poor bands. The numbers are "
+    "coaching-grade, not lab-grade, so speak in tendencies, never exact degrees. "
+    "Encourage first, then fix the 1-2 weakest things. "
+    "Return STRICT JSON only, no markdown, with keys: "
+    "summary (1-2 sentences), cues (array of 2-4 short imperative coaching cues), "
+    "drills (array of 2-3 short drills to fix the weak points)."
+)
+
+
+def build_user_prompt(fs: FeatureSet) -> str:
+    import json
+    return ("Here are the measured features for this kick:\n"
+            + json.dumps(features_to_dict(fs), indent=2)
+            + "\n\nWrite the coaching JSON now.")
+
+
+def rule_based_report(fs: FeatureSet) -> CoachReport:
+    score = overall_score(fs)
+    goods = [f for f in fs.features if f.band == "good"]
+    weak = [f for f in fs.features if f.band in ("amber", "poor")]
+    weak.sort(key=lambda f: 0 if f.band == "poor" else 1)
+
+    if score >= 80:
+        summary = ("Strong, well-balanced strike — the fundamentals are there. "
+                   "A couple of small tweaks will add power and consistency.")
+    elif score >= 55:
+        summary = ("Solid base with clear strengths. Tighten up the flagged areas "
+                   "and the strike will jump up a level.")
+    else:
+        summary = ("Good effort — there's real raw material here. Let's fix the basics "
+                   "one at a time and the power and accuracy will follow.")
+    if goods:
+        summary += f" Nice work on your {goods[0].label.lower()}."
+
+    cues = [f.note for f in weak if f.note][:4]
+    if not cues:
+        cues = ["Keep your eyes on the ball through contact.",
+                "Stay balanced over the plant foot and follow through to the target."]
+
+    drills: list[str] = []
+    for f in weak[:2]:
+        drills.extend(DRILL_BANK.get(f.key, []))
+    if not drills:
+        drills = ["Wall-pass reps: 20 firm side-foot passes each leg, focusing on a clean plant.",
+                  "Approach-and-strike: 10 controlled shots from 5 paces, holding your finish."]
+    seen, uniq = set(), []
+    for d in drills:
+        if d not in seen:
+            seen.add(d); uniq.append(d)
+
+    return CoachReport(summary=summary, cues=cues, drills=uniq[:3], score=score, engine="rule")

futheros/domain/config.py

@@ -0,0 +1,113 @@
+"""Domain analysis parameters — pure data, no infrastructure concerns.
+
+Model repos / GPU settings / download URLs live in the adapters layer, not here.
+This file holds only the biomechanics knowledge: landmark indices, visibility
+floor, COCO class ids, and the feature target bands.
+"""
+from __future__ import annotations
+
+# COCO class ids (detection contract — domain knows what it wants found)
+COCO_PERSON = 0
+COCO_SPORTS_BALL = 32
+
+# Detection thresholds (analysis policy)
+PERSON_CONF = 0.35
+BALL_CONF = 0.10          # ball is small+fast -> low threshold, lean on temporal smoothing
+BALL_MAX_INTERP_GAP = 8
+
+# MediaPipe BlazePose 33-landmark indices we rely on
+LM = {
+    "nose": 0,
+    "l_shoulder": 11, "r_shoulder": 12,
+    "l_elbow": 13, "r_elbow": 14,
+    "l_hip": 23, "r_hip": 24,
+    "l_knee": 25, "r_knee": 26,
+    "l_ankle": 27, "r_ankle": 28,
+    "l_heel": 29, "r_heel": 30,
+    "l_foot": 31, "r_foot": 32,
+}
+POSE_MIN_VISIBILITY = 0.3
+
+# 5-feature biomechanics shortlist + target bands (good range, amber pad, coaching notes)
+FEATURE_SPEC = {
+    "knee_flexion_strike": {
+        "label": "Kicking-knee bend at strike",
+        "unit": "deg",
+        "good": (35, 55),
+        "amber_pad": 12,
+        "help_low": "Knee too straight at contact — bend the kicking knee more to load the strike.",
+        "help_high": "Knee very bent at contact — let the lower leg extend through the ball for more snap.",
+        "confidence": "high",
+    },
+    "trunk_lean_strike": {
+        "label": "Trunk lean at contact",
+        "unit": "deg",
+        "good": (3, 20),
+        "amber_pad": 10,
+        "help_low": "You're leaning forward over the ball — sit back slightly to get under it and drive through.",
+        "help_high": "Leaning back a lot — a touch more upright keeps the strike compact.",
+        "confidence": "high",
+    },
+    "plant_foot_dist": {
+        "label": "Plant-foot distance to ball",
+        "unit": "shank",
+        "good": (0.6, 1.3),
+        "amber_pad": 0.5,
+        "help_low": "Plant foot is right on top of the ball — plant 10-15cm further to the side for room to swing.",
+        "help_high": "Plant foot is too far from the ball — step in closer so you can strike cleanly with power.",
+        "confidence": "med",
+    },
+    "hip_flexion_strike": {
+        "label": "Hip drive (kicking leg)",
+        "unit": "deg",
+        "good": (95, 135),
+        "amber_pad": 20,
+        "help_low": "Limited hip drive — bring the thigh through harder from the hip for more power.",
+        "help_high": "Big hip swing — good drive; keep it controlled for accuracy.",
+        "confidence": "med",
+    },
+    "follow_through_height": {
+        "label": "Follow-through height",
+        "unit": "leg",
+        "good": (0.45, 1.1),
+        "amber_pad": 0.3,
+        "help_low": "Short follow-through — swing the leg up and through the target to finish the strike.",
+        "help_high": "Big follow-through — lots of swing; fine for power shots.",
+        "confidence": "med",
+    },
+    "launch_angle": {
+        "label": "Shot launch angle",
+        "unit": "deg",                 # 2D elevation of the ball path just after contact
+        "good": (8, 35),
+        "amber_pad": 20,
+        "help_low": "Flat shot — plant your foot beside the ball and lean back slightly to get under it and lift it.",
+        "help_high": "Ballooned high — stay over the ball and strike through its middle to keep it down.",
+        "confidence": "med",
+    },
+}
+
+# Drill bank keyed by feature (coaching domain knowledge)
+DRILL_BANK = {
+    "knee_flexion_strike": [
+        "Slow-mo strikes: kick at half pace focusing on cocking the knee back before you swing through.",
+        "Resistance-band knee snaps: 3x12 to groove a sharper lower-leg whip.",
+    ],
+    "trunk_lean_strike": [
+        "Lean-back finishes: practice 10 shots exaggerating sitting slightly back over the ball.",
+        "Plant-and-pause: strike, then freeze your finish for 2s to feel your upper-body angle.",
+    ],
+    "plant_foot_dist": [
+        "Cone-spot plant: place a cone a boot's width to the side of the ball and hit 15 balls planting onto it.",
+        "Walk-up reps: rehearse the last two steps so the plant foot lands beside, not on top of, the ball.",
+    ],
+    "hip_flexion_strike": [
+        "High-knee drive: march drills then strikes, leading with the thigh from the hip.",
+        "Power-step shots: explode the kicking thigh through 12 shots, prioritising hip drive over foot speed.",
+    ],
+    "follow_through_height": [
+        "Full-finish shots: swing the kicking leg all the way up to chest height on 12 strikes.",
+        "Target-and-through: aim at a high target so the follow-through naturally extends.",
+    ],
+}
+
+MAX_FRAMES = 600          # cap processing for long / slow-mo clips

futheros/domain/contact.py

@@ -0,0 +1,82 @@
+"""Ball-contact frame detection — pure function over poses + detections.
+
+All in the 2D image plane (no depth):
+  1. kicking leg = ankle with the largest peak speed
+  2. primary: local min of kicking-foot <-> ball-center distance
+  3. confirm: ball velocity onset (stationary -> moving) just after
+  4. fallback (no ball): peak kicking-foot speed
+A 60fps clip can't resolve the true ~7-16ms impact, so accept +-1 frame.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .geometry import smooth
+from .models import ContactResult, Detection, FramePose
+
+
+def _ankle_series(poses: list[FramePose], side: str) -> np.ndarray:
+    pts = []
+    for p in poses:
+        a = p.pt(f"{side}_ankle") if p.ok() else None
+        pts.append(a if a is not None else [np.nan, np.nan])
+    return np.array(pts, dtype=np.float32)
+
+
+def identify_kicking_leg(poses: list[FramePose]) -> str:
+    best, best_side = -1.0, "r"
+    for side in ("l", "r"):
+        s = _ankle_series(poses, side)
+        valid = ~np.isnan(s[:, 0])
+        if valid.sum() < 3:
+            continue
+        speed = np.linalg.norm(np.diff(s[valid], axis=0), axis=1)
+        score = float(np.nanmax(speed)) if len(speed) else 0.0
+        if score > best:
+            best, best_side = score, side
+    return best_side
+
+
+def detect_contact(poses: list[FramePose], dets: list[Detection]) -> ContactResult:
+    n = len(poses)
+    side = identify_kicking_leg(poses)
+
+    ball = np.full((n, 2), np.nan, dtype=np.float32)
+    for i, d in enumerate(dets):
+        if d.ball is not None:
+            ball[i] = [d.ball.cx, d.ball.cy]
+    has_ball = int((~np.isnan(ball[:, 0])).sum()) >= 3
+
+    foot = np.full((n, 2), np.nan, dtype=np.float32)
+    for i, p in enumerate(poses):
+        fp = p.foot(side) if p.ok() else None
+        if fp is not None:
+            foot[i] = fp
+
+    if has_ball:
+        dist = np.linalg.norm(foot - ball, axis=1)
+        valid = ~np.isnan(dist)
+        if valid.sum() >= 3:
+            d_s = dist.copy()
+            d_s[~valid] = np.nanmax(dist[valid]) * 2
+            d_s = smooth(d_s, 5)
+            cand = int(np.nanargmin(d_s))
+
+            bspeed = np.full(n, np.nan, dtype=np.float32)
+            bspeed[1:] = np.linalg.norm(np.diff(ball, axis=0), axis=1)
+            after = bspeed[cand:min(n, cand + 4)]
+            onset = float(np.nanmax(after)) if np.any(~np.isnan(after)) else 0.0
+            ref = float(np.nanmedian(bspeed[~np.isnan(bspeed)])) if np.any(~np.isnan(bspeed)) else 0.0
+            if onset > 2.5 * (ref + 1e-6):
+                return ContactResult(cand, side, "velocity_onset", 0.85, ball)
+            return ContactResult(cand, side, "foot_ball_min", 0.6, ball)
+
+    fseries = _ankle_series(poses, side)
+    if (~np.isnan(fseries[:, 0])).sum() >= 3:
+        speed = np.full(n, np.nan, dtype=np.float32)
+        speed[1:] = np.linalg.norm(np.diff(fseries, axis=0), axis=1)
+        speed = np.where(np.isnan(speed), -1, speed)
+        cand = int(np.argmax(smooth(np.maximum(speed, 0), 5)))
+        return ContactResult(cand, side, "foot_speed", 0.4, ball if has_ball else None)
+
+    return ContactResult(n // 2, side, "fallback_mid", 0.1, None)

futheros/domain/geometry.py

@@ -0,0 +1,25 @@
+"""Pure 2D geometry helpers used by the biomechanics core."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def angle_at(a: np.ndarray, b: np.ndarray, c: np.ndarray) -> float:
+    """Interior angle ABC in degrees, vertex at b."""
+    ba = a - b
+    bc = c - b
+    cosang = np.dot(ba, bc) / (np.linalg.norm(ba) * np.linalg.norm(bc) + 1e-9)
+    return float(np.degrees(np.arccos(np.clip(cosang, -1.0, 1.0))))
+
+
+def angle_to_vertical(top: np.ndarray, bottom: np.ndarray) -> float:
+    """Signed lean (deg) of vector bottom->top from vertical-up.
+    Image y grows downward, so 'up' is -y. +ve leans one way, -ve the other."""
+    v = top - bottom
+    return float(np.degrees(np.arctan2(v[0], -v[1])))
+
+
+def smooth(x: np.ndarray, k: int = 5) -> np.ndarray:
+    if len(x) < k:
+        return x
+    return np.convolve(x, np.ones(k) / k, mode="same")

futheros/domain/goal.py

@@ -0,0 +1,328 @@
+"""Goal-event detection + scorer attribution — pure domain logic.
+
+The product's real anchor: don't guess which of many players to coach — find the
+GOAL, then coach the strike that scored it.
+
+  1. goal event = the ball enters the goal-mouth region and stays/disappears there
+  2. scorer kick = the last foot-to-ball contact BEFORE the ball crossed in
+  3. that contact frame + that player = what we analyse
+
+This module is detector-agnostic: it takes the goal-mouth box (from whatever goalpost
+detector), the per-frame ball track, and per-frame all-person boxes. Everything is in
+the 2D image plane.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .models import Box, Detection, FramePose
+
+
+@dataclass
+class GoalEvent:
+    goal_frame: int                 # frame the ball entered the goal mouth
+    contact_frame: int              # last foot-to-ball contact before the goal
+    scorer_box: Box | None          # the scoring player's box at the contact frame
+    kicking_side: str               # 'l' | 'r'
+    confidence: float
+    ball_track: np.ndarray = field(default_factory=lambda: np.empty((0, 2)))
+
+
+def _ball_centers(dets: list[Detection]) -> np.ndarray:
+    n = len(dets)
+    pts = np.full((n, 2), np.nan, dtype=np.float32)
+    for i, d in enumerate(dets):
+        if d.ball is not None:
+            pts[i] = [d.ball.cx, d.ball.cy]
+    return pts
+
+
+def _inside(box: Box, x: float, y: float, pad: float = 0.0) -> bool:
+    return (box.x1 - pad) <= x <= (box.x2 + pad) and (box.y1 - pad) <= y <= (box.y2 + pad)
+
+
+class GoalRegion:
+    """The goal mouth as a polygon (the projected goal PLANE).
+
+    A user-annotated 4-point polygon beats any detector box: it encodes exactly which
+    crossing counts as goal-ward. A detector Box converts to its 4 corners.
+    """
+
+    def __init__(self, polygon: np.ndarray):
+        self.poly = np.asarray(polygon, dtype=np.float32).reshape(-1, 2)
+        self.centre = self.poly.mean(axis=0)
+        d = self.poly - self.centre
+        self.radius = float(np.linalg.norm(d, axis=1).max())
+
+    @classmethod
+    def from_box(cls, b: Box) -> "GoalRegion":
+        return cls(np.array([[b.x1, b.y1], [b.x2, b.y1], [b.x2, b.y2], [b.x1, b.y2]]))
+
+    def contains(self, x: float, y: float, pad: float = 0.0) -> bool:
+        # ray cast (even-odd rule)
+        px, py = self.poly[:, 0], self.poly[:, 1]
+        n = len(px)
+        inside = False
+        j = n - 1
+        for i in range(n):
+            if (py[i] > y) != (py[j] > y):
+                xint = (px[j] - px[i]) * (y - py[i]) / (py[j] - py[i] + 1e-12) + px[i]
+                if x < xint:
+                    inside = not inside
+            j = i
+        if inside:
+            return True
+        if pad <= 0:
+            return False
+        # near-miss: distance from point to the closest polygon edge
+        p = np.array([x, y], dtype=np.float32)
+        best = 1e18
+        for i in range(n):
+            a, b = self.poly[i], self.poly[(i + 1) % n]
+            ab = b - a
+            t = float(np.clip(np.dot(p - a, ab) / (np.dot(ab, ab) + 1e-12), 0, 1))
+            best = min(best, float(np.linalg.norm(p - (a + t * ab))))
+        return best <= pad
+
+    def crossed_by(self, p0: np.ndarray, p1: np.ndarray) -> bool:
+        """Does the segment p0->p1 (ball path between two frames) cross this region?
+
+        Essential for goal planes annotated edge-on from a corner camera: the mouth
+        projects to a sliver only a few px wide, so a flying ball is sampled on one
+        side then the other and is NEVER inside — but its path segment crosses.
+        """
+        if self.contains(*p0) or self.contains(*p1):
+            return True
+
+        def ccw(a, b, c):
+            return (c[1] - a[1]) * (b[0] - a[0]) > (b[1] - a[1]) * (c[0] - a[0])
+
+        def seg_intersect(a, b, c, d):
+            return (ccw(a, c, d) != ccw(b, c, d)) and (ccw(a, b, c) != ccw(a, b, d))
+
+        n = len(self.poly)
+        for i in range(n):
+            if seg_intersect(p0, p1, self.poly[i], self.poly[(i + 1) % n]):
+                return True
+        return False
+
+
+def clean_ball_track(ball: np.ndarray, grid: int = 10, max_frac: float = 0.05) -> np.ndarray:
+    """Remove static false-positive 'balls'.
+
+    A real ball moves; white pitch markings / goal frames / scoreboard elements get
+    re-detected at the SAME pixel spot for a large share of the clip. Any grid cell
+    holding more than max_frac of all detections is static junk — NaN those frames.
+    """
+    out = ball.copy()
+    valid = ~np.isnan(ball[:, 0])
+    if valid.sum() < 10:
+        return out
+    cells = (ball[valid] // grid).astype(np.int64)
+    keys = cells[:, 0] * 100003 + cells[:, 1]
+    uniq, counts = np.unique(keys, return_counts=True)
+    bad = set(uniq[counts > max(3, int(max_frac * valid.sum()))].tolist())
+    vi = np.where(valid)[0]
+    for k, i in enumerate(vi):
+        if keys[k] in bad:
+            out[i] = np.nan
+    return out
+
+
+def detect_cuts(frames: list[np.ndarray], min_gap: int = 5) -> list[int]:
+    """Indices where a hard scene cut occurs (highlight montages jump between moments).
+
+    Fixed-camera montages are subtle: a cut keeps the identical pitch background and
+    only the (small) players + overlay jump, so absolute change is low. We therefore
+    use an ADAPTIVE threshold: the per-frame changed-pixel fraction is near-constant
+    during play; a cut is a statistical outlier spike above that baseline.
+    Tracking must never cross a cut, or it silently jumps into a different highlight.
+    """
+    if len(frames) < 3:
+        return []
+    fracs = np.zeros(len(frames), dtype=np.float32)
+    prev = None
+    for i, f in enumerate(frames):
+        g = f[::8, ::8].mean(axis=2)          # cheap thumbnail
+        if prev is not None:
+            fracs[i] = float((np.abs(g - prev) > 25).mean())
+        prev = g
+    base = float(np.median(fracs[1:]))
+    mad = float(np.median(np.abs(fracs[1:] - base))) + 1e-6
+    thresh = max(base + 8 * mad, 2.5 * base, 0.02)
+    cuts: list[int] = []
+    for i in range(1, len(frames)):
+        if fracs[i] > thresh:
+            if not cuts or (i - cuts[-1]) >= min_gap:
+                cuts.append(i)
+    return cuts
+
+
+def segment_of(idx: int, cuts: list[int], n: int) -> tuple[int, int]:
+    """[start, end) of the montage segment containing frame idx."""
+    start = 0
+    end = n
+    for c in cuts:
+        if c <= idx:
+            start = c
+        else:
+            end = c
+            break
+    return start, end
+
+
+def find_goal_events(dets: list[Detection], goal_box: "Box | GoalRegion",
+                     min_gap: int = 30, pad: float = 15.0,
+                     approach_window: int = 6,
+                     cuts: list[int] | None = None,
+                     fps: float = 60.0) -> list[int]:
+    """Frames where the ball flies INTO the goal mouth.
+
+    goal_box may be a detector Box or (better) a user-annotated GoalRegion polygon —
+    the projected goal plane, which encodes exactly which crossing counts.
+    On a cleaned track (static FPs removed), a goal = the ball reaches the region
+    (within `pad` px) at the end of a CONSISTENT approach: over the last few valid
+    points the ball must have moved toward the goal centre by a meaningful distance.
+    Detection noise teleporting near the goal has no such approach and is rejected.
+    """
+    region = goal_box if isinstance(goal_box, GoalRegion) else GoalRegion.from_box(goal_box)
+    ball = clean_ball_track(_ball_centers(dets))
+    n = len(dets)
+    cut_set = set(cuts or [])
+
+    # Build continuous ball RUNS: consecutive valid points with small frame gaps, no
+    # teleports (picker jumping to another ball), and never spanning a montage cut.
+    # The teleport threshold scales with frame rate: a shot ball moves ~25px/frame at
+    # 60fps, so at lower fps the same ball legitimately jumps further between frames.
+    MAX_FRAME_GAP = 3
+    MAX_STEP_PX = max(80.0, 80.0 * (60.0 / max(10.0, fps)))
+    runs: list[list[int]] = []
+    cur: list[int] = []
+    for i in range(n):
+        if np.isnan(ball[i, 0]):
+            continue
+        if cur:
+            gap = i - cur[-1]
+            jump = float(np.linalg.norm(ball[i] - ball[cur[-1]]))
+            crosses_cut = any(c in cut_set for c in range(cur[-1] + 1, i + 1))
+            if gap > MAX_FRAME_GAP or jump > MAX_STEP_PX * gap or crosses_cut:
+                runs.append(cur)
+                cur = []
+        cur.append(i)
+    if cur:
+        runs.append(cur)
+
+    EXTRAP_FRAMES = 8       # how far past a lost track we project the flight
+    MIN_SHOT_SPEED = 5.0    # px/frame — only fast balls get extrapolated
+
+    events: list[int] = []
+
+    def add(i: int):
+        if not events or (i - events[-1]) >= min_gap:
+            events.append(i)
+
+    for run in runs:
+        # 1) direct crossing: any path segment within the run crosses the goal plane
+        fired = False
+        for a, b in zip(run, run[1:]):
+            if region.crossed_by(ball[a], ball[b]):
+                add(b)
+                fired = True
+                break
+        if fired:
+            continue
+        # 2) extrapolation: a fast goal-ward run that ends (blur kills detection at
+        # peak speed — exactly at the goal). Project the last velocity forward.
+        if len(run) >= 3:
+            tail = run[-3:]
+            dt = tail[-1] - tail[0]
+            v = (ball[tail[-1]] - ball[tail[0]]) / max(1, dt)   # px/frame
+            speed = float(np.linalg.norm(v))
+            if speed >= MIN_SHOT_SPEED:
+                p_end = ball[run[-1]]
+                if region.crossed_by(p_end, p_end + EXTRAP_FRAMES * v):
+                    add(run[-1])
+
+    return sorted(events)
+
+
+def merge_goal_events(events_by_region: list[list[int]], fps: float,
+                      refractory_s: float = 5.0) -> list[int]:
+    """Merge per-goal event lists into one timeline, dropping kickoff returns.
+
+    Football rule, not a heuristic: you cannot score twice within a few seconds —
+    there's a kickoff in between. The ball being returned after a goal often crosses
+    a goal plane again, so any event within `refractory_s` of an accepted goal is
+    the return, not a new goal.
+    """
+    all_events = sorted(e for evs in events_by_region for e in evs)
+    kept: list[int] = []
+    for e in all_events:
+        if kept and (e - kept[-1]) < refractory_s * fps:
+            continue
+        kept.append(e)
+    return kept
+
+
+def attribute_scorer(dets: list[Detection], poses: list[FramePose], goal_frame: int,
+                     lookback: int = 90, cuts: list[int] | None = None) -> GoalEvent | None:
+    """Track the ball BACKWARDS from the goal to the kick.
+
+    After the kick the ball travels goal-ward in one continuous fast run. Walking
+    backwards from the goal frame, the kick moment is where that run begins — ball
+    speed collapses from fast to slow (or the track starts). The leg-ball contact is
+    at/just before that onset; the nearest foot there identifies the scorer + side.
+    """
+    ball = clean_ball_track(_ball_centers(dets))
+    n = len(ball)
+    floor = segment_of(goal_frame, cuts, n)[0] if cuts else 0
+    start = max(floor, goal_frame - lookback)
+
+    # per-frame ball speed (nan-safe)
+    speed = np.full(n, np.nan, dtype=np.float32)
+    speed[1:] = np.linalg.norm(np.diff(ball, axis=0), axis=1)
+    valid = ~np.isnan(speed[start:goal_frame + 1])
+    if valid.sum() < 3:
+        return None
+    fast = float(np.nanpercentile(speed[start:goal_frame + 1], 75))
+    slow_thresh = max(2.0, 0.35 * fast)
+
+    # walk back from the goal while the ball is in its fast goal-ward run;
+    # the kick onset = first frame (going backwards) where speed drops below slow_thresh
+    kick_frame = None
+    in_run = False
+    for i in range(goal_frame, start - 1, -1):
+        s = speed[i] if i < n else np.nan
+        if np.isnan(s):
+            continue
+        if s >= slow_thresh:
+            in_run = True
+            kick_frame = i          # earliest fast frame seen so far
+        elif in_run:
+            break                   # run just started after this slow frame
+    if kick_frame is None:
+        return None
+    kick_frame = max(start, kick_frame - 1)   # contact is the frame before launch
+
+    # nearest foot to the ball around the kick frame (+-2) -> scorer + kicking side
+    best_d, best_side, best_frame = 1e18, "r", kick_frame
+    best_box: Box | None = None
+    for i in range(max(start, kick_frame - 2), min(goal_frame, kick_frame + 3)):
+        if np.isnan(ball[i, 0]) or i >= len(poses) or not poses[i].ok():
+            continue
+        for side in ("l", "r"):
+            foot = poses[i].foot(side)
+            if foot is None:
+                continue
+            d = float(np.linalg.norm(foot - ball[i]))
+            if d < best_d:
+                best_d, best_side, best_frame = d, side, i
+                best_box = dets[i].person
+
+    r = dets[best_frame].ball.radius if dets[best_frame].ball is not None else 15.0
+    near = best_d < max(3.0 * r, 60.0)
+    conf = float(np.clip(1.0 - best_d / 150.0, 0.2, 0.95)) if near else 0.3
+    return GoalEvent(goal_frame=goal_frame, contact_frame=best_frame, scorer_box=best_box,
+                     kicking_side=best_side, confidence=conf, ball_track=ball)

futheros/domain/models.py

@@ -0,0 +1,166 @@
+"""Domain value objects — the shared language of the core.
+
+Pure data. No external model libs, no I/O. numpy is used only as the numeric
+substrate for keypoint coordinates. Everything the application and adapters pass
+around is defined here, so the domain never depends on a framework.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .config import LM, POSE_MIN_VISIBILITY
+
+
+# ---------- vision primitives ----------
+
+@dataclass(frozen=True)
+class Box:
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    conf: float
+
+    @property
+    def cx(self) -> float:
+        return (self.x1 + self.x2) / 2
+
+    @property
+    def cy(self) -> float:
+        return (self.y1 + self.y2) / 2
+
+    @property
+    def center(self) -> np.ndarray:
+        return np.array([self.cx, self.cy], dtype=np.float32)
+
+    @property
+    def area(self) -> float:
+        return max(0.0, self.x2 - self.x1) * max(0.0, self.y2 - self.y1)
+
+    @property
+    def radius(self) -> float:
+        return max(self.x2 - self.x1, self.y2 - self.y1) / 2
+
+
+@dataclass
+class Detection:
+    """Chosen subject + ball for a single frame."""
+    person: Box | None = None
+    ball: Box | None = None
+    ball_interpolated: bool = False
+
+
+@dataclass
+class FramePose:
+    """2D image-plane landmarks for one frame (pixels) + visibility.
+
+    The 3D/Z axis is intentionally absent: monocular depth from a side/3-4 view is
+    unreliable, so the domain refuses to model it.
+    """
+    xy: np.ndarray | None        # (33, 2) float32 pixels
+    vis: np.ndarray | None       # (33,) float32
+
+    def ok(self) -> bool:
+        return self.xy is not None
+
+    def pt(self, name: str) -> np.ndarray | None:
+        if self.xy is None:
+            return None
+        i = LM[name]
+        if self.vis is not None and self.vis[i] < POSE_MIN_VISIBILITY:
+            return None
+        return self.xy[i]
+
+    def foot(self, side: str) -> np.ndarray | None:
+        for nm in (f"{side}_foot", f"{side}_heel", f"{side}_ankle"):
+            p = self.pt(nm)
+            if p is not None:
+                return p
+        return None
+
+
+@dataclass
+class Clip:
+    frames: list[np.ndarray]     # upright BGR uint8
+    fps: float
+    width: int
+    height: int
+    t0_s: float = 0.0            # wall-clock time of frame 0 (for windowed loads)
+
+    @property
+    def n(self) -> int:
+        return len(self.frames)
+
+    def time_of(self, frame_idx: int) -> float:
+        return self.t0_s + frame_idx / (self.fps or 30.0)
+
+
+# ---------- analysis results ----------
+
+@dataclass
+class ContactResult:
+    frame_idx: int
+    kicking_side: str            # 'l' | 'r'
+    method: str                  # how contact was found
+    confidence: float            # 0..1
+    ball_track: np.ndarray | None = None
+
+
+@dataclass
+class Feature:
+    key: str
+    label: str
+    value: float | None
+    unit: str
+    band: str                    # 'good' | 'amber' | 'poor' | 'na'
+    confidence: str              # 'high' | 'med' | 'low'
+    note: str = ""
+
+
+@dataclass
+class FeatureSet:
+    features: list[Feature] = field(default_factory=list)
+    kicking_side: str = "r"
+    contact_idx: int = 0
+
+    def by_key(self, key: str) -> Feature | None:
+        return next((f for f in self.features if f.key == key), None)
+
+
+@dataclass
+class CoachReport:
+    summary: str
+    cues: list[str] = field(default_factory=list)
+    drills: list[str] = field(default_factory=list)
+    score: int = 0
+    engine: str = "rule"
+
+
+@dataclass
+class Trajectory:
+    """Ball flight path around contact (2D image plane). Pre/post points are
+    (frame_idx, x, y) tuples; launch_angle_deg is the elevation of the path just
+    after contact (positive = rising)."""
+    pre_points: list[tuple[int, float, float]] = field(default_factory=list)
+    post_points: list[tuple[int, float, float]] = field(default_factory=list)
+    launch_angle_deg: float | None = None
+    direction: str = "—"             # 'left' | 'right' | '—'
+    valid: bool = False
+
+
+@dataclass
+class AnalysisResult:
+    """The full output of an AnalyzeKick run (domain-level; adapters render it)."""
+    feature_set: FeatureSet
+    report: CoachReport
+    contact: ContactResult
+    score: int
+    fps: float
+    diagnostics: dict = field(default_factory=dict)
+    trajectory: "Trajectory | None" = None
+    # populated by output adapters:
+    annotated_video_path: str | None = None
+    hero_image: np.ndarray | None = None
+    scorecard_image: np.ndarray | None = None

futheros/domain/trajectory.py

@@ -0,0 +1,56 @@
+"""Ball trajectory + shot launch angle — pure domain logic (2D image plane).
+
+We already detect the ball most frames, so the path is nearly free. The launch angle
+is the elevation of the ball's path in the frames just after contact: positive = the
+ball is rising. This is an in-plane ratio (rise over run), so it's defensible from a
+side/3-4 view without any depth or metric scale — unlike speed, which we never claim.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .biomechanics import make_feature
+from .models import ContactResult, Detection, Feature, Trajectory
+
+POST_WINDOW = 12      # frames after contact used to fit the launch direction
+PRE_WINDOW = 12
+
+
+def _centers(dets: list[Detection]) -> np.ndarray:
+    n = len(dets)
+    pts = np.full((n, 2), np.nan, dtype=np.float32)
+    for i, d in enumerate(dets):
+        if d.ball is not None:
+            pts[i] = [d.ball.cx, d.ball.cy]
+    return pts
+
+
+def compute_trajectory(dets: list[Detection], contact: ContactResult) -> Trajectory:
+    n = len(dets)
+    ci = contact.frame_idx
+    pts = _centers(dets)
+
+    pre = [(i, float(pts[i, 0]), float(pts[i, 1]))
+           for i in range(max(0, ci - PRE_WINDOW), ci + 1) if not np.isnan(pts[i, 0])]
+    post = [(i, float(pts[i, 0]), float(pts[i, 1]))
+            for i in range(ci, min(n, ci + POST_WINDOW + 1)) if not np.isnan(pts[i, 0])]
+
+    traj = Trajectory(pre_points=pre, post_points=post)
+    if len(post) >= 3:
+        # launch vector from contact point to the mean of the next few detections
+        x0, y0 = post[0][1], post[0][2]
+        tail = post[1:6] if len(post) > 6 else post[1:]
+        dx = float(np.mean([p[1] for p in tail])) - x0
+        dy = float(np.mean([p[2] for p in tail])) - y0   # image y grows downward
+        if abs(dx) + abs(dy) > 2.0:                       # ball actually moved
+            # elevation above horizontal: rise = -dy (up positive), run = |dx|
+            traj.launch_angle_deg = float(np.degrees(np.arctan2(-dy, abs(dx) + 1e-6)))
+            traj.direction = "right" if dx > 0 else "left"
+            traj.valid = True
+    return traj
+
+
+def launch_angle_feature(traj: Trajectory) -> Feature:
+    """Wrap the launch angle as a scored Feature so it flows into the scorecard,
+    coach and LLM like the biomechanics features."""
+    return make_feature("launch_angle", traj.launch_angle_deg if traj.valid else None)

futheros/ports/__init__.py

@@ -0,0 +1,14 @@
+"""Ports — the abstract boundary of the hexagon.
+
+The application service depends only on these Protocols; concrete adapters in
+`futheros.adapters` implement them. Swapping RF-DETR for YOLO, or llama.cpp for a
+rule engine, is a wiring change in the composition root, not a code change here.
+"""
+from .coach import CoachPort
+from .detector import DetectorPort
+from .pose import PosePort
+from .renderer import RendererPort
+from .video import VideoSinkPort, VideoSourcePort
+
+__all__ = ["CoachPort", "DetectorPort", "PosePort", "RendererPort",
+           "VideoSinkPort", "VideoSourcePort"]

futheros/ports/coach.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..domain.models import CoachReport, FeatureSet
+
+
+@runtime_checkable
+class CoachPort(Protocol):
+    """Turns measured features into a coaching report (summary, cues, drills)."""
+
+    name: str
+
+    def coach(self, feature_set: FeatureSet) -> CoachReport:
+        ...

futheros/ports/detector.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from ..domain.models import Detection
+
+
+@runtime_checkable
+class DetectorPort(Protocol):
+    """Finds the subject player + ball per frame and returns one Detection each."""
+
+    name: str
+
+    def detect(self, frames_bgr: list[np.ndarray]) -> list[Detection]:
+        ...

futheros/ports/goal_detector.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from ..domain.models import Box
+
+
+@runtime_checkable
+class GoalDetectorPort(Protocol):
+    """Locates the goal-mouth region(s) in a frame. For a fixed camera this is run
+    once and reused; the result feeds goal-event detection + scorer attribution."""
+
+    name: str
+
+    def detect_goals(self, frame_bgr: np.ndarray, conf: float = 0.4) -> list[Box]:
+        ...

futheros/ports/pose.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from ..domain.models import FramePose
+
+
+@runtime_checkable
+class PosePort(Protocol):
+    """Extracts per-frame 2D body landmarks (image plane only)."""
+
+    name: str
+
+    def estimate(self, frames_bgr: list[np.ndarray]) -> list[FramePose]:
+        ...
+
+    def close(self) -> None:
+        ...

futheros/ports/renderer.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from ..domain.models import (Clip, ContactResult, Detection, FeatureSet, FramePose,
+                             Trajectory)
+
+
+@runtime_checkable
+class RendererPort(Protocol):
+    """Produces visual artifacts: annotated frames, hero freeze-frame, scorecard."""
+
+    def annotate(self, clip: Clip, poses: list[FramePose], dets: list[Detection],
+                 fs: FeatureSet, contact: ContactResult,
+                 trajectory: Trajectory | None = None) -> list[np.ndarray]:
+        ...
+
+    def hero(self, clip: Clip, poses: list[FramePose], dets: list[Detection],
+             fs: FeatureSet, contact: ContactResult,
+             trajectory: Trajectory | None = None) -> np.ndarray:
+        ...
+
+    def scorecard(self, fs: FeatureSet, score: int) -> np.ndarray:
+        ...

futheros/ports/video.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from ..domain.models import Clip
+
+
+@runtime_checkable
+class VideoSourcePort(Protocol):
+    """Loads a video file into an upright in-memory Clip."""
+
+    def load(self, path: str, force_rotation: int | None = None) -> Clip:
+        ...
+
+
+@runtime_checkable
+class VideoSinkPort(Protocol):
+    """Writes annotated frames to a playable video file, returns its path."""
+
+    def write(self, frames_bgr: list[np.ndarray], out_path: str, fps: float) -> str:
+        ...

requirements.txt

@@ -0,0 +1,9 @@
+numpy
+opencv-python-headless
+gradio
+spaces
+mediapipe>=0.10.18
+rfdetr>=1.0
+supervision
+sam3==0.1.4
+huggingface-hub