api.py

import os
import json
import time
import uuid
import shutil
import traceback
import re
import sys
import importlib.util
import threading
import subprocess
import concurrent.futures
from urllib.parse import urlsplit, urlunsplit
import cv2
import numpy as np
from fastapi import FastAPI, File, UploadFile, Form, Request, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from fastapi.concurrency import run_in_threadpool
from fastapi.responses import JSONResponse
from fastapi.staticfiles import StaticFiles
from typing import List
from huggingface_hub import hf_hub_download, snapshot_download, HfApi

app = FastAPI(title="Sporalize Labs 3D Analysis Engine")

CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))


def default_runtime_root():
    if os.path.isdir("/data"):
        return os.path.join("/data", "sporalize_runtime")
    return os.path.join(os.path.expanduser("~"), ".sporalize_runtime")


RUNTIME_ROOT = os.environ.get("SPORALIZE_RUNTIME_DIR", default_runtime_root())
ASSETS_RUNTIME_ROOT = os.environ.get("SPORALIZE_ASSETS_DIR", os.path.join(RUNTIME_ROOT, "assets"))
WEIGHTS_RUNTIME_ROOT = os.environ.get("SPORALIZE_WEIGHTS_DIR", os.path.join(RUNTIME_ROOT, "weights"))
DEFAULT_LOCAL_STORAGE_ROOT = os.path.join(CURRENT_DIR, "Storage")
if not os.path.isdir("/data") and not os.access(CURRENT_DIR, os.W_OK):
    DEFAULT_LOCAL_STORAGE_ROOT = os.path.join(RUNTIME_ROOT, "storage")
STORAGE_ROOT = os.environ.get(
    "SPORALIZE_STORAGE_DIR",
    os.path.join("/data", "sporalize_storage") if os.path.isdir("/data") else DEFAULT_LOCAL_STORAGE_ROOT,
)
STORAGE_DATASET_REPO_ID = os.environ.get("SPORALIZE_STORAGE_REPO_ID", "Shoraky/SporalizeLabs-runtime-private").strip()
STORAGE_DATASET_REPO_TYPE = os.environ.get("SPORALIZE_STORAGE_REPO_TYPE", "dataset").strip()
STORAGE_DATASET_PATH = os.environ.get("SPORALIZE_STORAGE_DATASET_PATH", "Storage").strip("/").strip()
STORAGE_SYNC_INTERVAL_SECONDS = float(os.environ.get("SPORALIZE_STORAGE_SYNC_INTERVAL_SECONDS", "20"))
CONFIGURED_ASSETS_REPO_ID = os.environ.get("SPORALIZE_ASSETS_REPO_ID", "").strip()
ASSETS_REPO_ID = CONFIGURED_ASSETS_REPO_ID or STORAGE_DATASET_REPO_ID
ASSETS_REPO_TYPE = os.environ.get("SPORALIZE_ASSETS_REPO_TYPE", STORAGE_DATASET_REPO_TYPE or "dataset").strip() or "dataset"
ASSETS_REVISION = os.environ.get("SPORALIZE_ASSETS_REVISION")
ASSETS_REVISION = ASSETS_REVISION.strip() if ASSETS_REVISION else None
USE_LOCAL_ASSETS = os.environ.get("SPORALIZE_USE_LOCAL_ASSETS", "").strip().lower() in {"1", "true", "yes", "on"}

_storage_sync_lock = threading.Lock()
_storage_last_sync_ts = 0.0


DEFAULT_WEIGHT_SPECS = {
    "POSE_PATH": {
        "filename": "vitpose-s-coco_25.onnx",
        "repo_id": os.environ.get("SPORALIZE_POSE_MODEL_REPO_ID", "JunkyByte/easy_ViTPose"),
        "repo_type": os.environ.get("SPORALIZE_POSE_MODEL_REPO_TYPE", "model"),
        "repo_file": os.environ.get("SPORALIZE_POSE_MODEL_FILE", "onnx/coco_25/vitpose-25-s.onnx"),
        "override_env": "SPORALIZE_POSE_MODEL_PATH",
        "local_fallback": os.path.join(CURRENT_DIR, "Weights", "vitpose-s-coco_25.onnx"),
    },
    "YOLO_PATH": {
        "filename": "yolov8m.pt",
        "repo_id": os.environ.get("SPORALIZE_YOLO_MODEL_REPO_ID", "Ultralytics/YOLOv8"),
        "repo_type": os.environ.get("SPORALIZE_YOLO_MODEL_REPO_TYPE", "model"),
        "repo_file": os.environ.get("SPORALIZE_YOLO_MODEL_FILE", "yolov8m.pt"),
        "override_env": "SPORALIZE_YOLO_MODEL_PATH",
        "local_fallback": os.path.join(CURRENT_DIR, "Weights", "yolov8m.pt"),
    },
}

runtime_state = {
    "ready": False,
    "pipeline_root": None,
    "pipeline_source": None,
    "assets_repo_id": None,
    "assets_repo_type": None,
    "assets_revision": None,
    "run_pipeline": None,
    "weights": {},
}


def get_hf_token():
    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")


def hf_storage_enabled():
    return bool(STORAGE_DATASET_REPO_ID and STORAGE_DATASET_PATH)


def hf_storage_path(*parts: str) -> str:
    normalized = [STORAGE_DATASET_PATH]
    normalized.extend(part.strip("/").replace("\\", "/") for part in parts if part is not None and str(part).strip("/"))
    return "/".join(segment for segment in normalized if segment)


def sync_storage_from_hf(force: bool = False):
    global _storage_last_sync_ts
    if not hf_storage_enabled():
        return
    now = time.time()
    if not force and (now - _storage_last_sync_ts) < STORAGE_SYNC_INTERVAL_SECONDS:
        return

    with _storage_sync_lock:
        now = time.time()
        if not force and (now - _storage_last_sync_ts) < STORAGE_SYNC_INTERVAL_SECONDS:
            return

        print(f"[SPORALIZE] Storage sync: downloading from HF repo '{STORAGE_DATASET_REPO_ID}'...", flush=True)
        t0 = time.time()
        sync_cache_root = os.path.join(RUNTIME_ROOT, "storage-sync-cache")
        os.makedirs(sync_cache_root, exist_ok=True)
        local_repo_dir = os.path.join(sync_cache_root, safe_name(STORAGE_DATASET_REPO_ID))

        snapshot_download(
            repo_id=STORAGE_DATASET_REPO_ID,
            repo_type=STORAGE_DATASET_REPO_TYPE,
            token=get_hf_token(),
            local_dir=local_repo_dir,
            allow_patterns=[f"{STORAGE_DATASET_PATH}/**"],
        )

        source_storage = os.path.join(local_repo_dir, STORAGE_DATASET_PATH)
        if os.path.isdir(source_storage):
            if os.path.isdir(STORAGE_ROOT):
                shutil.rmtree(STORAGE_ROOT, ignore_errors=True)
            shutil.copytree(source_storage, STORAGE_ROOT, dirs_exist_ok=True)
        _storage_last_sync_ts = time.time()
        print(f"[SPORALIZE] Storage sync: done in {time.time() - t0:.1f}s", flush=True)


def push_session_to_hf(player_id: str, session_id: str, session_dir: str):
    if not hf_storage_enabled():
        return
    api = HfApi(token=get_hf_token())
    api.upload_folder(
        repo_id=STORAGE_DATASET_REPO_ID,
        repo_type=STORAGE_DATASET_REPO_TYPE,
        folder_path=session_dir,
        path_in_repo=hf_storage_path(safe_name(player_id), safe_name(session_id)),
        commit_message=f"Add session {safe_name(session_id)} for player {safe_name(player_id)}",
    )


def delete_session_from_hf(player_id: str, session_id: str):
    if not hf_storage_enabled():
        return
    api = HfApi(token=get_hf_token())
    api.delete_folder(
        repo_id=STORAGE_DATASET_REPO_ID,
        repo_type=STORAGE_DATASET_REPO_TYPE,
        path_in_repo=hf_storage_path(safe_name(player_id), safe_name(session_id)),
        commit_message=f"Delete session {safe_name(session_id)} for player {safe_name(player_id)}",
    )


def delete_player_from_hf(player_id: str):
    if not hf_storage_enabled():
        return
    api = HfApi(token=get_hf_token())
    api.delete_folder(
        repo_id=STORAGE_DATASET_REPO_ID,
        repo_type=STORAGE_DATASET_REPO_TYPE,
        path_in_repo=hf_storage_path(safe_name(player_id)),
        commit_message=f"Delete player {safe_name(player_id)} storage",
    )


def path_has_session_data(directory: str):
    if not os.path.isdir(directory):
        return False
    for _root, _dirs, files in os.walk(directory):
        if "session.json" in files:
            return True
    return False


def seed_storage_if_needed(seed_dir: str, target_dir: str):
    if not os.path.isdir(seed_dir):
        return
    os.makedirs(target_dir, exist_ok=True)
    if path_has_session_data(target_dir):
        return
    shutil.copytree(seed_dir, target_dir, dirs_exist_ok=True)


def local_pipeline_bundle_available():
    return (
        os.path.isfile(os.path.join(CURRENT_DIR, "pipeline.py"))
        and os.path.isdir(os.path.join(CURRENT_DIR, "ViTPose"))
    )


def use_local_pipeline_bundle():
    seed_storage_if_needed(os.path.join(CURRENT_DIR, "Storage"), STORAGE_ROOT)
    runtime_state.update({
        "pipeline_source": "local_bundle",
        "assets_repo_id": None,
        "assets_repo_type": None,
        "assets_revision": None,
    })
    return CURRENT_DIR


def use_private_pipeline_repo():
    if not ASSETS_REPO_ID:
        raise RuntimeError(
            "A private runtime pipeline is required. Set SPORALIZE_ASSETS_REPO_ID "
            "or run from a directory that contains both pipeline.py and ViTPose."
        )

    assets_dir = os.path.join(ASSETS_RUNTIME_ROOT, safe_name(ASSETS_REPO_ID))
    snapshot_download(
        repo_id=ASSETS_REPO_ID,
        repo_type=ASSETS_REPO_TYPE,
        revision=ASSETS_REVISION,
        token=get_hf_token(),
        local_dir=assets_dir,
        allow_patterns=["pipeline.py", "ViTPose/**", "Storage/**", "Weights/**"],
    )

    if not os.path.isfile(os.path.join(assets_dir, "pipeline.py")):
        raise RuntimeError(f"pipeline.py was not found in private assets repo {ASSETS_REPO_ID}")
    if not os.path.isdir(os.path.join(assets_dir, "ViTPose")):
        raise RuntimeError(f"ViTPose was not found in private assets repo {ASSETS_REPO_ID}")

    seed_storage_if_needed(os.path.join(assets_dir, "Storage"), STORAGE_ROOT)
    runtime_state.update({
        "pipeline_source": "private_repo",
        "assets_repo_id": ASSETS_REPO_ID,
        "assets_repo_type": ASSETS_REPO_TYPE,
        "assets_revision": ASSETS_REVISION,
    })
    return assets_dir


def resolve_pipeline_root():
    if local_pipeline_bundle_available() and (USE_LOCAL_ASSETS or not CONFIGURED_ASSETS_REPO_ID):
        return use_local_pipeline_bundle()

    if ASSETS_REPO_ID:
        return use_private_pipeline_repo()

    if local_pipeline_bundle_available():
        return use_local_pipeline_bundle()

    raise RuntimeError(
        "No runtime pipeline is available. Provide a private Hugging Face repo via "
        "SPORALIZE_ASSETS_REPO_ID or bundle pipeline.py with ViTPose for local development."
    )


def load_pipeline_callable(pipeline_root: str):
    pipeline_path = os.path.join(pipeline_root, "pipeline.py")
    if not os.path.isfile(pipeline_path):
        raise RuntimeError(f"pipeline.py was not found at {pipeline_path}")

    if pipeline_root not in sys.path:
        sys.path.insert(0, pipeline_root)

    module_name = "sporalize_runtime_pipeline"
    if module_name in sys.modules:
        del sys.modules[module_name]

    spec = importlib.util.spec_from_file_location(module_name, pipeline_path)
    if spec is None or spec.loader is None:
        raise RuntimeError(f"Unable to create import spec for {pipeline_path}")
    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module
    spec.loader.exec_module(module)

    run_pipeline = getattr(module, "run_pipeline", None)
    if run_pipeline is None:
        raise RuntimeError("run_pipeline was not found in the resolved pipeline module")
    return run_pipeline


def ensure_weight_file(spec: dict, pipeline_root: str):
    override_path = os.environ.get(spec["override_env"])
    if override_path and os.path.isfile(override_path):
        print(f"[SPORALIZE] Weight '{spec['filename']}': using env override at {override_path}", flush=True)
        return override_path

    pipeline_weight = os.path.join(pipeline_root, "Weights", spec["filename"])
    if os.path.isfile(pipeline_weight):
        print(f"[SPORALIZE] Weight '{spec['filename']}': found in pipeline bundle", flush=True)
        return pipeline_weight

    local_fallback = spec.get("local_fallback")
    if local_fallback and os.path.isfile(local_fallback):
        print(f"[SPORALIZE] Weight '{spec['filename']}': using local fallback at {local_fallback}", flush=True)
        return local_fallback

    os.makedirs(WEIGHTS_RUNTIME_ROOT, exist_ok=True)
    cached_path = os.path.join(WEIGHTS_RUNTIME_ROOT, spec["filename"])
    if os.path.isfile(cached_path):
        print(f"[SPORALIZE] Weight '{spec['filename']}': cache hit at {cached_path}", flush=True)
        return cached_path

    print(f"[SPORALIZE] Weight '{spec['filename']}': not cached, downloading from HF repo '{spec['repo_id']}'...", flush=True)
    t0 = time.time()
    result = hf_hub_download(
        repo_id=spec["repo_id"],
        repo_type=spec.get("repo_type", "model"),
        filename=spec["repo_file"],
        token=get_hf_token(),
        local_dir=WEIGHTS_RUNTIME_ROOT,
    )
    print(f"[SPORALIZE] Weight '{spec['filename']}': downloaded in {time.time() - t0:.1f}s -> {result}", flush=True)
    return result


def ensure_runtime_ready(force: bool = False):
    if runtime_state["ready"] and not force:
        return runtime_state

    os.makedirs(RUNTIME_ROOT, exist_ok=True)
    os.makedirs(STORAGE_ROOT, exist_ok=True)

    pipeline_root = resolve_pipeline_root()
    run_pipeline = load_pipeline_callable(pipeline_root)
    weight_paths = {name: ensure_weight_file(spec, pipeline_root) for name, spec in DEFAULT_WEIGHT_SPECS.items()}

    runtime_state.update({
        "ready": True,
        "pipeline_root": pipeline_root,
        "run_pipeline": run_pipeline,
        "weights": weight_paths,
    })
    return runtime_state


os.makedirs(STORAGE_ROOT, exist_ok=True)
app.mount("/storage", StaticFiles(directory=STORAGE_ROOT), name="storage")

progress_store = {}

cancel_store = {}
TERMINAL_PROGRESS_STATUSES = {"completed", "failed", "cancelled"}
CANCEL_PROGRESS_STATUSES = {"cancelling", "cancelled"}
ACTIVE_PROGRESS_STATUSES = {"queued", "running"}
active_job_futures = {}
active_job_lock = threading.Lock()

def env_int(name: str, default: int) -> int:
    try:
        return int(os.environ.get(name, str(default)))
    except Exception:
        return default


ANALYSIS_WORKERS = max(1, env_int("SPORALIZE_ANALYSIS_WORKERS", 1))
analysis_executor = concurrent.futures.ThreadPoolExecutor(
    max_workers=ANALYSIS_WORKERS,
    thread_name_prefix="sporalize-analysis",
)
JOB_PROGRESS_ROOT = os.environ.get("SPORALIZE_JOB_PROGRESS_DIR", os.path.join(RUNTIME_ROOT, "jobs"))
_progress_file_last_write = {}


def progress_file_path(client_id: str) -> str:
    return os.path.join(JOB_PROGRESS_ROOT, f"{safe_name(client_id)}.json")


def write_progress_file(client_id: str, payload: dict):
    try:
        os.makedirs(JOB_PROGRESS_ROOT, exist_ok=True)
        with open(progress_file_path(client_id), "w", encoding="utf-8") as f:
            json.dump(payload, f, indent=2)
    except Exception:
        pass


def read_progress_file(client_id: str):
    try:
        path = progress_file_path(client_id)
        if not os.path.isfile(path):
            return None
        with open(path, "r", encoding="utf-8") as f:
            return json.load(f)
    except Exception:
        return None


def current_progress_payload(client_id: str):
    memory_payload = progress_store.get(client_id) or {}
    file_payload = read_progress_file(client_id) or {}
    if file_payload.get("updatedAt", 0) > memory_payload.get("updatedAt", 0):
        return file_payload
    return memory_payload or file_payload


def cleanup_active_job_futures():
    with active_job_lock:
        for stored_client_id, future in list(active_job_futures.items()):
            if future.done() or future.cancelled():
                active_job_futures.pop(stored_client_id, None)


def register_active_job(client_id: str, future):
    cleanup_active_job_futures()
    with active_job_lock:
        active_job_futures[client_id] = future


def unregister_active_job(client_id: str):
    with active_job_lock:
        active_job_futures.pop(client_id, None)


def get_active_job_future(client_id: str):
    cleanup_active_job_futures()
    with active_job_lock:
        return active_job_futures.get(client_id)


def active_job_client_ids():
    cleanup_active_job_futures()
    with active_job_lock:
        return list(active_job_futures.keys())


def build_active_job_payload(client_id: str, payload: dict):
    updated_at = int(payload.get("updatedAt") or time.time() * 1000)
    return {
        "clientId": payload.get("clientId") or client_id,
        "sessionId": payload.get("sessionId"),
        "playerId": payload.get("playerId"),
        "createdAt": int(payload.get("createdAt") or updated_at),
        "updatedAt": updated_at,
        "progress": payload.get("progress", 0.0),
        "phase": payload.get("phase") or "Queued for Processing",
        "status": payload.get("status") or "queued",
        "resultUrl": payload.get("resultUrl"),
        "error": payload.get("error"),
    }


def is_cancel_requested(client_id: str):
    if cancel_store.get(client_id):
        return True
    stored_progress = read_progress_file(client_id)
    return bool(stored_progress and stored_progress.get("status") in CANCEL_PROGRESS_STATUSES)


def clear_cancel_request(client_id: str):
    cancel_store.pop(client_id, None)


def should_write_progress_file(client_id: str, payload: dict):
    status = payload.get("status")
    if status in {"uploading", "queued", "cancelling", "completed", "failed", "cancelled"}:
        _progress_file_last_write[client_id] = time.time()
        return True

    now = time.time()
    if (now - _progress_file_last_write.get(client_id, 0.0)) >= 1.0:
        _progress_file_last_write[client_id] = now
        return True
    return False


def set_progress(
    client_id: str,
    progress: float,
    phase: str,
    step: int = 0,
    total: int = 0,
    status: str = "running",
    **extra,
):
    memory_payload = progress_store.get(client_id, {})
    file_payload = read_progress_file(client_id) or {}
    if file_payload.get("updatedAt", 0) > memory_payload.get("updatedAt", 0):
        payload = dict(file_payload)
    else:
        payload = dict(memory_payload)

    now_ms = int(time.time() * 1000)
    if not payload.get("createdAt"):
        payload["createdAt"] = now_ms

    if payload.get("status") == "cancelling" and status not in TERMINAL_PROGRESS_STATUSES:
        status = "cancelling"
        phase = payload.get("phase") or "Cancellation Requested"

    payload.update({
        "clientId": client_id,
        "progress": max(0.0, min(100.0, float(progress))),
        "step": max(0, int(step or 0)),
        "total": max(0, int(total or 0)),
        "phase": phase,
        "status": status,
        "updatedAt": now_ms,
    })
    payload.update({key: value for key, value in extra.items() if value is not None})
    progress_store[client_id] = payload
    if should_write_progress_file(client_id, payload):
        write_progress_file(client_id, payload)


def safe_name(value: str) -> str:
    allowed = []
    for ch in str(value):
        if ch.isalnum() or ch in ("-", "_", "."):
            allowed.append(ch)
        else:
            allowed.append("_")
    cleaned = "".join(allowed).strip("._")
    return cleaned or "item"


def session_storage_paths(player_id: str, session_id: str):
    player_dir = os.path.join(STORAGE_ROOT, safe_name(player_id))
    session_dir = os.path.join(player_dir, safe_name(session_id))
    videos_dir = os.path.join(session_dir, "videos")
    return player_dir, session_dir, videos_dir


def list_session_files():
    session_files = []
    for root, _, files in os.walk(STORAGE_ROOT):
        if "session.json" in files:
            session_files.append(os.path.join(root, "session.json"))
    return sorted(session_files, key=os.path.getmtime, reverse=True)


def request_public_base_url(request: Request) -> str:
    configured_public_base = os.environ.get("SPORALIZE_PUBLIC_BASE_URL", "").strip()
    if configured_public_base:
        return configured_public_base.rstrip("/")

    forwarded_proto = request.headers.get("x-forwarded-proto", "").split(",")[0].strip().lower()
    forwarded_host = request.headers.get("x-forwarded-host", "").split(",")[0].strip()
    if forwarded_proto in ("http", "https") and forwarded_host:
        return f"{forwarded_proto}://{forwarded_host}".rstrip("/")

    base_url = str(request.base_url).rstrip("/")
    if forwarded_proto in ("http", "https"):
        parsed = urlsplit(base_url)
        base_url = urlunsplit((forwarded_proto, parsed.netloc, parsed.path, "", "")).rstrip("/")

    return base_url


def build_storage_url(request_or_base_url, *parts: str) -> str:
    relative = "/".join(safe_name(part) if idx < len(parts) - 1 else part.replace("\\", "/") for idx, part in enumerate(parts))
    if isinstance(request_or_base_url, str):
        base_url = request_or_base_url.rstrip("/")
    else:
        base_url = request_public_base_url(request_or_base_url)
    return base_url + "/storage/" + relative.lstrip("/")


def parse_video_timecode(value, fps=30.0):
    if value is None:
        return 0.0
    if isinstance(value, (int, float, np.integer, np.floating)):
        return max(0.0, float(value))

    parts = str(value).split(":")
    if len(parts) == 4:
        h, m, s, f = [int(float(part or 0)) for part in parts]
        return max(0.0, (h * 3600) + (m * 60) + s + (f / max(1.0, float(fps))))

    try:
        return max(0.0, float(value))
    except Exception:
        return 0.0


def detect_camera_id(file_name: str):
    match = re.search(r"_cam_(\d+)_", file_name)
    if match:
        return int(match.group(1))
    return None


def split_camera_video_variants(videos_dir: str):
    grouped: dict[int, dict[str, str]] = {}
    for file_name in sorted(os.listdir(videos_dir)):
        camera_id = detect_camera_id(file_name)
        if camera_id is None:
            continue
        full_path = os.path.join(videos_dir, file_name)
        if not os.path.isfile(full_path):
            continue
        bucket = grouped.setdefault(camera_id, {})
        if file_name.lower().endswith(".web.mp4"):
            bucket["web"] = full_path
        else:
            bucket["base"] = full_path

    primary_map = {}
    fallback_map = {}
    for camera_id in sorted(grouped.keys()):
        base_path = grouped[camera_id].get("base")
        web_path = grouped[camera_id].get("web")
        if base_path:
            primary_map[camera_id] = base_path
            if web_path:
                fallback_map[camera_id] = web_path
        elif web_path:
            primary_map[camera_id] = web_path

    return primary_map, fallback_map


def normalize_video_for_web(input_path: str) -> str:
    """
    Re-encode uploaded video to a browser-friendly MP4 stream.
    Falls back to the original file if normalization fails.
    """
    output_path = os.path.splitext(input_path)[0] + ".web.mp4"

    # First try ffmpeg -> H.264 + yuv420p for maximum browser compatibility.
    ffmpeg_cmd = [
        "ffmpeg",
        "-y",
        "-i",
        input_path,
        "-an",
        "-c:v",
        "libx264",
        "-preset",
        "veryfast",
        "-pix_fmt",
        "yuv420p",
        "-movflags",
        "+faststart",
        output_path,
    ]
    try:
        ffmpeg_proc = subprocess.run(ffmpeg_cmd, capture_output=True, text=True)
        if ffmpeg_proc.returncode == 0 and os.path.exists(output_path) and os.path.getsize(output_path) > 0:
            return output_path
    except Exception:
        pass

    # Fallback: OpenCV transcode when ffmpeg is unavailable.
    cap = cv2.VideoCapture(input_path)
    if not cap.isOpened():
        return input_path

    fps = cap.get(cv2.CAP_PROP_FPS)
    if not fps or not np.isfinite(fps) or fps <= 0:
        fps = 30.0

    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
    if width <= 0 or height <= 0:
        cap.release()
        return input_path

    writer = cv2.VideoWriter(
        output_path,
        cv2.VideoWriter_fourcc(*"mp4v"),
        float(fps),
        (width, height),
    )
    if not writer.isOpened():
        cap.release()
        return input_path

    frame_count = 0
    success = True
    while True:
        ok, frame = cap.read()
        if not ok:
            break
        writer.write(frame)
        frame_count += 1

    cap.release()
    writer.release()

    if frame_count <= 0:
        success = False
    elif not os.path.exists(output_path) or os.path.getsize(output_path) <= 0:
        success = False

    if not success:
        if os.path.exists(output_path):
            os.remove(output_path)
        return input_path

    return output_path


def normalize_camera_videos_for_web(camera_map):
    fallback_map = {}
    items = [(camera_id, video_path) for camera_id, video_path in sorted(camera_map.items()) if video_path]
    if not items:
        return fallback_map

    def normalize_item(item):
        camera_id, video_path = item
        normalized_path = normalize_video_for_web(video_path)
        if normalized_path != video_path and os.path.exists(normalized_path):
            return camera_id, normalized_path
        return None

    max_workers = min(4, len(items))
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        for result in executor.map(normalize_item, items):
            if result is not None:
                camera_id, normalized_path = result
                fallback_map[int(camera_id)] = normalized_path

    return fallback_map


def build_camera_video_entries(request_or_base_url, player_id: str, session_id: str, camera_map):
    return [
        {
            "cameraId": int(camera_id),
            "url": build_storage_url(
                request_or_base_url,
                safe_name(player_id),
                safe_name(session_id),
                "videos",
                os.path.basename(video_path),
            ),
        }
        for camera_id, video_path in sorted(camera_map.items())
        if video_path and os.path.exists(video_path)
    ]


def build_action_clip_entries(request_or_base_url, player_id: str, session_id: str, clip_map):
    return [
        {
            "cameraId": int(camera_id),
            "url": build_storage_url(
                request_or_base_url,
                safe_name(player_id),
                safe_name(session_id),
                "clips",
                os.path.basename(clip_path),
            ),
        }
        for camera_id, clip_path in sorted(clip_map.items())
        if clip_path and os.path.exists(clip_path)
    ]


def normalize_session_payload(session: dict, request: Request):
    session_id = session.get("id")
    player_id = session.get("playerId")
    if not session_id or not player_id:
        return session

    session_dir = find_session_path(session_id)
    if not session_dir:
        return session

    videos_dir = os.path.join(session_dir, "videos")
    if not os.path.isdir(videos_dir):
        return session

    camera_map, fallback_camera_map = split_camera_video_variants(videos_dir)

    if not camera_map:
        return session

    normalized_actions = []
    for action in session.get("actions", []):
        normalized_action = dict(action)
        fps = float(normalized_action.get("fps") or 30.0)
        fps = max(1.0, fps)

        absolute_start_frame = normalized_action.get("sourceStartFrame")
        absolute_end_frame = normalized_action.get("sourceEndFrame")
        if absolute_start_frame is None or absolute_end_frame is None:
            absolute_start_frame = normalized_action.get("startFrame")
            absolute_end_frame = normalized_action.get("endFrame")

        try:
            absolute_start_frame = int(absolute_start_frame) if absolute_start_frame is not None else None
            absolute_end_frame = int(absolute_end_frame) if absolute_end_frame is not None else None
        except Exception:
            absolute_start_frame = None
            absolute_end_frame = None

        if absolute_start_frame is not None and absolute_end_frame is not None and absolute_end_frame >= absolute_start_frame:
            start_seconds = max(0.0, absolute_start_frame / fps)
            end_seconds = max(start_seconds, (absolute_end_frame + 1) / fps)
            normalized_action["startFrame"] = absolute_start_frame
            normalized_action["endFrame"] = absolute_end_frame
        else:
            total_frames = int(normalized_action.get("totalFrames") or 0)
            start_seconds = parse_video_timecode(normalized_action.get("start"), fps=fps)
            if total_frames > 0:
                end_seconds = start_seconds + (total_frames / fps)
            else:
                end_seconds = max(start_seconds, parse_video_timecode(normalized_action.get("end"), fps=fps))

        normalized_action["cameraClips"] = normalized_action.get("cameraClips") or build_camera_video_entries(
            request, player_id, session_id, camera_map
        )
        if fallback_camera_map:
            normalized_action["sourceCameraClips"] = normalized_action.get("sourceCameraClips") or build_camera_video_entries(
                request, player_id, session_id, fallback_camera_map
            )
        normalized_action["startSeconds"] = round(start_seconds, 6)
        normalized_action["endSeconds"] = round(end_seconds, 6)
        normalized_actions.append(normalized_action)

    normalized_session = dict(session)
    normalized_session["actions"] = normalized_actions
    return normalized_session


def summarize_action_for_archive(action: dict):
    return {
        "id": action.get("id"),
        "label": action.get("label", "Unknown"),
        "start": action.get("start", "00:00:00:00"),
        "end": action.get("end", "00:00:00:00"),
        "fps": action.get("fps"),
        "startFrame": action.get("startFrame"),
        "endFrame": action.get("endFrame"),
        "startSeconds": action.get("startSeconds", 0),
        "endSeconds": action.get("endSeconds", 0),
        "activeFoot": action.get("activeFoot"),
        "totalFrames": action.get("totalFrames", 0),
        "preFrames": action.get("preFrames", 0),
        "inFrame": action.get("inFrame", 0),
        "postFrames": action.get("postFrames", 0),
        "sourceStartFrame": action.get("sourceStartFrame"),
        "sourceEndFrame": action.get("sourceEndFrame"),
        "sourceStartSeconds": action.get("sourceStartSeconds"),
        "sourceEndSeconds": action.get("sourceEndSeconds"),
        "cameraClips": [],
        "sourceCameraClips": [],
        "preMetrics": [],
        "preActionMetrics": [],
        "inActionMetrics": [],
        "postMetrics": [],
        "postActionMetrics": [],
        "fullIntervalMetrics": [],
        "skeleton": [],
    }


def build_session_summary_payload(session: dict):
    return {
        "id": session.get("id"),
        "playerId": session.get("playerId"),
        "playerName": session.get("playerName"),
        "summaryOnly": True,
        "createdAt": session.get("createdAt"),
        "targetSize": session.get("targetSize"),
        "cameraCount": session.get("cameraCount", 0),
        "actions": [
            summarize_action_for_archive(action)
            for action in session.get("actions", [])
            if isinstance(action, dict)
        ],
        "failedActions": session.get("failedActions", []),
    }


def session_summary_path(session_file: str):
    return os.path.join(os.path.dirname(session_file), "session-summary.json")


def write_session_summary(session_file: str, session: dict):
    summary = build_session_summary_payload(session)
    with open(session_summary_path(session_file), "w", encoding="utf-8") as f:
        json.dump(summary, f, indent=2)
    return summary


def load_session_summary(session_file: str):
    summary_file = session_summary_path(session_file)
    if os.path.isfile(summary_file):
        with open(summary_file, "r", encoding="utf-8") as f:
            return json.load(f)

    with open(session_file, "r", encoding="utf-8") as f:
        session = json.load(f)

    summary = build_session_summary_payload(session)
    try:
        with open(summary_file, "w", encoding="utf-8") as f:
            json.dump(summary, f, indent=2)
    except Exception:
        pass
    return summary


def json_default(value):
    if isinstance(value, np.generic):
        return value.item()
    if isinstance(value, np.ndarray):
        return value.tolist()
    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")


def make_json_safe(value):
    if value is None or isinstance(value, (str, bool, int)):
        return value
    if isinstance(value, float):
        return value if np.isfinite(value) else None
    if isinstance(value, np.generic):
        return make_json_safe(value.item())
    if isinstance(value, np.ndarray):
        return make_json_safe(value.tolist())
    if isinstance(value, dict):
        return {str(key): make_json_safe(item) for key, item in value.items()}
    if isinstance(value, (list, tuple, set)):
        return [make_json_safe(item) for item in value]
    if hasattr(value, "tolist"):
        try:
            return make_json_safe(value.tolist())
        except Exception:
            pass
    return str(value)


def export_action_clips(camera_map, clips_dir, action_index, start_frame, end_frame, fps):
    os.makedirs(clips_dir, exist_ok=True)
    frame_count = max(0, end_frame - start_frame + 1)
    clip_paths = {}

    for camera_id, video_path in sorted(camera_map.items()):
        cap = cv2.VideoCapture(video_path)
        if not cap.isOpened():
            continue

        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
        if width <= 0 or height <= 0:
            cap.release()
            continue

        clip_name = f"action_{action_index:02d}_cam_{camera_id}.mp4"
        clip_path = os.path.join(clips_dir, clip_name)
        writer = cv2.VideoWriter(
            clip_path,
            cv2.VideoWriter_fourcc(*"mp4v"),
            max(1.0, float(fps)),
            (width, height),
        )

        cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
        written = 0
        while written < frame_count:
            ok, frame = cap.read()
            if not ok:
                break
            writer.write(frame)
            written += 1

        writer.release()
        cap.release()

        if written > 0 and os.path.exists(clip_path):
            clip_paths[camera_id] = clip_path
        elif os.path.exists(clip_path):
            os.remove(clip_path)

    return clip_paths


def load_session_by_id(session_id: str):
    target_name = safe_name(session_id)
    for session_file in list_session_files():
        session_dir = os.path.basename(os.path.dirname(session_file))
        if session_dir != target_name:
            continue
        with open(session_file, "r", encoding="utf-8") as f:
            return json.load(f)
    return None


def find_session_path(session_id: str):
    target_name = safe_name(session_id)
    for session_file in list_session_files():
        session_dir = os.path.dirname(session_file)
        if os.path.basename(session_dir) == target_name:
            return session_dir
    return None


def player_storage_path(player_id: str):
    return os.path.join(STORAGE_ROOT, safe_name(player_id))


def get_cors_origins():
    configured = os.environ.get("CORS_ALLOW_ORIGINS", "*").strip()
    if not configured or configured == "*":
        return ["*"]
    return [origin.strip() for origin in configured.split(",") if origin.strip()]


@app.on_event("startup")
def startup_event():
    print("[SPORALIZE] Server startup: initializing runtime...", flush=True)
    t0 = time.time()
    ensure_runtime_ready()
    print(f"[SPORALIZE] Runtime ready in {time.time() - t0:.1f}s (pipeline_source={runtime_state.get('pipeline_source')})", flush=True)
    t1 = time.time()
    sync_storage_from_hf(force=True)
    print(f"[SPORALIZE] Storage sync done in {time.time() - t1:.1f}s", flush=True)
    print(f"[SPORALIZE] Startup complete in {time.time() - t0:.1f}s total", flush=True)


@app.get("/healthz")
def healthz():
    runtime = ensure_runtime_ready()
    return {
        "status": "ok",
        "storageRoot": STORAGE_ROOT,
        "pipelineRoot": runtime.get("pipeline_root"),
        "pipelineSource": runtime.get("pipeline_source"),
        "assetsRepoId": runtime.get("assets_repo_id"),
        "assetsRepoType": runtime.get("assets_repo_type"),
        "assetsRevision": runtime.get("assets_revision"),
    }

@app.post("/api/cancel/{client_id}")
def cancel_processing(client_id: str):
    current = current_progress_payload(client_id)
    current_status = current.get("status")
    if current_status in TERMINAL_PROGRESS_STATUSES:
        return {
            "status": current_status,
            "clientId": client_id,
            "sessionId": current.get("sessionId"),
        }

    cancel_store[client_id] = True
    future = get_active_job_future(client_id)
    queued_cancelled = bool(future and future.cancel())
    set_progress(
        client_id,
        current.get("progress", 0.0),
        "Processing Cancelled" if queued_cancelled else "Cancellation Requested",
        current.get("step", 0),
        current.get("total", 0),
        "cancelled" if queued_cancelled else "cancelling",
    )
    if queued_cancelled:
        session_id = current.get("sessionId")
        player_id = current.get("playerId")
        if player_id and session_id:
            _player_dir, session_dir, _videos_dir = session_storage_paths(player_id, session_id)
            if os.path.isdir(session_dir):
                shutil.rmtree(session_dir, ignore_errors=True)
        unregister_active_job(client_id)
        clear_cancel_request(client_id)
    return {
        "status": "cancelled" if queued_cancelled else "cancelling",
        "clientId": client_id,
        "sessionId": current.get("sessionId"),
    }

@app.get("/api/progress/{client_id}")
def get_progress(client_id: str):
    stored_progress = current_progress_payload(client_id)
    if stored_progress:
        return stored_progress
    return {
        "progress": 0.0,
        "step": 0,
        "total": 0,
        "phase": "Initializing",
        "status": "idle",
        "updatedAt": int(time.time() * 1000),
    }


@app.get("/api/active-analyses")
def get_active_analyses():
    jobs = []
    for client_id in active_job_client_ids():
        payload = current_progress_payload(client_id)
        if not payload:
            continue
        status = payload.get("status")
        if status not in ACTIVE_PROGRESS_STATUSES:
            continue
        jobs.append(build_active_job_payload(client_id, payload))

    jobs.sort(key=lambda item: item.get("updatedAt", 0), reverse=True)
    return {"jobs": jobs}


@app.get("/api/sessions/{session_id}")
def get_session(session_id: str, request: Request):
    session = load_session_by_id(session_id)
    if session is None:
        raise HTTPException(status_code=404, detail="Session not found")
    return normalize_session_payload(session, request)


@app.get("/api/archive")
def get_archive(request: Request, full: bool = False):
    sessions = []
    for session_file in list_session_files():
        try:
            if full:
                with open(session_file, "r", encoding="utf-8") as f:
                    session = json.load(f)
                sessions.append(normalize_session_payload(session, request))
            else:
                sessions.append(load_session_summary(session_file))
        except Exception:
            continue
    return {"sessions": sessions}


@app.delete("/api/sessions/{session_id}")
def delete_session(session_id: str):
    session_dir = find_session_path(session_id)
    if session_dir is None:
        raise HTTPException(status_code=404, detail="Session not found")

    player_dir = os.path.dirname(session_dir)
    player_id = os.path.basename(player_dir)
    shutil.rmtree(session_dir, ignore_errors=True)
    try:
        delete_session_from_hf(player_id, session_id)
    except Exception:
        pass

    if os.path.isdir(player_dir) and not os.listdir(player_dir):
        os.rmdir(player_dir)

    return {"status": "deleted", "sessionId": session_id}


@app.delete("/api/players/{player_id}")
def delete_player(player_id: str):
    player_dir = player_storage_path(player_id)
    if not os.path.isdir(player_dir):
        raise HTTPException(status_code=404, detail="Player storage not found")

    shutil.rmtree(player_dir, ignore_errors=True)
    try:
        delete_player_from_hf(player_id)
    except Exception:
        pass
    return {"status": "deleted", "playerId": player_id}

cors_origins = get_cors_origins()
app.add_middleware(
    CORSMiddleware,
    allow_origins=cors_origins,
    allow_credentials=(cors_origins != ["*"]),
    allow_methods=["*"],
    allow_headers=["*"],
)


def format_metric_series(name, unit, values_list):
    return {
        "name": name,
        "unit": unit,
        "values": [
            {"frame": i, "value": safe_float(v)}
            for i, v in enumerate(values_list)
        ]
    }


def safe_float(value):
    try:
        number = float(value)
        return None if np.isnan(number) else number
    except Exception:
        return None


def frame_number(value):
    try:
        if value is None:
            return None
        return int(float(value))
    except Exception:
        return None


def relative_frame(value, start_frame=0, fallback=0):
    frame = frame_number(value)
    if frame is None:
        return fallback
    start = frame_number(start_frame) or 0
    return frame - start if frame >= start else frame


def safe_metric_value(value):
    if value is None:
        return None
    number = safe_float(value)
    if number is not None:
        return round(number, 3)
    if isinstance(value, (str, bool)):
        return value
    if isinstance(value, (dict, list, tuple)):
        return None
    return str(value)


def point_to_float_list(point):
    if point is None:
        return None
    if hasattr(point, "tolist"):
        point = point.tolist()
    try:
        values = list(point)
    except Exception:
        return None
    if len(values) < 3:
        return None
    xyz = []
    for component in values[:3]:
        number = safe_float(component)
        if number is None:
            return None
        xyz.append(float(number))
    return xyz


def map_value(mapping, key):
    if not isinstance(mapping, dict):
        return None
    if key in mapping:
        return mapping[key]
    str_key = str(key)
    if str_key in mapping:
        return mapping[str_key]
    target = frame_number(key)
    for current_key, value in mapping.items():
        if frame_number(current_key) == target:
            return value
    return None


def skeleton_joint(raw_skel, joint_index):
    if raw_skel is None:
        return None
    if hasattr(raw_skel, "tolist") and not isinstance(raw_skel, dict):
        raw_skel = raw_skel.tolist()
    if isinstance(raw_skel, dict):
        if joint_index in raw_skel:
            return raw_skel[joint_index]
        return raw_skel.get(str(joint_index))
    if isinstance(raw_skel, (list, tuple)) and joint_index < len(raw_skel):
        return raw_skel[joint_index]
    return None


def max_joint_index(raw_skel):
    if raw_skel is None:
        return 32
    if hasattr(raw_skel, "tolist") and not isinstance(raw_skel, dict):
        raw_skel = raw_skel.tolist()
    if isinstance(raw_skel, dict):
        keys = [frame_number(key) for key in raw_skel.keys()]
        keys = [key for key in keys if key is not None]
        return max(keys, default=32)
    if isinstance(raw_skel, (list, tuple)):
        return max(32, len(raw_skel) - 1)
    return 32


def build_skeleton_frames(rep, analytics, start_frame, end_frame):
    tracking_data = analytics.get("tracking_data", {}) if isinstance(analytics, dict) else {}
    player_skeletons = tracking_data.get("player_skeletons") if isinstance(tracking_data, dict) else None
    ball_positions = tracking_data.get("ball_positions") if isinstance(tracking_data, dict) else None

    if not isinstance(player_skeletons, dict):
        player_skeletons = rep.get("skel_history", {})
    if not isinstance(ball_positions, dict):
        ball_positions = rep.get("ball_history", {})

    skeleton_frames = []
    for f_idx in range(start_frame, end_frame + 1):
        raw_skel = map_value(player_skeletons, f_idx)
        raw_ball = map_value(ball_positions, f_idx)
        n_joints = max(33, max_joint_index(raw_skel) + 1)
        joints = []
        for joint_index in range(n_joints):
            point = point_to_float_list(skeleton_joint(raw_skel, joint_index))
            joints.append(point if point is not None else [0.0, 0.0, 0.0])
        frame_payload = {"frame": f_idx - start_frame, "joints": joints}
        ball_point = point_to_float_list(raw_ball)
        if ball_point is not None:
            frame_payload["ball"] = ball_point
        skeleton_frames.append(frame_payload)
    return skeleton_frames


METRIC_DISPLAY_NAMES = {
    "stationary_foot_ball_distance_pctw_shoulder": "Support Foot-Ball Distance (% Shoulder Width)",
}


def metric_name(key: str) -> str:
    return METRIC_DISPLAY_NAMES.get(key, key.replace("_", " ").title())


FULL_INTERVAL_KEYS = [
    "head_angle",
    "left_knee_angle",
    "right_knee_angle",
    "trunk_pitch_angle",
    "active_foot_ball_distance",
    "stationary_foot_ball_distance_pctw_shoulder",
    "foot_anteroposterior_offset",
    "foot_inclination_angle",
    "left_knee_angles",
    "right_knee_angles",
    "torso_pitch_angles",
    "head_angles",
    "mid_foot_ball_distances",
    "left_right_foot_distances",
]

ACTION_METRIC_LAYOUTS = {
    "Pass": {
        "pre": ["body_to_ball_angle"],
        "in": [
            "foot_region",
            "ball_contact_zone",
            "head_angle",
            "left_knee_angle",
            "right_knee_angle",
            "trunk_pitch_angle",
            "stationary_foot_ball_distance_pctw_shoulder",
            "body_to_ball_angle",
            "l_r_foot_distance",
            "trunc_pitch_angle",
            "trunc_roll_angle",
            "left_foot_orientation_angle",
            "right_foot_orientation_angle",
            "difference_in_angles",
            "l_knee_angle",
            "r_knee_angle",
            "head_pitch_angle",
            "head_roll_angle",
            "stand_foot_angle",
            "active_foot_height_pct",
        ],
        "post": ["head_angle", "body_to_ball_angle"],
        "top_level_scalars": ["backward_weighted_angle", "forward_weighted_angle"],
    },
    "Shoot": {
        "pre": ["max_backward_swing_distance", "max_backward_swing_angle", "body_to_ball_angle"],
        "in": [
            "foot_region",
            "ball_contact_zone",
            "head_angle",
            "left_knee_angle",
            "right_knee_angle",
            "trunk_pitch_angle",
            "stationary_foot_ball_distance_pctw_shoulder",
            "foot_inclination_angle",
            "body_to_ball_angle",
            "l_r_foot_distance",
            "trunc_pitch_angle",
            "trunc_roll_angle",
            "left_foot_orientation_angle",
            "right_foot_orientation_angle",
            "difference_in_angles",
            "l_knee_angle",
            "r_knee_angle",
            "head_pitch_angle",
            "head_roll_angle",
            "stand_foot_angle",
            "l_elbow_shoulder_hip_angle",
            "r_elbow_shoulder_hip_angle",
            "active_ankle_angle",
        ],
        "post": ["max_forward_swing_distance", "max_forward_swing_angle", "head_angle", "body_to_ball_angle"],
        "top_level_scalars": ["backward_weighted_angle", "forward_weighted_angle"],
    },
    "Receive": {
        "pre": ["body_orientation_vs_ball", "head_angle"],
        "in": [
            "foot_region",
            "ball_contact_zone",
            "head_angle",
            "left_knee_angle",
            "right_knee_angle",
            "trunk_pitch_angle",
            "stationary_foot_ball_distance_pctw_shoulder",
            "foot_anteroposterior_offset",
            "l_knee_angle",
            "r_knee_angle",
            "trunc_pitch_angle",
            "trunc_roll_angle",
            "left_foot_orientation_angle",
            "right_foot_orientation_angle",
            "difference_in_angles",
            "l_r_foot_distance",
            "stand_foot_angle",
            "body_orientation_vs_ball",
            "active_foot_height_pct",
        ],
        "post": ["mid_feet_ball_dist", "ball_height_pct_body"],
        "top_level_scalars": [],
    },
    "Dribble": {
        "frames": [
            "head_angle",
            "left_knee_angle",
            "right_knee_angle",
            "trunk_pitch_angle",
            "left_heel_height",
            "right_heel_height",
            "active_foot_ball_distance",
            "ball_feet_distance",
            "trunk_pitch",
            "trunk_roll",
            "ball_possession_score",
        ],
        "top_level_scalars": [],
    },
}


def ordered_metric_keys(observed_keys, preferred_keys=None):
    seen = set()
    ordered = []
    for key in preferred_keys or []:
        if key in observed_keys and key not in seen:
            seen.add(key)
            ordered.append(key)
    for key in sorted(observed_keys):
        if key not in seen:
            seen.add(key)
            ordered.append(key)
    return ordered


def normalized_metric_identity(name):
    return re.sub(r"\s+", " ", str(name or "").strip().lower())


def dedupe_metric_items(items):
    deduped = []
    seen = set()
    for item in items:
        if not isinstance(item, dict):
            deduped.append(item)
            continue
        identity = normalized_metric_identity(item.get("name"))
        if not identity:
            deduped.append(item)
            continue
        if identity in seen:
            continue
        seen.add(identity)
        deduped.append(item)
    return deduped


def is_frame_metric_payload(payload):
    if isinstance(payload, list):
        return True
    if not isinstance(payload, dict) or not payload:
        return False
    keys_are_frames = all(frame_number(key) is not None for key in payload.keys())
    has_metric_dict = any(isinstance(value, dict) for value in payload.values())
    return keys_are_frames and has_metric_dict


def entries_from_frame_payload(payload, start_frame=0):
    entries = []
    if isinstance(payload, list):
        for index, item in enumerate(payload):
            if not isinstance(item, dict):
                continue
            entry = dict(item)
            entry["frame"] = relative_frame(entry.get("frame", index), start_frame, index)
            entries.append(entry)
        return entries

    if not isinstance(payload, dict):
        return entries

    def sort_key(item):
        frame = frame_number(item[0])
        return (frame is None, frame if frame is not None else 0)

    for index, (frame_key, frame_payload) in enumerate(sorted(payload.items(), key=sort_key)):
        if not isinstance(frame_payload, dict):
            continue
        entry = dict(frame_payload)
        entry["frame"] = relative_frame(frame_key, start_frame, index)
        entries.append(entry)
    return entries


def build_series_from_entries(entries, unit_for, skip_keys=None, preferred_keys=None):
    skip = {"frame"}
    if skip_keys:
        skip.update(skip_keys)

    metric_keys = set()
    for entry in entries:
        metric_keys.update(
            key for key in entry.keys()
            if key not in skip and safe_float(entry.get(key)) is not None
        )

    series = []
    for key in ordered_metric_keys(metric_keys, preferred_keys):
        series.append({
            "name": metric_name(key),
            "unit": unit_for(key),
            "values": [
                {
                    "frame": relative_frame(entry.get("frame"), 0, index),
                    "value": safe_float(entry.get(key)),
                }
                for index, entry in enumerate(entries)
            ],
        })
    return dedupe_metric_items(series)


def build_series_from_frame_payload(payload, unit_for, start_frame=0, skip_keys=None, preferred_keys=None):
    return build_series_from_entries(
        entries_from_frame_payload(payload, start_frame),
        unit_for,
        skip_keys=skip_keys,
        preferred_keys=preferred_keys,
    )


def build_scalar_metrics(payload, unit_for, skip_keys=None, preferred_keys=None):
    if not isinstance(payload, dict):
        return []
    skip = set(skip_keys or [])
    skip.add("frame")
    metrics = []
    observed_keys = {
        key for key, value in payload.items()
        if key not in skip and not isinstance(value, (dict, list, tuple))
    }
    for key in ordered_metric_keys(observed_keys, preferred_keys):
        if key in skip:
            continue
        value = safe_metric_value(payload.get(key))
        metrics.append({
            "name": metric_name(key),
            "value": value,
            "unit": unit_for(key) if isinstance(value, (int, float)) else "",
        })
    return dedupe_metric_items(metrics)


def build_top_level_interval_metrics(analytics, unit_for, skip_keys=None, preferred_keys=None):
    skip = {
        "action",
        "active_foot",
        "touch_frame",
        "pre_action",
        "action_frame",
        "post_action",
        "frames",
        "in_action_data",
        "pre_action_data",
        "post_action_data",
        "full_interval_data",
        "per_frame",
        "tracking_data",
    }
    if skip_keys:
        skip.update(skip_keys)

    observed_keys = {
        key for key, value in analytics.items()
        if key not in skip and isinstance(value, list)
    }

    series = []
    for key in ordered_metric_keys(observed_keys, preferred_keys):
        if key in skip:
            continue
        values = analytics.get(key)
        if values is None:
            values = []
        if not isinstance(values, list):
            continue
        series.append(format_metric_series(metric_name(key), unit_for(key), values))
    order_index = {}
    for idx, key in enumerate(preferred_keys or []):
        name = metric_name(key)
        if name not in order_index:
            order_index[name] = idx
    return dedupe_metric_items(sorted(series, key=lambda item: order_index.get(item["name"], len(order_index))))


async def save_upload_to_path(upload: UploadFile, destination: str):
    with open(destination, "wb") as f:
        while True:
            chunk = await upload.read(1024 * 1024)
            if not chunk:
                break
            f.write(chunk)


def run_analysis_job(
    request_base_url: str,
    player_id: str,
    target_w: float,
    target_h: float,
    client_id: str,
    session_id: str,
    session_dir: str,
    actions_path: str,
    calib_path: str,
    camera_map,
):
    def ensure_not_cancelled():
        if is_cancel_requested(client_id):
            raise InterruptedError("Processing cancelled by user")

    try:
        ensure_not_cancelled()

        set_progress(client_id, 10.0, "Preparing AI Models", status="running", sessionId=session_id)
        runtime = ensure_runtime_ready()
        utils_paths = {
            "POSE_PATH": runtime["weights"]["POSE_PATH"],
            "YOLO_PATH": runtime["weights"]["YOLO_PATH"],
            "CALIBRATION_PATH": calib_path,
            "ACTIONS_PATH": actions_path,
        }

        sizes = {
            "TARGET_SIZE": (int(target_w), int(target_h)),
            "YOLO_IMGSZ": 960,
        }

        ensure_not_cancelled()

        print(f"[SPORALIZE] Pipeline start: session={session_id} target_size={target_w}x{target_h} cameras={list(camera_map.keys())}", flush=True)
        _pipeline_t0 = time.time()
        set_progress(client_id, 20.0, "Extracting 3D Kinematics", status="running", sessionId=session_id)

        def progress_tracker(current_act, total_act, step, total_frames):
            if is_cancel_requested(client_id):
                return False

            processed_step = min(max(1, total_frames), max(0, step + 1))
            base_p = current_act / max(1, total_act)
            segment_p = (processed_step / max(1, total_frames)) * (1.0 / max(1, total_act))
            pct = 20.0 + round((base_p + segment_p) * 70.0, 1)
            set_progress(
                client_id,
                pct,
                f"Processing Action {current_act + 1}/{total_act}",
                processed_step,
                total_frames,
                status="running",
                sessionId=session_id,
            )
            return True

        reports = runtime["run_pipeline"](camera_map, utils_paths, sizes, progress_tracker)
        print(f"[SPORALIZE] Pipeline done: session={session_id} elapsed={time.time() - _pipeline_t0:.1f}s actions={len(reports)}", flush=True)
        ensure_not_cancelled()

        set_progress(client_id, 92.0, "Preparing Playback Assets", status="running", sessionId=session_id)
        ensure_not_cancelled()
        fallback_camera_map = normalize_camera_videos_for_web(camera_map)
        ensure_not_cancelled()
        set_progress(client_id, 96.0, "Finalizing Results", status="running", sessionId=session_id)
        ensure_not_cancelled()

        raw_reports_path = os.path.join(session_dir, "raw_reports.json")
        with open(raw_reports_path, "w", encoding="utf-8") as f:
            json.dump(reports, f, indent=2, default=json_default)

        with open(actions_path, "r", encoding="utf-8") as f:
            raw_actions = json.load(f).get("actions", [])

        formatted_actions = []
        failed_actions = []
        camera_videos = build_camera_video_entries(request_base_url, player_id, session_id, camera_map)
        source_camera_videos = build_camera_video_entries(request_base_url, player_id, session_id, fallback_camera_map)
        degree_keys = {
            "head_angle",
            "l_knee_angle",
            "r_knee_angle",
            "trunc_pitch_angle",
            "trunc_roll_angle",
            "trunk_pitch",
            "trunk_roll",
            "head_pitch_angle",
            "head_roll_angle",
            "left_foot_orientation_angle",
            "right_foot_orientation_angle",
            "difference_in_angles",
            "body_to_ball_angle",
            "body_orientation_vs_ball",
            "stand_foot_angle",
            "active_ankle_angle",
            "l_elbow_shoulder_hip_angle",
            "r_elbow_shoulder_hip_angle",
            "backward_weighted_angle",
            "forward_weighted_angle",
            "leg_separation_angle",
            "left_knee_angle",
            "right_knee_angle",
            "trunk_pitch_angle",
            "max_backward_swing_angle",
            "max_forward_swing_angle",
            "foot_inclination_angle",
        }
        UNITS = {key: "\u00b0" for key in degree_keys}
        UNITS.update({
            "l_r_foot_distance": "cm",
            "l_foot_ball_distance": "cm",
            "r_foot_ball_distance": "cm",
            "mid_feet_ball_dist": "cm",
            "active_foot_height_pct": "%",
            "ball_height_pct_body": "%",
            "ball_possession_score": "%",
            "ball_feet_distance": "cm",
            "active_foot_ball_distance": "cm",
            "stationary_foot_ball_distance_pctw_shoulder": "%",
            "left_heel_height": "cm",
            "right_heel_height": "cm",
            "foot_anteroposterior_offset": "cm",
            "max_backward_swing_distance": "cm",
            "max_forward_swing_distance": "cm",
        })

        def unit_for(key):
            return UNITS.get(key, "")

        for i, rep in enumerate(reports):
            ensure_not_cancelled()
            raw = raw_actions[i] if i < len(raw_actions) else {}

            if "error" in rep:
                failed_actions.append({
                    "id": f"err-{uuid.uuid4().hex[:6]}",
                    "label": rep.get("action", raw.get("label", "Unknown")),
                    "start": raw.get("start", "00:00:00:00"),
                    "end": raw.get("end", "00:00:00:00"),
                    "error": rep["error"],
                })
                continue

            an = rep.get("analytics", {})
            if not isinstance(an, dict):
                an = {}
            action_name = rep.get("action", raw.get("label", an.get("action", "Unknown")))
            sf = int(rep.get("start_frame", 0))
            ef = int(rep.get("end_frame", sf))
            fps = float(rep.get("fps", 30))
            is_dribble = action_name.lower() == "dribble" or "per_frame" in an
            tf = relative_frame(an.get("touch_frame"), sf, (ef - sf) // 2)
            skeleton_frames = build_skeleton_frames(rep, an, sf, ef)

            action_layout = ACTION_METRIC_LAYOUTS.get(action_name, {})
            active_foot = an.get("active_foot")
            pre_action_metrics = []
            post_action_metrics = []

            if is_dribble:
                dribble_payload = an.get("per_frame", an.get("frames", []))
                pre_metrics = []
                in_action_metrics = []
                post_metrics = []
                full_interval_metrics = build_series_from_frame_payload(
                    dribble_payload,
                    unit_for,
                    start_frame=sf,
                    preferred_keys=action_layout.get("frames"),
                )
            else:
                pre_payload = an.get("pre_action_data", an.get("pre_action", []))
                post_payload = an.get("post_action_data", an.get("post_action", []))
                action_frame_data = an.get("in_action_data", an.get("action_frame", {}))
                if is_frame_metric_payload(pre_payload):
                    pre_metrics = build_series_from_frame_payload(
                        pre_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=action_layout.get("pre"),
                    )
                else:
                    pre_metrics = []
                    pre_action_metrics = build_scalar_metrics(
                        pre_payload,
                        unit_for,
                        preferred_keys=action_layout.get("pre"),
                    )
                in_action_metrics = build_scalar_metrics(
                    action_frame_data,
                    unit_for,
                    skip_keys={"active_foot"},
                    preferred_keys=action_layout.get("in"),
                )
                if "in_action_data" not in an:
                    in_action_metrics.extend(
                        build_scalar_metrics(
                            an,
                            unit_for,
                            skip_keys={
                                "action",
                                "active_foot",
                                "touch_frame",
                                "pre_action",
                                "action_frame",
                                "post_action",
                                "frames",
                                "left_knee_angles",
                                "right_knee_angles",
                                "torso_pitch_angles",
                                "head_angles",
                                "mid_foot_ball_distances",
                                "left_right_foot_distances",
                            },
                            preferred_keys=action_layout.get("top_level_scalars"),
                        )
                    )
                if is_frame_metric_payload(post_payload):
                    post_metrics = build_series_from_frame_payload(
                        post_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=action_layout.get("post"),
                    )
                else:
                    post_metrics = []
                    post_action_metrics = build_scalar_metrics(
                        post_payload,
                        unit_for,
                        preferred_keys=action_layout.get("post"),
                    )

                full_payload = an.get("full_interval_data")
                if full_payload is not None:
                    full_interval_metrics = build_series_from_frame_payload(
                        full_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=FULL_INTERVAL_KEYS,
                    )
                else:
                    full_interval_metrics = build_top_level_interval_metrics(
                        an,
                        unit_for,
                        preferred_keys=FULL_INTERVAL_KEYS,
                    )

            formatted_actions.append({
                "id": f"{action_name.lower()}-{uuid.uuid4().hex[:6]}",
                "label": action_name,
                "activeFoot": active_foot,
                "start": raw.get("start", "00:00:00:00"),
                "end": raw.get("end", "00:00:00:00"),
                "fps": fps,
                "startFrame": sf,
                "endFrame": ef,
                "startSeconds": max(0.0, sf / max(1.0, fps)),
                "endSeconds": max(0.0, (ef + 1) / max(1.0, fps)),
                "totalFrames": ef - sf + 1,
                "preFrames": max(0, tf),
                "inFrame": max(0, tf),
                "postFrames": max(0, (ef - sf) - tf),
                "cameraClips": camera_videos,
                "sourceCameraClips": source_camera_videos,
                "preMetrics": dedupe_metric_items(pre_metrics),
                "preActionMetrics": dedupe_metric_items(pre_action_metrics),
                "inActionMetrics": dedupe_metric_items(in_action_metrics),
                "postMetrics": dedupe_metric_items(post_metrics),
                "postActionMetrics": dedupe_metric_items(post_action_metrics),
                "fullIntervalMetrics": dedupe_metric_items(full_interval_metrics),
                "skeleton": skeleton_frames,
                "rawAnalytics": an,
            })

        print(f"Pipeline successful. Session {session_id} saved.")
        response_payload = {
            "id": session_id,
            "playerId": player_id,
            "createdAt": int(time.time() * 1000),
            "targetSize": [int(target_w), int(target_h)],
            "cameraCount": len(camera_map),
            "actions": formatted_actions,
            "failedActions": failed_actions,
        }
        response_payload = make_json_safe(response_payload)
        ensure_not_cancelled()

        session_json_path = os.path.join(session_dir, "session.json")
        with open(session_json_path, "w", encoding="utf-8") as f:
            json.dump(response_payload, f, indent=2)
        write_session_summary(session_json_path, response_payload)
        try:
            push_session_to_hf(player_id, session_id, session_dir)
        except Exception as sync_error:
            print("--- STORAGE SYNC WARNING ---")
            print(f"Session {session_id} was created locally but could not be pushed to Hugging Face storage: {sync_error}")

        set_progress(
            client_id,
            100.0,
            "Completed",
            status="completed",
            sessionId=session_id,
            resultUrl=f"/results/{session_id}",
        )
        clear_cancel_request(client_id)
        return response_payload

    except Exception as e:
        print("--- PIPELINE ERROR ---")
        traceback.print_exc()
        current_progress = current_progress_payload(client_id).get("progress", 0.0)
        was_cancelled = isinstance(e, InterruptedError) or is_cancel_requested(client_id)
        if was_cancelled:
            set_progress(
                client_id,
                current_progress,
                "Processing Cancelled",
                status="cancelled",
                sessionId=session_id,
                error=str(e),
            )
        else:
            set_progress(
                client_id,
                current_progress,
                "Failed",
                status="failed",
                sessionId=session_id,
                error=str(e),
            )
        clear_cancel_request(client_id)
        if session_dir and os.path.isdir(session_dir):
            shutil.rmtree(session_dir, ignore_errors=True)
        return None


@app.post("/api/analyze")
async def analyze_endpoint(
    request: Request,
    playerId: str = Form(...),
    targetW: float = Form(...),
    targetH: float = Form(...),
    clientId: str = Form(...),
    videoOrders: List[int] = Form(...),
    actionsJson: UploadFile = File(...),
    calibration: UploadFile = File(...),
    videos: List[UploadFile] = File(...),
):
    session_id = f"session-{int(time.time())}-{uuid.uuid4().hex[:6]}"
    _player_dir, session_dir, videos_dir = session_storage_paths(playerId, session_id)
    try:
        if is_cancel_requested(clientId):
            raise InterruptedError("Processing cancelled by user")
        set_progress(
            clientId,
            2.0,
            "Uploading & Validating Data",
            status="uploading",
            sessionId=session_id,
            playerId=playerId,
        )

        if len(videoOrders) != len(videos):
            raise ValueError("Each uploaded video must include a matching camera order")
        if len(set(videoOrders)) != len(videoOrders):
            raise ValueError("Camera order values must be unique")

        os.makedirs(videos_dir, exist_ok=True)

        actions_path = os.path.join(session_dir, "actions.json")
        await save_upload_to_path(actionsJson, actions_path)

        calib_path = os.path.join(session_dir, "calibration.npz")
        await save_upload_to_path(calibration, calib_path)

        camera_map = {}
        for idx, (camera_order, video) in enumerate(zip(videoOrders, videos)):
            original_name = video.filename or f"camera_{camera_order}.mp4"
            video_name = f"{idx:02d}_cam_{camera_order}_{safe_name(os.path.basename(original_name))}"
            vid_path = os.path.join(videos_dir, video_name)
            await save_upload_to_path(video, vid_path)
            camera_map[int(camera_order)] = vid_path

        if is_cancel_requested(clientId):
            raise InterruptedError("Processing cancelled by user")

        request_base_url = request_public_base_url(request)
        set_progress(
            clientId,
            8.0,
            "Queued for Processing",
            status="queued",
            sessionId=session_id,
            playerId=playerId,
        )
        future = analysis_executor.submit(
            run_analysis_job,
            request_base_url,
            playerId,
            targetW,
            targetH,
            clientId,
            session_id,
            session_dir,
            actions_path,
            calib_path,
            camera_map,
        )
        register_active_job(clientId, future)
        future.add_done_callback(lambda _future, stored_client_id=clientId: unregister_active_job(stored_client_id))

        return JSONResponse(
            status_code=202,
            content={
                "accepted": True,
                "status": "queued",
                "clientId": clientId,
                "sessionId": session_id,
            },
        )

    except Exception as e:
        print("--- UPLOAD ERROR ---")
        traceback.print_exc()
        was_cancelled = isinstance(e, InterruptedError) or is_cancel_requested(clientId)
        status = "cancelled" if was_cancelled else "failed"
        phase = "Processing Cancelled" if was_cancelled else "Failed"
        set_progress(
            clientId,
            current_progress_payload(clientId).get("progress", 0.0),
            phase,
            status=status,
            sessionId=session_id,
            error=str(e),
        )
        if was_cancelled:
            clear_cancel_request(clientId)
        if session_dir and os.path.isdir(session_dir):
            shutil.rmtree(session_dir, ignore_errors=True)
        if was_cancelled:
            raise HTTPException(status_code=409, detail=str(e))
        raise HTTPException(status_code=500, detail=str(e))


async def analyze_endpoint_inline(
    request: Request,
    playerId: str = Form(...),
    targetW: float = Form(...),
    targetH: float = Form(...),
    clientId: str = Form(...),
    videoOrders: List[int] = Form(...),
    actionsJson: UploadFile = File(...),
    calibration: UploadFile = File(...),
    videos: List[UploadFile] = File(...)
):
    temp_dir = None
    session_id = f"session-{int(time.time())}-{uuid.uuid4().hex[:6]}"
    player_dir, session_dir, videos_dir = session_storage_paths(playerId, session_id)
    try:
        if is_cancel_requested(clientId):
            raise InterruptedError("Processing cancelled by user")
        set_progress(clientId, 2.0, "Uploading & Validating Data")

        os.makedirs(videos_dir, exist_ok=True)
        temp_dir = session_dir

        # 1. Store incoming payloads
        actions_path = os.path.join(session_dir, "actions.json")
        with open(actions_path, "wb") as f:
            f.write(await actionsJson.read())
            
        calib_path = os.path.join(session_dir, "calibration.npz")
        with open(calib_path, "wb") as f:
            f.write(await calibration.read())
            
        if len(videoOrders) != len(videos):
            raise ValueError("Each uploaded video must include a matching camera order")
        if len(set(videoOrders)) != len(videoOrders):
            raise ValueError("Camera order values must be unique")

        camera_map = {}
        for idx, (camera_order, video) in enumerate(zip(videoOrders, videos)):
            original_name = video.filename or f"camera_{camera_order}.mp4"
            video_name = f"{idx:02d}_cam_{camera_order}_{safe_name(os.path.basename(original_name))}"
            vid_path = os.path.join(videos_dir, video_name)
            with open(vid_path, "wb") as f:
                f.write(await video.read())
            camera_id = int(camera_order)
            camera_map[camera_id] = vid_path

        if is_cancel_requested(clientId):
            raise InterruptedError("Processing cancelled by user")

        set_progress(clientId, 10.0, "Preparing AI Models")
        runtime = ensure_runtime_ready()
        utils_paths = {
            "POSE_PATH": runtime["weights"]["POSE_PATH"],
            "YOLO_PATH": runtime["weights"]["YOLO_PATH"],
            "CALIBRATION_PATH": calib_path,
            "ACTIONS_PATH": actions_path
        }
        
        sizes = {
            "TARGET_SIZE": (int(targetW), int(targetH)),
            "YOLO_IMGSZ": 960
        }
        
        print("Starting physical pipeline execution...")
        set_progress(clientId, 20.0, "Extracting 3D Kinematics")
        
        def progress_tracker(current_act, total_act, step, total_frames):
            if is_cancel_requested(clientId):
                return False  # Signal pipeline to abort
                
            processed_step = min(max(1, total_frames), max(0, step + 1))
            base_p = current_act / max(1, total_act)
            segment_p = (processed_step / max(1, total_frames)) * (1.0 / max(1, total_act))
            # Rescale 20% to 90% for processing
            pct = 20.0 + round((base_p + segment_p) * 70.0, 1)
            set_progress(clientId, pct, f"Processing Action {current_act + 1}/{total_act}", processed_step, total_frames)
            return True

        # 2. Yield to worker thread to allow concurrent polling from front-end
        def execute_pipeline():
            return runtime["run_pipeline"](camera_map, utils_paths, sizes, progress_tracker)
            
        reports = await run_in_threadpool(execute_pipeline)
        set_progress(clientId, 92.0, "Preparing Playback Assets")
        fallback_camera_map = await run_in_threadpool(normalize_camera_videos_for_web, camera_map)
        set_progress(clientId, 96.0, "Finalizing Results")

        raw_reports_path = os.path.join(session_dir, "raw_reports.json")
        with open(raw_reports_path, "w", encoding="utf-8") as f:
            json.dump(reports, f, indent=2, default=json_default)
        
        # 3. Format output dict perfectly mapping to the Frontend Types
        with open(actions_path, "r") as f:
            raw_actions = json.load(f).get("actions", [])

        formatted_actions = []
        failed_actions = []
        camera_videos = build_camera_video_entries(request, playerId, session_id, camera_map)
        source_camera_videos = build_camera_video_entries(request, playerId, session_id, fallback_camera_map)
        for i, rep in enumerate(reports):
            raw = raw_actions[i] if i < len(raw_actions) else {}
            
            if "error" in rep:
                failed_actions.append({
                    "id": f"err-{uuid.uuid4().hex[:6]}",
                    "label": rep.get("action", raw.get("label", "Unknown")),
                    "start": raw.get("start", "00:00:00:00"),
                    "end": raw.get("end", "00:00:00:00"),
                    "error": rep["error"]
                })
                continue

            an = rep.get("analytics", {})
            if not isinstance(an, dict):
                an = {}
            action_name = rep.get("action", raw.get("label", an.get("action", "Unknown")))
            sf = int(rep.get("start_frame", 0))
            ef = int(rep.get("end_frame", sf))
            fps = float(rep.get("fps", 30))
            is_dribble = action_name.lower() == "dribble" or "per_frame" in an
            tf = relative_frame(an.get("touch_frame"), sf, (ef - sf) // 2)
            
            # --- Skeleton: support full COCO-25/WB joint range (0–32) ---
            skeleton_frames = build_skeleton_frames(rep, an, sf, ef)
            
            # --- Unit dictionary for known metric names ---
            DEG = "\u00b0"
            UNITS = {
                "head_angle": "°", "l_knee_angle": "°", "r_knee_angle": "°",
                "trunc_pitch_angle": "°", "trunc_roll_angle": "°",
                "trunk_pitch": "°", "trunk_roll": "°",
                "head_pitch_angle": "°", "head_roll_angle": "°",
                "left_foot_orientation_angle": "°", "right_foot_orientation_angle": "°",
                "difference_in_angles": "°", "body_to_ball_angle": "°",
                "body_orientation_vs_ball": "°", "stand_foot_angle": "°",
                "active_ankle_angle": "°", "l_elbow_shoulder_hip_angle": "°",
                "r_elbow_shoulder_hip_angle": "°", "backward_weighted_angle": "°",
                "forward_weighted_angle": "°", "leg_separation_angle": "°",
                "l_r_foot_distance": "cm", "l_foot_ball_distance": "cm",
                "r_foot_ball_distance": "cm", "mid_feet_ball_dist": "cm",
                "active_foot_height_pct": "%", "ball_height_pct_body": "%",
                "ball_possession_score": "%", "ball_feet_distance": "cm",
            }
            UNITS.update({
                "left_knee_angle": DEG,
                "right_knee_angle": DEG,
                "trunk_pitch_angle": DEG,
                "max_backward_swing_angle": DEG,
                "max_forward_swing_angle": DEG,
                "foot_inclination_angle": DEG,
                "active_foot_ball_distance": "cm",
                "stationary_foot_ball_distance_pctw_shoulder": "%",
                "left_heel_height": "cm",
                "right_heel_height": "cm",
                "foot_anteroposterior_offset": "cm",
                "max_backward_swing_distance": "cm",
                "max_forward_swing_distance": "cm",
            })
            
            def unit_for(key):
                return UNITS.get(key, "")
            
            action_layout = ACTION_METRIC_LAYOUTS.get(action_name, {})
            active_foot = an.get("active_foot")
            pre_action_metrics = []
            post_action_metrics = []

            if is_dribble:
                dribble_payload = an.get("per_frame", an.get("frames", []))
                pre_metrics = []
                in_action_metrics = []
                post_metrics = []
                full_interval_metrics = build_series_from_frame_payload(
                    dribble_payload,
                    unit_for,
                    start_frame=sf,
                    preferred_keys=action_layout.get("frames"),
                )
            else:
                pre_payload = an.get("pre_action_data", an.get("pre_action", []))
                post_payload = an.get("post_action_data", an.get("post_action", []))
                action_frame_data = an.get("in_action_data", an.get("action_frame", {}))
                if is_frame_metric_payload(pre_payload):
                    pre_metrics = build_series_from_frame_payload(
                        pre_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=action_layout.get("pre"),
                    )
                else:
                    pre_metrics = []
                    pre_action_metrics = build_scalar_metrics(
                        pre_payload,
                        unit_for,
                        preferred_keys=action_layout.get("pre"),
                    )
                in_action_metrics = build_scalar_metrics(
                    action_frame_data,
                    unit_for,
                    skip_keys={"active_foot"},
                    preferred_keys=action_layout.get("in"),
                )
                if "in_action_data" not in an:
                    in_action_metrics.extend(
                        build_scalar_metrics(
                            an,
                            unit_for,
                            skip_keys={
                                "action",
                                "active_foot",
                                "touch_frame",
                                "pre_action",
                                "action_frame",
                                "post_action",
                                "frames",
                                "left_knee_angles",
                                "right_knee_angles",
                                "torso_pitch_angles",
                                "head_angles",
                                "mid_foot_ball_distances",
                                "left_right_foot_distances",
                            },
                            preferred_keys=action_layout.get("top_level_scalars"),
                        )
                    )
                if is_frame_metric_payload(post_payload):
                    post_metrics = build_series_from_frame_payload(
                        post_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=action_layout.get("post"),
                    )
                else:
                    post_metrics = []
                    post_action_metrics = build_scalar_metrics(
                        post_payload,
                        unit_for,
                        preferred_keys=action_layout.get("post"),
                    )

                full_payload = an.get("full_interval_data")
                if full_payload is not None:
                    full_interval_metrics = build_series_from_frame_payload(
                        full_payload,
                        unit_for,
                        start_frame=sf,
                        preferred_keys=FULL_INTERVAL_KEYS,
                    )
                else:
                    full_interval_metrics = build_top_level_interval_metrics(
                        an,
                        unit_for,
                        preferred_keys=FULL_INTERVAL_KEYS,
                    )

            formatted_actions.append({
                "id": f"{action_name.lower()}-{uuid.uuid4().hex[:6]}",
                "label": action_name,
                "activeFoot": active_foot,
                "start": raw.get("start", "00:00:00:00"),
                "end": raw.get("end", "00:00:00:00"),
                "fps": fps,
                "startFrame": sf,
                "endFrame": ef,
                "startSeconds": max(0.0, sf / max(1.0, fps)),
                "endSeconds": max(0.0, (ef + 1) / max(1.0, fps)),
                "totalFrames": ef - sf + 1,
                "preFrames": max(0, tf),
                "inFrame": max(0, tf),
                "postFrames": max(0, (ef - sf) - tf),
                "cameraClips": camera_videos,
                "sourceCameraClips": source_camera_videos,
                "preMetrics": dedupe_metric_items(pre_metrics),
                "preActionMetrics": dedupe_metric_items(pre_action_metrics),
                "inActionMetrics": dedupe_metric_items(in_action_metrics),
                "postMetrics": dedupe_metric_items(post_metrics),
                "postActionMetrics": dedupe_metric_items(post_action_metrics),
                "fullIntervalMetrics": dedupe_metric_items(full_interval_metrics),
                "skeleton": skeleton_frames,
                "rawAnalytics": an,
            })
            
        print("Pipeline successful. Yielding payload payload.")
        response_payload = {
            "id": session_id,
            "playerId": playerId,
            "createdAt": int(time.time() * 1000),
            "targetSize": [int(targetW), int(targetH)],
            "cameraCount": len(camera_map),
            "actions": formatted_actions,
            "failedActions": failed_actions
        }
        response_payload = make_json_safe(response_payload)

        session_json_path = os.path.join(session_dir, "session.json")
        with open(session_json_path, "w", encoding="utf-8") as f:
            json.dump(response_payload, f, indent=2)
        write_session_summary(session_json_path, response_payload)
        try:
            push_session_to_hf(playerId, session_id, session_dir)
        except Exception as sync_error:
            print("--- STORAGE SYNC WARNING ---")
            print(f"Session {session_id} was created locally but could not be pushed to Hugging Face storage: {sync_error}")

        set_progress(clientId, 100.0, "Completed", status="completed")
        return response_payload
        
    except Exception as e:
        print("--- PIPELINE ERROR ---")
        traceback.print_exc()
        was_cancelled = isinstance(e, InterruptedError) or is_cancel_requested(clientId)
        if was_cancelled:
            set_progress(clientId, current_progress_payload(clientId).get("progress", 0.0), "Processing Cancelled", status="cancelled")
            clear_cancel_request(clientId)
        else:
            set_progress(clientId, current_progress_payload(clientId).get("progress", 0.0), "Failed", status="failed")
        if temp_dir and os.path.isdir(temp_dir):
            shutil.rmtree(temp_dir, ignore_errors=True)
        if was_cancelled:
            raise HTTPException(status_code=409, detail=str(e))
        raise HTTPException(status_code=500, detail=str(e))

if __name__ == "__main__":
    import uvicorn
    # Start ASGI interface natively mapping locally to the React vite environment
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8000")))