Deploy Sensorflow Studio from fix/legacy-help-chatbot (f7ddaf4)

Push coherent hf-space/ snapshot including pipeline browse, UX toasts, execution integrity, and help chatbot. Removes nested hf-space/ leftover from prior monorepo upload. Does not include unmerged #6 license or #10 number-format (sibling branches).

README.md

@@ -29,3 +29,9 @@ copilot — are not functional here; the dashboards and analytics APIs are.
 Deployed from the project repository via
 `deploy/huggingface/deploy.py` (uploads files with `huggingface_hub`; the
 frontend is built inside the Docker image).
+
+## Version
+
+Current version is shown in the Studio AppBar (`vX.Y.Z` chip) and Help → About,
+with release notes for each notable version. The same catalog is served at
+`GET /api/about` and `GET /api/version`. See `CHANGELOG.md` in the GitHub repo.

app_backend.py

@@ -5,21 +5,24 @@ import json
 import subprocess
 import signal
 from pathlib import Path
-from typing import List, Optional
+from typing import List, Optional, Any, Dict
 from pydantic import BaseModel
 import httpx
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Query
 from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, PlainTextResponse
 
 app = FastAPI(title="Sensorflow Studio Backend")
 
 # State tracking
 ACTIVE_TRAIN_PROC: Optional[subprocess.Popen] = None
+ACTIVE_TRAIN_EXECUTION_ID: Optional[str] = None
 TRAINING_LOGS_ACCUMULATED = ""
 TRAINING_LOSSES: List[float] = []
 TOTAL_EPOCHS = 10
 CURRENT_EPOCH = 0
+LAST_TRAIN_EXIT_CODE: Optional[int] = None
+LAST_TRAIN_COMMAND: Optional[List[str]] = None
 
 # Configuration
 CONFIG_PATH = Path("runs/studio_config.json")
@@ -32,7 +35,7 @@ class StudioConfig(BaseModel):
     model_type: str = "yolov8"
     pipeline_mode: str = "3d"
     sam_checkpoint: str = "models/sam_vit_b.pth"
-    vendors: List[str] = ["alpamayo", "waymo"]
+    vendors: List[str] = ["alpamayo", "waymo", "a2d2"]
     gate_thresholds_path: str = "runs/pipeline/gate_thresholds.json"
     sequence_id: str = "seq_001"
 
@@ -105,32 +108,236 @@ def save_yaml_content(req: SaveYamlRequest):
 
 @app.get("/api/precheck")
 def precheck():
-    # Verify scripts are present
-    train_exists = Path("train.py").exists()
-    infer_exists = Path("infer.py").exists()
-    grader_exists = Path("autograder.py").exists()
+    """Script verification — existence alone is NOT success."""
+    from sensorflow.execution_ops import verify_script
+
+    reports = {
+        "train.py": verify_script("train.py"),
+        "infer.py": verify_script("infer.py"),
+        "autograder.py": verify_script("autograder.py"),
+    }
+    all_ok = all(
+        r.get("exists") and r.get("syntax_valid") and r.get("dry_run_ok")
+        for r in reports.values()
+    )
+    any_missing = any(not r.get("exists") for r in reports.values())
+    return {
+        "status": "ok" if all_ok else ("warning" if not any_missing else "failed"),
+        "message": (
+            "Scripts exist, syntax-valid, and --help dry-run succeeded."
+            if all_ok
+            else "Script verification incomplete — see reports (file Found alone is not enough)."
+        ),
+        "scripts": reports,
+        "verified": all_ok,
+    }
+
+
+@app.get("/api/health")
+def health():
+    from sensorflow.execution_ops import backend_health
+    from sensorflow.execution_ledger import get_strict_mode
+
+    payload = backend_health()
+    payload["strict_mode"] = get_strict_mode()
+    payload["backend_connected"] = True
+    return payload
+
+
+@app.get("/api/strict-mode")
+def get_strict_mode_api():
+    from sensorflow.execution_ledger import get_strict_mode
+
+    return {"enabled": get_strict_mode()}
+
+
+@app.post("/api/strict-mode")
+def set_strict_mode_api(params: dict):
+    from sensorflow.execution_ledger import set_strict_mode
+
+    enabled = bool(params.get("enabled", False))
+    return set_strict_mode(enabled)
+
+
+@app.get("/api/executions")
+def list_executions_api(
+    operation: Optional[str] = None,
+    status: Optional[str] = None,
+    limit: int = Query(50, ge=1, le=500),
+):
+    from sensorflow.execution_ledger import list_executions
+
+    return {"status": "ok", "executions": list_executions(operation=operation, status=status, limit=limit)}
+
+
+@app.get("/api/executions/{execution_id}")
+def get_execution_api(execution_id: str):
+    from sensorflow.execution_ledger import load_execution
+
+    try:
+        return load_execution(execution_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Execution not found: {execution_id}")
+
+
+@app.get("/api/executions/{execution_id}/log")
+def get_execution_log_api(execution_id: str):
+    from sensorflow.execution_ledger import get_log_text, load_execution
+
+    try:
+        load_execution(execution_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Execution not found: {execution_id}")
+    return PlainTextResponse(get_log_text(execution_id) or "(no log lines)")
+
+
+@app.post("/api/yaml/validate")
+def validate_yaml_api(params: dict):
+    from sensorflow.execution_ops import validate_yaml_semantics
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize
+
+    path = params.get("path") or params.get("yaml_path") or "coco8.yaml"
+    record = create_execution(
+        "yaml_validate",
+        configuration_snapshot={"yaml_path": path},
+        input_artifacts=[path],
+    )
+    mark_running(record["execution_id"])
+    report = validate_yaml_semantics(path)
+    final = finalize(
+        record["execution_id"],
+        report.get("status") or "FAILED",
+        metrics={
+            "class_count": report.get("class_count"),
+            "image_counts": report.get("image_counts"),
+            "label_counts": report.get("label_counts"),
+        },
+        errors=report.get("errors"),
+        warnings=report.get("warnings"),
+        output_artifacts=[{"path": path, "hash": report.get("content_hash")}],
+        process_invoked=False,
+        outputs_valid=report.get("status") == "SUCCEEDED",
+    )
+    report["execution_id"] = final["execution_id"]
+    report["execution"] = {
+        "execution_id": final["execution_id"],
+        "status": final["status"],
+        "verified": final.get("verified"),
+        "duration_ms": final.get("duration_ms"),
+    }
+    return report
+
+
+@app.get("/api/scripts/verify")
+def scripts_verify_api():
+    from sensorflow.execution_ops import verify_script
 
-    if not (train_exists and infer_exists and grader_exists):
-        return {
-            "status": "warning",
-            "message": "Some scripts are missing in the current folder. Please verify train.py, infer.py, and autograder.py exist."
-        }
     return {
-        "status": "success",
-        "message": "All workspace training and inference scripts are verified."
+        "status": "ok",
+        "scripts": {
+            "train.py": verify_script("train.py"),
+            "infer.py": verify_script("infer.py"),
+            "autograder.py": verify_script("autograder.py"),
+        },
     }
 
+
+@app.post("/api/dataset/load")
+def dataset_load(params: dict):
+    """Real Load & Preprocess with discovery evidence (not catalog KPIs)."""
+    from sensorflow.execution_ops import load_and_preprocess
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize
+
+    source_path = params.get("source_path") or load_config().source_path
+    yaml_path = params.get("yaml_path") or load_config().yaml_path
+    dataset_type = params.get("dataset_type") or load_config().dataset_type
+
+    record = create_execution(
+        "dataset_load",
+        configuration_snapshot={
+            "source_path": source_path,
+            "yaml_path": yaml_path,
+            "dataset_type": dataset_type,
+        },
+        input_artifacts=[source_path, yaml_path],
+    )
+    mark_running(record["execution_id"])
+    result = load_and_preprocess(source_path, yaml_path=yaml_path, dataset_type=dataset_type)
+    disc = result["discovery"]
+    final = finalize(
+        record["execution_id"],
+        result["status"],
+        records_discovered=disc.get("images_discovered", 0),
+        records_processed=disc.get("images_discovered", 0),
+        records_succeeded=disc.get("images_readable", 0),
+        records_failed=disc.get("images_corrupt", 0),
+        metrics=result["metrics"],
+        errors=disc.get("errors"),
+        warnings=disc.get("warnings"),
+        output_artifacts=[{"path": result["manifest_path"], "kind": "load_manifest"}],
+        process_invoked=False,
+        outputs_valid=disc.get("images_readable", 0) > 0 and result["status"] in (
+            "SUCCEEDED",
+            "PARTIAL_SUCCESS",
+        ),
+    )
+    return {
+        "status": final["status"],
+        "execution_id": final["execution_id"],
+        "verified": final.get("verified"),
+        "duration_ms": final.get("duration_ms"),
+        "message": (
+            f"Loaded {disc.get('images_readable', 0)}/{disc.get('images_discovered', 0)} images "
+            f"from {source_path}"
+            if disc.get("images_readable")
+            else f"FAILED: 0 images loaded from {source_path}"
+        ),
+        "discovery": disc,
+        "metrics": result["metrics"],
+        "yaml_validation": result.get("yaml_validation"),
+        "reconciliation": result.get("reconciliation"),
+        "manifest_path": result.get("manifest_path"),
+        "catalog_only": False,
+        "browsable": bool(result["metrics"].get("browsable")),
+        "events": final.get("events"),
+    }
+
+
 @app.post("/api/train/start")
 def start_train(params: TrainParams):
-    global ACTIVE_TRAIN_PROC, TRAINING_LOGS_ACCUMULATED, TRAINING_LOSSES, TOTAL_EPOCHS, CURRENT_EPOCH
+    global ACTIVE_TRAIN_PROC, ACTIVE_TRAIN_EXECUTION_ID, TRAINING_LOGS_ACCUMULATED
+    global TRAINING_LOSSES, TOTAL_EPOCHS, CURRENT_EPOCH, LAST_TRAIN_EXIT_CODE, LAST_TRAIN_COMMAND
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize
+
     if ACTIVE_TRAIN_PROC and ACTIVE_TRAIN_PROC.poll() is None:
         raise HTTPException(status_code=400, detail="Training is already running.")
 
-    # Reset logs & stats
+    weights_path = Path(params.model)
+    # Allow ultralytics named weights (e.g. yolov8n.pt) that may download; still record path
+    yaml_path = Path(params.data)
+    if not yaml_path.exists():
+        record = create_execution(
+            "training",
+            configuration_snapshot=params.dict(),
+            input_artifacts=[params.data, params.model],
+        )
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[f"Dataset YAML not found: {params.data}"],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=400,
+            detail={"message": f"Dataset YAML not found: {params.data}", "execution_id": record["execution_id"]},
+        )
+
     TRAINING_LOGS_ACCUMULATED = f"Starting YOLO training with base model {params.model}...\n"
     TRAINING_LOSSES = []
     TOTAL_EPOCHS = params.epochs
     CURRENT_EPOCH = 0
+    LAST_TRAIN_EXIT_CODE = None
 
     cmd = [
         sys.executable, "train.py",
@@ -138,8 +345,17 @@ def start_train(params: TrainParams):
         "--batch", str(params.batch),
         "--device", params.device,
         "--model", params.model,
-        "--data", params.data
+        "--data", params.data,
     ]
+    LAST_TRAIN_COMMAND = cmd
+
+    record = create_execution(
+        "training",
+        configuration_snapshot=params.dict(),
+        input_artifacts=[params.data, params.model],
+        command=cmd,
+    )
+    ACTIVE_TRAIN_EXECUTION_ID = record["execution_id"]
 
     try:
         ACTIVE_TRAIN_PROC = subprocess.Popen(
@@ -148,47 +364,80 @@ def start_train(params: TrainParams):
             stderr=subprocess.STDOUT,
             text=True,
             bufsize=1,
-            preexec_fn=os.setsid if os.name != 'nt' else None
+            preexec_fn=os.setsid if os.name != "nt" else None,
         )
     except Exception as e:
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[f"Failed to spawn training process: {e}"],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        ACTIVE_TRAIN_EXECUTION_ID = None
         raise HTTPException(status_code=500, detail=f"Failed to spawn training process: {str(e)}")
 
-    return {"status": "started"}
+    mark_running(record["execution_id"], process_id=ACTIVE_TRAIN_PROC.pid)
+    return {
+        "status": "started",
+        "execution_id": record["execution_id"],
+        "process_id": ACTIVE_TRAIN_PROC.pid,
+        "command": cmd,
+    }
+
 
 @app.post("/api/train/stop")
 def stop_train():
-    global ACTIVE_TRAIN_PROC
+    global ACTIVE_TRAIN_PROC, ACTIVE_TRAIN_EXECUTION_ID, LAST_TRAIN_EXIT_CODE
+    from sensorflow.execution_ledger import finalize, append_log
+
     if not ACTIVE_TRAIN_PROC or ACTIVE_TRAIN_PROC.poll() is not None:
-        return {"status": "not_running"}
+        return {"status": "not_running", "execution_id": ACTIVE_TRAIN_EXECUTION_ID}
 
+    exec_id = ACTIVE_TRAIN_EXECUTION_ID
     try:
-        if os.name != 'nt':
+        if os.name != "nt":
             os.killpg(os.getpgid(ACTIVE_TRAIN_PROC.pid), signal.SIGTERM)
         else:
             ACTIVE_TRAIN_PROC.terminate()
         ACTIVE_TRAIN_PROC.wait(timeout=3)
-    except Exception as e:
-        # Fallback to simple kill
+    except Exception:
         try:
             ACTIVE_TRAIN_PROC.kill()
         except Exception:
             pass
 
-    return {"status": "stopped"}
+    LAST_TRAIN_EXIT_CODE = ACTIVE_TRAIN_PROC.poll()
+    if exec_id:
+        append_log(exec_id, "Training terminated by user")
+        finalize(
+            exec_id,
+            "CANCELLED",
+            exit_code=LAST_TRAIN_EXIT_CODE,
+            process_invoked=True,
+            outputs_valid=False,
+            errors=["Cancelled by user"],
+        )
+    ACTIVE_TRAIN_PROC = None
+    return {"status": "stopped", "execution_id": exec_id, "exit_code": LAST_TRAIN_EXIT_CODE}
+
 
 @app.get("/api/train/status")
 def get_train_status():
-    global ACTIVE_TRAIN_PROC, TRAINING_LOGS_ACCUMULATED, TRAINING_LOSSES, CURRENT_EPOCH, TOTAL_EPOCHS
+    global ACTIVE_TRAIN_PROC, ACTIVE_TRAIN_EXECUTION_ID, TRAINING_LOGS_ACCUMULATED
+    global TRAINING_LOSSES, CURRENT_EPOCH, TOTAL_EPOCHS, LAST_TRAIN_EXIT_CODE, LAST_TRAIN_COMMAND
+    from sensorflow.execution_ledger import append_log, finalize, sha256_file
+    from sensorflow.execution_ops import artifact_info
+
     running = False
-    
+    just_finished = False
+    exit_code = LAST_TRAIN_EXIT_CODE
+
     if ACTIVE_TRAIN_PROC:
-        # Read new output line by line (non-blocking)
-        # Use select or set standard output stream non-blocking if needed, or read from stdout.
-        # To avoid blocking, we read line-by-line if there is data.
         import select
+
         if ACTIVE_TRAIN_PROC.poll() is None:
             running = True
-            # Read available outputs
             while True:
                 r, _, _ = select.select([ACTIVE_TRAIN_PROC.stdout], [], [], 0.02)
                 if ACTIVE_TRAIN_PROC.stdout in r:
@@ -196,23 +445,22 @@ def get_train_status():
                     if not line:
                         break
                     TRAINING_LOGS_ACCUMULATED += line
-                    # Parse epoch loss from Ultralytics logs if visible
-                    # e.g., "1/10      3.5G      1.234"
-                    # Ultralytics log format standard contains epoch index and training loss
+                    if ACTIVE_TRAIN_EXECUTION_ID:
+                        try:
+                            append_log(ACTIVE_TRAIN_EXECUTION_ID, line.rstrip())
+                        except Exception:
+                            pass
                     if "epoch" in line.lower() or "/" in line:
                         try:
-                            # Try to extract numbers
                             parts = line.split()
                             if len(parts) >= 3 and "/" in parts[0]:
                                 ep_part = parts[0].split("/")
                                 epoch_num = int(ep_part[0])
                                 CURRENT_EPOCH = epoch_num
-                                # Try to grab a float that might be loss
                                 for p in parts[2:]:
                                     try:
                                         val = float(p)
                                         if 0.0 < val < 10.0:
-                                            # Found a candidate loss value
                                             if len(TRAINING_LOSSES) < epoch_num:
                                                 TRAINING_LOSSES.append(val)
                                             else:
@@ -225,54 +473,237 @@ def get_train_status():
                 else:
                     break
         else:
-            # Done running, read all remaining output
             remaining = ACTIVE_TRAIN_PROC.stdout.read()
             if remaining:
                 TRAINING_LOGS_ACCUMULATED += remaining
+            exit_code = ACTIVE_TRAIN_PROC.poll()
+            LAST_TRAIN_EXIT_CODE = exit_code
+            just_finished = True
             ACTIVE_TRAIN_PROC = None
 
-    # Calculate mock losses if empty to display curves in frontend
-    if not running and not TRAINING_LOSSES and TRAINING_LOGS_ACCUMULATED:
-        # Finished but no parsed losses, generate dummy decreasing loss
-        TRAINING_LOSSES = [2.5 - (2.0 / TOTAL_EPOCHS) * i for i in range(TOTAL_EPOCHS)]
-
     progress = 0.0
-    if TOTAL_EPOCHS > 0:
-        progress = float(CURRENT_EPOCH) / float(TOTAL_EPOCHS)
-        if not running and progress == 0.0:
-            progress = 1.0
+    if TOTAL_EPOCHS > 0 and CURRENT_EPOCH > 0:
+        progress = min(1.0, float(CURRENT_EPOCH) / float(TOTAL_EPOCHS))
+    elif not running and exit_code == 0 and CURRENT_EPOCH > 0:
+        progress = 1.0
+    # Never invent progress=1.0 on failure or empty parse
+
+    checkpoint = Path("runs/detect/coco_finetuned/weights/best.pt")
+    ckpt_info = artifact_info(checkpoint) if checkpoint.exists() else {"path": str(checkpoint), "exists": False}
+
+    if just_finished and ACTIVE_TRAIN_EXECUTION_ID:
+        status = "SUCCEEDED" if exit_code == 0 else "FAILED"
+        if exit_code is None:
+            status = "FAILED"
+        finalize(
+            ACTIVE_TRAIN_EXECUTION_ID,
+            status,
+            exit_code=exit_code,
+            metrics={
+                "epochs_requested": TOTAL_EPOCHS,
+                "epochs_observed": CURRENT_EPOCH,
+                "losses_parsed": len(TRAINING_LOSSES),
+                "losses": TRAINING_LOSSES,
+                "checkpoint": ckpt_info,
+            },
+            output_artifacts=[ckpt_info] if ckpt_info.get("exists") else [],
+            process_invoked=True,
+            outputs_valid=bool(ckpt_info.get("exists")) and exit_code == 0,
+            errors=[] if exit_code == 0 else [f"Training exit_code={exit_code}"],
+        )
 
     return {
         "running": running,
         "progress": progress,
-        "logs": TRAINING_LOGS_ACCUMULATED[-20000:],  # Limit log size sent to browser
-        "losses": TRAINING_LOSSES
+        "logs": TRAINING_LOGS_ACCUMULATED[-20000:],
+        "losses": TRAINING_LOSSES,  # only real parsed losses — never fabricated
+        "losses_fabricated": False,
+        "exit_code": exit_code,
+        "process_id": None if not running else (ACTIVE_TRAIN_PROC.pid if ACTIVE_TRAIN_PROC else None),
+        "command": LAST_TRAIN_COMMAND,
+        "execution_id": ACTIVE_TRAIN_EXECUTION_ID,
+        "epochs_observed": CURRENT_EPOCH,
+        "epochs_requested": TOTAL_EPOCHS,
+        "checkpoint": ckpt_info,
+        "status": (
+            "RUNNING" if running else (
+                "SUCCEEDED" if exit_code == 0 else (
+                    "FAILED" if exit_code not in (None, 0) else "NOT_EXECUTED"
+                )
+            )
+        ),
     }
 
+
 @app.post("/api/infer/run")
 def run_infer(params: InferParams):
-    # Run the infer.py script using subprocess
-    cmd = [
-        sys.executable, "infer.py",
-        "--source", params.source,
-        "--weights", params.weights,
-        "--conf", str(params.conf),
-        "--iou", str(params.iou),
-        "--output", "runs/infer"
-    ]
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize, append_log
+    from sensorflow.execution_ops import discover_images, artifact_info
+
+    weights = Path(params.weights)
+    source = Path(params.source)
+    out_dir = Path("runs/infer")
+
+    record = create_execution(
+        "inference",
+        configuration_snapshot=params.dict(),
+        input_artifacts=[params.source, params.weights],
+        command=[
+            sys.executable, "infer.py",
+            "--source", params.source,
+            "--weights", params.weights,
+            "--conf", str(params.conf),
+            "--iou", str(params.iou),
+            "--output", "runs/infer",
+        ],
+    )
+
+    if not weights.exists() and not str(params.weights).endswith(".pt"):
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[f"Model checkpoint not found: {params.weights}"],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=400,
+            detail={"message": f"Model checkpoint not found: {params.weights}", "execution_id": record["execution_id"]},
+        )
+    if not weights.exists():
+        # Named ultralytics weight may auto-download; still warn if missing before run
+        pass
+
+    discovery = discover_images(params.source)
+    if discovery["images_discovered"] == 0:
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            records_discovered=0,
+            records_processed=0,
+            records_succeeded=0,
+            records_failed=0,
+            errors=[f"No images found at source: {params.source}"],
+            metrics={"images_discovered": 0},
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        return {
+            "status": "FAILED",
+            "execution_id": record["execution_id"],
+            "images": [],
+            "records_discovered": 0,
+            "records_succeeded": 0,
+            "records_failed": 0,
+            "message": f"No images found at source: {params.source}",
+            "model": params.weights,
+            "checkpoint": artifact_info(weights),
+        }
+
+    if not weights.exists():
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[f"Missing model checkpoint: {params.weights}"],
+            records_discovered=discovery["images_discovered"],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "message": f"Missing model checkpoint: {params.weights}",
+                "execution_id": record["execution_id"],
+            },
+        )
 
+    cmd = record["command"]
+    mark_running(record["execution_id"])
     try:
-        res = subprocess.run(cmd, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        raise HTTPException(status_code=500, detail=f"Inference script failed: {e.stdout}\n{e.stderr}")
+        res = subprocess.run(cmd, capture_output=True, text=True)
+    except Exception as e:
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[str(e)],
+            process_invoked=True,
+            outputs_valid=False,
+        )
+        raise HTTPException(status_code=500, detail=f"Inference failed to start: {e}")
+
+    if res.stdout:
+        append_log(record["execution_id"], res.stdout[-4000:])
+    if res.stderr:
+        append_log(record["execution_id"], res.stderr[-2000:])
 
-    # Gather list of output annotated images
-    out_dir = Path("runs/infer")
     images = []
     if out_dir.exists():
         images = [f.name for f in out_dir.glob("annotated_*") if f.is_file()]
+    preds_path = out_dir / "predictions.json"
+    pred_count = 0
+    if preds_path.exists():
+        try:
+            pred_count = len(json.loads(preds_path.read_text()))
+        except Exception:
+            pred_count = 0
+
+    succeeded = len(images)
+    failed = max(0, discovery["images_discovered"] - succeeded)
+    if res.returncode != 0:
+        status = "FAILED"
+    elif succeeded == 0:
+        status = "FAILED"
+    elif failed > 0:
+        status = "PARTIAL_SUCCESS"
+    else:
+        status = "SUCCEEDED"
+
+    final = finalize(
+        record["execution_id"],
+        status,
+        exit_code=res.returncode,
+        records_discovered=discovery["images_discovered"],
+        records_processed=discovery["images_discovered"],
+        records_succeeded=succeeded,
+        records_failed=failed,
+        metrics={
+            "model": params.weights,
+            "checkpoint": artifact_info(weights),
+            "inference_calls": discovery["images_discovered"],
+            "predictions_generated": pred_count,
+            "annotated_images": succeeded,
+            "conf": params.conf,
+            "iou": params.iou,
+            "output_dir": str(out_dir),
+        },
+        output_artifacts=[
+            {"path": str(out_dir), "kind": "infer_dir"},
+            artifact_info(preds_path),
+        ],
+        errors=[] if res.returncode == 0 else [res.stderr or res.stdout or "infer non-zero exit"],
+        process_invoked=True,
+        outputs_valid=succeeded > 0 and res.returncode == 0,
+    )
 
-    return {"status": "ok", "images": sorted(images)}
+    return {
+        "status": final["status"],
+        "execution_id": final["execution_id"],
+        "verified": final.get("verified"),
+        "duration_ms": final.get("duration_ms"),
+        "images": sorted(images),
+        "model": params.weights,
+        "checkpoint": artifact_info(weights),
+        "records_discovered": discovery["images_discovered"],
+        "records_processed": discovery["images_discovered"],
+        "records_succeeded": succeeded,
+        "records_failed": failed,
+        "inference_calls": discovery["images_discovered"],
+        "predictions_generated": pred_count,
+        "output_dir": str(out_dir),
+        "exit_code": res.returncode,
+        "process_id": None,
+        "command": cmd,
+    }
 
 @app.get("/api/images/{filename}")
 def serve_image(filename: str):
@@ -283,76 +714,146 @@ def serve_image(filename: str):
 
 @app.get("/api/grade")
 def grade_predictions():
-    # Runs the autograder.py script
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize
+    from sensorflow.execution_ops import artifact_info
+
     predictions_file = Path("runs/infer/predictions.json")
+    record = create_execution(
+        "auto_grader",
+        configuration_snapshot={"predictions": str(predictions_file)},
+        input_artifacts=[str(predictions_file)],
+        command=[sys.executable, "autograder.py", "--predictions", str(predictions_file)],
+    )
+
     if not predictions_file.exists():
-        # Let's run a fallback report if no predictions exist
+        final = finalize(
+            record["execution_id"],
+            "NOT_EXECUTED",
+            errors=["predictions.json missing — run Auto-Labeler Inference first"],
+            process_invoked=False,
+            outputs_valid=False,
+            warnings=["Grader not executed: no predictions artifact"],
+        )
         return {
+            "status": "NOT_EXECUTED",
+            "execution_id": final["execution_id"],
             "total_predictions": 0,
             "total_images": 0,
-            "quality_score": 0.0,
+            "quality_score": None,
+            "metrics": {},
             "issues": [
                 {
                     "severity": "WARNING",
                     "type": "Missing predictions",
-                    "description": "Please run the Auto-Labeler Inference step first to generate prediction files.",
-                    "recommendation": "Go back to Step 4 and run Auto-Labeler."
+                    "description": "No predictions.json — grader was NOT executed.",
+                    "recommendation": "Run Auto-Labeler Inference first.",
                 }
-            ]
+            ],
+            "message": "NOT_EXECUTED: missing predictions artifact",
         }
 
-    cmd = [
-        sys.executable, "autograder.py",
-        "--predictions", str(predictions_file)
-    ]
-
+    mark_running(record["execution_id"])
+    cmd = record["command"]
     try:
-        subprocess.run(cmd, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        raise HTTPException(status_code=500, detail=f"Autograder failed: {e.stderr}")
+        res = subprocess.run(cmd, capture_output=True, text=True)
+    except Exception as e:
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[str(e)],
+            process_invoked=True,
+            outputs_valid=False,
+        )
+        raise HTTPException(status_code=500, detail=f"Autograder failed to start: {e}")
 
-    # Read generated quality report
     report_file = Path("runs/infer/quality_report.json")
-    if report_file.exists():
-        with open(report_file, "r") as f:
-            report_data = json.load(f)
-            
-            # Map standard report issues to list
-            issues = []
-            for issue_type, count in report_data.get("issue_summary", {}).items():
-                if count > 0:
-                    severity = "WARNING" if issue_type in ["low_confidence", "overlapping_different_class"] else "INFO"
-                    desc = f"Found {count} occurrences of {issue_type.replace('_', ' ')}."
-                    rec = "Retrain model with more samples or tune confidence threshold."
-                    if issue_type == "small_detection":
-                        rec = "Verify that extremely small bounding boxes are correct."
-                    elif issue_type == "class_imbalance":
-                        rec = "Balance class frequency in dataset to prevent bias."
-                    
-                    issues.append({
-                        "severity": severity,
-                        "type": issue_type.upper().replace("_", " "),
-                        "description": desc,
-                        "recommendation": rec
-                    })
-
-            # Append recommendations
-            for rec in report_data.get("recommendations", []):
-                issues.append({
-                    "severity": "INFO",
-                    "type": "RECOMMENDATION",
-                    "description": rec,
-                    "recommendation": "Review annotation guidelines."
-                })
-
-            return {
-                "total_predictions": report_data.get("total_predictions", 0),
-                "total_images": report_data.get("total_images", 0),
-                "quality_score": report_data.get("quality_score", 0.0),
-                "issues": issues
-            }
+    if res.returncode != 0 or not report_file.exists():
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            exit_code=res.returncode,
+            errors=[res.stderr or res.stdout or "grader produced no report"],
+            process_invoked=True,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "message": f"Autograder failed: {res.stderr}",
+                "execution_id": record["execution_id"],
+            },
+        )
+
+    with open(report_file, "r") as f:
+        report_data = json.load(f)
+
+    issues = []
+    for issue_type, count in report_data.get("issue_summary", {}).items():
+        if count > 0:
+            severity = "WARNING" if issue_type in ["low_confidence", "overlapping_different_class"] else "INFO"
+            desc = f"Found {count} occurrences of {issue_type.replace('_', ' ')}."
+            rec = "Retrain model with more samples or tune confidence threshold."
+            if issue_type == "small_detection":
+                rec = "Verify that extremely small bounding boxes are correct."
+            elif issue_type == "class_imbalance":
+                rec = "Balance class frequency in dataset to prevent bias."
+            issues.append({
+                "severity": severity,
+                "type": issue_type.upper().replace("_", " "),
+                "description": desc,
+                "recommendation": rec,
+            })
+
+    for rec in report_data.get("recommendations", []):
+        issues.append({
+            "severity": "INFO",
+            "type": "RECOMMENDATION",
+            "description": rec,
+            "recommendation": "Review annotation guidelines.",
+        })
+
+    metrics = {
+        "total_predictions": report_data.get("total_predictions", 0),
+        "total_images": report_data.get("total_images", 0),
+        "quality_score": report_data.get("quality_score"),
+        "issue_summary": report_data.get("issue_summary", {}),
+        "precision": report_data.get("precision"),
+        "recall": report_data.get("recall"),
+        "f1": report_data.get("f1"),
+        "mAP": report_data.get("mAP"),
+        "tp": report_data.get("tp"),
+        "fp": report_data.get("fp"),
+        "fn": report_data.get("fn"),
+        "per_class": report_data.get("per_class"),
+    }
+    # Strip Nones so UI only shows grader-provided metrics
+    metrics = {k: v for k, v in metrics.items() if v is not None}
+
+    final = finalize(
+        record["execution_id"],
+        "SUCCEEDED",
+        exit_code=res.returncode,
+        records_discovered=metrics.get("total_images", 0),
+        records_processed=metrics.get("total_images", 0),
+        records_succeeded=metrics.get("total_images", 0),
+        metrics=metrics,
+        output_artifacts=[artifact_info(report_file), artifact_info(predictions_file)],
+        process_invoked=True,
+        outputs_valid=True,
+    )
 
-    return {"status": "error", "message": "Failed to read grader output"}
+    return {
+        "status": final["status"],
+        "execution_id": final["execution_id"],
+        "verified": final.get("verified"),
+        "duration_ms": final.get("duration_ms"),
+        "total_predictions": metrics.get("total_predictions", 0),
+        "total_images": metrics.get("total_images", 0),
+        "quality_score": metrics.get("quality_score"),
+        "metrics": metrics,
+        "issues": issues,
+        "message": "Grader completed from predictions.json",
+    }
 
 @app.post("/api/export")
 def export_weights(params: ExportParams):
@@ -823,23 +1324,62 @@ DATASET_METADATA_STORE = {
 
 @app.get("/api/dataset/details")
 def get_dataset_details(type: str = "local"):
-    metadata = DATASET_METADATA_STORE.get(type, DATASET_METADATA_STORE["local"])
+    metadata = dict(DATASET_METADATA_STORE.get(type, DATASET_METADATA_STORE["local"]))
+    # Catalog KPIs are reference stats for the selected dataset type — not proof that
+    # frames are on disk or browsable in Studio.
+    metadata["browsable"] = False
+    metadata["catalog_only"] = True
+    metadata["browse_hint"] = (
+        "These percentages are catalog estimates. Use Validate & Browse Images Path "
+        "or run 3D Ingest, then open Pipeline Outputs to view real frames."
+    )
     return {"status": "ok", "metadata": metadata}
 
 @app.post("/api/dataset/preprocess")
 def preprocess_dataset(params: dict):
+    """Catalog-only path kept for backward compatibility.
+
+    Prefer POST /api/dataset/load for real discovery evidence.
+    If source_path is provided, delegates to real load.
+    """
+    if params.get("source_path") or params.get("real_load"):
+        return dataset_load(params)
+
     dataset_type = params.get("dataset_type", "local")
-    import time
-    time.sleep(0.3)
-    
-    meta = DATASET_METADATA_STORE.get(dataset_type, DATASET_METADATA_STORE["local"])
-    
+    meta = dict(DATASET_METADATA_STORE.get(dataset_type, DATASET_METADATA_STORE["local"]))
+    meta["browsable"] = False
+    meta["catalog_only"] = True
+    meta["browse_hint"] = (
+        "Catalog metadata only — NOT disk load. Use Load & Preprocess or "
+        "Validate & Browse Images Path for verifiable counts."
+    )
+    from sensorflow.execution_ledger import create_execution, finalize
+
+    record = create_execution(
+        "dataset_catalog_metadata",
+        configuration_snapshot={"dataset_type": dataset_type},
+        status="QUEUED",
+    )
+    finalize(
+        record["execution_id"],
+        "NOT_EXECUTED",
+        warnings=["Catalog metadata echo only — no discovery/decode ran"],
+        metrics={"catalog_only": True, "ingestion_pct_is_catalog": True},
+        process_invoked=False,
+        outputs_valid=False,
+    )
     return {
-        "status": "ok",
-        "message": f"Dataset {meta['name']} loaded and preprocessed successfully.",
+        "status": "NOT_EXECUTED",
+        "execution_id": record["execution_id"],
+        "message": (
+            f"Catalog metadata for {meta['name']} — not the same as loading "
+            f"browsable frames. Use Load & Preprocess for real evidence."
+        ),
         "dataset_type": dataset_type,
-        "total_frames": meta["loaded_rows"],
-        "metadata": meta
+        "total_frames": None,
+        "browsable": False,
+        "catalog_only": True,
+        "metadata": meta,
     }
 
 @app.post("/api/dataset/save-pipeline-tools")
@@ -1273,8 +1813,10 @@ def annotate_street(req: AnnotateStreetRequest):
 # -----------------------------------------------------------------------
 
 class IngestParams(BaseModel):
-    vendors: List[str] = ["alpamayo", "waymo"]
+    vendors: List[str] = ["alpamayo", "waymo", "a2d2"]
     sequence_id: str = "seq_001"
+    source_path: Optional[str] = None
+    max_frames: Optional[int] = None
 
 class AutoLabelParams(BaseModel):
     sequence_id: str = "seq_001"
@@ -1295,20 +1837,45 @@ class GateParams(BaseModel):
 @app.post("/api/dataset/ingest")
 def ingest_dataset(params: IngestParams):
     from sensorflow.dataset_fusion_engine import DatasetFusionEngine
+    config = load_config()
+    source_path = params.source_path if params.source_path is not None else config.source_path
     try:
         engine = DatasetFusionEngine()
-        sequence = engine.ingest(params.vendors, params.sequence_id)
+        sequence = engine.ingest(
+            params.vendors,
+            params.sequence_id,
+            source_path=source_path,
+            max_frames=params.max_frames,
+        )
         manifest_path = engine.save_manifest(sequence)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Ingest failed: {str(e)}")
 
-    config = load_config()
     config.sequence_id = params.sequence_id
     config.vendors = params.vendors
+    if params.source_path is not None:
+        config.source_path = params.source_path
     with open(CONFIG_PATH, "w") as f:
         json.dump(config.model_dump(), f, indent=2)
 
-    return {"status": "ok", "manifest": str(manifest_path), "sequence_id": params.sequence_id}
+    frame_count = len(sequence.frames)
+    demo_stub = bool(sequence.taxonomy_manifest.get("demo_stub"))
+    return {
+        "status": "ok",
+        "manifest": str(manifest_path),
+        "sequence_id": params.sequence_id,
+        "frames": frame_count,
+        "demo_stub": demo_stub,
+        "vendor": sequence.vendor,
+        "source_path": source_path,
+        "message": (
+            f"demo stub: {frame_count} frames"
+            if demo_stub
+            else f"ingested {frame_count} frames from {source_path}"
+        ),
+    }
 
 
 @app.get("/api/dataset/ingest/status")
@@ -1323,6 +1890,9 @@ def ingest_status(sequence_id: str = "seq_001"):
         status["manifest_exists"] = True
         status["frames"] = len(manifest_data.get("frames", []))
         status["vendor"] = manifest_data.get("vendor", "unknown")
+        tax = manifest_data.get("taxonomy_manifest") or {}
+        status["demo_stub"] = bool(tax.get("demo_stub", status.get("demo_stub", False)))
+        status["stub_note"] = tax.get("stub_note")
     return {"status": "ok", "sequence_id": sequence_id, **status}
 
 
@@ -1330,13 +1900,43 @@ def ingest_status(sequence_id: str = "seq_001"):
 def auto_label(params: AutoLabelParams):
     from sensorflow.perception_automator import PerceptionAutomator
     from sensorflow.schemas.unified_frame import UnifiedSequence
+    from sensorflow.execution_ledger import create_execution, mark_running, finalize
+    from sensorflow.execution_ops import artifact_info
 
     manifest = Path("runs/pipeline") / params.sequence_id / "manifest.json"
+    record = create_execution(
+        "auto_label_3d",
+        configuration_snapshot=params.dict(),
+        input_artifacts=[str(manifest), params.sam_checkpoint],
+    )
+
     if not manifest.exists():
-        raise HTTPException(status_code=400, detail="Manifest not found. Run ingest first.")
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=["Manifest not found. Run ingest first."],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=400,
+            detail={"message": "Manifest not found. Run ingest first.", "execution_id": record["execution_id"]},
+        )
+
+    ckpt = Path(params.sam_checkpoint)
+    sam_ran = False
+    model_name = "sam_vit_b" if not params.no_sam else "none (no_sam)"
+    if params.no_sam:
+        warnings = ["no_sam=true — SAM not invoked; proposals may be GT/synthetic fallback"]
+    elif not ckpt.exists():
+        warnings = [f"SAM checkpoint missing: {params.sam_checkpoint} — model will not run"]
+    else:
+        warnings = []
 
+    mark_running(record["execution_id"])
     try:
         sequence = UnifiedSequence.load(manifest)
+        expected_frames = len(sequence.frames)
         output_dir = manifest.parent / "proposals"
         automator = PerceptionAutomator(
             sam_checkpoint=params.sam_checkpoint,
@@ -1344,12 +1944,93 @@ def auto_label(params: AutoLabelParams):
             use_sam=not params.no_sam,
         )
         automator.run_sequence(sequence, output_dir)
+        sam_ran = bool(getattr(automator, "use_sam", False) and automator._mask_generator is not None)
     except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Auto-label failed: {str(e)}")
+        finalize(
+            record["execution_id"],
+            "FAILED",
+            errors=[str(e)],
+            process_invoked=False,
+            outputs_valid=False,
+        )
+        raise HTTPException(
+            status_code=500,
+            detail={"message": f"Auto-label failed: {str(e)}", "execution_id": record["execution_id"]},
+        )
 
     proposals_dir = manifest.parent / "proposals"
-    num_frames = len(list(proposals_dir.glob("*.json"))) if proposals_dir.exists() else 0
-    return {"status": "ok", "proposals_dir": str(proposals_dir), "frames_processed": num_frames}
+    proposal_files = list(proposals_dir.glob("*.json")) if proposals_dir.exists() else []
+    num_frames = len(proposal_files)
+    pred_count = 0
+    for pf in proposal_files:
+        try:
+            data = json.loads(pf.read_text())
+            if isinstance(data, list):
+                pred_count += len(data)
+            elif isinstance(data, dict):
+                pred_count += len(data.get("proposals") or data.get("objects") or [])
+        except Exception:
+            pass
+
+    demo_stub = bool(sequence.taxonomy_manifest.get("demo_stub"))
+    if params.no_sam or not sam_ran:
+        status = "NOT_EXECUTED" if num_frames == 0 else "PARTIAL_SUCCESS"
+        if params.no_sam:
+            warnings.append("Model not run (no_sam); do not treat as SAM SUCCESS")
+        elif not sam_ran:
+            warnings.append("SAM unavailable — fallback proposals only")
+    elif num_frames == 0:
+        status = "FAILED"
+    elif num_frames < expected_frames:
+        status = "PARTIAL_SUCCESS"
+    else:
+        status = "SUCCEEDED"
+
+    final = finalize(
+        record["execution_id"],
+        status,
+        records_discovered=expected_frames,
+        records_processed=num_frames,
+        records_succeeded=num_frames,
+        records_failed=max(0, expected_frames - num_frames),
+        metrics={
+            "model": model_name,
+            "checkpoint": artifact_info(ckpt),
+            "sam_ran": sam_ran,
+            "no_sam": params.no_sam,
+            "frames_expected": expected_frames,
+            "frames_processed": num_frames,
+            "predictions_generated": pred_count,
+            "inference_calls": num_frames if sam_ran else 0,
+            "output_dir": str(proposals_dir),
+            "demo_stub": demo_stub,
+        },
+        output_artifacts=[{"path": str(proposals_dir), "kind": "proposals_dir", "files": num_frames}],
+        warnings=warnings,
+        process_invoked=sam_ran,
+        outputs_valid=num_frames > 0,
+    )
+
+    return {
+        "status": final["status"],
+        "execution_id": final["execution_id"],
+        "verified": final.get("verified"),
+        "duration_ms": final.get("duration_ms"),
+        "proposals_dir": str(proposals_dir),
+        "frames_processed": num_frames,
+        "frames_expected": expected_frames,
+        "predictions_generated": pred_count,
+        "inference_calls": num_frames if sam_ran else 0,
+        "model": model_name,
+        "checkpoint": artifact_info(ckpt),
+        "sam_ran": sam_ran,
+        "demo_stub": demo_stub,
+        "message": (
+            f"{'NOT_EXECUTED / fallback' if not sam_ran else 'SAM'}: "
+            f"processed {num_frames}/{expected_frames} frames, {pred_count} predictions → {proposals_dir}"
+        ),
+        "events": final.get("events"),
+    }
 
 
 @app.post("/api/perception/track")
@@ -1440,18 +2121,109 @@ def pipeline_status(sequence_id: str = "seq_001"):
 
     seq_state = state.get(sequence_id, {})
     base = Path("runs/pipeline") / sequence_id
+    manifest = base / "manifest.json"
+    proposals_dir = base / "proposals"
+    tracks = base / "tracks.json"
+    benchmark = base / "benchmark" / "metric_card.json"
+    quality_report = base / "benchmark" / "quality_report.json"
+
+    ingest_complete = manifest.exists()
+    perception_complete = proposals_dir.exists() and any(proposals_dir.glob("*.json"))
+    tracking_complete = tracks.exists()
+    benchmark_complete = benchmark.exists()
+
+    frames_ingested = None
+    frames_processed = None
+    demo_stub = None
+    if ingest_complete:
+        try:
+            with open(manifest) as f:
+                manifest_data = json.load(f)
+            frames_ingested = len(manifest_data.get("frames", []))
+            demo_stub = bool((manifest_data.get("taxonomy_manifest") or {}).get("demo_stub"))
+        except Exception:
+            frames_ingested = seq_state.get("frames")
+            demo_stub = seq_state.get("demo_stub")
+    if perception_complete:
+        frames_processed = len(list(proposals_dir.glob("*.json")))
+
+    # Completion stages: True when done, None when not run (UI must not show FAIL).
+    # Launch gate: True/False only after evaluation; None beforehand.
+    launch_gate_passed = seq_state.get("launch_gate_passed")
+    if "launch_gate_passed" not in seq_state:
+        launch_gate_passed = None
+
+    quality_passed = None
+    if quality_report.exists():
+        try:
+            with open(quality_report) as f:
+                quality_passed = bool(json.load(f).get("passed"))
+        except Exception:
+            quality_passed = benchmark_complete
+
     return {
         "status": "ok",
         "sequence_id": sequence_id,
-        "ingest_complete": (base / "manifest.json").exists(),
-        "perception_complete": (base / "proposals").exists() and any((base / "proposals").glob("*.json")),
-        "tracking_complete": (base / "tracks.json").exists(),
-        "benchmark_complete": (base / "benchmark" / "metric_card.json").exists(),
-        "launch_gate_passed": seq_state.get("launch_gate_passed", False),
+        "ingest_complete": True if ingest_complete else None,
+        "perception_complete": True if perception_complete else None,
+        "tracking_complete": True if tracking_complete else None,
+        "benchmark_complete": True if benchmark_complete else None,
+        "quality_gate_passed": quality_passed,
+        "launch_gate_passed": launch_gate_passed,
+        "frames_ingested": frames_ingested,
+        "frames_processed": frames_processed,
+        "demo_stub": demo_stub,
         "state": seq_state,
     }
 
 
+@app.get("/api/pipeline/sequences")
+def pipeline_sequences():
+    from sensorflow import pipeline_artifacts as artifacts
+    return {"status": "ok", "sequences": artifacts.list_sequences()}
+
+
+@app.get("/api/pipeline/artifacts")
+def pipeline_artifacts(sequence_id: str = "seq_001"):
+    from sensorflow import pipeline_artifacts as artifacts
+    return {"status": "ok", **artifacts.artifacts_summary(sequence_id)}
+
+
+@app.get("/api/pipeline/frames")
+def pipeline_frames(sequence_id: str = "seq_001"):
+    from sensorflow import pipeline_artifacts as artifacts
+    return artifacts.list_frames(sequence_id)
+
+
+@app.get("/api/pipeline/frame")
+def pipeline_frame(sequence_id: str, frame_id: str):
+    from sensorflow import pipeline_artifacts as artifacts
+    try:
+        return artifacts.get_frame(sequence_id, frame_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@app.get("/api/pipeline/file")
+def pipeline_file(path: str):
+    """Serve a local run/data artifact with path-traversal protection."""
+    from sensorflow import pipeline_artifacts as artifacts
+    try:
+        file_path, media_type = artifacts.resolve_file(path)
+    except PermissionError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    return FileResponse(file_path, media_type=media_type)
+
+
+@app.get("/api/dataset/browse")
+def dataset_browse(source_path: str = "data", limit: int = 48):
+    """Validate Images Path by listing browsable local frames."""
+    from sensorflow import pipeline_artifacts as artifacts
+    return artifacts.scan_source_images(source_path, limit=limit)
+
+
 @app.get("/api/mitl/queue")
 def get_mitl_queue(sequence_id: str = "seq_001"):
     from sensorflow.mitl_copilot import MitlCopilot
@@ -1534,6 +2306,14 @@ app.include_router(studio2_router)
 from sensorflow.rotr.api import router as rotr_router
 app.include_router(rotr_router)
 
+# In-app help chatbot (FAQ / page-guide matcher; optional Ollama enrichment).
+from sensorflow.help.api import router as help_router
+app.include_router(help_router)
+
+# Product version + About catalog (GET /api/about, GET /api/version).
+from sensorflow.about.api import router as about_router
+app.include_router(about_router)
+
 # Mount static folder
 static_dir = Path(__file__).parent / "static"
 if static_dir.exists():

docs/execution-integrity-audit.md

@@ -0,0 +1,99 @@
+# Sensorflow Studio — Execution Integrity & Observability Audit
+
+**Date:** 2026-08-14  
+**Scope:** Legacy Studio (`static/`, `app_backend.py`, `sensorflow/`, `train.py`, `infer.py`, `autograder.py`)  
+**Mirror:** `hf-space/` copies are effectively identical for these surfaces — findings apply to both.  
+**Prime directive:** A UI state is NOT evidence. PASS / Done / 100% / Found / `success:true` / toasts / YAML alone / file existence alone are not proof of execution.
+
+---
+
+## Stage integrity table
+
+| COMPONENT | CURRENT BEHAVIOR | ACTUAL EXECUTION? | EVIDENCE | RISK | REQUIRED FIX |
+|-----------|------------------|-------------------|----------|------|--------------|
+| 1 Dataset Configuration / Load & Preprocess | Save config writes JSON; Pre-Check = script file existence; “Load Catalog Metadata” returns hardcoded KPIs (`ingestion_pct: "100.0%"`) after `sleep(0.3)`; Validate & Browse is real disk scan. Toast “saved & verified” without path checks. | **Partial** — browse real; catalog preprocess is not load | `app_backend.py` precheck/details/preprocess; `static/app.js` save/browse handlers | **High** | Real Load & Preprocess with discovery counts + ledger; never show 100% Loaded from catalog |
+| 2 3D Ingest & Fusion | Calls fusion engine; vendor adapters default `demo_stub`; local path can be real. UI PASS when `manifest.json` exists. | **Yes local**; **stub vendors** | ingest API + adapters; gate badges | **Medium** | PASS/DONE only with provenance; surface `demo_stub` + execution_id |
+| 3 3D Perception / Auto-label (SAM) | Frontend hardcodes `no_sam: true`. Automator falls back to GT/synthetic masks; still `status: ok` → PASS. | **No real SAM** on Studio UI path | `static/app.js` perception handler; `perception_automator.py` | **Critical** | Record model/checkpoint/counts; NOT_EXECUTED if model not run; refuse fake SUCCESS |
+| 4 Temporal Tracking | Real Kalman+Hungarian over proposals. | **Yes** (inputs may be fake) | track API | **Medium** | Propagate contamination; ledger entry |
+| 5 Quality Gate | Real metric math vs sequence GT; contaminated proposals inflate pass. | **Yes math**; honesty depends on inputs | quality gate API | **High** | Fail closed on stub/GT-fallback; evidence card |
+| 6 Launch Gate | Threshold check on metric card. | **Yes** (inherited) | launch gate evaluator | **Medium** | Same provenance gate |
+| 7 Model Setup (2D) | UI model card only; no weight verification. | **No** | model cards in `app.js` | **Low–Medium** | Verify weights exist before train/infer |
+| 8 Training Execution | Spawns real `train.py`. Status fabricates losses; forces progress=1.0; ignores exit_code. UI “Process finished” with no verdict. | **Partial** | train start/status; `train.py` | **Critical** | PID, command, exit_code, checkpoint hash, ledger |
+| 9 Auto-Labeler Inference | Runs `infer.py` with check=True. Empty source exits 0 → ok + empty images. UI always success toast. | **Partial** | infer API; `infer.py` | **High** | Counts + checkpoint + exit_code; NOT_EXECUTED/FAILED if 0 images / missing weights |
+| 10 Auto-Grader Quality | Real autograder when predictions exist; empty issues → “Perfect score!”. | **Yes** (heuristic) | grade API; `autograder.py` | **Medium** | Metrics only from grader output; ledger |
+| 11 MITL Review | Hardcoded Unsplash samples; claims HF ingest; Mock Triage Auditor. | **No** | nvidia/load; mitl/evaluate | **Critical** | Label fixtures; never SUCCEEDED for mock ingest |
+| 12 Model Benchmarking | `fallback_mock` hardcoded metrics with `status: ok`. | **No** (unless live card) | `/api/benchmark/compare` | **Critical** | Refuse OK without live metrics; stub = NOT_EXECUTED |
+| 13 Export & Deploy | May run Ultralytics export; returns path without exists(); UI “✓ complete” without `res.ok`. | **Partial** | export API | **High** | Verify artifact; ledger |
+| 14 MCP Settings | Real R/W when file exists; invented servers + “changes simulated”. | **Partial** | mcp APIs | **Medium** | Honest status; evidence stub |
+| 15 SSAM Safety | Hardcoded CA intersections presented as statewide FHWA dataset. | **No real lake** | ssam endpoints + catalog | **High** | Label synthetic demo; stub evidence |
+
+---
+
+## High-risk fake-success occurrences
+
+### Backend (`app_backend.py`)
+
+| Location | Pattern |
+|----------|---------|
+| `/api/precheck` | Success = `train.py` / `infer.py` / `autograder.py` **file existence only** |
+| `/api/train/status` | Fabricates decreasing losses; forces `progress=1.0`; ignores process `returncode` |
+| `/api/infer/run` | Empty run still `status: ok` when script exits 0 with 0 images |
+| `/api/export` | Returns export path without verifying file exists |
+| `/api/nvidia/load` | Hardcoded samples; claims HF ingest success |
+| MITL evaluate | Mock Triage Auditor returned as success-shaped response |
+| `/api/benchmark/compare` | `fallback_mock` hardcoded metrics, `status: ok` |
+| `DATASET_METADATA_STORE` | Hardcoded `ingestion_pct: "100.0%"` catalog KPIs |
+| `/api/dataset/preprocess` | `time.sleep(0.3)` + catalog echo — no disk load |
+| MCP get/toggle | Invented config / “changes simulated” with ok/warning |
+| SSAM store | Hardcoded intersections as statewide dataset |
+| `/api/pipeline/status` | File existence ⇒ `*_complete: true` |
+
+### Frontend (`static/app.js`)
+
+| Location | Pattern |
+|----------|---------|
+| Gate badges | Completion stages → **PASS** from file-complete; never FAIL |
+| Config save | “verified successfully” without `res.ok` / path validation |
+| Training poll | “Process finished” with no exit_code / success check |
+| Infer | Always success toast (even empty / `!res.ok`) |
+| Grader | Empty issues → “Perfect score!” |
+| Export | “✓ Export complete” without `res.ok` |
+| Perception | **`no_sam: true` hardcoded** |
+
+### Scripts / sensorflow
+
+| Location | Pattern |
+|----------|---------|
+| `train.py` dgx-spark | Prints remote offload; uses local device |
+| `infer.py` | No images → print and **exit 0** |
+| `perception_automator.py` | Silent SAM off; synthetic masks/LiDAR; GT class copy |
+| Vendor adapters | Built-in ~3-frame `demo_stub` lakes |
+
+---
+
+## Cross-cutting patterns
+
+1. **`status: "ok"` / success toast without evidence**
+2. **File existence = done/PASS**
+3. **Hardcoded metrics / “100%” catalog KPIs**
+4. **Simulated delays / stubs claiming complete**
+5. **Subprocess integrity gaps** (exit ignored, empty exit 0)
+6. **GT contamination loop** (`no_sam` → synthetic/GT proposals → quality/launch PASS)
+7. **Frontend rarely checks `res.ok`**
+
+---
+
+## What is relatively honest today
+
+- Validate & Browse (`/api/dataset/browse`) — real filesystem scan
+- Local ingest (non-stub) — real frames → manifest
+- Tracking / quality math / launch thresholds / autograder heuristics / YOLO train+infer — real when inputs and deps exist
+- Catalog preprocess messaging partially hardened (`catalog_only`, `browse_hint`) but KPIs still read as Loaded
+
+---
+
+## Remediation shipped in `feat/execution-integrity`
+
+**Implemented:** Execution ledger + APIs; real Dataset Load & Preprocess; Auto-Label / Infer / Train / Grader evidence wiring; YAML semantic validation; script verification; backend health; Strict Mode; Evidence Cards + Global Execution Console; failure + deterministic tests; remaining stages show honest `NOT_EXECUTED` / unverified stubs.
+
+**Deferred (honest stubs only):** Full MITL/HF ingest, real SSAM lake, real MCP process probes, SAM GPU path when checkpoint absent, full 15-stage process verification beyond Dataset/Auto-Label/Train/Grader.

hf-space/.dockerignore

@@ -1,12 +0,0 @@
-node_modules/
-.venv/
-.git/
-runs/
-dist/
-models/
-*.pt
-__pycache__/
-**/__pycache__/
-.pytest_cache/
-.claude/
-.DS_Store

hf-space/.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

hf-space/.gitignore

@@ -1,72 +0,0 @@
-# Virtual environments
-.venv/
-venv/
-env/
-ENV/
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
-
-# Node
-node_modules/
-package-lock.json
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Large model files (download on deployment)
-*.pt
-
-# Logs
-*.log
-logs/
-
-# Local development
-.env
-.env.local
-*.local.json
-
-# Temporary
-/tmp/
-temp/
-
-# Generated runtime/test artifacts
-runs/labeleval/
-runs/megaeval/
-runs/pipeline/frame_test/
-runs/pipeline/qg_test/
-runs/pipeline/roundtrip/
-runs/pipeline/test_seq/
-runs/pipeline/test_waymo/

hf-space/ANTIGRAVITY_PROMPT.md

@@ -1,192 +0,0 @@
-# Accident Analysis Feature Implementation Prompt for Ollama
-
-**Implementation Model**: `qwen3-coder:30b` (ollama-spark-coding)
-
-**MCP Host**: `http://dgx-spark.tail16d8d9.ts.net:11434`
-
----
-
-## Quick Summary
-
-Implement a production-grade accident/crash analysis feature using two available toolkits:
-1. **CrashDataAnalyzer** (`crash_analyzer.py`) — SWITRS data analysis
-2. **DataExtractionPipeline** (`data_extractor.py`) — ETL for any source
-
-Build 6 layers: Ingestion → Validation → Cleaning → Analysis → Insights → API
-
----
-
-## Direct Prompt for qwen3-coder:30b
-
-Copy and submit to `qwen3-coder:30b` via Ollama MCP:
-
-```
-=== ACCIDENT ANALYSIS FEATURE - IMPLEMENTATION ===
-
-Build a production accident/crash analysis platform in Python 3.9+.
-
-AVAILABLE TOOLKITS (in repository):
-- crash_analyzer.py: CrashDataAnalyzer for SWITRS data analysis
-- data_extractor.py: DataExtractionPipeline, DataValidator, DataCleaner
-- Examples: example_crash_analysis.py, example_data_extraction.py
-
-BUILD 6 LAYERS (in order):
-
-LAYER 1: DATA INGESTION (accident_importer.py)
-- Class: AccidentDataImporter
-- Load from: CSV, APIs (paginated), SQL databases, JSON/Parquet
-- Auto-detect format, handle errors, standardize schema
-- Base: DataExtractionPipeline
-
-LAYER 2: DATA VALIDATION (accident_validator.py)
-- Class: AccidentDataValidator
-- Validate: required fields, types, coordinate ranges, date ranges
-- Detect: outliers, missing values, anomalies
-- Return: quality report with score
-- Base: DataValidator
-
-LAYER 3: DATA CLEANING (accident_cleaner.py)
-- Class: AccidentDataCleaner
-- Standardize: column names (snake_case), severity, vehicle types
-- Handle: missing values, duplicates, datetime, coordinates
-- Base: DataCleaner
-
-LAYER 4: ANALYSIS ENGINE (accident_analysis.py)
-- Classes: MetadataAnalyzer, GeospatialAnalyzer, DemographicsAnalyzer
-- Orchestrator: AccidentAnalysisEngine
-- Analyze: temporal patterns, hotspots, demographics
-- Cache results in memory
-- Base: CrashDataAnalyzer
-
-LAYER 5: INSIGHTS & REPORTING (accident_insights.py, accident_report.py)
-- AccidentInsights: deadliest times/places/groups, risk scores
-- AccidentReport: HTML/PDF/JSON export, visualizations
-
-LAYER 6: API & INTEGRATION (main.py, routes/, models/)
-- FastAPI endpoints:
-  POST /api/analyze (upload CSV)
-  GET /api/hotspots (geographic)
-  GET /api/insights (findings)
-  GET /api/report (download)
-  WebSocket /ws/stream (real-time)
-
-PRODUCTION REQUIREMENTS:
-✓ Complete working code (no TODOs)
-✓ Type hints on all functions
-✓ Google-style docstrings
-✓ Error handling (try/except with logging)
-✓ 80%+ test coverage (pytest)
-✓ Performance: <5s for 10k records
-✓ Security: input validation, SQL injection protection
-✓ Logging: DEBUG/INFO/ERROR/CRITICAL levels
-✓ Config: environment variables
-
-OUTPUT EACH LAYER:
-1. Complete working Python code
-2. Unit tests (pytest)
-3. Integration tests
-4. Full docstrings & type hints
-5. Error handling with examples
-6. Usage examples
-
-Start with LAYER 1. Use existing toolkits. Follow PEP 8.
-```
-
----
-
-## MCP Server Configuration
-
-```json
-{
-  "mcpServers": {
-    "ollama-spark-coding": {
-      "command": "npx",
-      "args": ["-y", "@iflow-mcp/ollama-mcp"],
-      "env": {
-        "OLLAMA_HOST": "http://dgx-spark.tail16d8d9.ts.net:11434",
-        "OLLAMA_MODEL": "qwen3-coder:30b"
-      }
-    }
-  }
-}
-```
-
----
-
-## Model Selection
-
-**Primary**: `qwen3-coder:30b` (code generation specialist)
-- Best for Python implementation across 6 layers
-- Understands complex architecture and APIs
-- Large context window for full specs
-
-**Optional**: `reasoning-core` (planning/validation)
-- Good for architecture review
-- Validates implementation decisions
-
-**Optional**: `gemma4:26b` (documentation)
-- Generate docs, examples, deployment guides
-
----
-
-## 6-Layer Architecture
-
-```
-Data Source (CSV/API/DB)
-        ↓
-LAYER 1: Data Ingestion
-        ↓
-LAYER 2: Data Validation (Quality Check)
-        ↓
-LAYER 3: Data Cleaning (Normalization)
-        ↓
-LAYER 4: Analysis Engine (Metadata/Geo/Demographics)
-        ↓
-LAYER 5: Insights & Reports (HTML/PDF/JSON)
-        ↓
-LAYER 6: REST API (FastAPI endpoints)
-```
-
----
-
-## Key Requirements
-
-- **Language**: Python 3.9+
-- **Framework**: FastAPI (API layer)
-- **Testing**: pytest (80%+ coverage)
-- **Data**: SWITRS format (accidents.csv, vehicles.csv, parties.csv)
-- **Performance**: <5 seconds for 10k records
-- **Code Quality**: Type hints, docstrings, error handling
-
----
-
-## Timeline
-
-- Layer 1 (Ingestion): 1-2 days
-- Layer 2 (Validation): 1 day
-- Layer 3 (Cleaning): 1 day
-- Layer 4 (Analysis): 2-3 days
-- Layer 5 (Insights): 1-2 days
-- Layer 6 (API): 2 days
-- Tests & Deployment: 2 days
-
-**Total**: 11-17 days
-
----
-
-## Success Criteria
-
-✅ Extract from 3+ sources (CSV, API, database)
-✅ Validate with >95% accuracy
-✅ Analyze temporal, geospatial, demographic patterns
-✅ Identify hotspots and high-risk groups
-✅ Generate HTML/PDF/JSON reports
-✅ Provide REST API
-✅ Support real-time analysis
-✅ Handle 1GB+ datasets
-✅ 80%+ test coverage
-✅ Production-ready code
-
----
-
-**Ready for Ollama Implementation**: qwen3-coder:30b

hf-space/ARCHITECTURE.md

@@ -1,78 +0,0 @@
-# Sensorflow Studio — Aggregate-First Evaluation Architecture (megaeval)
-
-The `sensorflow/megaeval/` layer replaces the "evaluation-record browser" model
-(annotation as the primary unit) with an **aggregate-first, risk-first,
-cohort-first, drill-down-on-demand** design.
-
-## Mental model → code
-
-| Concept | Meaning | Module / storage |
-| --- | --- | --- |
-| Dataset | immutable source population | `population.py` → `runs/megaeval/populations/{pop}/part-*.npz` |
-| Evaluation Run | model+config being evaluated (async job, first-class) | `runs.py` → `runs/megaeval/runs/{run}/run.json` |
-| Population | all objects evaluated in a run | headline row of the metric cube |
-| Cohort | slice by class/weather/lighting/road/scenario/sensor/distance/speed/occlusion | cube cells + `POST /api/evaluations/query` |
-| Container | scene/frame/segment holding related objects | `containers.npz` aggregate table |
-| Annotation | individual object — forensic view only | per-object `objects-part-*.npz`, loaded one partition at a time |
-
-## Data flow
-
-```
-generate population (vectorized numpy, partitioned npz)
-        │
-create run (queued) ──► worker pool (4 threads) processes partitions:
-        │                 model simulation → PARTIAL sufficient statistics
-        │                 (n, tp, fp, fn, sum_iou, conf sums, histograms …)
-        │                 grouped by the 9 cube dimensions, per partition
-        ▼
-reduce (concat + groupby-sum) ──► materialize METRIC CUBE (cube.npz)
-        │                          + error index, container table, sketches,
-        │                          container embeddings
-        ▼
-publish ──► queries served by QueryRouter: cache → cube → (rare) record scan
-```
-
-Aggregation **never** scans raw records at query time; queries like
-"pedestrian recall at night in rain for model v42" are cube lookups.
-
-## Single-node stand-ins for distributed infrastructure
-
-This repo runs on one laptop; the seams are shaped so each piece maps to the
-production-scale equivalent:
-
-| Here (single node) | Production analogue |
-| --- | --- |
-| npz column partitions (`part-0000.npz…`, hash-partitioned by container) | Parquet files in an Iceberg/Delta table, partitioned by scene |
-| `ThreadPoolExecutor` workers over partitions | Spark executors / Flink task slots |
-| partial stats per partition + `reduce_partials` | map-side combine + shuffle reduce |
-| `QueryRouter` (cache → cube → scan) with latency+source reporting | OLAP engine (Druid/Pinot/ClickHouse) over the lakehouse |
-| `QueryCache` keyed by hash(dataset+model+filters+group_by+metrics) | result cache / materialized views |
-| in-process SSE progress events | job-status topic (Kafka) + progress service |
-| numpy cosine similarity over container embeddings | vector DB (hybrid retrieval) |
-
-## Honesty rules encoded in the API
-
-- Cube counts and derived ratios are **exact** (`meta.exact = true`).
-- Percentiles/distributions come from fixed-bin quantile histograms;
-  cardinalities from HyperLogLog — always labeled approximate.
-- Precision/recall from human review are **sampling estimates with 95% CIs**
-  (stratified risk-weighted design: Wilson per stratum, weighted normal-approx
-  combination), reported with n reviewed / frame size / method.
-- Every query response reports `source` (cache/cube/scan), `cache_hit`,
-  and `latency_ms` so aggregate-first behavior is observable in the UI.
-- Evaluation runs are reproducible: lineage (dataset, model+checkpoint, label
-  version, evaluator code version, metric version, thresholds, sampling config,
-  seed, hardware) is stored on the run and derives the deterministic seed.
-
-## Performance SLOs (measured locally, 320k-object population, 67k cube cells)
-
-| Query | SLO | Measured |
-| --- | --- | --- |
-| aggregate dashboard (group by class) | < 2 s | ~75 ms |
-| filtered cohort query | < 3 s | ~350 ms first / sub-ms cached |
-| cached query | < 100 ms | ~0.1 ms |
-| object investigation (one container, forensic) | < 1 s | ~50–200 ms |
-
-The legacy `sensorflow/evaluation/` layer (label-evaluation pipeline, triage,
-HITL, training flywheel) remains unchanged; megaeval integrates with its
-regression tracker and alerting rather than duplicating them.

hf-space/CRASH_DATA_GUIDE.md

@@ -1,378 +0,0 @@
-# Crash Data Analysis Guide
-
-Complete guide to analyzing crash data with metadata, geospatial, and vehicle/traveler dimensions.
-
-## Quick Start
-
-```python
-from crash_analyzer import load_switrs_data
-
-# Load SWITRS CSV data
-analyzer = load_switrs_data('accidents.csv', 'vehicles.csv', 'parties.csv')
-
-# Generate full report
-report = analyzer.generate_summary_report()
-```
-
-## Data Source: SWITRS
-
-**Reference**: https://tims.berkeley.edu/help/crashdata/switrs-geocoding.php
-
-SWITRS (Statewide Integrated Traffic Records System) provides comprehensive California highway crash data with three main record types:
-
-### 1. Accidents Table (Core Records)
-Primary crash incident information.
-
-| Field | Type | Description | Example |
-|---|---|---|---|
-| `case_id` | int | Unique crash identifier | 123456 |
-| `accident_date` | date | Date of crash | 2024-01-15 |
-| `accident_time` | time | Time of crash (24-hr) | 14:30 |
-| `latitude` | float | Geocoded latitude | 37.7749 |
-| `longitude` | float | Geocoded longitude | -122.4194 |
-| `county` | string | County name | "San Francisco" |
-| `district` | string | CHP district | "SF" |
-| `severity` | string | Crash severity | F/I/P (Fatal/Injury/PropertyDamage) |
-| `collision_type` | string | Type of collision | "Rear End", "Broadside", etc. |
-| `weather_1` | string | Primary weather | "Clear", "Rain", "Fog" |
-| `weather_2` | string | Secondary weather | Optional |
-| `surface_condition` | string | Road surface | "Dry", "Wet", "Snow" |
-| `traffic_control_device` | string | Traffic control status | "Functioning", "Not Functioning" |
-| `fatality_count` | int | Number of fatalities | 0-5 |
-| `injury_count` | int | Number of injuries | 0-10 |
-
-### 2. Vehicles Table (Vehicle Details)
-Vehicle information for each crash.
-
-| Field | Type | Description |
-|---|---|---|
-| `case_id` | int | Link to accidents table |
-| `vehicle_id` | int | Unique vehicle in crash |
-| `vehicle_type` | string | Car, Truck, Motorcycle, SUV, Van, etc. |
-| `vehicle_year` | int | Vehicle model year |
-| `vehicle_make` | string | Manufacturer (Toyota, Ford, etc.) |
-| `vehicle_model` | string | Model name |
-| `vehicle_color` | string | Color |
-| `damage_extent` | string | Severe, Moderate, Minor |
-| `direction_of_travel` | string | N, S, E, W, etc. |
-
-### 3. Parties Table (Occupants & Pedestrians)
-Information about crash participants (drivers, passengers, pedestrians).
-
-| Field | Type | Description |
-|---|---|---|
-| `case_id` | int | Link to accidents table |
-| `party_number` | int | Sequence in crash |
-| `party_type` | string | Driver, Passenger, Pedestrian, Cyclist |
-| `age` | int | Age in years | 
-| `gender` | string | M/F |
-| `sobriety` | int | 1=Sober, 2=Drinking, 3=Intoxicated, 4=Unknown |
-| `injury_level` | int | 0=None, 1=Possible, 2=Probable, 3=Severe, 4=Fatal |
-| `safety_equipment_used` | string | Seatbelt, Helmet, etc. |
-| `ejection` | string | Yes/No/Unknown |
-| `primary_collision_factor` | string | Cause (Speeding, DUI, etc.) |
-
----
-
-## Analysis Dimensions
-
-### 1. METADATA ANALYSIS
-
-**Time-Based Patterns**
-```python
-# Identify dangerous times
-temporal = analyzer.analyze_temporal_patterns()
-# Returns: crashes by hour, day, month, year + deadliest times
-```
-
-**What to Look For**:
-- Rush hour peaks (7-9am, 4-6pm)
-- Weekend spikes
-- Holiday effect (New Year, July 4th)
-- Seasonal trends (winter weather, spring break)
-
-**Severity Analysis**
-```python
-severity = analyzer.analyze_severity()
-# Returns: distribution of Fatal/Injury/Property Damage
-```
-
-**What to Report**:
-- Fatality rate (total deaths / total crashes)
-- Injury-to-crash ratio
-- Crash trend over time (increasing/decreasing)
-
-**Collision Types**
-```python
-collisions = analyzer.analyze_collision_types()
-# Returns: most common collision types and deadliest types
-```
-
-**Key Metrics**:
-- Most common collision type
-- Deadliest collision type (by fatality rate)
-- Preventable vs. unpreventable patterns
-
----
-
-### 2. GEOSPATIAL ANALYSIS
-
-**Geographic Summaries**
-```python
-geo = analyzer.get_geographic_summary()
-# Returns: crashes by county/district with severity breakdown
-```
-
-**Geographic Hotspot Detection**
-```python
-hotspots = analyzer.identify_hotspots()
-# Returns: grid-based clustering of high-crash areas
-```
-
-**Interpretation**:
-- Cluster size = grid cell crashes
-- Coordinates = center of high-risk area
-- Fatal count = number of fatal crashes in area
-- Focus enforcement/infrastructure improvements on hotspots
-
-**Use Cases**:
-- Identify intersections needing traffic signal upgrades
-- Plan emergency response deployments
-- Target enforcement activities
-- Prioritize road maintenance
-
-**Visualization Recommendations**:
-- Heatmap of crash density (Folium, Kepler.gl)
-- Cluster markers on interactive map
-- Severity overlay (color-coded pins)
-- Temporal animation (crashes by month)
-
----
-
-### 3. VEHICLE/TRAVELER ANALYSIS
-
-**Vehicle Risk Analysis**
-```python
-vehicles_analysis = analyzer.analyze_vehicle_types()
-# Returns: crashes per vehicle type + fatality rates
-```
-
-**Insights**:
-- Which vehicle types are overrepresented in crashes?
-- Which have highest fatality rates?
-- Older vs. newer vehicles
-- Motorcycle vs. car comparison
-
-**Traveler Demographics**
-```python
-demographics = analyzer.analyze_demographics()
-# Returns: age distribution, gender, sobriety, injury levels
-```
-
-**Key Demographics**:
-- Age group risk (teenagers, elderly highest risk)
-- Gender patterns
-- Impairment prevalence
-- Safety equipment usage (seatbelt, helmet)
-
-**Injury Patterns**
-```python
-injuries = analyzer.analyze_injury_patterns()
-# Returns: injury severity by age group, party type
-```
-
-**Focus Areas**:
-- Vulnerable road users (pedestrians, cyclists)
-- Age-specific injury severity
-- Occupant vs. pedestrian injury rates
-- Effectiveness of safety equipment
-
----
-
-## Data Preparation
-
-### Step 1: Obtain SWITRS Data
-Options:
-- **TIMS Website**: https://tims.berkeley.edu (public access, some limitations)
-- **California Highway Patrol**: Direct request
-- **Local Law Enforcement**: May have county-specific data
-
-### Step 2: Data Format
-- Expected format: **CSV files** (one file per table type)
-- Delimiter: Comma (`,`)
-- Character encoding: UTF-8
-- Missing values: Blank or `NULL`
-
-### Step 3: Clean Data
-```python
-import pandas as pd
-
-accidents = pd.read_csv('accidents.csv')
-
-# Remove duplicates
-accidents = accidents.drop_duplicates(subset=['case_id'])
-
-# Handle missing geolocation
-accidents = accidents.dropna(subset=['latitude', 'longitude'])
-
-# Validate date format
-accidents['accident_date'] = pd.to_datetime(accidents['accident_date'], errors='coerce')
-```
-
-### Step 4: Load into Analyzer
-```python
-from crash_analyzer import CrashDataAnalyzer
-
-analyzer = CrashDataAnalyzer(accidents, vehicles, parties)
-```
-
----
-
-## Common Analyses
-
-### Find Most Dangerous Intersections
-```python
-hotspots = analyzer.identify_hotspots(grid_size=0.005)  # ~500m cells
-# Focus on grid cells with >10 crashes
-```
-
-### Compare Age Groups
-```python
-demographics = analyzer.analyze_demographics()
-# Look for age groups with highest injury rates
-```
-
-### Identify Impairment Patterns
-```python
-# Filter parties where sobriety == 3 (intoxicated)
-impaired_crashes = analyzer.parties[analyzer.parties['sobriety'] == 3]
-# Analyze time of day, day of week, location
-```
-
-### Seasonal Trends
-```python
-temporal = analyzer.analyze_temporal_patterns()
-# Compare summer vs. winter crash counts
-```
-
-### Vehicle Type Safety
-```python
-vehicles = analyzer.analyze_vehicle_types()
-# Motorcycle fatality rate vs. car fatality rate
-```
-
----
-
-## Visualization Examples
-
-### 1. Time Series: Crashes by Hour
-```python
-import matplotlib.pyplot as plt
-
-hourly = analyzer.accidents.groupby('hour').size()
-plt.bar(hourly.index, hourly.values)
-plt.xlabel('Hour of Day')
-plt.ylabel('Number of Crashes')
-plt.title('Crashes by Hour of Day')
-```
-
-### 2. Geographic Hotmap (Folium)
-```python
-import folium
-
-m = folium.Map(location=[37.0, -120.0], zoom_start=6)
-
-for hotspot in analyzer.identify_hotspots():
-    folium.CircleMarker(
-        location=[hotspot['center_lat'], hotspot['center_lon']],
-        radius=5 + hotspot['crash_count'] / 10,
-        color='red' if hotspot['fatal_count'] > 0 else 'orange',
-        popup=f"{hotspot['crash_count']} crashes"
-    ).add_to(m)
-
-m.save('hotspots_map.html')
-```
-
-### 3. Vehicle Risk Comparison (Plotly)
-```python
-import plotly.express as px
-
-vehicle_risk = analyzer.analyze_vehicle_types()['vehicle_risk_analysis']
-df = pd.DataFrame(vehicle_risk).T
-
-px.bar(df, y='fatality_rate', title='Fatality Rate by Vehicle Type').show()
-```
-
-### 4. Age Demographics (Seaborn)
-```python
-import seaborn as sns
-
-sns.histplot(analyzer.parties, x='age', hue='injury_level', kde=True)
-plt.title('Injury Severity by Age')
-```
-
----
-
-## Key Metrics to Track
-
-| Metric | Formula | Interpretation |
-|---|---|---|
-| Fatality Rate | Fatal Crashes / Total Crashes | Higher = more dangerous |
-| Injury Rate | Injury Crashes / Total Crashes | Focus on prevention |
-| Fatality per Crash | Total Fatalities / Total Crashes | Severity measure |
-| Peak Hour | Hour with most crashes | Traffic management |
-| Hotspot Density | Crashes per sq km | Infrastructure need |
-| Demographics Risk | Deaths / Population Group | Target safety programs |
-
----
-
-## API Reference
-
-### CrashDataAnalyzer Methods
-
-```python
-class CrashDataAnalyzer:
-    # Metadata
-    analyze_temporal_patterns() -> Dict
-    analyze_severity() -> Dict
-    analyze_collision_types() -> Dict
-    
-    # Geospatial
-    get_geographic_summary() -> Dict
-    identify_hotspots(lat_col, lon_col, grid_size) -> List[Dict]
-    
-    # Vehicle/Traveler
-    analyze_vehicle_types() -> Dict
-    analyze_demographics() -> Dict
-    analyze_injury_patterns() -> Dict
-    
-    # Combined
-    generate_summary_report() -> Dict
-```
-
----
-
-## Tips for Analysis
-
-✅ **Do**:
-- Start with summary statistics before deep dives
-- Validate data quality before conclusions
-- Cross-reference multiple data sources
-- Account for population denominators (risk per capita)
-- Visualize before presenting findings
-
-❌ **Don't**:
-- Confuse correlation with causation
-- Ignore data quality issues
-- Over-interpret small sample sizes
-- Make policy recommendations without context
-- Ignore survivor bias in injury data
-
----
-
-## Resources
-
-- **TIMS**: https://tims.berkeley.edu/
-- **SWITRS Documentation**: https://tims.berkeley.edu/help/crashdata/switrs-geocoding.php
-- **Berkeley Safe Transportation Research & Education Center**: https://safetrec.berkeley.edu
-- **CHP Statewide Integrated Traffic Records System**: https://www.chp.ca.gov/

hf-space/DASHBOARD_README.md

@@ -1,393 +0,0 @@
-# Comparative Analytics Dashboard
-
-Production-grade comparative analytics system for evaluating and comparing multiple ML techniques, configurations, and models across datasets with rich visualizations and comprehensive reporting.
-
-## 🎯 Goal
-
-Design and implement a comparative analytics dashboard that compares the performance of multiple techniques and configurations across chosen datasets and models.
-
-**Requirements Met**:
-✅ Compare all selected techniques and configurations
-✅ Display results for each dataset and model combination
-✅ Include key evaluation metrics (accuracy, precision, recall, F1-score, AUC, inference time, memory, etc.)
-✅ Support filtering by dataset, model, technique, and configuration
-✅ Enable side-by-side comparisons through tables and visualizations
-✅ Highlight best-performing configurations
-✅ Provide summary statistics and rankings
-
-## 📊 Features
-
-### Core Analytics
-- **Multi-Technique Comparison** — Compare all techniques side-by-side with statistics
-- **Multi-Configuration Analysis** — Evaluate different configurations for each technique
-- **Multi-Metric Evaluation** — Support 9+ metrics (accuracy, F1, AUC, timing, memory)
-- **Advanced Filtering** — Filter by any combination of dataset/model/technique/configuration
-- **Best-Performer Detection** — Automatically identify optimal configurations
-- **Summary Statistics** — Mean, std, min, max, median, count per group
-- **Technique Rankings** — Overall rankings with win rates and performance data
-
-### Visualizations (Planned)
-- 📊 **Bar Charts** — Technique/configuration comparison by metric
-- 🔥 **Heatmaps** — Dataset × Technique × Metric matrices
-- 📈 **Scatter Plots** — Two-metric trade-off visualization
-- 🎯 **Pareto Frontier** — Optimal trade-off curves
-- 📉 **Line Charts** — Temporal trends across experiments
-- 🔀 **Subplots** — Multi-metric side-by-side comparison
-
-### Export & Reporting
-- 📄 **HTML Reports** — Interactive reports with all visualizations
-- 📋 **JSON Export** — Machine-readable results
-- 📊 **DataFrame Export** — Pandas integration
-- 🌐 **REST API** — FastAPI backend for dashboards
-
-## 📁 Components
-
-```
-comparative_analytics.py
-├── ComparativeAnalytics          # Main analytics engine
-├── Configuration                 # Technique + parameters
-├── PerformanceMetrics            # 9+ evaluation metrics
-├── ExperimentResult              # Single experiment
-└── DashboardBuilder              # Analysis & aggregation
-
-test_dashboard.py                 # Working example
-```
-
-## 🚀 Quick Start
-
-### 1. Add Results
-
-```python
-from comparative_analytics import (
-    ComparativeAnalytics,
-    Configuration,
-    PerformanceMetrics,
-    ExperimentResult
-)
-
-analytics = ComparativeAnalytics()
-
-config = Configuration(
-    config_id='cfg_1',
-    name='Config A',
-    technique='Technique_1',
-    parameters={'param_a': 0.1}
-)
-
-metrics = PerformanceMetrics(
-    accuracy=0.92,
-    f1_score=0.89,
-    inference_time=0.05,
-    memory_usage=256,
-    auc=0.95
-)
-
-result = ExperimentResult(
-    dataset='Dataset_A',
-    model='Model_X',
-    configuration=config,
-    metrics=metrics
-)
-
-analytics.add_result(result)
-```
-
-### 2. Analyze Results
-
-```python
-# Get best configurations
-best = analytics.get_best_configurations(
-    metric='f1_score',
-    dataset='Dataset_A',
-    top_n=5
-)
-
-# Compare techniques
-comparison = analytics.compare_techniques(
-    metric='f1_score',
-    dataset='Dataset_A'
-)
-
-# Get summary statistics
-stats = analytics.get_summary_statistics(
-    metric='f1_score',
-    groupby='technique'
-)
-
-# Create DataFrame
-df = analytics.to_dataframe()
-```
-
-### 3. Filter Data
-
-```python
-# Single criterion
-results = analytics.filter_results(datasets=['Dataset_A'])
-
-# Multiple criteria
-results = analytics.filter_results(
-    datasets=['Dataset_A', 'Dataset_B'],
-    techniques=['Technique_1'],
-    models=['Model_X']
-)
-
-# Convert to DataFrame
-df = analytics.to_dataframe(datasets=['Dataset_A'])
-```
-
-## 📈 Supported Metrics
-
-| Metric | Type | Use |
-|--------|------|-----|
-| Accuracy | Classification | Overall correctness |
-| Precision | Classification | False positive rate |
-| Recall | Classification | False negative rate |
-| F1-Score | Classification | Harmonic mean |
-| AUC | Classification | Ranking quality |
-| Inference Time | Performance | Latency per prediction |
-| Memory Usage | Performance | RAM consumption |
-| Training Time | Performance | Model training duration |
-| Throughput | Performance | Samples/second |
-| Latency | Performance | Response time (ms) |
-
-## 🔍 Key Methods
-
-### ComparativeAnalytics
-```python
-analytics.add_result(result)                    # Add single result
-analytics.add_results_batch(results)            # Add multiple results
-analytics.filter_results(...)                   # Filter by criteria
-analytics.to_dataframe(...)                     # Convert to DataFrame
-analytics.get_best_configurations(...)          # Top N configurations
-analytics.compare_techniques(...)               # Compare by technique
-analytics.compare_configurations(...)           # Compare by configuration
-analytics.get_dataset_model_matrix(...)         # Performance matrix
-analytics.get_summary_statistics(...)           # Summary stats
-analytics.get_metric_correlation()              # Metric correlations
-```
-
-### Filtering Examples
-```python
-# By dataset
-results = analytics.filter_results(datasets=['Dataset_A'])
-
-# By model
-results = analytics.filter_results(models=['Model_X', 'Model_Y'])
-
-# By technique
-results = analytics.filter_results(techniques=['Technique_1'])
-
-# By configuration
-results = analytics.filter_results(configurations=['cfg_1', 'cfg_2'])
-
-# Multiple criteria (AND logic)
-results = analytics.filter_results(
-    datasets=['Dataset_A'],
-    techniques=['Technique_1'],
-    models=['Model_X']
-)
-```
-
-## 📊 Analysis Examples
-
-### Best Configurations
-```python
-# Top 5 overall
-best = analytics.get_best_configurations(metric='f1_score', top_n=5)
-
-# Top 3 for specific dataset
-best = analytics.get_best_configurations(
-    metric='f1_score',
-    dataset='Dataset_A',
-    top_n=3
-)
-
-# Top 3 for specific model
-best = analytics.get_best_configurations(
-    metric='f1_score',
-    model='Model_X',
-    top_n=3
-)
-```
-
-### Technique Comparison
-```python
-# Overall comparison
-comp = analytics.compare_techniques(metric='f1_score')
-# Returns: mean, std, min, max, count per technique
-
-# For specific dataset
-comp = analytics.compare_techniques(
-    metric='f1_score',
-    dataset='Dataset_A'
-)
-```
-
-### Performance Matrices
-```python
-# Dataset × Model
-matrix = analytics.get_dataset_model_matrix(metric='f1_score')
-# Returns: DataFrame with datasets as rows, models as columns
-
-# Shows: Average F1-Score for each dataset-model combination
-```
-
-### Summary Statistics
-```python
-# By technique
-stats = analytics.get_summary_statistics(
-    metric='f1_score',
-    groupby='technique'
-)
-# Returns: {technique: {mean, std, min, max, median, count}}
-
-# By dataset
-stats = analytics.get_summary_statistics(
-    metric='accuracy',
-    groupby='dataset'
-)
-```
-
-## 🧪 Testing
-
-Run the example test:
-```bash
-python test_dashboard.py
-```
-
-Expected output:
-```
-✓ ComparativeAnalytics created
-✓ Added 24 experiment results
-✓ Created DataFrame
-✓ Top 3 configurations by F1-Score
-✓ Technique Comparison
-✓ Summary Statistics
-✓ Dataset × Model Matrix
-✅ All tests passed!
-```
-
-## 📦 Dependencies
-
-### Required
-```
-pandas>=1.3.0
-numpy>=1.21.0
-```
-
-### Optional (for visualizations)
-```
-plotly>=5.0.0      # Interactive charts
-fastapi>=0.68.0    # REST API
-uvicorn>=0.15.0    # ASGI server
-matplotlib>=3.4.0  # Static plots
-```
-
-Install:
-```bash
-pip install pandas numpy plotly fastapi uvicorn matplotlib
-```
-
-## 📋 Comparison Table Example
-
-```
-      dataset    model    technique  f1_score accuracy inference_time
-15  Dataset_B  Model_X  Technique_2  0.801029  0.82    0.05
- 9  Dataset_A  Model_Y  Technique_2  0.790573  0.80    0.06
-18  Dataset_B  Model_Y  Technique_1  0.764297  0.78    0.07
-```
-
-## 🎯 Next Steps
-
-The following components are planned and ready for implementation:
-
-1. **Visualization Layer** (dashboard.py)
-   - Bar charts (Plotly)
-   - Heatmaps
-   - Scatter plots
-   - Pareto frontier
-   - Temporal trends
-
-2. **REST API** (DashboardServer)
-   - `/api/comparison/bar`
-   - `/api/comparison/heatmap`
-   - `/api/filters`
-   - `/api/summary`
-   - `/api/export/html`
-   - `/api/export/json`
-
-3. **Report Generation**
-   - Interactive HTML reports
-   - Summary statistics tables
-   - Performance rankings
-   - Best configuration highlights
-
-4. **Advanced Analysis**
-   - Pareto frontier detection
-   - Trade-off analysis
-   - Correlation matrices
-   - Anomaly detection
-
-## 🏗️ Architecture
-
-```
-Experiment Results
-        ↓
-ComparativeAnalytics (filter, organize, aggregate)
-        ↓
-DashboardBuilder (compute statistics)
-        ↓
-InteractiveDashboard (visualize)
-        ↓
-HTML Reports / REST API / JSON
-```
-
-## 💡 Design Philosophy
-
-- **Simple to Extend** — Add new metrics or techniques without code changes
-- **Flexible Filtering** — Any combination of dimensions
-- **Production Ready** — Type hints, error handling, comprehensive testing
-- **Standards-Based** — DataFrames for pandas integration, JSON for exchange
-- **Visualization Agnostic** — Works with plotly, matplotlib, seaborn
-
-## 📚 Examples
-
-See `test_dashboard.py` for working example with:
-- Creating analytics engine
-- Generating sample results
-- Filtering and grouping
-- Computing statistics
-- Comparing techniques
-- Creating matrices
-
-## 🔄 Data Flow
-
-1. Create `ExperimentResult` objects with metrics
-2. Add to `ComparativeAnalytics` via `add_result()` or `add_results_batch()`
-3. Filter using `filter_results()` or `to_dataframe()`
-4. Analyze using `compare_*()` methods
-5. Export via JSON/DataFrame/HTML
-
-## ✅ Status
-
-- ✅ Core analytics engine
-- ✅ Filtering and grouping
-- ✅ Statistics computation
-- ✅ Best configuration detection
-- ✅ Ranking and comparison
-- 🔄 Visualization layer (in progress)
-- 🔄 REST API server (in progress)
-- 🔄 HTML report generation (in progress)
-
-## 📖 Documentation
-
-Full documentation available in:
-- `COMPARATIVE_DASHBOARD_GUIDE.md` (detailed reference)
-- `test_dashboard.py` (working examples)
-- Code docstrings (API documentation)
-
----
-
-**Version**: 1.0 (Core Engine)  
-**Status**: Production Ready  
-**Last Updated**: 2026-07-26

hf-space/DATA_EXTRACTION_QUICK_REF.md

@@ -1,348 +0,0 @@
-# Data Extraction Toolkit — Quick Reference
-
-## One-Liner Pipeline
-```python
-from data_extractor import DataExtractionPipeline
-DataExtractionPipeline('Data').extract('input.csv').validate({'required_columns': ['id']}).transform({'standardize_names': {}}).export('output.csv')
-```
-
----
-
-## Extract from Source
-
-### CSV
-```python
-from data_extractor import FileExtractor
-df = FileExtractor.extract_csv('file.csv')
-```
-
-### JSON
-```python
-df = FileExtractor.extract_json('file.json')
-df = FileExtractor.extract_jsonl('file.jsonl')
-```
-
-### Excel
-```python
-df = FileExtractor.extract_excel('file.xlsx', sheet_name=0)
-```
-
-### Parquet
-```python
-df = FileExtractor.extract_parquet('file.parquet')
-```
-
-### API
-```python
-from data_extractor import APIExtractor
-api = APIExtractor('https://api.example.com')
-df = api.fetch_paginated('/data', params={'limit': 100})
-```
-
-### Database
-```python
-from data_extractor import DatabaseExtractor
-db = DatabaseExtractor('postgresql://user:pass@localhost/db')
-df = db.query_to_dataframe('SELECT * FROM table')
-```
-
-### Batch (Multiple Files)
-```python
-df = FileExtractor.batch_extract('data/*.csv', filetype='csv')
-```
-
----
-
-## Validate Data
-
-```python
-from data_extractor import DataValidator
-validator = DataValidator(df)
-
-# Required columns
-validator.validate_required_columns(['id', 'name'])
-
-# No nulls
-validator.validate_no_nulls(['id'])
-
-# Data types
-validator.validate_data_types({'age': 'int', 'date': 'datetime64'})
-
-# Unique values
-validator.validate_unique(['email'])
-
-# Value range
-validator.validate_value_range('age', min_val=0, max_val=150)
-
-# Get report
-report = validator.get_report()
-print(f"Valid: {report.valid}, Errors: {report.errors}")
-```
-
----
-
-## Transform Data
-
-```python
-from data_extractor import DataCleaner
-cleaner = DataCleaner()
-
-# Remove duplicates
-df = cleaner.remove_duplicates(df, subset=['id'])
-
-# Standardize column names
-df = cleaner.standardize_column_names(df)
-
-# Trim whitespace
-df = cleaner.trim_whitespace(df)
-
-# Handle missing values
-df = cleaner.handle_missing_values(df, strategy='drop')
-
-# Convert types
-df = cleaner.convert_dtypes(df, {'date': 'date', 'amount': 'float'})
-```
-
----
-
-## Export Data
-
-```python
-from data_extractor import DataExporter
-exporter = DataExporter(df)
-
-exporter.to_csv('output.csv')
-exporter.to_json('output.json', orient='records')
-exporter.to_parquet('output.parquet')  # Smallest file size
-exporter.to_excel('output.xlsx', sheet_name='Data')
-exporter.to_dict_list()  # List of dictionaries
-```
-
----
-
-## Complete Pipeline
-
-```python
-from data_extractor import DataExtractionPipeline
-
-pipeline = DataExtractionPipeline('MyProject')
-
-# Step 1: Extract
-pipeline.extract('input.csv', source_type='csv')
-
-# Step 2: Validate
-pipeline.validate({
-    'required_columns': ['id', 'name'],
-    'no_nulls': ['id'],
-    'data_types': {'age': 'int'}
-})
-
-# Step 3: Transform
-pipeline.transform({
-    'remove_duplicates': {},
-    'standardize_names': {},
-    'trim_whitespace': {}
-})
-
-# Step 4: Export
-pipeline.export('output.csv', format='csv')
-
-# View summary
-print(pipeline.get_summary())
-```
-
----
-
-## Chained Pipeline
-
-```python
-DataExtractionPipeline('MyData') \
-    .extract('input.csv') \
-    .validate({'required_columns': ['id']}) \
-    .transform({'standardize_names': {}}) \
-    .export('output.csv')
-```
-
----
-
-## Source Types
-
-| Type | Use | Example |
-|------|-----|---------|
-| `csv` | CSV files | `data.csv` |
-| `json` | JSON | `data.json` |
-| `jsonl` | JSON Lines | `data.jsonl` |
-| `excel` | Excel | `data.xlsx` |
-| `parquet` | Parquet | `data.parquet` |
-| `database` | SQL DB | `postgresql://...` |
-| `api` | REST API | `https://api.example.com` |
-| `web` | HTML table | `https://example.com` |
-| `batch` | Multiple files | `data/*.csv` |
-
----
-
-## Export Formats
-
-| Format | Best For | Speed | Size |
-|--------|----------|-------|------|
-| CSV | Excel, sharing | Fast | Large |
-| JSON | APIs, web | Medium | Large |
-| Parquet | Big data | Very fast | Small |
-| Excel | Business | Slow | Medium |
-
----
-
-## Validation Rules
-
-```python
-# Check columns exist
-'required_columns': ['id', 'name']
-
-# Check no nulls
-'no_nulls': ['id', 'email']
-
-# Check types
-'data_types': {'age': 'int', 'salary': 'float'}
-
-# Check unique
-'unique': ['email', 'username']
-
-# Check range
-'value_range': {'age': (0, 150)}
-```
-
----
-
-## Transform Operations
-
-```python
-# Remove duplicate rows
-'remove_duplicates': {}
-'remove_duplicates': {'subset': ['id']}
-
-# Standardize column names (snake_case)
-'standardize_names': {}
-
-# Trim whitespace
-'trim_whitespace': {}
-'trim_whitespace': {'columns': ['name']}
-
-# Handle missing values
-'handle_missing': {'strategy': 'drop'}  # or 'fill', 'forward', 'backward'
-
-# Convert data types
-'convert_types': {'date': 'date', 'amount': 'float'}
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Clean CSV
-```python
-DataExtractionPipeline('Clean') \
-    .extract('raw.csv') \
-    .validate({'required_columns': ['id']}) \
-    .transform({'remove_duplicates': {}, 'standardize_names': {}}) \
-    .export('clean.csv')
-```
-
-### Pattern 2: API to CSV
-```python
-DataExtractionPipeline('API') \
-    .extract('https://api.example.com', source_type='api', 
-             endpoint='/data', params={'limit': 100}) \
-    .validate({'no_nulls': ['id']}) \
-    .export('api_data.csv')
-```
-
-### Pattern 3: Combine Files
-```python
-DataExtractionPipeline('Combine') \
-    .extract('data/*.csv', source_type='batch', filetype='csv') \
-    .validate({'unique': ['id']}) \
-    .export('combined.csv')
-```
-
-### Pattern 4: Database to Parquet
-```python
-DataExtractionPipeline('DB') \
-    .extract('postgresql://user:pass@host/db', source_type='database',
-             sql_query='SELECT * FROM table') \
-    .validate({'no_nulls': ['id']}) \
-    .transform({'convert_types': {'amount': 'float'}}) \
-    .export('data.parquet', format='parquet')
-```
-
----
-
-## Error Handling
-
-```python
-try:
-    pipeline.extract('file.csv') \
-            .validate({'required_columns': ['id']}) \
-            .export('output.csv')
-except Exception as e:
-    print(f"Error: {e}")
-    print(f"Data: {pipeline.data.head()}")
-```
-
----
-
-## Debugging
-
-```python
-# Check columns
-print(df.columns)
-
-# Check data types
-print(df.dtypes)
-
-# Check first rows
-print(df.head())
-
-# Check nulls
-print(df.isnull().sum())
-
-# Check shape
-print(f"Rows: {len(df)}, Columns: {len(df.columns)}")
-```
-
----
-
-## Performance
-
-| Scenario | Action |
-|----------|--------|
-| Large CSV | Use Parquet format export |
-| Many files | Use batch extraction |
-| Slow API | Use `fetch_with_retry()` |
-| Memory issues | Use `chunked_extract()` |
-
----
-
-## Dependencies
-
-```bash
-pip install pandas requests
-pip install openpyxl          # Excel
-pip install pyarrow            # Parquet
-pip install sqlalchemy         # Database
-```
-
----
-
-## Files
-
-```
-Skill:      .claude/skills/data-extraction-toolkit.md
-Module:     data_extractor.py
-Examples:   example_data_extraction.py
-Guide:      DATA_EXTRACTION_GUIDE.md
-README:     DATA_EXTRACTION_TOOLKIT_README.md
-```
-
----
-
-**Print this page for quick reference!**

hf-space/Dockerfile

@@ -1,51 +0,0 @@
-# Sensorflow Studio — Hugging Face Spaces (Docker SDK) image.
-# Multi-stage: build the React frontend, then assemble a slim Python runtime.
-# The frontend is built INSIDE the image so deploys only need repo files.
-
-# ---------- Stage 1: frontend build ----------
-FROM node:22-alpine AS frontend
-WORKDIR /build
-
-# Lockfile may or may not exist / be in sync mid-refactor; fall back gracefully.
-COPY package.json package-lock.json* ./
-RUN npm ci || npm install
-
-COPY index.html vite.config.ts tsconfig.json ./
-COPY src ./src
-# The React app is served at /dashboard/ (root is taken by the legacy static UI),
-# so asset URLs must be built with that base. vite.config.ts must not be edited,
-# hence the --base flag here.
-RUN npx vite build --base=/dashboard/
-
-# ---------- Stage 2: Python runtime ----------
-FROM python:3.12-slim AS runtime
-
-ENV PYTHONUNBUFFERED=1 \
-    PORT=7860 \
-    HF_HOME=/app/.cache
-
-WORKDIR /app
-
-# Slim dependency set: heavy GPU/vision deps (torch, ultralytics, opencv) are
-# lazily imported by app_backend routes and are NOT needed at import time.
-COPY deploy/huggingface/requirements-space.txt ./requirements-space.txt
-RUN pip install --no-cache-dir -r requirements-space.txt
-
-# Backend code + assets (filtered by .dockerignore: no node_modules, .venv,
-# runs/, *.pt, models/, dist/, .git).
-COPY . .
-
-# Built React app from stage 1.
-COPY --from=frontend /build/dist ./dist
-
-# HF Spaces runs the container as uid 1000; the app writes runtime files
-# (runs/studio_config.json, ssam_streets.json, ...) relative to the workdir,
-# so /app must be writable by that user.
-RUN useradd -m -u 1000 user && chown -R user:user /app
-USER user
-
-EXPOSE 7860
-
-# app_backend.py's own __main__ block uses 127.0.0.1:8000 and must not be
-# edited; space_app wraps it and adds the /dashboard mount for the React build.
-CMD ["uvicorn", "space_app:app", "--host", "0.0.0.0", "--port", "7860"]

hf-space/FILES_CREATED.txt

@@ -1,135 +0,0 @@
-================================================================================
-DATA EXTRACTION & CRASH ANALYSIS TOOLKITS - FILES CREATED
-================================================================================
-
-SKILL FILES (Use in Claude Code)
-================================================================================
-.claude/skills/crash-data-analyzer.md              (6.5 KB)
-.claude/skills/data-extraction-toolkit.md          (12.8 KB)
-
-PYTHON MODULES (Import & use in code)
-================================================================================
-crash_analyzer.py                                  (8.2 KB)
-data_extractor.py                                  (15.4 KB)
-
-EXAMPLE SCRIPTS (Run to see toolkit in action)
-================================================================================
-example_crash_analysis.py                          (6.1 KB)
-example_data_extraction.py                         (9.3 KB)
-
-DOCUMENTATION - CRASH ANALYSIS
-================================================================================
-CRASH_ANALYSIS_README.md                           (11.2 KB)
-CRASH_DATA_GUIDE.md                                (18.5 KB)
-CRASH_ANALYSIS_QUICK_REF.md                        (2.8 KB)
-
-DOCUMENTATION - DATA EXTRACTION
-================================================================================
-DATA_EXTRACTION_TOOLKIT_README.md                  (13.4 KB)
-DATA_EXTRACTION_GUIDE.md                           (22.1 KB)
-DATA_EXTRACTION_QUICK_REF.md                       (3.2 KB)
-
-SUMMARY & NAVIGATION
-================================================================================
-TOOLKIT_SUMMARY.md                                 (7.9 KB)
-FILES_CREATED.txt                                  (This file)
-
-================================================================================
-TOTAL: 18 files, ~137 KB of code and documentation
-================================================================================
-
-QUICK START GUIDE
-================================================================================
-
-For Crash Data Analysis:
-  1. Read:    CRASH_ANALYSIS_README.md
-  2. Run:     python example_crash_analysis.py
-  3. Code:    from crash_analyzer import load_switrs_data
-  4. Claude:  /crash-data-analyzer
-
-For Data Extraction:
-  1. Read:    DATA_EXTRACTION_TOOLKIT_README.md
-  2. Run:     python example_data_extraction.py
-  3. Code:    from data_extractor import DataExtractionPipeline
-  4. Claude:  /data-extraction-toolkit
-
-================================================================================
-
-KEY FEATURES
-================================================================================
-
-CRASH ANALYZER:
-  ✓ Analyze crash data (SWITRS format)
-  ✓ Metadata analysis (temporal patterns, severity)
-  ✓ Geospatial analysis (hotspots, location analysis)
-  ✓ Vehicle/traveler analysis (demographics, risk)
-  ✓ Generate comprehensive reports
-
-DATA EXTRACTION TOOLKIT:
-  ✓ Extract from 8+ sources (CSV, JSON, APIs, databases, web)
-  ✓ Validate data quality
-  ✓ Transform and clean data
-  ✓ Export in multiple formats (CSV, JSON, Parquet, Excel)
-  ✓ Complete ETL pipeline
-
-================================================================================
-
-USAGE EXAMPLES
-================================================================================
-
-CRASH ANALYSIS:
-  from crash_analyzer import load_switrs_data
-  analyzer = load_switrs_data('accidents.csv', 'vehicles.csv', 'parties.csv')
-  report = analyzer.generate_summary_report()
-
-DATA EXTRACTION:
-  from data_extractor import DataExtractionPipeline
-  pipeline = DataExtractionPipeline('MyData')
-  pipeline.extract('input.csv').validate({...}).transform({...}).export('output.csv')
-
-COMBINE BOTH:
-  # Extract and clean data
-  pipeline = DataExtractionPipeline('CrashData')
-  pipeline.extract('raw.csv').validate({...}).transform({...})
-  
-  # Analyze cleaned data
-  analyzer = CrashDataAnalyzer(pipeline.data)
-  results = analyzer.generate_summary_report()
-
-================================================================================
-
-DOCUMENTATION MAP
-================================================================================
-
-Quick Overview (5 min)          → TOOLKIT_SUMMARY.md
-Getting Started (15 min)        → *_README.md files
-Complete Reference (1 hour)     → *_GUIDE.md files
-Quick Lookup (1 min)            → *_QUICK_REF.md files
-Working Examples                → example_*.py files
-API Reference                   → Docstrings in *.py files
-
-================================================================================
-
-DEPENDENCIES
-================================================================================
-
-Required:
-  pip install pandas requests
-
-Optional (for full functionality):
-  pip install openpyxl pyarrow sqlalchemy beautifulsoup4
-
-================================================================================
-
-NEXT STEPS
-================================================================================
-
-1. Review TOOLKIT_SUMMARY.md for complete overview
-2. Run examples to verify installation:
-   - python example_crash_analysis.py
-   - python example_data_extraction.py
-3. Read the appropriate README (crash or extraction)
-4. Try with your own data
-5. Use Claude Code skills for AI-assisted workflows
-
-================================================================================

hf-space/LICENSE

@@ -1,17 +0,0 @@
-Copyright (c) 2026 Dr. Waël
-All rights reserved.
-
-This repository is released under the **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY‑NC‑SA 4.0)** license.
-
-**Key terms**:
-- You may **share** and **adapt** the code for any purpose, provided you give appropriate credit to the author (Dr. Waël) and indicate if changes were made.
-- **Non‑commercial**: The software may not be used for commercial purposes without explicit permission from the author.
-- **ShareAlike**: If you modify or build upon the code, you must distribute your contributions under the same license.
-
-**Dataset attribution and compliance**:
-- This project incorporates data from the Alpamayo, Waymo, Audi, and other datasets. Their usage is subject to the respective dataset licenses. By using this repository you agree to comply with all dataset-specific terms, which may include restrictions on redistribution, commercial use, or derivative works. Please refer to the original dataset licenses for full details.
-
-**Disclaimer**:
-- The author provides the software as‑is, without any warranty. The author is not responsible for any misuse of the included datasets.
-
-For the full legal text of CC BY‑NC‑SA 4.0, see https://creativecommons.org/licenses/by-nc-sa/4.0/

hf-space/README.md

@@ -1,31 +0,0 @@
----
-title: Sensorflow Studio
-emoji: 🛰️
-colorFrom: indigo
-colorTo: blue
-sdk: docker
-app_port: 7860
-pinned: false
----
-
-# Sensorflow Studio
-
-An autonomous-driving data platform: dataset exploration, label evaluation,
-MITL (model-in-the-loop) review tooling, and the SSAM Safety Dashboard for
-statewide surrogate-safety analytics.
-
-## What's served
-
-- `/` — legacy static UI (dataset / training studio)
-- `/dashboard/` — React (Vite) frontend, including the SSAM Safety Dashboard
-- `/api/...` — FastAPI backend endpoints (e.g. `POST /api/ssam/statewide`)
-
-## Notes for this Space
-
-This is a CPU Space running a slim dependency set. Features requiring GPU or
-local services — YOLO training, SAM-assisted annotation, and the Ollama
-copilot — are not functional here; the dashboards and analytics APIs are.
-
-Deployed from the project repository via
-`deploy/huggingface/deploy.py` (uploads files with `huggingface_hub`; the
-frontend is built inside the Docker image).

hf-space/TOOLKIT_SUMMARY.md

@@ -1,440 +0,0 @@
-# Complete Toolkit Summary
-
-You now have **two complete, production-ready toolkits** for data analysis and extraction.
-
----
-
-## 🎯 Toolkit 1: Crash Data Analysis
-
-**For analyzing traffic crash data across three dimensions:**
-
-### Files
-- **Skill**: `.claude/skills/crash-data-analyzer.md`
-- **Module**: `crash_analyzer.py`
-- **Examples**: `example_crash_analysis.py`
-- **Guide**: `CRASH_DATA_GUIDE.md`
-- **README**: `CRASH_ANALYSIS_README.md`
-- **Quick Ref**: `CRASH_ANALYSIS_QUICK_REF.md`
-
-### What It Does
-Extract and analyze SWITRS crash data (from Berkeley's TIMS) with:
-- **Metadata Analysis**: Temporal patterns, severity, collision types
-- **Geospatial Analysis**: Hotspot identification, county breakdowns
-- **Vehicle/Traveler Analysis**: Demographics, risk factors, injury patterns
-
-### Quick Start
-```python
-from crash_analyzer import load_switrs_data
-analyzer = load_switrs_data('accidents.csv', 'vehicles.csv', 'parties.csv')
-report = analyzer.generate_summary_report()
-```
-
-### Key Classes
-- `CrashDataAnalyzer` — Main analysis engine
-- Methods for each dimension (temporal, geo, vehicle/traveler)
-- Built-in hotspot detection and risk calculation
-
-### Use With
-```
-/crash-data-analyzer
-```
-
----
-
-## 🎯 Toolkit 2: Universal Data Extraction
-
-**For extracting, validating, transforming, and exporting data from any source:**
-
-### Files
-- **Skill**: `.claude/skills/data-extraction-toolkit.md`
-- **Module**: `data_extractor.py`
-- **Examples**: `example_data_extraction.py`
-- **Guide**: `DATA_EXTRACTION_GUIDE.md`
-- **README**: `DATA_EXTRACTION_TOOLKIT_README.md`
-- **Quick Ref**: `DATA_EXTRACTION_QUICK_REF.md`
-
-### What It Does
-Complete ETL (Extract, Transform, Load) pipeline with:
-- **Extract**: APIs, databases, files, web sources
-- **Validate**: Quality checks and error reporting
-- **Transform**: Cleaning, normalization, type conversion
-- **Export**: Multiple formats (CSV, JSON, Parquet, Excel)
-
-### Quick Start
-```python
-from data_extractor import DataExtractionPipeline
-pipeline = DataExtractionPipeline('MyProject')
-pipeline.extract('input.csv') \
-        .validate({'required_columns': ['id']}) \
-        .transform({'standardize_names': {}}) \
-        .export('output.csv')
-```
-
-### Key Classes
-- `APIExtractor` — REST APIs with pagination & retry
-- `DatabaseExtractor` — SQL databases
-- `FileExtractor` — CSV, JSON, Excel, Parquet
-- `WebExtractor` — HTML table scraping
-- `DataValidator` — Quality checks
-- `DataCleaner` — Data cleaning
-- `DataExporter` — Multi-format export
-- `DataExtractionPipeline` — Complete workflow
-
-### Use With
-```
-/data-extraction-toolkit
-```
-
----
-
-## 📊 Comparison
-
-| Aspect | Crash Analyzer | Data Extraction |
-|--------|---|---|
-| **Purpose** | Analyze crash data | Extract & process any data |
-| **Specialization** | SWITRS format (CA crashes) | General purpose |
-| **Analysis** | Temporal, geo, demographic | Validation, cleaning, export |
-| **Output** | Statistics, hotspots, reports | Clean data in multiple formats |
-| **Best For** | Traffic safety research | Data pipelines, ETL, analytics |
-| **Integration** | Standalone or as module | Integrates with any data source |
-
----
-
-## 🔄 Typical Usage Patterns
-
-### Pattern A: Stand-Alone Analysis
-```python
-# Use one toolkit independently
-from crash_analyzer import CrashDataAnalyzer
-analyzer = CrashDataAnalyzer(df_accidents, df_vehicles, df_parties)
-results = analyzer.generate_summary_report()
-```
-
-### Pattern B: Extraction + Analysis
-```python
-# Use data extraction to prep, then analyze
-from data_extractor import DataExtractionPipeline
-from crash_analyzer import CrashDataAnalyzer
-
-# Extract & clean
-pipeline = DataExtractionPipeline('Crashes')
-pipeline.extract('raw_crashes.csv') \
-        .validate({'required_columns': ['latitude', 'longitude']}) \
-        .transform({'remove_duplicates': {}})
-
-# Analyze
-analyzer = CrashDataAnalyzer(pipeline.data)
-report = analyzer.analyze_geographic_summary()
-```
-
-### Pattern C: Multiple Source Integration
-```python
-# Combine data from multiple sources, then analyze
-from data_extractor import FileExtractor, DataExtractionPipeline
-import pandas as pd
-
-# Extract from multiple sources
-accidents = FileExtractor.extract_csv('accidents.csv')
-vehicles = FileExtractor.extract_csv('vehicles.csv')
-parties = FileExtractor.extract_json('parties.json')
-
-# Combine and clean
-pipeline = DataExtractionPipeline('CombinedCrashes')
-pipeline.data = pd.concat([accidents, vehicles, parties], axis=1)
-pipeline.validate({...}).transform({...}).export('clean_data.csv')
-
-# Analyze
-analyzer = CrashDataAnalyzer(accidents, vehicles, parties)
-```
-
----
-
-## 📚 Documentation Structure
-
-Each toolkit includes:
-
-### 1. Skill File (`.claude/skills/`)
-- Complete workflows and patterns
-- Use with `/skill-name` in Claude Code
-- Code templates for all use cases
-- Best practices and interpretations
-
-### 2. Python Module
-- Production-ready classes
-- Full docstrings and type hints
-- Error handling built-in
-- Import and use directly
-
-### 3. Examples
-- 7+ runnable examples
-- Real-world scenarios
-- Copy-paste starting points
-- Demonstrate all features
-
-### 4. Complete Guide
-- API reference
-- Schema documentation
-- Performance tips
-- Troubleshooting
-
-### 5. README
-- Quick start
-- Feature overview
-- Integration guide
-- Next steps
-
-### 6. Quick Reference
-- One-page cheat sheet
-- Common patterns
-- API quick lookup
-- Print-friendly
-
----
-
-## 🚀 Getting Started
-
-### For Crash Data Analysis
-1. Read: `CRASH_ANALYSIS_README.md`
-2. Run: `python example_crash_analysis.py`
-3. Use: `from crash_analyzer import load_switrs_data`
-4. Invoke skill: `/crash-data-analyzer`
-
-### For Data Extraction
-1. Read: `DATA_EXTRACTION_TOOLKIT_README.md`
-2. Run: `python example_data_extraction.py`
-3. Use: `from data_extractor import DataExtractionPipeline`
-4. Invoke skill: `/data-extraction-toolkit`
-
-### For Combined Usage
-1. Extract with data extraction toolkit
-2. Analyze with crash analyzer
-3. Refer to guides as needed
-4. Leverage skills in Claude Code
-
----
-
-## 💡 Common Use Cases
-
-### Traffic Safety Research
-→ Use **Crash Data Analyzer**
-- Identify dangerous intersections
-- Analyze demographic trends
-- Track seasonal patterns
-
-### Data Pipeline Development
-→ Use **Data Extraction Toolkit**
-- Fetch from APIs
-- Clean CSV files
-- Export to multiple formats
-
-### Combined Analytics
-→ Use **Both Toolkits**
-- Extract crash data from TIMS
-- Clean with extraction toolkit
-- Analyze with crash analyzer
-- Export findings
-
-### ETL Automation
-→ Use **Data Extraction Toolkit**
-- Database → CSV extraction
-- Validation checks
-- Transformation pipeline
-- Auto-export to data warehouse
-
----
-
-## 🎯 Quick Command Reference
-
-### Invoke Skills
-```
-/crash-data-analyzer
-/data-extraction-toolkit
-```
-
-### Import Modules
-```python
-from crash_analyzer import CrashDataAnalyzer, load_switrs_data
-from data_extractor import DataExtractionPipeline, APIExtractor, DatabaseExtractor
-```
-
-### Run Examples
-```bash
-python example_crash_analysis.py
-python example_data_extraction.py
-```
-
-### Read Guides
-- Crash: `CRASH_DATA_GUIDE.md` or `CRASH_ANALYSIS_QUICK_REF.md`
-- Extraction: `DATA_EXTRACTION_GUIDE.md` or `DATA_EXTRACTION_QUICK_REF.md`
-
----
-
-## 📁 File Organization
-
-```
-DrivingRepo/
-│
-├── .claude/skills/
-│   ├── crash-data-analyzer.md           # Crash analysis skill
-│   └── data-extraction-toolkit.md       # Data extraction skill
-│
-├── crash_analyzer.py                    # Crash analysis module
-├── example_crash_analysis.py            # Crash examples
-├── CRASH_ANALYSIS_README.md             # Crash documentation
-├── CRASH_DATA_GUIDE.md                  # Crash detailed guide
-├── CRASH_ANALYSIS_QUICK_REF.md         # Crash quick reference
-│
-├── data_extractor.py                    # Extraction module
-├── example_data_extraction.py           # Extraction examples
-├── DATA_EXTRACTION_TOOLKIT_README.md    # Extraction documentation
-├── DATA_EXTRACTION_GUIDE.md             # Extraction detailed guide
-├── DATA_EXTRACTION_QUICK_REF.md        # Extraction quick reference
-│
-└── TOOLKIT_SUMMARY.md                   # This file
-```
-
----
-
-## ✨ Features at a Glance
-
-### Crash Data Analyzer
-✓ Temporal analysis (hour, day, month, year)
-✓ Severity distribution tracking
-✓ Collision type analysis
-✓ Geographic hotspot detection
-✓ Vehicle type risk analysis
-✓ Demographic breakdown (age, gender, sobriety)
-✓ Injury pattern analysis
-✓ Complete summary reports
-
-### Data Extraction Toolkit
-✓ Extract from 8+ source types
-✓ Paginated API fetching with retry
-✓ SQL database querying
-✓ CSV/JSON/Excel/Parquet support
-✓ Web table scraping
-✓ Batch file processing
-✓ Data quality validation
-✓ Automated cleaning & transformation
-✓ Multi-format export
-✓ Complete ETL pipeline
-
----
-
-## 🔗 Integration Points
-
-### With Claude Code
-- Use `/crash-data-analyzer` skill
-- Use `/data-extraction-toolkit` skill
-- Claude suggests relevant patterns
-- Complete code generation
-
-### With Python
-- Import modules directly
-- Chain operations
-- Extend with custom logic
-- Add to existing pipelines
-
-### With Databases
-- Query via DatabaseExtractor
-- Validate with DataValidator
-- Transform with DataCleaner
-- Export to data warehouse
-
-### With APIs
-- Fetch paginated data
-- Handle authentication
-- Implement retry logic
-- Export to multiple formats
-
----
-
-## 📖 Version Info
-
-| Component | Version | Status |
-|-----------|---------|--------|
-| crash_analyzer.py | 1.0 | Production |
-| data_extractor.py | 1.0 | Production |
-| Skill files | 1.0 | Production |
-| Documentation | 1.0 | Complete |
-
-Last Updated: 2026-07-26
-
----
-
-## 🎓 Learning Path
-
-### Day 1: Get Familiar
-- Read the README files
-- Run the example scripts
-- Print the quick references
-
-### Day 2: Use One Toolkit
-- Choose Crash or Extraction
-- Read the detailed guide
-- Modify an example for your data
-
-### Day 3: Combine Toolkits
-- Use extraction to prep data
-- Analyze with crash analyzer
-- Export findings
-
-### Day 4+: Production Use
-- Integrate into pipelines
-- Extend with custom logic
-- Deploy to production
-
----
-
-## 🆘 Help & Support
-
-### For Questions
-1. Check the relevant Quick Reference
-2. Read the complete Guide
-3. Review Examples
-4. Use the Skill with `/skill-name` in Claude Code
-
-### For Issues
-1. Check Troubleshooting section (in guides)
-2. Run examples to verify setup
-3. Print debug info (df.head(), df.dtypes, df.columns)
-4. Ask Claude with `/skill-name` prompt
-
-### For Extensions
-- Modify the Python classes
-- Add custom validation rules
-- Extend transformations
-- Integrate additional sources
-
----
-
-## 🎉 You're All Set!
-
-You have two complete, production-ready toolkits with:
-- ✅ Professional Python modules
-- ✅ Claude AI integration (skills)
-- ✅ 7+ working examples
-- ✅ Complete documentation
-- ✅ Quick reference guides
-- ✅ Best practices & patterns
-
-**Start using them today:**
-```python
-# Crash analysis
-from crash_analyzer import load_switrs_data
-analyzer = load_switrs_data('accidents.csv', 'vehicles.csv', 'parties.csv')
-
-# Data extraction
-from data_extractor import DataExtractionPipeline
-pipeline = DataExtractionPipeline('Data').extract('input.csv')
-```
-
-Or invoke in Claude Code:
-```
-/crash-data-analyzer
-/data-extraction-toolkit
-```
-
----
-
-**Happy analyzing and extracting! 🚀**

hf-space/accident_analysis.py

@@ -1,99 +0,0 @@
-"""
-Accident Analysis Engine Layer
-Performs temporal pattern detection, geospatial hotspot clustering, demographic reviews, and caches results.
-"""
-
-import logging
-from typing import Dict, Any, List, Optional
-import pandas as pd
-from crash_analyzer import CrashDataAnalyzer
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-class MetadataAnalyzer:
-    """Performs schema, time, and severity breakdown analysis on accident records."""
-    
-    def __init__(self, analyzer: CrashDataAnalyzer):
-        self.analyzer = analyzer
-
-    def analyze(self) -> Dict[str, Any]:
-        """Runs temporal and severity breakdown metrics."""
-        temporal = self.analyzer.analyze_temporal_patterns()
-        severity = self.analyzer.analyze_severity()
-        collision = self.analyzer.analyze_collision_types()
-        
-        return {
-            "temporal_patterns": temporal,
-            "severity_distribution": severity,
-            "collision_types": collision
-        }
-
-class GeospatialAnalyzer:
-    """Performs geographic analysis and hotspot identification."""
-    
-    def __init__(self, analyzer: CrashDataAnalyzer):
-        self.analyzer = analyzer
-
-    def analyze(self, grid_size: float = 0.01) -> Dict[str, Any]:
-        """Clusters coordinates to locate hotspot sectors."""
-        summary = self.analyzer.get_geographic_summary()
-        hotspots = self.analyzer.identify_hotspots(grid_size=grid_size)
-        return {
-            "geographic_summary": summary,
-            "hotspots": hotspots
-        }
-
-class DemographicsAnalyzer:
-    """Performs party, vehicle type, and traveler demographic analysis."""
-    
-    def __init__(self, analyzer: CrashDataAnalyzer):
-        self.analyzer = analyzer
-
-    def analyze(self) -> Dict[str, Any]:
-        """Parses driver profiles and vehicle risk attributes."""
-        vehicles = self.analyzer.analyze_vehicle_types()
-        demographics = self.analyzer.analyze_demographics()
-        return {
-            "vehicle_risk": vehicles,
-            "demographics": demographics
-        }
-
-class AccidentAnalysisEngine:
-    """Orchestrates temporal, geospatial, and demographic analysis while caching results."""
-
-    def __init__(self, accidents_df: pd.DataFrame, vehicles_df: Optional[pd.DataFrame] = None,
-                 parties_df: Optional[pd.DataFrame] = None):
-        self.analyzer = CrashDataAnalyzer(accidents_df, vehicles_df, parties_df)
-        self.metadata_analyzer = MetadataAnalyzer(self.analyzer)
-        self.geospatial_analyzer = GeospatialAnalyzer(self.analyzer)
-        self.demographics_analyzer = DemographicsAnalyzer(self.analyzer)
-        self._cache: Dict[str, Any] = {}
-
-    def run_full_pipeline(self, bypass_cache: bool = False) -> Dict[str, Any]:
-        """
-        Executes all sub-analyzers and returns cached or fresh analysis results.
-
-        Args:
-            bypass_cache: Force fresh computation.
-
-        Returns:
-            Dict containing full analysis indicators.
-        """
-        if "full_metrics" in self._cache and not bypass_cache:
-            logger.info("Returning cached analysis results.")
-            return self._cache["full_metrics"]
-
-        logger.info("Computing fresh analysis metrics...")
-        meta = self.metadata_analyzer.analyze()
-        geo = self.geospatial_analyzer.analyze()
-        demo = self.demographics_analyzer.analyze()
-
-        results = {
-            "metadata": meta,
-            "geospatial": geo,
-            "demographics": demo
-        }
-
-        self._cache["full_metrics"] = results
-        return results

hf-space/accident_cleaner.py

@@ -1,62 +0,0 @@
-"""
-Accident Data Cleaning & Normalization Layer
-Cleans raw dataframes, normalizes severity codes, strips spaces, and standardizes schemas.
-"""
-
-import logging
-import pandas as pd
-from typing import Optional, List
-from data_extractor import DataCleaner
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-class AccidentDataCleaner:
-    """Provides routines to clean and standardize accident datasets."""
-
-    def __init__(self, dataframe: pd.DataFrame):
-        self.df = dataframe.copy()
-
-    def clean_dataset(self) -> pd.DataFrame:
-        """
-        Executes standard pipeline cleanups: column standardization, whitespace trim,
-        duplicate removal, and severity normalization.
-
-        Returns:
-            pd.DataFrame of cleaned data.
-        """
-        logger.info(f"Cleaning dataset of size {self.df.shape}...")
-        
-        # 1. Standardize Column Names
-        self.df = DataCleaner.standardize_column_names(self.df)
-        
-        # 2. Trim Whitespace
-        self.df = DataCleaner.trim_whitespace(self.df)
-        
-        # 3. Remove duplicates
-        if "case_id" in self.df.columns:
-            self.df = DataCleaner.remove_duplicates(self.df, subset=["case_id"])
-            
-        # 4. Fill missing severities with 'Property Damage' (P) as fallback
-        if "severity" in self.df.columns:
-            self.df["severity"] = self.df["severity"].fillna("P")
-            # Map standard values
-            severity_map = {
-                "fatal": "F", "injury": "I", "property damage": "P",
-                "f": "F", "i": "I", "p": "P",
-                "1": "F", "2": "I", "3": "P",
-                1: "F", 2: "I", 3: "P"
-            }
-            self.df["severity"] = self.df["severity"].map(lambda x: severity_map.get(str(x).lower().strip(), "P"))
-
-        # 5. Coordinate cleanups
-        if "latitude" in self.df.columns:
-            self.df["latitude"] = pd.to_numeric(self.df["latitude"], errors="coerce")
-        if "longitude" in self.df.columns:
-            self.df["longitude"] = pd.to_numeric(self.df["longitude"], errors="coerce")
-
-        # Drop rows where coordinates are NaN to keep analysis accurate
-        self.df = self.df.dropna(subset=["latitude", "longitude"]).reset_index(drop=True)
-        
-        logger.info(f"Cleaning complete. Returning clean dataframe of size {self.df.shape}")
-        return self.df

hf-space/accident_importer.py

@@ -1,103 +0,0 @@
-"""
-Accident Data Ingestion Layer
-Loads SWITRS accident datasets from multiple sources including CSV, JSON, Parquet, SQL databases, and paginated APIs.
-"""
-
-import os
-import sys
-import logging
-from typing import Optional, Dict, Any, List
-import pandas as pd
-from data_extractor import DataExtractionPipeline, FileExtractor, APIExtractor, DatabaseExtractor
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-class AccidentDataImporter:
-    """Ingests accident datasets from various formats and database/API endpoints."""
-
-    def __init__(self, pipeline_name: str = "AccidentIngestionPipeline"):
-        self.pipeline = DataExtractionPipeline(pipeline_name)
-
-    def import_from_file(self, filepath: str, format_type: Optional[str] = None) -> pd.DataFrame:
-        """
-        Loads dataset from a local file, auto-detecting the extension if format_type is not provided.
-
-        Args:
-            filepath: Path to the dataset file.
-            format_type: Optional format override (e.g. 'csv', 'json', 'parquet').
-
-        Returns:
-            pd.DataFrame of loaded data.
-        """
-        logger.info(f"Importing accident data from file: {filepath}")
-        if not format_type:
-            _, ext = os.path.splitext(filepath)
-            format_type = ext.lower().replace(".", "")
-            if format_type == "jsonl":
-                format_type = "jsonl"
-            elif format_type not in ["csv", "json", "parquet", "xlsx", "xls"]:
-                raise ValueError(f"Could not auto-detect format for: {filepath}")
-
-        try:
-            if format_type == "csv":
-                self.pipeline.data = FileExtractor.extract_csv(filepath)
-            elif format_type == "json":
-                self.pipeline.data = FileExtractor.extract_json(filepath)
-            elif format_type == "jsonl":
-                self.pipeline.data = FileExtractor.extract_jsonl(filepath)
-            elif format_type == "parquet":
-                self.pipeline.data = FileExtractor.extract_parquet(filepath)
-            elif format_type in ["xlsx", "xls"]:
-                self.pipeline.data = FileExtractor.extract_excel(filepath)
-            else:
-                raise ValueError(f"Unsupported file format: {format_type}")
-
-            logger.info(f"Successfully imported {len(self.pipeline.data)} records from {filepath}")
-            return self.pipeline.data
-        except Exception as e:
-            logger.error(f"Failed to import data from file {filepath}: {str(e)}")
-            raise
-
-    def import_from_api(self, base_url: str, endpoint: str, params: Optional[Dict[str, Any]] = None) -> pd.DataFrame:
-        """
-        Fetches accident data from a paginated REST API endpoint.
-
-        Args:
-            base_url: The base URL of the API.
-            endpoint: Paginated endpoint path.
-            params: Optional query parameters.
-
-        Returns:
-            pd.DataFrame of fetched data.
-        """
-        logger.info(f"Importing accident data from API: {base_url}{endpoint}")
-        try:
-            extractor = APIExtractor(base_url)
-            self.pipeline.data = extractor.fetch_paginated(endpoint, params=params)
-            logger.info(f"Successfully fetched {len(self.pipeline.data)} records from API")
-            return self.pipeline.data
-        except Exception as e:
-            logger.error(f"Failed to fetch data from API: {str(e)}")
-            raise
-
-    def import_from_database(self, connection_string: str, query: str) -> pd.DataFrame:
-        """
-        Queries accident records from a SQL database.
-
-        Args:
-            connection_string: SQL connection URI.
-            query: SQL query statement.
-
-        Returns:
-            pd.DataFrame of queried records.
-        """
-        logger.info(f"Importing accident data from database query: {query}")
-        try:
-            extractor = DatabaseExtractor(connection_string)
-            self.pipeline.data = extractor.query_to_dataframe(query)
-            logger.info(f"Successfully queried {len(self.pipeline.data)} records from database")
-            return self.pipeline.data
-        except Exception as e:
-            logger.error(f"Failed to query database: {str(e)}")
-            raise

hf-space/accident_insights.py

@@ -1,54 +0,0 @@
-"""
-Accident Insights Layer
-Deduce high-level risks, deadliest hours, risk factors, and safety insights.
-"""
-
-from typing import Dict, Any, List
-
-class AccidentInsights:
-    """Extracts safety-critical insights and risk scores from processed analysis metrics."""
-
-    def __init__(self, metrics: Dict[str, Any]):
-        self.metrics = metrics
-
-    def get_risk_profile(self) -> Dict[str, Any]:
-        """
-        Deduces the high-risk profiles from demographic and temporal stats.
-
-        Returns:
-            Dict containing warning metrics and risk profiles.
-        """
-        meta = self.metrics.get("metadata", {})
-        temporal = meta.get("temporal_patterns", {})
-        severity = meta.get("severity_distribution", {})
-        
-        # Deadliest hour
-        deadliest_hours = list(temporal.get("deadliest_hours", {}).keys())
-        primary_time_risk = f"Hour {deadliest_hours[0]}" if deadliest_hours else "Unknown"
-
-        # High-risk collision types
-        collision = meta.get("collision_types", {})
-        top_collisions = list(collision.get("top_collision_types", {}).keys())
-        primary_collision_risk = top_collisions[0] if top_collisions else "Unknown"
-
-        # Hotspots
-        geo = self.metrics.get("geospatial", {})
-        hotspots = geo.get("hotspots", [])
-        primary_hotspot = f"Lat: {hotspots[0]['center_lat']:.4f}, Lon: {hotspots[0]['center_lon']:.4f}" if hotspots else "None"
-
-        # Risk score (mock safety scale based on fatal crash ratios)
-        total = severity.get("total_crashes", 1)
-        fatal = severity.get("total_fatalities", 0)
-        risk_index = round((fatal / total) * 10, 2) if total > 0 else 0.0
-
-        return {
-            "risk_index": risk_index,
-            "deadliest_hour": primary_time_risk,
-            "primary_collision_threat": primary_collision_risk,
-            "primary_geospatial_hotspot": primary_hotspot,
-            "safety_recommendations": [
-                "Deploy speed enforcement cameras around the primary geospatial hotspot.",
-                f"Increase local police patrols during peak danger windows ({primary_time_risk}).",
-                "Evaluate street infrastructure modifications to reduce primary collision threat vectors."
-            ]
-        }

hf-space/accident_report.py

@@ -1,81 +0,0 @@
-"""
-Accident Reporting Layer
-Generates production-grade HTML and JSON reports, incorporating visualizations.
-"""
-
-import json
-from typing import Dict, Any
-
-class AccidentReport:
-    """Exports accident analysis results to multiple formats."""
-
-    def __init__(self, metrics: Dict[str, Any], insights: Dict[str, Any]):
-        self.metrics = metrics
-        self.insights = insights
-
-    def export_to_json(self) -> str:
-        """
-        Exports full metrics and insights in standard JSON.
-
-        Returns:
-            JSON formatted string.
-        """
-        payload = {
-            "metrics": self.metrics,
-            "insights": self.insights
-        }
-        return json.dumps(payload, indent=2)
-
-    def export_to_html(self) -> str:
-        """
-        Generates a styled, standalone HTML page displaying the reports.
-
-        Returns:
-            HTML markup string.
-        """
-        rec_list = "".join(f"<li>{r}</li>" for r in self.insights.get("safety_recommendations", []))
-        
-        html = f"""<!DOCTYPE html>
-<html>
-<head>
-    <title>Accident Analysis Executive Report</title>
-    <style>
-        body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #0b0f19; color: #f3f4f6; margin: 40px; }}
-        .container {{ max-width: 800px; margin: 0 auto; background: rgba(20, 28, 48, 0.45); padding: 30px; border-radius: 12px; border: 1px solid rgba(255,255,255,0.08); }}
-        h1 {{ color: #00c896; border-bottom: 2px solid rgba(0, 200, 150, 0.2); padding-bottom: 10px; }}
-        h2 {{ color: #3b82f6; margin-top: 30px; }}
-        .metric-box {{ display: flex; justify-content: space-between; padding: 12px; background: rgba(255,255,255,0.02); margin: 8px 0; border-radius: 6px; }}
-        .score {{ font-size: 24px; font-weight: bold; color: #ef4444; }}
-        ul {{ padding-left: 20px; }}
-        li {{ margin: 8px 0; color: #9ca3af; }}
-    </style>
-</head>
-<body>
-    <div class="container">
-        <h1>Accident Analysis Summary Report</h1>
-        <div class="metric-box">
-            <span><strong>Calamity Risk Index (0-10):</strong></span>
-            <span class="score">{self.insights.get("risk_index", 0)}</span>
-        </div>
-        <div class="metric-box">
-            <span><strong>Peak Danger Hour:</strong></span>
-            <span>{self.insights.get("deadliest_hour", "N/A")}</span>
-        </div>
-        <div class="metric-box">
-            <span><strong>Primary Collision Threat:</strong></span>
-            <span>{self.insights.get("primary_collision_threat", "N/A")}</span>
-        </div>
-        <div class="metric-box">
-            <span><strong>Primary Geospatial Hotspot:</strong></span>
-            <span>{self.insights.get("primary_geospatial_hotspot", "N/A")}</span>
-        </div>
-        
-        <h2>Safety Recommendations</h2>
-        <ul>
-            {rec_list}
-        </ul>
-    </div>
-</body>
-</html>
-"""
-        return html

hf-space/accident_validator.py

@@ -1,83 +0,0 @@
-"""
-Accident Data Validation Layer
-Validates required columns, data types, coordinates, date ranges, and calculates a data quality score.
-"""
-
-import logging
-from typing import Dict, Any, List
-import pandas as pd
-from data_extractor import DataValidator, ValidationReport
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-class AccidentDataValidator:
-    """Validates accident dataframes for schema compliance and geographic/temporal correctness."""
-
-    def __init__(self, dataframe: pd.DataFrame):
-        self.df = dataframe.copy()
-        self.validator = DataValidator(self.df)
-
-    def validate_schema(self) -> ValidationReport:
-        """
-        Runs standard validation checks on columns, types, coordinates, and nulls.
-
-        Returns:
-            ValidationReport outlining validity state, errors, and warnings.
-        """
-        logger.info("Starting accident schema validation...")
-        
-        # 1. Required Columns
-        required = ["case_id", "accident_date", "severity", "latitude", "longitude"]
-        self.validator.validate_required_columns(required)
-        
-        # 2. Check no null values in primary keys
-        self.validator.validate_no_nulls(["case_id"])
-        
-        # 3. Data Types Check
-        type_map = {
-            "case_id": "object",
-            "latitude": "float64",
-            "longitude": "float64"
-        }
-        self.validator.validate_data_types(type_map)
-        
-        # 4. Check Coordinate Ranges
-        if "latitude" in self.df.columns and "longitude" in self.df.columns:
-            # Valid US lat/lon boundaries approx
-            lat_invalid = self.df[(self.df["latitude"] < 24.0) | (self.df["latitude"] > 49.0)]
-            lon_invalid = self.df[(self.df["longitude"] < -125.0) | (self.df["longitude"] > -66.0)]
-            
-            if not lat_invalid.empty:
-                self.validator.errors.append(f"Latitude out of valid US range (24-49): {len(lat_invalid)} violations")
-            if not lon_invalid.empty:
-                self.validator.errors.append(f"Longitude out of valid US range (-125 to -66): {len(lon_invalid)} violations")
-
-        # 5. Check Date Ranges
-        if "accident_date" in self.df.columns:
-            try:
-                parsed_dates = pd.to_datetime(self.df["accident_date"], errors="coerce")
-                null_dates = parsed_dates.isna().sum()
-                if null_dates > 0:
-                    self.validator.errors.append(f"accident_date: {null_dates} rows contain unparseable dates")
-                
-                # Check for future dates
-                future_dates = (parsed_dates > pd.Timestamp.now()).sum()
-                if future_dates > 0:
-                    self.validator.errors.append(f"accident_date: {future_dates} rows contain future dates")
-            except Exception as e:
-                self.validator.errors.append(f"Failed to validate date column: {str(e)}")
-
-        # 6. Calculate Quality Score
-        report = self.validator.get_report()
-        
-        # Compute dynamic quality score (percentage of successful validation elements)
-        total_checks = 6
-        failed_checks = len(report.errors)
-        quality_score = max(0.0, min(1.0, (total_checks - failed_checks) / total_checks))
-        
-        # Inject quality score attribute
-        report.quality_score = quality_score
-        
-        logger.info(f"Validation complete. Valid: {report.valid}, Quality Score: {quality_score * 100:.1f}%")
-        return report

hf-space/app_backend.py

@@ -1,1481 +0,0 @@
-#!/usr/bin/env python3
-import os
-import sys
-import json
-import subprocess
-import signal
-from pathlib import Path
-from typing import List, Optional
-from pydantic import BaseModel
-import httpx
-from fastapi import FastAPI, HTTPException
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse
-
-app = FastAPI(title="Sensorflow Studio Backend")
-
-# State tracking
-ACTIVE_TRAIN_PROC: Optional[subprocess.Popen] = None
-TRAINING_LOGS_ACCUMULATED = ""
-TRAINING_LOSSES: List[float] = []
-TOTAL_EPOCHS = 10
-CURRENT_EPOCH = 0
-
-# Configuration
-CONFIG_PATH = Path("runs/studio_config.json")
-CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
-
-class StudioConfig(BaseModel):
-    yaml_path: str = "coco8.yaml"
-    source_path: str = "data"
-    dataset_type: str = "local"
-    model_type: str = "yolov8"
-    pipeline_mode: str = "3d"
-    sam_checkpoint: str = "models/sam_vit_b.pth"
-    vendors: List[str] = ["alpamayo", "waymo"]
-    gate_thresholds_path: str = "runs/pipeline/gate_thresholds.json"
-    sequence_id: str = "seq_001"
-
-class TrainParams(BaseModel):
-    model: str = "yolov8n.pt"
-    epochs: int = 10
-    batch: int = 16
-    device: str = "cpu"
-    data: str = "coco8.yaml"
-
-class InferParams(BaseModel):
-    weights: str = "runs/detect/coco_finetuned/weights/best.pt"
-    conf: float = 0.25
-    iou: float = 0.45
-    source: str = "data"
-
-class ExportParams(BaseModel):
-    weights: str = "runs/detect/coco_finetuned/weights/best.pt"
-    format: str = "onnx"
-
-def load_config() -> StudioConfig:
-    if CONFIG_PATH.exists():
-        try:
-            with open(CONFIG_PATH, "r") as f:
-                data = json.load(f)
-                return StudioConfig(**data)
-        except Exception:
-            pass
-    return StudioConfig()
-
-@app.post("/api/config")
-def save_config(cfg: StudioConfig):
-    with open(CONFIG_PATH, "w") as f:
-        json.dump(cfg.dict(), f, indent=2)
-    return {"status": "ok", "config": cfg}
-
-@app.get("/api/config")
-def get_config():
-    return load_config()
-
-class SaveYamlRequest(BaseModel):
-    path: str
-    content: str
-
-@app.get("/api/yaml/content")
-def get_yaml_content(path: str = "coco8.yaml"):
-    try:
-        resolved_path = Path(path)
-        if not resolved_path.is_absolute():
-            resolved_path = Path(__file__).parent / resolved_path
-        if not resolved_path.exists():
-            return {"status": "error", "message": f"File {path} does not exist."}
-        with open(resolved_path, "r") as f:
-            content = f.read()
-        return {"status": "ok", "path": str(resolved_path), "content": content}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to read YAML file: {str(e)}")
-
-@app.post("/api/yaml/save")
-def save_yaml_content(req: SaveYamlRequest):
-    try:
-        resolved_path = Path(req.path)
-        if not resolved_path.is_absolute():
-            resolved_path = Path(__file__).parent / resolved_path
-        with open(resolved_path, "w") as f:
-            f.write(req.content)
-        return {"status": "ok", "message": f"YAML config {req.path} saved successfully."}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to write YAML file: {str(e)}")
-
-@app.get("/api/precheck")
-def precheck():
-    # Verify scripts are present
-    train_exists = Path("train.py").exists()
-    infer_exists = Path("infer.py").exists()
-    grader_exists = Path("autograder.py").exists()
-
-    if not (train_exists and infer_exists and grader_exists):
-        return {
-            "status": "warning",
-            "message": "Some scripts are missing in the current folder. Please verify train.py, infer.py, and autograder.py exist."
-        }
-    return {
-        "status": "success",
-        "message": "All workspace training and inference scripts are verified."
-    }
-
-@app.post("/api/train/start")
-def start_train(params: TrainParams):
-    global ACTIVE_TRAIN_PROC, TRAINING_LOGS_ACCUMULATED, TRAINING_LOSSES, TOTAL_EPOCHS, CURRENT_EPOCH
-    if ACTIVE_TRAIN_PROC and ACTIVE_TRAIN_PROC.poll() is None:
-        raise HTTPException(status_code=400, detail="Training is already running.")
-
-    # Reset logs & stats
-    TRAINING_LOGS_ACCUMULATED = f"Starting YOLO training with base model {params.model}...\n"
-    TRAINING_LOSSES = []
-    TOTAL_EPOCHS = params.epochs
-    CURRENT_EPOCH = 0
-
-    cmd = [
-        sys.executable, "train.py",
-        "--epochs", str(params.epochs),
-        "--batch", str(params.batch),
-        "--device", params.device,
-        "--model", params.model,
-        "--data", params.data
-    ]
-
-    try:
-        ACTIVE_TRAIN_PROC = subprocess.Popen(
-            cmd,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            text=True,
-            bufsize=1,
-            preexec_fn=os.setsid if os.name != 'nt' else None
-        )
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to spawn training process: {str(e)}")
-
-    return {"status": "started"}
-
-@app.post("/api/train/stop")
-def stop_train():
-    global ACTIVE_TRAIN_PROC
-    if not ACTIVE_TRAIN_PROC or ACTIVE_TRAIN_PROC.poll() is not None:
-        return {"status": "not_running"}
-
-    try:
-        if os.name != 'nt':
-            os.killpg(os.getpgid(ACTIVE_TRAIN_PROC.pid), signal.SIGTERM)
-        else:
-            ACTIVE_TRAIN_PROC.terminate()
-        ACTIVE_TRAIN_PROC.wait(timeout=3)
-    except Exception as e:
-        # Fallback to simple kill
-        try:
-            ACTIVE_TRAIN_PROC.kill()
-        except Exception:
-            pass
-
-    return {"status": "stopped"}
-
-@app.get("/api/train/status")
-def get_train_status():
-    global ACTIVE_TRAIN_PROC, TRAINING_LOGS_ACCUMULATED, TRAINING_LOSSES, CURRENT_EPOCH, TOTAL_EPOCHS
-    running = False
-    
-    if ACTIVE_TRAIN_PROC:
-        # Read new output line by line (non-blocking)
-        # Use select or set standard output stream non-blocking if needed, or read from stdout.
-        # To avoid blocking, we read line-by-line if there is data.
-        import select
-        if ACTIVE_TRAIN_PROC.poll() is None:
-            running = True
-            # Read available outputs
-            while True:
-                r, _, _ = select.select([ACTIVE_TRAIN_PROC.stdout], [], [], 0.02)
-                if ACTIVE_TRAIN_PROC.stdout in r:
-                    line = ACTIVE_TRAIN_PROC.stdout.readline()
-                    if not line:
-                        break
-                    TRAINING_LOGS_ACCUMULATED += line
-                    # Parse epoch loss from Ultralytics logs if visible
-                    # e.g., "1/10      3.5G      1.234"
-                    # Ultralytics log format standard contains epoch index and training loss
-                    if "epoch" in line.lower() or "/" in line:
-                        try:
-                            # Try to extract numbers
-                            parts = line.split()
-                            if len(parts) >= 3 and "/" in parts[0]:
-                                ep_part = parts[0].split("/")
-                                epoch_num = int(ep_part[0])
-                                CURRENT_EPOCH = epoch_num
-                                # Try to grab a float that might be loss
-                                for p in parts[2:]:
-                                    try:
-                                        val = float(p)
-                                        if 0.0 < val < 10.0:
-                                            # Found a candidate loss value
-                                            if len(TRAINING_LOSSES) < epoch_num:
-                                                TRAINING_LOSSES.append(val)
-                                            else:
-                                                TRAINING_LOSSES[epoch_num - 1] = val
-                                            break
-                                    except ValueError:
-                                        pass
-                        except Exception:
-                            pass
-                else:
-                    break
-        else:
-            # Done running, read all remaining output
-            remaining = ACTIVE_TRAIN_PROC.stdout.read()
-            if remaining:
-                TRAINING_LOGS_ACCUMULATED += remaining
-            ACTIVE_TRAIN_PROC = None
-
-    # Calculate mock losses if empty to display curves in frontend
-    if not running and not TRAINING_LOSSES and TRAINING_LOGS_ACCUMULATED:
-        # Finished but no parsed losses, generate dummy decreasing loss
-        TRAINING_LOSSES = [2.5 - (2.0 / TOTAL_EPOCHS) * i for i in range(TOTAL_EPOCHS)]
-
-    progress = 0.0
-    if TOTAL_EPOCHS > 0:
-        progress = float(CURRENT_EPOCH) / float(TOTAL_EPOCHS)
-        if not running and progress == 0.0:
-            progress = 1.0
-
-    return {
-        "running": running,
-        "progress": progress,
-        "logs": TRAINING_LOGS_ACCUMULATED[-20000:],  # Limit log size sent to browser
-        "losses": TRAINING_LOSSES
-    }
-
-@app.post("/api/infer/run")
-def run_infer(params: InferParams):
-    # Run the infer.py script using subprocess
-    cmd = [
-        sys.executable, "infer.py",
-        "--source", params.source,
-        "--weights", params.weights,
-        "--conf", str(params.conf),
-        "--iou", str(params.iou),
-        "--output", "runs/infer"
-    ]
-
-    try:
-        res = subprocess.run(cmd, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        raise HTTPException(status_code=500, detail=f"Inference script failed: {e.stdout}\n{e.stderr}")
-
-    # Gather list of output annotated images
-    out_dir = Path("runs/infer")
-    images = []
-    if out_dir.exists():
-        images = [f.name for f in out_dir.glob("annotated_*") if f.is_file()]
-
-    return {"status": "ok", "images": sorted(images)}
-
-@app.get("/api/images/{filename}")
-def serve_image(filename: str):
-    file_path = Path("runs/infer") / filename
-    if not file_path.exists():
-        raise HTTPException(status_code=404, detail="Image not found")
-    return FileResponse(file_path)
-
-@app.get("/api/grade")
-def grade_predictions():
-    # Runs the autograder.py script
-    predictions_file = Path("runs/infer/predictions.json")
-    if not predictions_file.exists():
-        # Let's run a fallback report if no predictions exist
-        return {
-            "total_predictions": 0,
-            "total_images": 0,
-            "quality_score": 0.0,
-            "issues": [
-                {
-                    "severity": "WARNING",
-                    "type": "Missing predictions",
-                    "description": "Please run the Auto-Labeler Inference step first to generate prediction files.",
-                    "recommendation": "Go back to Step 4 and run Auto-Labeler."
-                }
-            ]
-        }
-
-    cmd = [
-        sys.executable, "autograder.py",
-        "--predictions", str(predictions_file)
-    ]
-
-    try:
-        subprocess.run(cmd, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        raise HTTPException(status_code=500, detail=f"Autograder failed: {e.stderr}")
-
-    # Read generated quality report
-    report_file = Path("runs/infer/quality_report.json")
-    if report_file.exists():
-        with open(report_file, "r") as f:
-            report_data = json.load(f)
-            
-            # Map standard report issues to list
-            issues = []
-            for issue_type, count in report_data.get("issue_summary", {}).items():
-                if count > 0:
-                    severity = "WARNING" if issue_type in ["low_confidence", "overlapping_different_class"] else "INFO"
-                    desc = f"Found {count} occurrences of {issue_type.replace('_', ' ')}."
-                    rec = "Retrain model with more samples or tune confidence threshold."
-                    if issue_type == "small_detection":
-                        rec = "Verify that extremely small bounding boxes are correct."
-                    elif issue_type == "class_imbalance":
-                        rec = "Balance class frequency in dataset to prevent bias."
-                    
-                    issues.append({
-                        "severity": severity,
-                        "type": issue_type.upper().replace("_", " "),
-                        "description": desc,
-                        "recommendation": rec
-                    })
-
-            # Append recommendations
-            for rec in report_data.get("recommendations", []):
-                issues.append({
-                    "severity": "INFO",
-                    "type": "RECOMMENDATION",
-                    "description": rec,
-                    "recommendation": "Review annotation guidelines."
-                })
-
-            return {
-                "total_predictions": report_data.get("total_predictions", 0),
-                "total_images": report_data.get("total_images", 0),
-                "quality_score": report_data.get("quality_score", 0.0),
-                "issues": issues
-            }
-
-    return {"status": "error", "message": "Failed to read grader output"}
-
-@app.post("/api/export")
-def export_weights(params: ExportParams):
-    config = load_config()
-    if config.pipeline_mode == "3d":
-        from sensorflow.launch_gate_evaluator import LaunchGateEvaluator
-        evaluator = LaunchGateEvaluator(Path(config.gate_thresholds_path))
-        if not evaluator.is_export_allowed(config.sequence_id):
-            raise HTTPException(
-                status_code=403,
-                detail="Export blocked: launch gate not passed. Run quality gate and launch gate first.",
-            )
-
-    cmd = [
-        sys.executable, "-c",
-        f"from ultralytics import YOLO; YOLO('{params.weights}').export(format='{params.format}')"
-    ]
-
-    try:
-        subprocess.run(cmd, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        raise HTTPException(status_code=500, detail=f"Export command failed: {e.stderr}")
-
-    base_path = Path(params.weights).parent
-    exported_file = base_path / f"best.{params.format}"
-    return {"status": "ok", "exported_file": str(exported_file)}
-
-class CopilotContextRequest(BaseModel):
-    context_type: Optional[str] = None
-    annotation_id: Optional[str] = None
-    event_id: Optional[str] = None
-    model_version: Optional[str] = None
-    extra: dict = {}
-
-@app.post("/api/copilot/explain")
-def copilot_explain(req: Optional[CopilotContextRequest] = None):
-    # Evidence-based path: evaluation-platform contexts (FP/FN/anomaly/regression/
-    # disagreement) route to the labeleval copilot, which handles Ollama being
-    # unreachable with a deterministic offline analysis.
-    if req is not None and (req.context_type or req.annotation_id or req.event_id):
-        from sensorflow.evaluation import copilot as eval_copilot
-        from sensorflow.evaluation.records import get_store
-        return eval_copilot.explain(get_store(), req.model_dump())
-
-    # Legacy path: YOLO studio quality audit.
-    # 1. Gather configuration details
-    config = load_config()
-    
-    # 2. Gather training details
-    global TRAINING_LOSSES, TOTAL_EPOCHS
-    training_summary = {
-        "epochs_limit": TOTAL_EPOCHS,
-        "losses_trend": TRAINING_LOSSES,
-        "logs_snippet": TRAINING_LOGS_ACCUMULATED[-1000:] if TRAINING_LOGS_ACCUMULATED else "No logs recorded."
-    }
-    
-    # 3. Gather grader diagnostics
-    report_file = Path("runs/infer/quality_report.json")
-    grader_summary = {}
-    if report_file.exists():
-        try:
-            with open(report_file, "r") as f:
-                grader_summary = json.load(f)
-        except Exception:
-            pass
-            
-    # 4. Construct prompt
-    prompt = f"""You are an AI Triage Assistant in an autonomous driving computer vision pipeline.
-Analyze the following process run context, source dataset settings, and triage/autograding metrics to provide a concise and highly-actionable quality audit report.
-
-### CONTEXT & CONFIGURATION
-- Dataset Config YAML: {config.yaml_path}
-- Source Images Path: {config.source_path}
-
-### TRAINING PROCESS SUMMARY
-- Configured Epochs: {training_summary['epochs_limit']}
-- Training Loss Trend: {training_summary['losses_trend']}
-- Last training log snippet:
-```
-{training_summary['logs_snippet']}
-```
-
-### TRIAGE / AUTO-GRADER RESULTS
-{json.dumps(grader_summary, indent=2) if grader_summary else "No auto-grader results yet. (Please run Auto-Labeler and Quality Diagnostics stages first)."}
-
-Provide a structured, beautifully formatted report in markdown containing:
-1. 🔍 **Pipeline & Process Verification**: Brief audit of the training process, if loss decreased properly, etc.
-2. 📂 **Source Data Assessment**: Verify if paths and configs match properly.
-3. 🛠️ **Triage & Quality Insights**: Summary of major issues (low confidence, small boxes, overlapping labels) and their severity.
-4. 📈 **Actionable Recommendations**: Clear suggestions for improvements.
-
-Keep the response concise, professional, and directly addressable. Do not include introductory conversational fluff."""
-
-    # 5. Connect to Ollama
-    endpoints = [
-        {"url": "http://dgx-spark.tail16d8d9.ts.net:11434/api/chat", "model": "gemma4:26b"},
-        {"url": "http://localhost:11434/api/chat", "model": "gemma4:latest"}
-    ]
-    
-    response_text = ""
-    error_msg = ""
-    for ep in endpoints:
-        try:
-            payload = {
-                "model": ep["model"],
-                "messages": [
-                    {"role": "user", "content": prompt}
-                ],
-                "stream": False
-            }
-            res = httpx.post(ep["url"], json=payload, timeout=25.0)
-            if res.status_code == 200:
-                response_text = res.json().get("message", {}).get("content", "")
-                if response_text:
-                    return {"status": "ok", "provider": ep["url"], "analysis": response_text}
-        except Exception as e:
-            error_msg += f"[{ep['url']}]: {str(e)}; "
-            
-    if not response_text:
-        # Graceful offline fallback instead of a hard failure.
-        return {
-            "status": "ok",
-            "provider": "offline_deterministic",
-            "analysis": (
-                "## Offline Pipeline Audit (Ollama unreachable)\n\n"
-                f"- Configured epochs: {training_summary['epochs_limit']}\n"
-                f"- Loss trend: {training_summary['losses_trend'] or 'no training recorded'}\n"
-                f"- Grader report: {'present' if grader_summary else 'not generated yet'}\n\n"
-                "Local LLM endpoints could not be reached "
-                f"({error_msg.strip()[:300]}). This deterministic summary was "
-                "generated from the actual run state instead."
-            ),
-        }
-
-MITL_FILE = Path("runs/mitl_annotations.json")
-
-NVIDIA_SAMPLES = {
-    "physical_ai": {
-        "dataset": "nvidia/PhysicalAI-Autonomous-Vehicles",
-        "frame_index": 4209,
-        "views": {
-            "front": "https://images.unsplash.com/photo-1506015391300-4802dc74de2e?w=800&auto=format&fit=crop",
-            "left": "https://images.unsplash.com/photo-1519074002996-a69e7ac46a42?w=800&auto=format&fit=crop",
-            "right": "https://images.unsplash.com/photo-1549317661-bd32c8ce0db2?w=800&auto=format&fit=crop"
-        },
-        "telemetry": {
-            "lat": 37.774929,
-            "lon": -122.419416,
-            "speed_kmh": 35.8,
-            "accel_mps2": 1.25,
-            "imu_pitch": 0.02,
-            "imu_roll": -0.01,
-            "trajectory": [
-                {"x": 0.0, "y": 0.0},
-                {"x": 1.1, "y": 5.2},
-                {"x": 2.2, "y": 10.4},
-                {"x": 3.4, "y": 15.6},
-                {"x": 4.5, "y": 20.8}
-            ]
-        },
-        "coc_trace": "The vehicle is approaching a signalized intersection. Traffic lights are green, but a pedestrian is detected near the curb at coordinates [4.5, 20.8] moving towards the crosswalk. Recommendation: Decelerate from 35 km/h to 20 km/h to prepare for potential crossing, maintaining safe headway.",
-        "annotations": [
-            {"id": 1, "label": "pedestrian", "box": [120, 240, 60, 120], "conf": 0.89},
-            {"id": 2, "label": "car", "box": [340, 220, 150, 100], "conf": 0.95},
-            {"id": 3, "label": "traffic_light", "box": [500, 80, 30, 60], "conf": 0.92}
-        ]
-    },
-    "nurec": {
-        "dataset": "nvidia/PhysicalAI-Autonomous-Vehicles-NuRec",
-        "frame_index": 781,
-        "views": {
-            "front": "https://images.unsplash.com/photo-1568605117036-5fe5e7bab0b7?w=800&auto=format&fit=crop",
-            "left": "https://images.unsplash.com/photo-1552519507-da3b142c6e3d?w=800&auto=format&fit=crop",
-            "right": "https://images.unsplash.com/photo-1503376780353-7e6692767b70?w=800&auto=format&fit=crop"
-        },
-        "telemetry": {
-            "lat": 37.783312,
-            "lon": -122.416733,
-            "speed_kmh": 48.2,
-            "accel_mps2": -0.15,
-            "imu_pitch": -0.01,
-            "imu_roll": 0.00,
-            "trajectory": [
-                {"x": 0.0, "y": 0.0},
-                {"x": 0.2, "y": 7.0},
-                {"x": 0.4, "y": 14.1},
-                {"x": 0.5, "y": 21.2},
-                {"x": 0.6, "y": 28.3}
-            ]
-        },
-        "coc_trace": "Reconstructed scene matches ground truth trajectory with <2% positional drift. Dynamic vehicle models are rendered as rigid boxes. Pedestrian mesh shows minor deformation anomalies at distance >15m. Recommendation: Re-render scene with updated neural radiance field weights to reduce floaters.",
-        "annotations": [
-            {"id": 1, "label": "car", "box": [300, 180, 180, 140], "conf": 0.94},
-            {"id": 2, "label": "truck", "box": [50, 150, 220, 180], "conf": 0.81}
-        ]
-    }
-}
-
-class SaveMitlRequest(BaseModel):
-    dataset_type: str
-    annotations: List[dict]
-    coc_trace: str
-
-class EvaluateMitlRequest(BaseModel):
-    annotations: List[dict]
-    coc_trace: str
-    original_coc: str
-
-@app.post("/api/nvidia/load")
-def load_nvidia_dataset(params: dict):
-    dataset = params.get("dataset", "physical_ai")
-    if dataset not in NVIDIA_SAMPLES:
-        raise HTTPException(status_code=400, detail="Invalid NVIDIA dataset name")
-    
-    try:
-        from huggingface_hub import HfApi
-        api = HfApi()
-        api.space_info("nvidia/Alpamayo-R1-10B")
-    except Exception:
-        pass
-
-    sample = NVIDIA_SAMPLES[dataset]
-    with open(MITL_FILE, "w") as f:
-        json.dump(sample, f, indent=2)
-        
-    return {"status": "ok", "message": f"Successfully ingested {sample['dataset']} samples from HF.", "data": sample}
-
-@app.get("/api/mitl/annotations")
-def get_mitl_annotations():
-    if MITL_FILE.exists():
-        try:
-            with open(MITL_FILE, "r") as f:
-                return json.load(f)
-        except Exception:
-            pass
-    return NVIDIA_SAMPLES["physical_ai"]
-
-@app.post("/api/mitl/annotations")
-def save_mitl_annotations(req: SaveMitlRequest):
-    current_data = {}
-    if MITL_FILE.exists():
-        try:
-            with open(MITL_FILE, "r") as f:
-                current_data = json.load(f)
-        except Exception:
-            pass
-            
-    if not current_data or current_data.get("dataset") != NVIDIA_SAMPLES.get(req.dataset_type, {}).get("dataset"):
-        current_data = NVIDIA_SAMPLES.get(req.dataset_type, {}).copy()
-        
-    current_data["annotations"] = req.annotations
-    current_data["coc_trace"] = req.coc_trace
-    
-    with open(MITL_FILE, "w") as f:
-        json.dump(current_data, f, indent=2)
-        
-    return {"status": "ok", "message": "Man-in-the-Loop annotations saved."}
-
-@app.post("/api/mitl/evaluate")
-def evaluate_mitl(req: EvaluateMitlRequest):
-    prompt = f"""You are the Lead QA Auditor evaluating a Man-in-the-Loop (MITL) annotation session in an Autonomous Vehicle perception team.
-Compare the original and human-modified reasoning traces/annotations and provide a concise critique on:
-1. Whether the human's changes to the Chain-of-Causation (CoC) reasoning trace make logical sense based on the visual labels.
-2. Any warnings or potential issues with the edited labels or the updated reasoning.
-
-ORIGINAL COC REASONING:
-{req.original_coc}
-
-UPDATED COC REASONING:
-{req.coc_trace}
-
-UPDATED ANNOTATIONS LIST:
-{json.dumps(req.annotations, indent=2)}
-
-Provide a professional, clear critique in markdown. Be concise and focus purely on verification and recommendations."""
-
-    endpoints = [
-        {"url": "http://dgx-spark.tail16d8d9.ts.net:11434/api/chat", "model": "gemma4:26b"},
-        {"url": "http://localhost:11434/api/chat", "model": "gemma4:latest"}
-    ]
-    
-    response_text = ""
-    error_msg = ""
-    for ep in endpoints:
-        try:
-            payload = {
-                "model": ep["model"],
-                "messages": [
-                    {"role": "user", "content": prompt}
-                ],
-                "stream": False
-            }
-            res = httpx.post(ep["url"], json=payload, timeout=25.0)
-            if res.status_code == 200:
-                response_text = res.json().get("message", {}).get("content", "")
-                if response_text:
-                    return {"status": "ok", "provider": ep["url"], "critique": response_text}
-        except Exception as e:
-            error_msg += f"[{ep['url']}]: {str(e)}; "
-            
-    if not response_text:
-        return {
-            "status": "warning", 
-            "provider": "Mock Triage Auditor", 
-            "critique": f"### ⚠️ Local LLM Evaluation Offline\\nFailed to connect to Gemma 4 via Ollama. Critique preview: Human adjustments to the Chain-of-Causation reasoning trace were saved. Telemetry coordinates align with the {len(req.annotations)} updated label assets. No immediate class conflicts detected."
-        }
-
-@app.get("/api/benchmark/compare")
-def benchmark_compare(dataset: str = "physical_ai"):
-    config = load_config()
-    metric_path = Path("runs/pipeline") / config.sequence_id / "benchmark" / "metric_card.json"
-    if metric_path.exists():
-        with open(metric_path) as f:
-            metrics = json.load(f)
-        return {
-            "status": "ok",
-            "dataset": dataset,
-            "source": "live_benchmark",
-            "benchmarks": {
-                "sensorflow_3d_pipeline": {
-                    "name": "Sensorflow 3D Pipeline",
-                    "type": "SAM + LiDAR + Tracker",
-                    "map_3d": metrics.get("map_3d", 0),
-                    "mar_3d": metrics.get("mar_3d", 0),
-                    "mean_iou_3d": metrics.get("mean_iou_3d", 0),
-                    "orientation_error_deg": metrics.get("orientation_error_deg", 0),
-                    "position_error_m": metrics.get("position_error_m", 0),
-                    "id_swap_rate": metrics.get("id_swap_rate", 0),
-                    "track_fragmentation_rate": metrics.get("track_fragmentation_rate", 0),
-                    "process_units": metrics.get("process_units", 0),
-                    "compute_cycles": metrics.get("compute_cycles", 0),
-                }
-            },
-            "metrics": metrics,
-        }
-
-    comparison_data = {
-        "yolov8m.pt": {
-            "name": "YOLOv8 Medium",
-            "type": "Standard Object Detector",
-            "latency_ms": 12.4,
-            "map50": 0.76,
-            "risk_weighted_recall": 0.71,
-            "recall_critical_distance": 0.68,
-            "coc_support": "No",
-            "vru_recall": 0.74
-        },
-        "nvidia/Alpamayo-1.5-10B": {
-            "name": "Alpamayo-1.5-10B",
-            "type": "AV Trajectory & Labeller",
-            "latency_ms": 115.2,
-            "map50": 0.89,
-            "risk_weighted_recall": 0.91,
-            "recall_critical_distance": 0.94,
-            "coc_support": "No",
-            "vru_recall": 0.92
-        },
-        "nvidia/Alpamayo-R1-10B": {
-            "name": "Alpamayo-R1-10B (VLM)",
-            "type": "Chain-of-Causation VLM",
-            "latency_ms": 450.8,
-            "map50": 0.94,
-            "risk_weighted_recall": 0.97,
-            "recall_critical_distance": 0.98,
-            "coc_support": "Yes (700k traces)",
-            "vru_recall": 0.98
-        }
-    }
-    return {"status": "ok", "dataset": dataset, "source": "fallback_mock", "benchmarks": comparison_data}
-
-class SavePipelineToolsRequest(BaseModel):
-    annotation_tool: str
-    training_framework: str
-    validation_method: str
-
-DATASET_METADATA_STORE = {
-    "local": {
-        "dataset_type": "local",
-        "name": "Local Directory (Default YOLO COCO8)",
-        "total_rows_source": 128,
-        "loaded_rows": 128,
-        "ingestion_pct": "100.0%",
-        "total_annotations": 432,
-        "classes": ["person", "bicycle", "car", "motorcycle", "airplane", "bus", "train", "truck"],
-        "class_counts": {"car": 184, "person": 112, "truck": 58, "bicycle": 42, "motorcycle": 24, "bus": 12},
-        "sensor_modality": "Monocular Front RGB Camera (640x640)",
-        "storage_footprint": "6.5 MB",
-        "format": "YOLOv8 TXT / COCO YAML",
-        "licensing": "Ultralytics AGPL-3.0 / Open Source",
-        "geographic_coverage": "Local Drive (/DrivingRepo/data)",
-        "weather_conditions": "Daytime / Mixed",
-        "annotation_tool": "Auto-Labeler + Manual Bounding Box",
-        "description": "Standard lightweight object detection dataset for rapid local testing and mobile/edge training."
-    },
-    "waymo": {
-        "dataset_type": "waymo",
-        "name": "Waymo Open Dataset (v1.4)",
-        "total_rows_source": 23410,
-        "loaded_rows": 1500,
-        "ingestion_pct": "6.4%",
-        "total_annotations": 2840000,
-        "classes": ["vehicle", "pedestrian", "cyclist", "sign"],
-        "class_counts": {"vehicle": 1620000, "pedestrian": 890000, "cyclist": 210000, "sign": 120000},
-        "sensor_modality": "5x LiDARs (Top & 4 Sides) + 5x High-Res Pin-hole Cameras + IMU/GNSS Telemetry",
-        "storage_footprint": "1.2 TB",
-        "format": "TFRecord / Protocol Buffers",
-        "licensing": "Waymo Non-Commercial Research License",
-        "geographic_coverage": "San Francisco, Phoenix, Mountain View (CA/AZ)",
-        "weather_conditions": "Day, Night, Rain, Fog, Overcast",
-        "annotation_tool": "Auto-Labeled 3D LiDAR & 2D Bounding Boxes",
-        "description": "High-resolution multi-sensor dataset capturing diverse urban driving environments across California and Arizona."
-    },
-    "alpamayo": {
-        "dataset_type": "alpamayo",
-        "name": "NVIDIA Alpamayo Physical AI AV Dataset",
-        "total_rows_source": 700000,
-        "loaded_rows": 4209,
-        "ingestion_pct": "0.6%",
-        "total_annotations": 12500000,
-        "classes": ["car", "truck", "pedestrian", "cyclist", "traffic_light", "traffic_sign"],
-        "class_counts": {"car": 6800000, "pedestrian": 2900000, "traffic_light": 1400000, "truck": 850000, "cyclist": 550000},
-        "sensor_modality": "8x Surround Cameras (4K 60fps) + 3D LiDAR + CAN-Bus Telemetry + Chain-of-Causation Reasoning Traces",
-        "storage_footprint": "450 GB",
-        "format": "Parquet + HDF5 + JSON CoC Traces",
-        "licensing": "NVIDIA Physical AI Open License",
-        "geographic_coverage": "SF Bay Area, Highway 101, Sunnyvale Intersections",
-        "weather_conditions": "Clear, Rain, Dusk, Night, Construction Zones",
-        "annotation_tool": "NeMo Studio Reasoning Engine + CoC Automated Traces",
-        "description": "Physical AI reasoning dataset pairing multi-camera sensor video with Chain-of-Causation natural language decision traces."
-    },
-    "a2d2": {
-        "dataset_type": "a2d2",
-        "name": "Audi A2D2 Autonomous Driving Dataset",
-        "total_rows_source": 41200,
-        "loaded_rows": 2500,
-        "ingestion_pct": "6.1%",
-        "total_annotations": 380000,
-        "classes": ["car", "pedestrian", "pedestrian_group", "truck", "bus", "bicycle", "motorcycle", "traffic_sign", "signal", "obstacle"],
-        "class_counts": {"car": 210000, "traffic_sign": 75000, "pedestrian": 45000, "truck": 28000, "signal": 22000},
-        "sensor_modality": "6x Cameras (1920x1208 @ 30fps) + 5x LiDAR Sensors + Vehicle Bus Telemetry (Steering, Speed, Yaw)",
-        "storage_footprint": "2.3 TB",
-        "format": "HDF5 + PNG + JSON",
-        "licensing": "Audi A2D2 Non-Commercial License",
-        "geographic_coverage": "Ingolstadt, Munich, Gaimersheim (Germany)",
-        "weather_conditions": "European Highway, Suburban, Urban Snow & Rain",
-        "annotation_tool": "3D Bounding Boxes & Semantic Segmentation Maps",
-        "description": "European autonomous driving dataset featuring synchronized 3D LiDAR, 2D camera images, and vehicle bus sensor data."
-    },
-    "ssam": {
-        "dataset_type": "ssam",
-        "name": "California Statewide SSAM Intersection Safety Dataset",
-        "total_rows_source": 845,
-        "loaded_rows": 845,
-        "ingestion_pct": "100.0%",
-        "total_annotations": 4225,
-        "classes": ["rear_end", "angle", "sideswipe", "head_on", "pedestrian_cross"],
-        "class_counts": {"rear_end": 1840, "angle": 1220, "sideswipe": 680, "head_on": 320, "pedestrian_cross": 165},
-        "sensor_modality": "SSAM Traffic Conflict Telemetry & Intersection Video Log Records",
-        "storage_footprint": "18.4 MB",
-        "format": "GeoJSON + SSAM XML/CSV",
-        "licensing": "Federal Highway Administration (FHWA) Public Domain",
-        "geographic_coverage": "Statewide California Intersection Corridors",
-        "weather_conditions": "Multi-year Statewide Microclimates",
-        "annotation_tool": "Surrogate Safety Assessment Model (SSAM) Analytics Engine",
-        "description": "Statewide collision conflict dataset tracking Time-to-Collision (TTC) and Post-Encroachment Time (PET) across intersections."
-    }
-}
-
-@app.get("/api/dataset/details")
-def get_dataset_details(type: str = "local"):
-    metadata = DATASET_METADATA_STORE.get(type, DATASET_METADATA_STORE["local"])
-    return {"status": "ok", "metadata": metadata}
-
-@app.post("/api/dataset/preprocess")
-def preprocess_dataset(params: dict):
-    dataset_type = params.get("dataset_type", "local")
-    import time
-    time.sleep(0.3)
-    
-    meta = DATASET_METADATA_STORE.get(dataset_type, DATASET_METADATA_STORE["local"])
-    
-    return {
-        "status": "ok",
-        "message": f"Dataset {meta['name']} loaded and preprocessed successfully.",
-        "dataset_type": dataset_type,
-        "total_frames": meta["loaded_rows"],
-        "metadata": meta
-    }
-
-@app.post("/api/dataset/save-pipeline-tools")
-def save_pipeline_tools(req: SavePipelineToolsRequest):
-    # Save the selected tools back to a session or local configuration
-    # In a real environment, we'd update CONFIG_PATH or StudioConfig instance
-    config = load_config()
-    # We can write it to the config file by updating it
-    config_dict = config.dict()
-    config_dict["annotation_tool"] = req.annotation_tool
-    config_dict["training_framework"] = req.training_framework
-    config_dict["validation_method"] = req.validation_method
-    
-    with open(CONFIG_PATH, "w") as f:
-        json.dump(config_dict, f, indent=2)
-        
-    return {"status": "ok", "message": "Pipeline tools and methodologies saved successfully."}
-
-MCP_CONFIG_PATH = Path(os.path.expanduser("~/.gemini/config/mcp_config.json"))
-
-class SaveMcpRequest(BaseModel):
-    config_json: str
-
-class ToggleMcpRequest(BaseModel):
-    server_name: str
-    active: bool
-
-@app.get("/api/mcp/config")
-def get_mcp_config():
-    if not MCP_CONFIG_PATH.exists():
-        fallback_data = {
-            "mcpServers": {
-                "ollama-local": {
-                    "command": "npx",
-                    "args": ["-y", "@modelcontextprotocol/server-ollama", "--host", "localhost"]
-                },
-                "ollama-spark-disabled": {
-                    "command": "npx",
-                    "args": ["-y", "@modelcontextprotocol/server-ollama", "--host", "dgx-spark.tail16d8d9.ts.net"]
-                }
-            }
-        }
-        return {"status": "ok", "raw": json.dumps(fallback_data, indent=2), "file_exists": False, "config": fallback_data}
-        
-    try:
-        with open(MCP_CONFIG_PATH, "r") as f:
-            content = f.read()
-        try:
-            import re
-            clean_content = re.sub(r'//.*', '', content)
-            clean_content = re.sub(r'/\*.*?\*/', '', clean_content, flags=re.DOTALL)
-            if not clean_content.strip():
-                data = {"mcpServers": {}}
-            else:
-                data = json.loads(clean_content)
-        except Exception:
-            data = {"mcpServers": {}}
-        return {"status": "ok", "raw": content, "file_exists": True, "config": data}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to read MCP config: {str(e)}")
-
-@app.post("/api/mcp/save")
-def save_mcp_config(req: SaveMcpRequest):
-    try:
-        data = json.loads(req.config_json)
-        MCP_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
-        with open(MCP_CONFIG_PATH, "w") as f:
-            f.write(req.config_json)
-        return {"status": "ok", "message": "MCP config successfully saved."}
-    except json.JSONDecodeError as e:
-        raise HTTPException(status_code=400, detail=f"Invalid JSON content: {str(e)}")
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to save MCP config: {str(e)}")
-
-@app.post("/api/mcp/toggle")
-def toggle_mcp_server(req: ToggleMcpRequest):
-    if not MCP_CONFIG_PATH.exists():
-        return {"status": "warning", "message": "MCP config file does not exist, changes simulated."}
-        
-    try:
-        with open(MCP_CONFIG_PATH, "r") as f:
-            data = json.load(f)
-            
-        servers = data.get("mcpServers", {})
-        target = req.server_name
-        
-        if req.active:
-            disabled_key = f"{target}-disabled"
-            if disabled_key in servers:
-                servers[target] = servers.pop(disabled_key)
-            elif target not in servers:
-                servers[target] = {"command": "node", "args": []}
-        else:
-            if target in servers:
-                disabled_key = f"{target}-disabled"
-                servers[disabled_key] = servers.pop(target)
-                
-        data["mcpServers"] = servers
-        
-        with open(MCP_CONFIG_PATH, "w") as f:
-            json.dump(data, f, indent=2)
-            
-        return {"status": "ok", "message": f"Server {target} successfully toggled.", "config": data}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to toggle MCP server: {str(e)}")
-
-SSAM_STREETS_PATH = Path("ssam_streets.json")
-
-class AnnotateStreetRequest(BaseModel):
-    street_name: str
-    manual_annotation: str
-
-# ---------------------------------------------------------------------------
-# Statewide California SSAM dataset – representative intersections across
-# all 58 counties with realistic lat/lng, conflict metrics, and severity.
-# ---------------------------------------------------------------------------
-import random as _rng
-_rng.seed(42)
-
-_CA_INTERSECTIONS = [
-    # Northern California
-    {"street_name": "Market St & 4th St", "county": "San Francisco", "lat": 37.7855, "lng": -122.4057, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.2, "max_speed": 12.5},
-    {"street_name": "Mission St & 16th St", "county": "San Francisco", "lat": 37.7651, "lng": -122.4197, "conflict_type": "Lane-change", "min_ttc": 0.5, "min_pet": 0.9, "max_speed": 15.0},
-    {"street_name": "Van Ness Ave & Geary Blvd", "county": "San Francisco", "lat": 37.7863, "lng": -122.4213, "conflict_type": "Crossing", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 11.0},
-    {"street_name": "Broadway & Embarcadero", "county": "San Francisco", "lat": 37.7987, "lng": -122.3974, "conflict_type": "Rear-end", "min_ttc": 1.4, "min_pet": 3.2, "max_speed": 9.0},
-    {"street_name": "Telegraph Ave & Ashby Ave", "county": "Alameda", "lat": 37.8559, "lng": -122.2600, "conflict_type": "Rear-end", "min_ttc": 1.6, "min_pet": 4.5, "max_speed": 8.0},
-    {"street_name": "International Blvd & 73rd Ave", "county": "Alameda", "lat": 37.7530, "lng": -122.1735, "conflict_type": "Crossing", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.2},
-    {"street_name": "Hegenberger Rd & 98th Ave", "county": "Alameda", "lat": 37.7378, "lng": -122.1848, "conflict_type": "Lane-change", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 13.1},
-    {"street_name": "El Camino Real & University Ave", "county": "Santa Clara", "lat": 37.4445, "lng": -122.1633, "conflict_type": "Crossing", "min_ttc": 1.2, "min_pet": 2.3, "max_speed": 10.5},
-    {"street_name": "Stevens Creek Blvd & De Anza Blvd", "county": "Santa Clara", "lat": 37.3232, "lng": -122.0316, "conflict_type": "Rear-end", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.8},
-    {"street_name": "Capitol Expwy & Story Rd", "county": "Santa Clara", "lat": 37.3283, "lng": -121.8500, "conflict_type": "Crossing", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 13.5},
-    {"street_name": "Bascom Ave & Hamilton Ave", "county": "Santa Clara", "lat": 37.3022, "lng": -121.9319, "conflict_type": "Lane-change", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.8},
-    {"street_name": "Broadway Blvd & El Camino", "county": "San Mateo", "lat": 37.4865, "lng": -122.2319, "conflict_type": "Rear-end", "min_ttc": 1.6, "min_pet": 4.5, "max_speed": 8.0},
-    {"street_name": "Hillsdale Blvd & El Camino", "county": "San Mateo", "lat": 37.5395, "lng": -122.2944, "conflict_type": "Crossing", "min_ttc": 1.1, "min_pet": 2.1, "max_speed": 10.2},
-    {"street_name": "Sir Francis Drake Blvd & Hwy 101", "county": "Marin", "lat": 38.0028, "lng": -122.5236, "conflict_type": "Lane-change", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 14.0},
-    {"street_name": "Lincoln Ave & 3rd St", "county": "Marin", "lat": 37.9253, "lng": -122.5113, "conflict_type": "Rear-end", "min_ttc": 1.5, "min_pet": 3.8, "max_speed": 7.5},
-    {"street_name": "Sonoma Blvd & Tennessee St", "county": "Solano", "lat": 38.0993, "lng": -122.2567, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.6, "max_speed": 12.0},
-    {"street_name": "Texas St & Springs Rd", "county": "Solano", "lat": 38.3505, "lng": -121.9619, "conflict_type": "Rear-end", "min_ttc": 1.4, "min_pet": 3.5, "max_speed": 8.5},
-    {"street_name": "Petaluma Blvd S & D St", "county": "Sonoma", "lat": 38.2358, "lng": -122.6404, "conflict_type": "Crossing", "min_ttc": 1.2, "min_pet": 2.4, "max_speed": 9.5},
-    {"street_name": "Mendocino Ave & College Ave", "county": "Sonoma", "lat": 38.4545, "lng": -122.7132, "conflict_type": "Lane-change", "min_ttc": 1.0, "min_pet": 1.9, "max_speed": 11.0},
-    {"street_name": "Contra Costa Blvd & Treat Blvd", "county": "Contra Costa", "lat": 37.9580, "lng": -122.0569, "conflict_type": "Crossing", "min_ttc": 0.7, "min_pet": 1.2, "max_speed": 13.8},
-    {"street_name": "San Pablo Ave & Cutting Blvd", "county": "Contra Costa", "lat": 37.9302, "lng": -122.3564, "conflict_type": "Rear-end", "min_ttc": 1.3, "min_pet": 3.0, "max_speed": 9.2},
-    {"street_name": "Napa Valley Hwy & Imola Ave", "county": "Napa", "lat": 38.2877, "lng": -122.2757, "conflict_type": "Crossing", "min_ttc": 1.5, "min_pet": 3.6, "max_speed": 8.0},
-    # Sacramento / Central Valley
-    {"street_name": "Stockton Blvd & Fruitridge Rd", "county": "Sacramento", "lat": 38.5246, "lng": -121.4579, "conflict_type": "Crossing", "min_ttc": 0.6, "min_pet": 0.9, "max_speed": 15.2},
-    {"street_name": "Watt Ave & Arden Way", "county": "Sacramento", "lat": 38.5987, "lng": -121.3832, "conflict_type": "Rear-end", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 13.0},
-    {"street_name": "Florin Rd & Power Inn Rd", "county": "Sacramento", "lat": 38.4953, "lng": -121.4200, "conflict_type": "Lane-change", "min_ttc": 1.1, "min_pet": 2.2, "max_speed": 11.5},
-    {"street_name": "J St & 16th St", "county": "Sacramento", "lat": 38.5767, "lng": -121.4859, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 10.0},
-    {"street_name": "McHenry Ave & Briggsmore Ave", "county": "Stanislaus", "lat": 37.6649, "lng": -120.9971, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 12.8},
-    {"street_name": "Yosemite Blvd & Coffee Rd", "county": "Stanislaus", "lat": 37.6182, "lng": -120.9517, "conflict_type": "Rear-end", "min_ttc": 1.2, "min_pet": 2.5, "max_speed": 10.0},
-    {"street_name": "Pacific Ave & March Ln", "county": "San Joaquin", "lat": 37.9914, "lng": -121.3258, "conflict_type": "Crossing", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 14.0},
-    {"street_name": "Hammer Ln & I-5", "county": "San Joaquin", "lat": 38.0204, "lng": -121.3536, "conflict_type": "Lane-change", "min_ttc": 0.5, "min_pet": 0.8, "max_speed": 16.5},
-    {"street_name": "Herndon Ave & Blackstone Ave", "county": "Fresno", "lat": 36.8267, "lng": -119.7886, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.4, "max_speed": 12.5},
-    {"street_name": "Shaw Ave & Cedar Ave", "county": "Fresno", "lat": 36.8078, "lng": -119.7696, "conflict_type": "Rear-end", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.2},
-    {"street_name": "Kings Canyon Rd & Clovis Ave", "county": "Fresno", "lat": 36.7268, "lng": -119.7020, "conflict_type": "Lane-change", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.8},
-    {"street_name": "Olive Ave & Chester Ave", "county": "Kern", "lat": 35.3863, "lng": -119.0188, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.0},
-    {"street_name": "White Ln & Wible Rd", "county": "Kern", "lat": 35.3256, "lng": -119.0476, "conflict_type": "Rear-end", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 10.8},
-    {"street_name": "Ming Ave & Ashe Rd", "county": "Kern", "lat": 35.3417, "lng": -119.0713, "conflict_type": "Lane-change", "min_ttc": 0.7, "min_pet": 1.2, "max_speed": 13.5},
-    {"street_name": "Mooney Blvd & Caldwell Ave", "county": "Tulare", "lat": 36.3269, "lng": -119.2883, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.7, "max_speed": 11.5},
-    {"street_name": "G St & Main St", "county": "Merced", "lat": 37.3022, "lng": -120.4829, "conflict_type": "Rear-end", "min_ttc": 1.3, "min_pet": 2.9, "max_speed": 9.5},
-    {"street_name": "Main St & Yosemite Ave", "county": "Madera", "lat": 36.9627, "lng": -120.0608, "conflict_type": "Crossing", "min_ttc": 1.4, "min_pet": 3.1, "max_speed": 8.8},
-    {"street_name": "Court St & D St", "county": "Kings", "lat": 36.3292, "lng": -119.6431, "conflict_type": "Lane-change", "min_ttc": 1.2, "min_pet": 2.4, "max_speed": 10.2},
-    # Southern California
-    {"street_name": "Hollywood Blvd & Highland Ave", "county": "Los Angeles", "lat": 34.1017, "lng": -118.3389, "conflict_type": "Crossing", "min_ttc": 0.4, "min_pet": 0.7, "max_speed": 16.0},
-    {"street_name": "Sunset Blvd & Vine St", "county": "Los Angeles", "lat": 34.0982, "lng": -118.3266, "conflict_type": "Lane-change", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.5},
-    {"street_name": "La Brea Ave & Wilshire Blvd", "county": "Los Angeles", "lat": 34.0621, "lng": -118.3441, "conflict_type": "Rear-end", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 13.0},
-    {"street_name": "Figueroa St & 7th St", "county": "Los Angeles", "lat": 34.0490, "lng": -118.2590, "conflict_type": "Crossing", "min_ttc": 0.5, "min_pet": 0.8, "max_speed": 15.5},
-    {"street_name": "Vermont Ave & MLK Blvd", "county": "Los Angeles", "lat": 33.9917, "lng": -118.2917, "conflict_type": "Crossing", "min_ttc": 0.3, "min_pet": 0.5, "max_speed": 17.2},
-    {"street_name": "Century Blvd & Crenshaw Blvd", "county": "Los Angeles", "lat": 33.9461, "lng": -118.3302, "conflict_type": "Lane-change", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 14.0},
-    {"street_name": "PCH & Sunset Blvd", "county": "Los Angeles", "lat": 34.0411, "lng": -118.5266, "conflict_type": "Rear-end", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.0},
-    {"street_name": "Sepulveda Blvd & National Blvd", "county": "Los Angeles", "lat": 34.0223, "lng": -118.3973, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.5},
-    {"street_name": "Harbor Blvd & Chapman Ave", "county": "Orange", "lat": 33.8316, "lng": -117.9178, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 12.8},
-    {"street_name": "Beach Blvd & Edinger Ave", "county": "Orange", "lat": 33.7582, "lng": -117.9974, "conflict_type": "Rear-end", "min_ttc": 1.1, "min_pet": 2.1, "max_speed": 10.5},
-    {"street_name": "Bristol St & MacArthur Blvd", "county": "Orange", "lat": 33.6814, "lng": -117.8855, "conflict_type": "Lane-change", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.2},
-    {"street_name": "Euclid St & Lincoln Ave", "county": "Orange", "lat": 33.8381, "lng": -117.9462, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.7, "max_speed": 11.5},
-    {"street_name": "University Ave & Iowa Ave", "county": "Riverside", "lat": 33.9716, "lng": -117.3431, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.2},
-    {"street_name": "Van Buren Blvd & Arlington Ave", "county": "Riverside", "lat": 33.9250, "lng": -117.4347, "conflict_type": "Rear-end", "min_ttc": 1.2, "min_pet": 2.5, "max_speed": 10.0},
-    {"street_name": "Date Palm Dr & Ramon Rd", "county": "Riverside", "lat": 33.7381, "lng": -116.3622, "conflict_type": "Lane-change", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.8},
-    {"street_name": "Mt Vernon Ave & Mill St", "county": "San Bernardino", "lat": 34.0689, "lng": -117.2838, "conflict_type": "Crossing", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 13.5},
-    {"street_name": "Foothill Blvd & Vineyard Ave", "county": "San Bernardino", "lat": 34.1069, "lng": -117.5884, "conflict_type": "Rear-end", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Bear Valley Rd & Hesperia Rd", "county": "San Bernardino", "lat": 34.4504, "lng": -117.3120, "conflict_type": "Lane-change", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 14.0},
-    {"street_name": "El Cajon Blvd & 30th St", "county": "San Diego", "lat": 32.7594, "lng": -117.1297, "conflict_type": "Crossing", "min_ttc": 0.7, "min_pet": 1.2, "max_speed": 13.0},
-    {"street_name": "Balboa Ave & Genesee Ave", "county": "San Diego", "lat": 32.8207, "lng": -117.1810, "conflict_type": "Rear-end", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 10.8},
-    {"street_name": "University Ave & Fairmount Ave", "county": "San Diego", "lat": 32.7490, "lng": -117.1062, "conflict_type": "Lane-change", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.5},
-    {"street_name": "Broadway & E St", "county": "San Diego", "lat": 32.7170, "lng": -117.1631, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "Palm Canyon Dr & Tahquitz Canyon Way", "county": "Riverside", "lat": 33.8254, "lng": -116.5453, "conflict_type": "Crossing", "min_ttc": 1.4, "min_pet": 3.2, "max_speed": 8.5},
-    {"street_name": "State St & De La Vina St", "county": "Santa Barbara", "lat": 34.4275, "lng": -119.7089, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.7, "max_speed": 9.8},
-    {"street_name": "Milpas St & Haley St", "county": "Santa Barbara", "lat": 34.4188, "lng": -119.6879, "conflict_type": "Rear-end", "min_ttc": 1.5, "min_pet": 3.5, "max_speed": 8.2},
-    {"street_name": "Ventura Blvd & Laurel Canyon Blvd", "county": "Ventura", "lat": 34.1543, "lng": -118.3975, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 13.0},
-    {"street_name": "Victoria Ave & Telephone Rd", "county": "Ventura", "lat": 34.2599, "lng": -119.2187, "conflict_type": "Lane-change", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Johnson Ave & Grand Ave", "county": "San Luis Obispo", "lat": 35.2697, "lng": -120.6597, "conflict_type": "Crossing", "min_ttc": 1.4, "min_pet": 3.0, "max_speed": 9.0},
-    {"street_name": "El Camino Real & Atascadero Ave", "county": "San Luis Obispo", "lat": 35.4872, "lng": -120.6726, "conflict_type": "Rear-end", "min_ttc": 1.6, "min_pet": 4.0, "max_speed": 7.5},
-    {"street_name": "Main St & Pine St", "county": "Monterey", "lat": 36.5949, "lng": -121.8957, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "N Main St & Alisal St", "county": "Monterey", "lat": 36.6705, "lng": -121.6558, "conflict_type": "Rear-end", "min_ttc": 1.0, "min_pet": 1.7, "max_speed": 11.8},
-    {"street_name": "River Park Dr & W Sacramento Ave", "county": "Yolo", "lat": 38.5791, "lng": -121.5520, "conflict_type": "Crossing", "min_ttc": 1.2, "min_pet": 2.3, "max_speed": 10.5},
-    {"street_name": "Bridge St & Main St", "county": "Yuba", "lat": 39.1394, "lng": -121.6147, "conflict_type": "Rear-end", "min_ttc": 1.5, "min_pet": 3.6, "max_speed": 8.0},
-    {"street_name": "10th St & E St", "county": "Yuba", "lat": 39.1413, "lng": -121.6093, "conflict_type": "Crossing", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 10.8},
-    {"street_name": "Colusa Ave & Sutter St", "county": "Sutter", "lat": 39.1451, "lng": -121.6207, "conflict_type": "Lane-change", "min_ttc": 1.3, "min_pet": 2.7, "max_speed": 9.5},
-    {"street_name": "East Ave & Lindo Channel", "county": "Butte", "lat": 39.7520, "lng": -121.8089, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Mangrove Ave & E 20th St", "county": "Butte", "lat": 39.7593, "lng": -121.8387, "conflict_type": "Rear-end", "min_ttc": 1.2, "min_pet": 2.4, "max_speed": 10.2},
-    {"street_name": "Hilltop Dr & Cypress Ave", "county": "Shasta", "lat": 40.5889, "lng": -122.3503, "conflict_type": "Crossing", "min_ttc": 1.1, "min_pet": 2.1, "max_speed": 10.8},
-    {"street_name": "Market St & Placer St", "county": "Shasta", "lat": 40.5855, "lng": -122.3916, "conflict_type": "Lane-change", "min_ttc": 1.4, "min_pet": 3.2, "max_speed": 8.5},
-    {"street_name": "Pine St & S Oregon St", "county": "Siskiyou", "lat": 41.7271, "lng": -122.6362, "conflict_type": "Rear-end", "min_ttc": 1.6, "min_pet": 4.2, "max_speed": 7.0},
-    {"street_name": "S Mt Shasta Blvd & E Alma St", "county": "Siskiyou", "lat": 41.3132, "lng": -122.3103, "conflict_type": "Crossing", "min_ttc": 1.5, "min_pet": 3.5, "max_speed": 8.0},
-    {"street_name": "Riverside Dr & Court St", "county": "Humboldt", "lat": 40.7854, "lng": -124.1576, "conflict_type": "Crossing", "min_ttc": 1.2, "min_pet": 2.3, "max_speed": 10.5},
-    {"street_name": "4th St & C St", "county": "Humboldt", "lat": 40.7872, "lng": -124.1565, "conflict_type": "Rear-end", "min_ttc": 1.4, "min_pet": 3.0, "max_speed": 9.0},
-    {"street_name": "Main St & Perkins St", "county": "Mendocino", "lat": 39.1503, "lng": -123.2072, "conflict_type": "Crossing", "min_ttc": 1.5, "min_pet": 3.5, "max_speed": 8.2},
-    {"street_name": "S State St & Perkins St", "county": "Mendocino", "lat": 39.1481, "lng": -123.2052, "conflict_type": "Lane-change", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "Spring St & Washington St", "county": "Nevada", "lat": 39.2627, "lng": -121.0172, "conflict_type": "Crossing", "min_ttc": 1.4, "min_pet": 3.1, "max_speed": 8.8},
-    {"street_name": "Auburn Folsom Rd & Douglas Blvd", "county": "Placer", "lat": 38.7516, "lng": -121.2563, "conflict_type": "Rear-end", "min_ttc": 1.1, "min_pet": 2.1, "max_speed": 11.0},
-    {"street_name": "Lincoln Way & Sunrise Ave", "county": "Placer", "lat": 38.7360, "lng": -121.2301, "conflict_type": "Lane-change", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.5},
-    {"street_name": "Placerville Dr & Missouri Flat Rd", "county": "El Dorado", "lat": 38.7222, "lng": -120.8263, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.7, "max_speed": 9.8},
-    {"street_name": "Main St & Jackson Gate Rd", "county": "Amador", "lat": 38.3487, "lng": -120.7732, "conflict_type": "Rear-end", "min_ttc": 1.6, "min_pet": 4.0, "max_speed": 7.5},
-    {"street_name": "Main St & Mono Way", "county": "Tuolumne", "lat": 37.9817, "lng": -120.3825, "conflict_type": "Crossing", "min_ttc": 1.4, "min_pet": 3.2, "max_speed": 8.5},
-    {"street_name": "E St & 12th St", "county": "Imperial", "lat": 32.7924, "lng": -115.5631, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Main St & 8th St", "county": "Imperial", "lat": 32.8426, "lng": -115.5681, "conflict_type": "Rear-end", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "Barstow Rd & Main St", "county": "San Bernardino", "lat": 34.8987, "lng": -117.0226, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.5},
-    # Additional urban hotspots
-    {"street_name": "Rosecrans Ave & Hawthorne Blvd", "county": "Los Angeles", "lat": 33.9014, "lng": -118.3525, "conflict_type": "Crossing", "min_ttc": 0.5, "min_pet": 0.8, "max_speed": 15.5},
-    {"street_name": "Atlantic Ave & Florence Ave", "county": "Los Angeles", "lat": 33.9725, "lng": -118.1547, "conflict_type": "Rear-end", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 13.8},
-    {"street_name": "Valley Blvd & Peck Rd", "county": "Los Angeles", "lat": 34.0752, "lng": -118.0277, "conflict_type": "Lane-change", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 12.5},
-    {"street_name": "Foothill Blvd & Towne Ave", "county": "Los Angeles", "lat": 34.1238, "lng": -117.6477, "conflict_type": "Crossing", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.2},
-    {"street_name": "Indian Ave & I-10", "county": "Riverside", "lat": 33.8680, "lng": -116.5092, "conflict_type": "Lane-change", "min_ttc": 0.7, "min_pet": 1.2, "max_speed": 15.0},
-    {"street_name": "Magnolia Ave & Adams St", "county": "Riverside", "lat": 33.9568, "lng": -117.3657, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.4, "max_speed": 12.8},
-    {"street_name": "Holt Blvd & Garey Ave", "county": "Los Angeles", "lat": 34.0590, "lng": -117.7513, "conflict_type": "Crossing", "min_ttc": 0.6, "min_pet": 1.0, "max_speed": 14.5},
-    {"street_name": "Katella Ave & State College Blvd", "county": "Orange", "lat": 33.8056, "lng": -117.8847, "conflict_type": "Rear-end", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.2},
-    {"street_name": "Brookhurst St & Adams Ave", "county": "Orange", "lat": 33.7767, "lng": -117.9380, "conflict_type": "Lane-change", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Tustin St & Edinger Ave", "county": "Orange", "lat": 33.7795, "lng": -117.8175, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 13.0},
-    {"street_name": "Vista Way & Melrose Dr", "county": "San Diego", "lat": 33.2001, "lng": -117.2412, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Mission Ave & College Blvd", "county": "San Diego", "lat": 33.1169, "lng": -117.1580, "conflict_type": "Rear-end", "min_ttc": 1.2, "min_pet": 2.3, "max_speed": 10.5},
-    {"street_name": "Palomar St & Broadway", "county": "San Diego", "lat": 32.6224, "lng": -117.0887, "conflict_type": "Lane-change", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.5},
-    # Rural / mountain / desert
-    {"street_name": "Tehachapi Blvd & Tucker Rd", "county": "Kern", "lat": 35.1335, "lng": -118.4498, "conflict_type": "Crossing", "min_ttc": 1.5, "min_pet": 3.5, "max_speed": 8.0},
-    {"street_name": "Grass Valley Hwy & Combie Rd", "county": "Nevada", "lat": 39.2019, "lng": -121.0603, "conflict_type": "Rear-end", "min_ttc": 1.4, "min_pet": 3.2, "max_speed": 8.5},
-    {"street_name": "Main St & Quincy Junction Rd", "county": "Plumas", "lat": 39.9369, "lng": -120.9466, "conflict_type": "Crossing", "min_ttc": 1.6, "min_pet": 4.0, "max_speed": 7.0},
-    {"street_name": "Lassen Ave & Antelope Blvd", "county": "Tehama", "lat": 40.1725, "lng": -122.2393, "conflict_type": "Rear-end", "min_ttc": 1.5, "min_pet": 3.8, "max_speed": 7.5},
-    {"street_name": "Main St & Center St", "county": "Lassen", "lat": 40.1767, "lng": -120.6359, "conflict_type": "Crossing", "min_ttc": 1.6, "min_pet": 4.2, "max_speed": 7.0},
-    {"street_name": "Main St & S Fir St", "county": "Modoc", "lat": 41.4483, "lng": -120.5419, "conflict_type": "Rear-end", "min_ttc": 1.7, "min_pet": 4.5, "max_speed": 6.5},
-    {"street_name": "N Mt Shasta Blvd & Chestnut St", "county": "Siskiyou", "lat": 41.3148, "lng": -122.3098, "conflict_type": "Lane-change", "min_ttc": 1.5, "min_pet": 3.5, "max_speed": 8.0},
-    {"street_name": "W Sacramento Ave & Jefferson Blvd", "county": "Yolo", "lat": 38.5819, "lng": -121.5307, "conflict_type": "Rear-end", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "Elk Grove Blvd & Laguna Blvd", "county": "Sacramento", "lat": 38.4088, "lng": -121.3716, "conflict_type": "Crossing", "min_ttc": 0.8, "min_pet": 1.3, "max_speed": 13.0},
-    {"street_name": "Sunrise Blvd & Greenback Ln", "county": "Sacramento", "lat": 38.6764, "lng": -121.2744, "conflict_type": "Lane-change", "min_ttc": 0.7, "min_pet": 1.1, "max_speed": 14.0},
-    {"street_name": "Lone Tree Blvd & Main St", "county": "Contra Costa", "lat": 37.9870, "lng": -121.7832, "conflict_type": "Crossing", "min_ttc": 1.0, "min_pet": 1.8, "max_speed": 11.5},
-    {"street_name": "Ygnacio Valley Rd & Bancroft Rd", "county": "Contra Costa", "lat": 37.9270, "lng": -122.0001, "conflict_type": "Rear-end", "min_ttc": 1.2, "min_pet": 2.3, "max_speed": 10.5},
-    {"street_name": "Santa Rosa Ave & Todd Rd", "county": "Sonoma", "lat": 38.3972, "lng": -122.7055, "conflict_type": "Lane-change", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 11.0},
-    {"street_name": "Cleveland Ave & Piner Rd", "county": "Sonoma", "lat": 38.4559, "lng": -122.7455, "conflict_type": "Crossing", "min_ttc": 0.9, "min_pet": 1.5, "max_speed": 12.0},
-    {"street_name": "S China Lake Blvd & W Ridgecrest Blvd", "county": "Kern", "lat": 35.6226, "lng": -117.6709, "conflict_type": "Crossing", "min_ttc": 1.3, "min_pet": 2.8, "max_speed": 9.5},
-    {"street_name": "Ventura Rd & 5th St", "county": "Ventura", "lat": 34.2022, "lng": -119.1776, "conflict_type": "Crossing", "min_ttc": 1.1, "min_pet": 2.0, "max_speed": 10.8},
-]
-
-# Add an id and manual_annotation to each record
-for _i, _rec in enumerate(_CA_INTERSECTIONS):
-    _rec["id"] = f"CA-SSAM-{_i+1:04d}"
-    _rec.setdefault("manual_annotation", "")
-
-
-def _compute_severity(ttc: float, pet: float, max_speed: float) -> dict:
-    """Return severity_index (0-1) and severity_label."""
-    score = 1.0 - (min(ttc, 1.5) / 1.5) * 0.5 - (min(pet, 5.0) / 5.0) * 0.2 - (1.0 - min(max_speed, 18.0) / 18.0) * 0.3
-    score = round(max(0.0, min(1.0, score)), 3)
-    if score >= 0.7:
-        label = "Critical"
-    elif score >= 0.45:
-        label = "High"
-    elif score >= 0.25:
-        label = "Medium"
-    else:
-        label = "Low"
-    return {"severity_index": score, "severity_label": label}
-
-
-def load_streets_db():
-    """Backwards-compatible loader; returns the old 3-row file if it exists."""
-    if not SSAM_STREETS_PATH.exists():
-        default_streets = [
-            {"street_name": "Market St & 4th St", "min_ttc": 0.8, "min_pet": 1.2, "max_speed": 12.5, "conflict_type": "Crossing", "manual_annotation": ""},
-            {"street_name": "Broadway Blvd", "min_ttc": 1.6, "min_pet": 4.5, "max_speed": 8.0, "conflict_type": "Rear-end", "manual_annotation": "High rear-end conflict frequency during commute hours"},
-            {"street_name": "Mission St & 16th St", "min_ttc": 0.5, "min_pet": 0.9, "max_speed": 15.0, "conflict_type": "Lane-change", "manual_annotation": ""},
-        ]
-        with open(SSAM_STREETS_PATH, "w") as f:
-            json.dump(default_streets, f, indent=2)
-        return default_streets
-    try:
-        with open(SSAM_STREETS_PATH, "r") as f:
-            return json.load(f)
-    except Exception:
-        return []
-
-
-# Legacy endpoint – kept for backward compatibility
-@app.get("/api/ssam/streets")
-def get_ssam_streets():
-    streets = load_streets_db()
-    for st in streets:
-        ttc = st.get("min_ttc", 1.5)
-        pet = st.get("min_pet", 5.0)
-        score = 1.0 - (min(ttc, 1.5) / 1.5) * 0.7 - (min(pet, 5.0) / 5.0) * 0.3
-        st["severity_index"] = round(max(0.0, min(1.0, score)), 2)
-    return {"status": "ok", "streets": streets}
-
-
-# -----------------------------------------------------------------------
-# NEW: Statewide endpoint with filtering + pagination + map points
-# -----------------------------------------------------------------------
-class StatewideQuery(BaseModel):
-    counties: Optional[List[str]] = None
-    conflict_types: Optional[List[str]] = None
-    severity_labels: Optional[List[str]] = None
-    ttc_max: Optional[float] = None
-    speed_min: Optional[float] = None
-    page: int = 1
-    page_size: int = 25
-    sort_by: str = "severity_index"
-    sort_dir: str = "desc"
-    search: Optional[str] = None
-
-
-@app.post("/api/ssam/statewide")
-def get_ssam_statewide(q: StatewideQuery):
-    """Return filtered, paginated SSAM records + GeoJSON points for the map."""
-    # Compute severity for every record
-    enriched = []
-    for rec in _CA_INTERSECTIONS:
-        sev = _compute_severity(rec["min_ttc"], rec["min_pet"], rec["max_speed"])
-        row = {**rec, **sev}
-        enriched.append(row)
-
-    # Apply filters
-    filtered = enriched
-    if q.counties:
-        lc = [c.lower() for c in q.counties]
-        filtered = [r for r in filtered if r["county"].lower() in lc]
-    if q.conflict_types:
-        lc = [c.lower() for c in q.conflict_types]
-        filtered = [r for r in filtered if r["conflict_type"].lower() in lc]
-    if q.severity_labels:
-        lc = [c.lower() for c in q.severity_labels]
-        filtered = [r for r in filtered if r["severity_label"].lower() in lc]
-    if q.ttc_max is not None:
-        filtered = [r for r in filtered if r["min_ttc"] <= q.ttc_max]
-    if q.speed_min is not None:
-        filtered = [r for r in filtered if r["max_speed"] >= q.speed_min]
-    if q.search:
-        term = q.search.lower()
-        filtered = [r for r in filtered if term in r["street_name"].lower() or term in r["county"].lower()]
-
-    # Sort
-    reverse = q.sort_dir.lower() == "desc"
-    if q.sort_by in ("severity_index", "min_ttc", "min_pet", "max_speed"):
-        filtered.sort(key=lambda r: r.get(q.sort_by, 0), reverse=reverse)
-    elif q.sort_by == "county":
-        filtered.sort(key=lambda r: r.get("county", ""), reverse=reverse)
-    elif q.sort_by == "street_name":
-        filtered.sort(key=lambda r: r.get("street_name", ""), reverse=reverse)
-
-    total = len(filtered)
-    total_pages = max(1, (total + q.page_size - 1) // q.page_size)
-    page = max(1, min(q.page, total_pages))
-    start = (page - 1) * q.page_size
-    page_rows = filtered[start:start + q.page_size]
-
-    # Build GeoJSON features for ALL filtered records (for the map)
-    features = []
-    for r in filtered:
-        features.append({
-            "type": "Feature",
-            "geometry": {"type": "Point", "coordinates": [r["lng"], r["lat"]]},
-            "properties": {
-                "id": r["id"],
-                "street_name": r["street_name"],
-                "county": r["county"],
-                "conflict_type": r["conflict_type"],
-                "min_ttc": r["min_ttc"],
-                "min_pet": r["min_pet"],
-                "max_speed": r["max_speed"],
-                "severity_index": r["severity_index"],
-                "severity_label": r["severity_label"],
-            }
-        })
-
-    # Summary stats per severity
-    summary = {"Critical": 0, "High": 0, "Medium": 0, "Low": 0}
-    for r in filtered:
-        summary[r["severity_label"]] = summary.get(r["severity_label"], 0) + 1
-
-    # Unique counties and conflict types (for filter dropdowns)
-    all_counties = sorted({r["county"] for r in enriched})
-    all_conflict_types = sorted({r["conflict_type"] for r in enriched})
-
-    return {
-        "status": "ok",
-        "total": total,
-        "page": page,
-        "page_size": q.page_size,
-        "total_pages": total_pages,
-        "rows": page_rows,
-        "geojson": {"type": "FeatureCollection", "features": features},
-        "summary": summary,
-        "filter_options": {
-            "counties": all_counties,
-            "conflict_types": all_conflict_types,
-            "severity_labels": ["Critical", "High", "Medium", "Low"],
-        },
-    }
-
-
-@app.post("/api/ssam/annotate")
-def annotate_street(req: AnnotateStreetRequest):
-    streets = load_streets_db()
-    found = False
-    for st in streets:
-        if st["street_name"] == req.street_name:
-            st["manual_annotation"] = req.manual_annotation
-            found = True
-            break
-    if not found:
-        streets.append({
-            "street_name": req.street_name,
-            "min_ttc": 1.5,
-            "min_pet": 5.0,
-            "max_speed": 0.0,
-            "conflict_type": "Rear-end",
-            "manual_annotation": req.manual_annotation
-        })
-    with open(SSAM_STREETS_PATH, "w") as f:
-        json.dump(streets, f, indent=2)
-    return {"status": "ok", "message": f"Annotation saved for {req.street_name}"}
-
-# -----------------------------------------------------------------------
-# 3D Perception Pipeline Routes
-# -----------------------------------------------------------------------
-
-class IngestParams(BaseModel):
-    vendors: List[str] = ["alpamayo", "waymo"]
-    sequence_id: str = "seq_001"
-
-class AutoLabelParams(BaseModel):
-    sequence_id: str = "seq_001"
-    sam_checkpoint: str = "models/sam_vit_b.pth"
-    device: str = "cpu"
-    no_sam: bool = False
-
-class TrackParams(BaseModel):
-    sequence_id: str = "seq_001"
-
-class BenchmarkParams(BaseModel):
-    sequence_id: str = "seq_001"
-
-class GateParams(BaseModel):
-    sequence_id: str = "seq_001"
-
-
-@app.post("/api/dataset/ingest")
-def ingest_dataset(params: IngestParams):
-    from sensorflow.dataset_fusion_engine import DatasetFusionEngine
-    try:
-        engine = DatasetFusionEngine()
-        sequence = engine.ingest(params.vendors, params.sequence_id)
-        manifest_path = engine.save_manifest(sequence)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Ingest failed: {str(e)}")
-
-    config = load_config()
-    config.sequence_id = params.sequence_id
-    config.vendors = params.vendors
-    with open(CONFIG_PATH, "w") as f:
-        json.dump(config.model_dump(), f, indent=2)
-
-    return {"status": "ok", "manifest": str(manifest_path), "sequence_id": params.sequence_id}
-
-
-@app.get("/api/dataset/ingest/status")
-def ingest_status(sequence_id: str = "seq_001"):
-    from sensorflow.dataset_fusion_engine import DatasetFusionEngine
-    engine = DatasetFusionEngine()
-    status = engine.get_status(sequence_id)
-    manifest = Path("runs/pipeline") / sequence_id / "manifest.json"
-    if manifest.exists():
-        with open(manifest) as f:
-            manifest_data = json.load(f)
-        status["manifest_exists"] = True
-        status["frames"] = len(manifest_data.get("frames", []))
-        status["vendor"] = manifest_data.get("vendor", "unknown")
-    return {"status": "ok", "sequence_id": sequence_id, **status}
-
-
-@app.post("/api/perception/auto-label")
-def auto_label(params: AutoLabelParams):
-    from sensorflow.perception_automator import PerceptionAutomator
-    from sensorflow.schemas.unified_frame import UnifiedSequence
-
-    manifest = Path("runs/pipeline") / params.sequence_id / "manifest.json"
-    if not manifest.exists():
-        raise HTTPException(status_code=400, detail="Manifest not found. Run ingest first.")
-
-    try:
-        sequence = UnifiedSequence.load(manifest)
-        output_dir = manifest.parent / "proposals"
-        automator = PerceptionAutomator(
-            sam_checkpoint=params.sam_checkpoint,
-            device=params.device,
-            use_sam=not params.no_sam,
-        )
-        automator.run_sequence(sequence, output_dir)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Auto-label failed: {str(e)}")
-
-    proposals_dir = manifest.parent / "proposals"
-    num_frames = len(list(proposals_dir.glob("*.json"))) if proposals_dir.exists() else 0
-    return {"status": "ok", "proposals_dir": str(proposals_dir), "frames_processed": num_frames}
-
-
-@app.post("/api/perception/track")
-def run_tracking(params: TrackParams):
-    from sensorflow.temporal_tracker import TemporalTracker
-
-    proposals_dir = Path("runs/pipeline") / params.sequence_id / "proposals"
-    if not proposals_dir.exists():
-        raise HTTPException(status_code=400, detail="Proposals not found. Run auto-label first.")
-
-    output = Path("runs/pipeline") / params.sequence_id / "tracks.json"
-    try:
-        tracker = TemporalTracker()
-        proposals = TemporalTracker.load_proposals(proposals_dir)
-        tracks = tracker.run_sequence(proposals, output)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Tracking failed: {str(e)}")
-
-    return {"status": "ok", "tracks_file": str(output), "num_tracks": len(tracks)}
-
-
-@app.post("/api/benchmark")
-def run_benchmark(params: BenchmarkParams):
-    from sensorflow.quality_gate import QualityGate
-    from sensorflow.schemas.unified_frame import UnifiedSequence
-
-    manifest = Path("runs/pipeline") / params.sequence_id / "manifest.json"
-    tracks_path = Path("runs/pipeline") / params.sequence_id / "tracks.json"
-    if not manifest.exists():
-        raise HTTPException(status_code=400, detail="Manifest not found.")
-
-    try:
-        sequence = UnifiedSequence.load(manifest)
-        pred_tracks = json.loads(tracks_path.read_text()) if tracks_path.exists() else []
-        gate = QualityGate()
-        results = gate.evaluate(sequence, pred_tracks)
-        gate.save_results(params.sequence_id, results)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Benchmark failed: {str(e)}")
-
-    return {"status": "ok", "metrics": results["metric_card"]}
-
-
-@app.post("/api/gates/quality")
-def quality_gate_eval(params: GateParams):
-    from sensorflow.quality_gate import QualityGate
-    from sensorflow.mitl_copilot import MitlCopilot
-    from sensorflow.schemas.unified_frame import UnifiedSequence
-
-    manifest = Path("runs/pipeline") / params.sequence_id / "manifest.json"
-    tracks_path = Path("runs/pipeline") / params.sequence_id / "tracks.json"
-    if not manifest.exists() or not tracks_path.exists():
-        raise HTTPException(status_code=400, detail="Run ingest, auto-label, and track first.")
-
-    try:
-        sequence = UnifiedSequence.load(manifest)
-        with open(tracks_path) as f:
-            pred_tracks = json.load(f)
-        gate = QualityGate()
-        results = gate.evaluate(sequence, pred_tracks)
-        gate.save_results(params.sequence_id, results)
-        if not results["passed"]:
-            copilot = MitlCopilot()
-            copilot.route_edge_cases(params.sequence_id, results["metric_card"], pred_tracks)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Quality gate failed: {str(e)}")
-
-    report = results["quality_report"]
-    return {"status": "ok", "metric_card": results["metric_card"], **report}
-
-
-@app.post("/api/gates/launch")
-def launch_gate_eval(params: GateParams):
-    from sensorflow.launch_gate_evaluator import LaunchGateEvaluator
-    config = load_config()
-    evaluator = LaunchGateEvaluator(Path(config.gate_thresholds_path))
-    result = evaluator.evaluate(params.sequence_id)
-    return {"status": "ok", **result}
-
-
-@app.get("/api/pipeline/status")
-def pipeline_status(sequence_id: str = "seq_001"):
-    state_path = Path("runs/pipeline/state.json")
-    state = {}
-    if state_path.exists():
-        with open(state_path) as f:
-            state = json.load(f)
-
-    seq_state = state.get(sequence_id, {})
-    base = Path("runs/pipeline") / sequence_id
-    return {
-        "status": "ok",
-        "sequence_id": sequence_id,
-        "ingest_complete": (base / "manifest.json").exists(),
-        "perception_complete": (base / "proposals").exists() and any((base / "proposals").glob("*.json")),
-        "tracking_complete": (base / "tracks.json").exists(),
-        "benchmark_complete": (base / "benchmark" / "metric_card.json").exists(),
-        "launch_gate_passed": seq_state.get("launch_gate_passed", False),
-        "state": seq_state,
-    }
-
-
-@app.get("/api/mitl/queue")
-def get_mitl_queue(sequence_id: str = "seq_001"):
-    from sensorflow.mitl_copilot import MitlCopilot
-    copilot = MitlCopilot()
-    return {"status": "ok", "queue": copilot.get_queue(sequence_id)}
-
-
-# L4 Perception Label Evaluation platform routes (must precede the static mount).
-from sensorflow.evaluation.api import router as labeleval_router
-app.include_router(labeleval_router)
-
-# Aggregate-first mega-scale evaluation layer (metric cube, async runs, query API).
-from sensorflow.megaeval.api import router as megaeval_router
-app.include_router(megaeval_router)
-
-# BEV-Fusion perception engine (camera+LiDAR fusion, masklet tracking, self-eval).
-from sensorflow.bevfusion.api import router as bevfusion_router
-app.include_router(bevfusion_router)
-
-# Mount static folder
-static_dir = Path(__file__).parent / "static"
-if static_dir.exists():
-    app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="static")
-
-if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run("app_backend:app", host="127.0.0.1", port=8000, reload=True)

hf-space/autograder.py

@@ -1,128 +0,0 @@
-#!/usr/bin/env python3
-"""2D prediction quality autograder."""
-
-import argparse
-import json
-from collections import Counter
-from pathlib import Path
-from typing import Dict, List
-
-
-def compute_iou(box_a: Dict, box_b: Dict) -> float:
-    x1 = max(box_a["x1"], box_b["x1"])
-    y1 = max(box_a["y1"], box_b["y1"])
-    x2 = min(box_a["x2"], box_b["x2"])
-    y2 = min(box_a["y2"], box_b["y2"])
-    inter = max(0, x2 - x1) * max(0, y2 - y1)
-    area_a = (box_a["x2"] - box_a["x1"]) * (box_a["y2"] - box_a["y1"])
-    area_b = (box_b["x2"] - box_b["x1"]) * (box_b["y2"] - box_b["y1"])
-    union = area_a + area_b - inter
-    return inter / union if union > 0 else 0.0
-
-
-def grade_predictions(predictions: List[Dict], conf_threshold: float = 0.5) -> Dict:
-    issues = []
-    issue_summary = Counter()
-    images = set(p["image"] for p in predictions)
-    classes = [p["class_name"] for p in predictions]
-
-    for i, pred in enumerate(predictions):
-        if pred["confidence"] < conf_threshold:
-            issue_summary["low_confidence"] += 1
-            issues.append({
-                "severity": "WARNING",
-                "type": "low_confidence",
-                "image": pred["image"],
-                "detection_id": i,
-                "confidence": pred["confidence"],
-                "threshold": conf_threshold,
-                "message": f"Confidence {pred['confidence']:.2f} below threshold",
-            })
-
-        bbox = pred["bbox"]
-        area = (bbox["x2"] - bbox["x1"]) * (bbox["y2"] - bbox["y1"])
-        if area < 100:
-            issue_summary["small_detection"] += 1
-            issues.append({
-                "severity": "INFO",
-                "type": "small_detection",
-                "image": pred["image"],
-                "detection_id": i,
-                "confidence": pred["confidence"],
-                "threshold": 100,
-                "message": f"Small bounding box area: {area:.0f}px",
-            })
-
-    for i, pred_a in enumerate(predictions):
-        for j, pred_b in enumerate(predictions):
-            if j <= i or pred_a["image"] != pred_b["image"]:
-                continue
-            if pred_a["class_name"] != pred_b["class_name"]:
-                iou = compute_iou(pred_a["bbox"], pred_b["bbox"])
-                if iou > 0.5:
-                    issue_summary["overlapping_different_class"] += 1
-                    issues.append({
-                        "severity": "WARNING",
-                        "type": "overlapping_different_class",
-                        "image": pred_a["image"],
-                        "detection_id": i,
-                        "confidence": pred_a["confidence"],
-                        "threshold": 0.5,
-                        "message": f"Overlap between {pred_a['class_name']} and {pred_b['class_name']}",
-                    })
-
-    class_counts = Counter(classes)
-    if class_counts:
-        dominant = class_counts.most_common(1)[0]
-        if dominant[1] / len(classes) > 0.8:
-            issue_summary["class_imbalance"] += 1
-
-    total_issues = sum(issue_summary.values())
-    quality_score = max(0, 100 - total_issues * 5)
-
-    return {
-        "total_predictions": len(predictions),
-        "total_images": len(images),
-        "quality_score": quality_score,
-        "issues_by_severity": dict(Counter(i["severity"] for i in issues)),
-        "issue_summary": dict(issue_summary),
-        "flagged_issues": issues[:50],
-        "recommendations": _recommendations(issue_summary),
-    }
-
-
-def _recommendations(summary: Counter) -> List[str]:
-    recs = []
-    if summary.get("low_confidence"):
-        recs.append("Tune confidence threshold or retrain with more diverse samples.")
-    if summary.get("overlapping_different_class"):
-        recs.append("Review overlapping class labels; consider NMS tuning.")
-    if summary.get("small_detection"):
-        recs.append("Verify small bounding boxes are valid annotations.")
-    if summary.get("class_imbalance"):
-        recs.append("Balance class frequency in training dataset.")
-    if not recs:
-        recs.append("No significant issues detected.")
-    return recs
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Grade 2D predictions")
-    parser.add_argument("--predictions", required=True)
-    parser.add_argument("--output", default=None)
-    parser.add_argument("--conf", type=float, default=0.5)
-    args = parser.parse_args()
-
-    pred_path = Path(args.predictions)
-    with open(pred_path) as f:
-        predictions = json.load(f)
-
-    report = grade_predictions(predictions, args.conf)
-    output_path = Path(args.output) if args.output else pred_path.parent / "quality_report.json"
-    with open(output_path, "w") as f:
-        json.dump(report, f, indent=2)
-    print(f"Quality score: {report['quality_score']}/100 -> {output_path}")
-
-
-if __name__ == "__main__":
-    main()

hf-space/coco8.yaml

@@ -1,21 +0,0 @@
-# Ultralytics YOLO 🚀, AGPL-3.0 license
-# COCO8 dataset by Ultralytics
-# Documentation: https://docs.ultralytics.com/datasets/detect/coco8/
-
-# Dataset root directory
-path: ./datasets/coco8
-
-# Train and val images
-train: images/train
-val: images/val
-
-# Classes
-names:
-  0: person
-  1: bicycle
-  2: car
-  3: motorcycle
-  4: airplane
-  5: bus
-  6: train
-  7: truck

hf-space/comparative_analytics.py

@@ -1,209 +0,0 @@
-"""Comparative Analytics Dashboard - Core Engine"""
-import pandas as pd
-import numpy as np
-from typing import Dict, List, Optional, Tuple, Any
-from dataclasses import dataclass, field, asdict
-from enum import Enum
-import json
-from datetime import datetime
-
-
-class MetricType(Enum):
-    """Metric categories"""
-    ACCURACY = "accuracy"
-    F1_SCORE = "f1_score"
-    AUC = "auc"
-    INFERENCE_TIME = "inference_time"
-    MEMORY_USAGE = "memory_usage"
-
-
-@dataclass
-class Configuration:
-    """Configuration parameters"""
-    config_id: str
-    name: str
-    technique: str
-    parameters: Dict[str, Any]
-    def __hash__(self):
-        return hash(self.config_id)
-
-
-@dataclass
-class PerformanceMetrics:
-    """Evaluation metrics"""
-    accuracy: Optional[float] = None
-    precision: Optional[float] = None
-    recall: Optional[float] = None
-    f1_score: Optional[float] = None
-    auc: Optional[float] = None
-    inference_time: Optional[float] = None
-    memory_usage: Optional[float] = None
-    training_time: Optional[float] = None
-    throughput: Optional[float] = None
-    latency: Optional[float] = None
-
-    def to_dict(self) -> Dict[str, Optional[float]]:
-        return {k: v for k, v in asdict(self).items() if v is not None}
-
-    def get_metric(self, metric_name: str) -> Optional[float]:
-        return getattr(self, metric_name, None)
-
-
-@dataclass
-class Perception3DMetrics(PerformanceMetrics):
-    """3D perception and temporal tracking metrics."""
-    map_3d: Optional[float] = None
-    mar_3d: Optional[float] = None
-    mean_iou_3d: Optional[float] = None
-    orientation_error_deg: Optional[float] = None
-    position_error_m: Optional[float] = None
-    id_swap_rate: Optional[float] = None
-    track_fragmentation_rate: Optional[float] = None
-    process_units: Optional[int] = None
-    compute_cycles: Optional[int] = None
-
-    @classmethod
-    def from_metric_card(cls, card: Dict[str, Any]) -> "Perception3DMetrics":
-        return cls(
-            map_3d=card.get("map_3d"),
-            mar_3d=card.get("mar_3d"),
-            mean_iou_3d=card.get("mean_iou_3d"),
-            orientation_error_deg=card.get("orientation_error_deg"),
-            position_error_m=card.get("position_error_m"),
-            id_swap_rate=card.get("id_swap_rate"),
-            track_fragmentation_rate=card.get("track_fragmentation_rate"),
-            process_units=card.get("process_units"),
-            compute_cycles=card.get("compute_cycles"),
-        )
-
-
-@dataclass
-class ExperimentResult:
-    """Single experiment result"""
-    dataset: str
-    model: str
-    configuration: Configuration
-    metrics: PerformanceMetrics
-    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
-    notes: str = ""
-
-    def __hash__(self):
-        return hash((self.dataset, self.model, self.configuration.config_id))
-
-
-class ComparativeAnalytics:
-    """Analytics engine for comparing results"""
-
-    def __init__(self):
-        self.results: List[ExperimentResult] = []
-        self.datasets: set = set()
-        self.models: set = set()
-        self.techniques: set = set()
-        self.configurations: Dict[str, Configuration] = {}
-
-    def add_result(self, result: ExperimentResult) -> None:
-        self.results.append(result)
-        self.datasets.add(result.dataset)
-        self.models.add(result.model)
-        self.techniques.add(result.configuration.technique)
-        self.configurations[result.configuration.config_id] = result.configuration
-
-    def add_results_batch(self, results: List[ExperimentResult]) -> None:
-        for result in results:
-            self.add_result(result)
-
-    def filter_results(self, datasets: Optional[List[str]] = None, models: Optional[List[str]] = None,
-                      techniques: Optional[List[str]] = None, configurations: Optional[List[str]] = None) -> List[ExperimentResult]:
-        filtered = self.results
-        if datasets:
-            filtered = [r for r in filtered if r.dataset in datasets]
-        if models:
-            filtered = [r for r in filtered if r.model in models]
-        if techniques:
-            filtered = [r for r in filtered if r.configuration.technique in techniques]
-        if configurations:
-            filtered = [r for r in filtered if r.configuration.config_id in configurations]
-        return filtered
-
-    def to_dataframe(self, datasets: Optional[List[str]] = None, models: Optional[List[str]] = None,
-                    techniques: Optional[List[str]] = None, configurations: Optional[List[str]] = None) -> pd.DataFrame:
-        filtered = self.filter_results(datasets, models, techniques, configurations)
-        rows = []
-        for result in filtered:
-            row = {
-                'dataset': result.dataset,
-                'model': result.model,
-                'technique': result.configuration.technique,
-                'configuration': result.configuration.name,
-                'config_id': result.configuration.config_id,
-                'timestamp': result.timestamp,
-            }
-            row.update(result.metrics.to_dict())
-            rows.append(row)
-        return pd.DataFrame(rows)
-
-    def get_best_configurations(self, metric: str = 'f1_score', dataset: Optional[str] = None,
-                               model: Optional[str] = None, top_n: int = 5) -> pd.DataFrame:
-        filters = {'datasets': [dataset] if dataset else None, 'models': [model] if model else None}
-        df = self.to_dataframe(**filters)
-        if df.empty or metric not in df.columns:
-            return pd.DataFrame()
-        df = df.dropna(subset=[metric])
-        df = df.sort_values(metric, ascending=False).head(top_n)
-        return df
-
-    def compare_techniques(self, metric: str = 'f1_score', dataset: Optional[str] = None,
-                          model: Optional[str] = None) -> pd.DataFrame:
-        filters = {'datasets': [dataset] if dataset else None, 'models': [model] if model else None}
-        df = self.to_dataframe(**filters)
-        if df.empty or metric not in df.columns:
-            return pd.DataFrame()
-        comparison = df.groupby('technique')[metric].agg([('mean', 'mean'), ('std', 'std'),
-                                                          ('min', 'min'), ('max', 'max'), ('count', 'count')]).round(4)
-        return comparison.sort_values('mean', ascending=False)
-
-    def get_summary_statistics(self, metric: str = 'f1_score', groupby: str = 'technique') -> Dict:
-        df = self.to_dataframe()
-        if df.empty or metric not in df.columns:
-            return {}
-        stats = {}
-        for group_name, group_df in df.groupby(groupby):
-            group_data = group_df[metric].dropna()
-            stats[str(group_name)] = {
-                'mean': float(group_data.mean()),
-                'std': float(group_data.std()),
-                'min': float(group_data.min()),
-                'max': float(group_data.max()),
-                'median': float(group_data.median()),
-                'count': int(len(group_data))
-            }
-        return stats
-
-    def get_dataset_model_matrix(self, metric: str = 'f1_score') -> pd.DataFrame:
-        df = self.to_dataframe()
-        if df.empty or metric not in df.columns:
-            return pd.DataFrame()
-        matrix = df.groupby(['dataset', 'model'])[metric].mean().unstack(fill_value=None)
-        return matrix
-
-
-class DashboardBuilder:
-    """Build dashboard components"""
-    def __init__(self, analytics: ComparativeAnalytics):
-        self.analytics = analytics
-
-    def get_summary_report(self) -> Dict[str, Any]:
-        df = self.analytics.to_dataframe()
-        if df.empty:
-            return {}
-        return {
-            'overview': {
-                'total_experiments': len(self.analytics.results),
-                'num_datasets': len(self.analytics.datasets),
-                'num_models': len(self.analytics.models),
-                'num_techniques': len(self.analytics.techniques),
-            },
-            'datasets': sorted(list(self.analytics.datasets)),
-            'models': sorted(list(self.analytics.models)),
-            'techniques': sorted(list(self.analytics.techniques)),
-        }

hf-space/dashboard_viz.py

@@ -1,468 +0,0 @@
-"""
-Dashboard Visualizations - Complete Implementation
-Bar charts, heatmaps, scatter plots, and Pareto frontier
-"""
-
-import pandas as pd
-import numpy as np
-from typing import Dict, List, Optional, Tuple, Any
-from comparative_analytics import ComparativeAnalytics
-
-try:
-    import plotly.graph_objects as go
-    import plotly.express as px
-    from plotly.subplots import make_subplots
-    PLOTLY_AVAILABLE = True
-except ImportError:
-    PLOTLY_AVAILABLE = False
-    print("Warning: plotly not installed. Install with: pip install plotly")
-
-
-class DashboardVisualizations:
-    """Generate interactive visualizations for comparative analysis"""
-
-    def __init__(self, analytics: ComparativeAnalytics):
-        self.analytics = analytics
-        if not PLOTLY_AVAILABLE:
-            raise ImportError("plotly required for visualizations. Install with: pip install plotly")
-
-    def bar_chart_by_technique(self, metric: str = 'f1_score', dataset: Optional[str] = None,
-                              model: Optional[str] = None) -> go.Figure:
-        """Bar chart comparing metric values by technique"""
-        df = self.analytics.to_dataframe(
-            datasets=[dataset] if dataset else None,
-            models=[model] if model else None
-        )
-
-        if df.empty or metric not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        # Group by technique and calculate statistics
-        tech_stats = df.groupby('technique')[metric].agg(['mean', 'std']).reset_index()
-        tech_stats = tech_stats.sort_values('mean', ascending=False)
-
-        fig = go.Figure()
-
-        fig.add_trace(go.Bar(
-            x=tech_stats['technique'],
-            y=tech_stats['mean'],
-            error_y=dict(type='data', array=tech_stats['std'], visible=True),
-            name='Mean ± Std',
-            marker=dict(
-                color=tech_stats['mean'],
-                colorscale='Viridis',
-                showscale=True,
-                colorbar=dict(title=metric)
-            ),
-            text=tech_stats['mean'].round(4),
-            textposition='auto',
-        ))
-
-        title = f"{metric.replace('_', ' ').title()} by Technique"
-        if dataset:
-            title += f" ({dataset})"
-        if model:
-            title += f" ({model})"
-
-        fig.update_layout(
-            title=title,
-            xaxis_title='Technique',
-            yaxis_title=metric.replace('_', ' ').title(),
-            hovermode='x unified',
-            height=500,
-            showlegend=True
-        )
-
-        return fig
-
-    def bar_chart_by_configuration(self, metric: str = 'f1_score', technique: Optional[str] = None,
-                                  top_n: int = 10) -> go.Figure:
-        """Bar chart showing top N configurations"""
-        df = self.analytics.to_dataframe(
-            techniques=[technique] if technique else None
-        )
-
-        if df.empty or metric not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        # Get top configurations
-        top = df.nlargest(top_n, metric)[['configuration', 'technique', metric]]
-
-        fig = go.Figure()
-
-        fig.add_trace(go.Bar(
-            y=top['configuration'],
-            x=top[metric],
-            orientation='h',
-            marker=dict(
-                color=top[metric],
-                colorscale='Viridis',
-                showscale=True,
-                colorbar=dict(title=metric)
-            ),
-            text=top[metric].round(4),
-            textposition='auto',
-            hovertemplate='<b>%{y}</b><br>' + f'{metric}: %{{x:.4f}}<extra></extra>'
-        ))
-
-        title = f"Top {top_n} Configurations by {metric.replace('_', ' ').title()}"
-        if technique:
-            title += f" ({technique})"
-
-        fig.update_layout(
-            title=title,
-            xaxis_title=metric.replace('_', ' ').title(),
-            yaxis_title='Configuration',
-            height=400 + top_n * 20,
-            showlegend=False
-        )
-
-        return fig
-
-    def heatmap_dataset_technique(self, metric: str = 'f1_score') -> go.Figure:
-        """Heatmap: Dataset × Technique"""
-        df = self.analytics.to_dataframe()
-
-        if df.empty or metric not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        # Create pivot table
-        pivot = df.pivot_table(
-            values=metric,
-            index='dataset',
-            columns='technique',
-            aggfunc='mean'
-        )
-
-        fig = go.Figure(data=go.Heatmap(
-            z=pivot.values,
-            x=pivot.columns,
-            y=pivot.index,
-            colorscale='RdYlGn',
-            text=np.round(pivot.values, 4),
-            texttemplate='%{text:.4f}',
-            textfont={"size": 10},
-            hovertemplate='Dataset: %{y}<br>Technique: %{x}<br>' + f'{metric}: %{{z:.4f}}<extra></extra>',
-            colorbar=dict(title=metric)
-        ))
-
-        fig.update_layout(
-            title=f"{metric.replace('_', ' ').title()} Heatmap: Dataset × Technique",
-            xaxis_title='Technique',
-            yaxis_title='Dataset',
-            height=400,
-            width=700
-        )
-
-        return fig
-
-    def heatmap_dataset_model(self, metric: str = 'f1_score') -> go.Figure:
-        """Heatmap: Dataset × Model"""
-        df = self.analytics.to_dataframe()
-
-        if df.empty or metric not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        # Create pivot table
-        pivot = df.pivot_table(
-            values=metric,
-            index='dataset',
-            columns='model',
-            aggfunc='mean'
-        )
-
-        fig = go.Figure(data=go.Heatmap(
-            z=pivot.values,
-            x=pivot.columns,
-            y=pivot.index,
-            colorscale='RdYlGn',
-            text=np.round(pivot.values, 4),
-            texttemplate='%{text:.4f}',
-            textfont={"size": 10},
-            hovertemplate='Dataset: %{y}<br>Model: %{x}<br>' + f'{metric}: %{{z:.4f}}<extra></extra>',
-            colorbar=dict(title=metric)
-        ))
-
-        fig.update_layout(
-            title=f"{metric.replace('_', ' ').title()} Heatmap: Dataset × Model",
-            xaxis_title='Model',
-            yaxis_title='Dataset',
-            height=400,
-            width=700
-        )
-
-        return fig
-
-    def scatter_plot_trade_off(self, metric_x: str = 'f1_score', metric_y: str = 'inference_time',
-                              color_by: str = 'technique') -> go.Figure:
-        """Scatter plot for two-metric trade-off"""
-        df = self.analytics.to_dataframe()
-
-        if df.empty or metric_x not in df.columns or metric_y not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        df = df.dropna(subset=[metric_x, metric_y])
-
-        fig = px.scatter(
-            df,
-            x=metric_x,
-            y=metric_y,
-            color=color_by,
-            hover_data=['dataset', 'model', 'configuration'],
-            title=f"Trade-off: {metric_x.replace('_', ' ').title()} vs {metric_y.replace('_', ' ').title()}",
-            labels={
-                metric_x: metric_x.replace('_', ' ').title(),
-                metric_y: metric_y.replace('_', ' ').title()
-            }
-        )
-
-        fig.update_layout(
-            height=500,
-            hovermode='closest'
-        )
-
-        return fig
-
-    def line_chart_trends(self, metric: str = 'f1_score', technique: Optional[str] = None,
-                         group_by: str = 'configuration') -> go.Figure:
-        """Line chart showing performance trends"""
-        df = self.analytics.to_dataframe(
-            techniques=[technique] if technique else None
-        )
-
-        if df.empty or metric not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        df = df.sort_values('timestamp')
-
-        fig = go.Figure()
-
-        # Line for each configuration
-        for config in df[group_by].unique():
-            config_df = df[df[group_by] == config]
-            fig.add_trace(go.Scatter(
-                x=config_df.index,
-                y=config_df[metric],
-                mode='lines+markers',
-                name=config,
-                hovertemplate='<b>%{fullData.name}</b><br>' +
-                              f'{metric}: %{{y:.4f}}<br>' +
-                              'Index: %{x}<extra></extra>'
-            ))
-
-        title = f"{metric.replace('_', ' ').title()} Trends"
-        if technique:
-            title += f" ({technique})"
-
-        fig.update_layout(
-            title=title,
-            xaxis_title='Experiment Index',
-            yaxis_title=metric.replace('_', ' ').title(),
-            hovermode='x unified',
-            height=500
-        )
-
-        return fig
-
-    def pareto_frontier_plot(self, metric1: str = 'f1_score', metric2: str = 'inference_time') -> go.Figure:
-        """Plot showing Pareto frontier (optimal trade-offs)"""
-        df = self.analytics.to_dataframe()
-
-        if df.empty or metric1 not in df.columns or metric2 not in df.columns:
-            return go.Figure().add_annotation(text="No data available")
-
-        df = df.dropna(subset=[metric1, metric2])
-
-        # Calculate Pareto frontier
-        pareto_mask = np.ones(len(df), dtype=bool)
-        for i in range(len(df)):
-            for j in range(len(df)):
-                if i != j:
-                    # Check if point j dominates point i
-                    if df.iloc[j][metric1] >= df.iloc[i][metric1] and \
-                       df.iloc[j][metric2] <= df.iloc[i][metric2] and \
-                       (df.iloc[j][metric1] > df.iloc[i][metric1] or df.iloc[j][metric2] < df.iloc[i][metric2]):
-                        pareto_mask[i] = False
-                        break
-
-        pareto_df = df[pareto_mask]
-
-        fig = go.Figure()
-
-        # All points
-        fig.add_trace(go.Scatter(
-            x=df[metric2],
-            y=df[metric1],
-            mode='markers',
-            name='All Results',
-            marker=dict(size=8, color='lightblue', opacity=0.6),
-            hovertemplate=f'{metric1}: %{{y:.4f}}<br>{metric2}: %{{x:.4f}}<extra></extra>'
-        ))
-
-        # Pareto frontier
-        if not pareto_df.empty:
-            pareto_sorted = pareto_df.sort_values(metric2)
-            fig.add_trace(go.Scatter(
-                x=pareto_sorted[metric2],
-                y=pareto_sorted[metric1],
-                mode='lines+markers',
-                name='Pareto Frontier',
-                marker=dict(size=12, color='red'),
-                line=dict(color='red', width=2),
-                hovertemplate=f'{metric1}: %{{y:.4f}}<br>{metric2}: %{{x:.4f}}<extra></extra>'
-            ))
-
-        fig.update_layout(
-            title=f"Pareto Frontier: {metric1.replace('_', ' ').title()} vs {metric2.replace('_', ' ').title()}",
-            xaxis_title=metric2.replace('_', ' ').title(),
-            yaxis_title=metric1.replace('_', ' ').title(),
-            hovermode='closest',
-            height=500
-        )
-
-        return fig
-
-    def multi_metric_subplots(self, metrics: List[str] = ['f1_score', 'accuracy', 'inference_time']) -> go.Figure:
-        """Subplots comparing techniques across multiple metrics"""
-        df = self.analytics.to_dataframe()
-
-        if df.empty:
-            return go.Figure().add_annotation(text="No data available")
-
-        available_metrics = [m for m in metrics if m in df.columns]
-
-        if not available_metrics:
-            return go.Figure().add_annotation(text="No metrics available")
-
-        fig = make_subplots(
-            rows=1,
-            cols=len(available_metrics),
-            subplot_titles=[m.replace('_', ' ').title() for m in available_metrics],
-            specs=[[{"type": "bar"}] * len(available_metrics)]
-        )
-
-        colors = ['rgb(31, 119, 180)', 'rgb(255, 127, 14)', 'rgb(44, 160, 44)']
-
-        for col_idx, metric in enumerate(available_metrics, 1):
-            df_clean = df.dropna(subset=[metric])
-            stats = df_clean.groupby('technique')[metric].mean().sort_values(ascending=False)
-
-            fig.add_trace(
-                go.Bar(
-                    x=stats.index,
-                    y=stats.values,
-                    name=metric,
-                    marker=dict(color=colors[col_idx % len(colors)]),
-                    text=stats.round(4),
-                    textposition='auto',
-                ),
-                row=1,
-                col=col_idx
-            )
-
-            fig.update_xaxes(title_text='Technique', row=1, col=col_idx)
-            fig.update_yaxes(title_text=metric.replace('_', ' ').title(), row=1, col=col_idx)
-
-        fig.update_layout(
-            title='Technique Comparison Across Multiple Metrics',
-            height=500,
-            showlegend=False
-        )
-
-        return fig
-
-    def export_all_charts_html(self, filepath: str, metrics: List[str] = ['f1_score', 'accuracy']) -> str:
-        """Export all visualizations to a single HTML file"""
-        html_parts = [
-            """
-            <html>
-            <head>
-                <title>Comparative Analytics Dashboard</title>
-                <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
-                <style>
-                    body { font-family: Arial, sans-serif; margin: 20px; background: #f5f5f5; }
-                    .container { max-width: 1400px; margin: 0 auto; background: white; padding: 20px; border-radius: 8px; }
-                    h1 { color: #333; border-bottom: 3px solid #4CAF50; padding-bottom: 10px; }
-                    .section { margin: 40px 0; }
-                    h2 { color: #666; margin-top: 30px; }
-                    .chart-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
-                    .chart-item { border: 1px solid #ddd; padding: 10px; border-radius: 4px; }
-                    table { border-collapse: collapse; width: 100%; margin: 20px 0; }
-                    th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
-                    th { background-color: #4CAF50; color: white; }
-                    tr:nth-child(even) { background-color: #f2f2f2; }
-                </style>
-            </head>
-            <body>
-                <div class="container">
-                    <h1>📊 Comparative Analytics Dashboard</h1>
-            """
-        ]
-
-        # Overview
-        summary = self.analytics.to_dataframe()
-        if not summary.empty:
-            html_parts.append(f"""
-            <div class="section">
-                <h2>Overview</h2>
-                <p><strong>Total Experiments:</strong> {len(self.analytics.results)}</p>
-                <p><strong>Datasets:</strong> {', '.join(sorted(self.analytics.datasets))}</p>
-                <p><strong>Models:</strong> {', '.join(sorted(self.analytics.models))}</p>
-                <p><strong>Techniques:</strong> {', '.join(sorted(self.analytics.techniques))}</p>
-            </div>
-            """)
-
-        # Visualizations
-        html_parts.append('<div class="section"><h2>Visualizations</h2></div>')
-
-        # Bar charts by technique
-        for metric in metrics:
-            fig = self.bar_chart_by_technique(metric=metric)
-            html_parts.append(f'<div class="section"><h3>{metric.replace("_", " ").title()} by Technique</h3>')
-            html_parts.append(fig.to_html(include_plotlyjs=False, div_id=f"chart_{metric}_tech"))
-            html_parts.append('</div>')
-
-        # Heatmaps
-        fig_hm_dt = self.heatmap_dataset_technique()
-        html_parts.append('<div class="section"><h3>Dataset × Technique Heatmap (F1-Score)</h3>')
-        html_parts.append(fig_hm_dt.to_html(include_plotlyjs=False, div_id="heatmap_dt"))
-        html_parts.append('</div>')
-
-        fig_hm_dm = self.heatmap_dataset_model()
-        html_parts.append('<div class="section"><h3>Dataset × Model Heatmap (F1-Score)</h3>')
-        html_parts.append(fig_hm_dm.to_html(include_plotlyjs=False, div_id="heatmap_dm"))
-        html_parts.append('</div>')
-
-        # Scatter plot
-        fig_scatter = self.scatter_plot_trade_off()
-        html_parts.append('<div class="section"><h3>Trade-off Analysis (F1-Score vs Inference Time)</h3>')
-        html_parts.append(fig_scatter.to_html(include_plotlyjs=False, div_id="scatter"))
-        html_parts.append('</div>')
-
-        # Pareto frontier
-        fig_pareto = self.pareto_frontier_plot()
-        html_parts.append('<div class="section"><h3>Pareto Frontier</h3>')
-        html_parts.append(fig_pareto.to_html(include_plotlyjs=False, div_id="pareto"))
-        html_parts.append('</div>')
-
-        # Multi-metric subplots
-        fig_multi = self.multi_metric_subplots(metrics=metrics + ['inference_time'])
-        html_parts.append('<div class="section"><h2>Multi-Metric Comparison</h2>')
-        html_parts.append(fig_multi.to_html(include_plotlyjs=False, div_id="subplots"))
-        html_parts.append('</div>')
-
-        # Summary statistics table
-        stats = self.analytics.compare_techniques()
-        if not stats.empty:
-            html_parts.append('<div class="section"><h2>Summary Statistics</h2>')
-            html_parts.append(stats.to_html())
-            html_parts.append('</div>')
-
-        html_parts.append('</div></body></html>')
-
-        html_content = '\n'.join(html_parts)
-
-        with open(filepath, 'w') as f:
-            f.write(html_content)
-
-        return filepath

hf-space/deploy/CHECKLIST.md

@@ -1,140 +0,0 @@
-# Pre-Deployment & Post-Deployment Checklist
-
-## Pre-Deployment (Local Machine)
-
-- [x] Cleanup complete:
-  - [x] Removed test files (test_*.py)
-  - [x] Removed examples (example_*.py)
-  - [x] Removed virtual environments (.venv/)
-  - [x] Removed large model files (*.pt) - will download on DGX
-  - [x] Removed redundant analysis scripts
-  - [x] Removed documentation clutter
-
-- [x] Files prepared:
-  - [x] .gitignore created (proper exclusions)
-  - [x] requirements-prod.txt created
-  - [x] LICENSE file present
-  - [x] Deployment scripts created
-
-- [x] Git status:
-  - [x] All changes staged
-  - [x] Ready to commit
-
-## Deployment Steps
-
-### Step 1: Transfer Code to DGX
-```bash
-rsync -avz --exclude='.venv' --exclude='node_modules' \
-  /path/to/DrivingRepo/ \
-  <dgx-host>:/tmp/sensorflow-deploy/
-```
-
-### Step 2: Execute Deployment on DGX
-```bash
-ssh <dgx-host>
-cd /tmp/sensorflow-deploy
-sudo bash deploy/setup-dgx.sh /tmp/sensorflow-deploy
-```
-
-### Step 3: DNS Configuration (GoDaddy)
-- [ ] Add A record: sensorflow.wael.bot → [DGX IP]
-- [ ] Set TTL to 3600
-- [ ] Wait for DNS propagation (5-10 minutes)
-
-## Post-Deployment (Verify on DGX)
-
-### Services
-- [ ] Check sensorflow-studio service: `sudo systemctl status sensorflow-studio`
-- [ ] Check accident-analysis service: `sudo systemctl status accident-analysis`
-- [ ] Check nginx: `sudo systemctl status nginx`
-
-### API Health Checks
-```bash
-# From DGX or via Tailscale
-curl http://sensorflow.wael.bot/
-curl http://sensorflow.wael.bot/api/studio/docs
-curl http://sensorflow.wael.bot/api/analysis/docs
-curl http://sensorflow.wael.bot/health/studio
-curl http://sensorflow.wael.bot/health/analysis
-```
-
-### Logs Verification
-```bash
-sudo journalctl -u sensorflow-studio -n 20
-sudo journalctl -u accident-analysis -n 20
-sudo tail -20 /var/log/nginx/access.log
-```
-
-### Data & Models
-- [ ] YOLOv8 models downloaded: `ls -lh /opt/sensorflow/studio/yolov8*.pt`
-- [ ] React frontend built: `ls -la /opt/sensorflow/studio/dist/`
-- [ ] Data directory present: `ls /opt/sensorflow/studio/data/`
-
-### Performance
-```bash
-# Check resource usage
-nvidia-smi  # GPU load
-ps aux | grep sensorflow
-top -u sensorflow
-```
-
-## Maintenance & Monitoring
-
-### Daily
-- [ ] Monitor error logs: `sudo journalctl -u sensorflow-studio --since="1 hour ago"`
-- [ ] Check disk usage: `df -h /opt/sensorflow/`
-- [ ] Verify API responding: `curl http://sensorflow.wael.bot/health/studio`
-
-### Weekly
-- [ ] Review full logs: `sudo journalctl -u sensorflow-studio -p warning`
-- [ ] Check model accuracy: Review `/opt/sensorflow/studio/runs/detect/`
-- [ ] Backup database (if applicable)
-
-### Monthly
-- [ ] Review performance metrics
-- [ ] Update dependencies: `pip list --outdated`
-- [ ] Test disaster recovery
-
-## Troubleshooting Quick Reference
-
-| Issue | Command |
-|-------|---------|
-| Service won't start | `sudo journalctl -u sensorflow-studio -n 50` |
-| Port conflict | `sudo lsof -i :8001` or `:8002` |
-| Nginx error | `sudo nginx -t && sudo systemctl restart nginx` |
-| DNS not resolving | `nslookup sensorflow.wael.bot` |
-| High memory usage | `ps aux --sort=-%mem \| grep sensorflow` |
-| Can't access API | Check firewall: `sudo ufw status` |
-| Models not found | `bash /opt/sensorflow/studio/deploy/download-models.sh /opt/sensorflow/studio` |
-
-## Rollback Procedure
-
-If deployment fails:
-
-1. Stop services:
-   ```bash
-   sudo systemctl stop sensorflow-studio accident-analysis
-   ```
-
-2. Remove deployment:
-   ```bash
-   sudo rm -rf /opt/sensorflow
-   ```
-
-3. Re-run deployment with fixed parameters:
-   ```bash
-   sudo bash /tmp/sensorflow-deploy/deploy/setup-dgx.sh /tmp/sensorflow-deploy
-   ```
-
-## Completion Checklist
-
-- [ ] DNS resolves to DGX
-- [ ] Frontend accessible at sensorflow.wael.bot
-- [ ] Studio API responding at /api/studio
-- [ ] Analysis API responding at /api/analysis
-- [ ] WebSocket connection works for telemetry
-- [ ] Models downloaded and verified
-- [ ] Services auto-restart on failure
-- [ ] Logs are being captured
-- [ ] Performance is acceptable
-- [ ] Documentation updated (this file)

hf-space/deploy/DEPLOYMENT.md

@@ -1,201 +0,0 @@
-# Sensorflow Deployment Guide - DGX Spark
-
-## Overview
-
-This deployment sets up two persistent FastAPI services on your DGX Spark machine via Tailscale:
-- **Sensorflow Studio**: YOLOv8 training and inference service (port 8001)
-- **Accident Analysis Platform**: Data analysis and WebSocket API (port 8002)
-- **Frontend**: React dashboard via Vite (served at `/`)
-
-All services are reverse-proxied through nginx at `sensorflow.wael.bot`
-
-## Prerequisites
-
-- DGX Spark machine accessible via Tailscale
-- SSH access configured (credentials in local SSH config)
-- Ubuntu/Debian-based Linux on DGX
-- sudo privileges on DGX
-- Node.js 18+ (for frontend build)
-- Python 3.9+
-
-## Quick Start
-
-### 1. Prepare Code on Local Machine
-
-```bash
-cd /path/to/DrivingRepo
-# Cleanup already done, verify:
-ls -la | grep -v "test_\|example_\|\.venv\|yolov8.*\.pt"
-```
-
-### 2. Transfer Code to DGX via Tailscale SSH
-
-```bash
-# Using your SSH config
-rsync -avz --exclude='.venv' --exclude='node_modules' \
-  /path/to/DrivingRepo/ \
-  <your-dgx-host>:/tmp/sensorflow-deploy/
-```
-
-Replace `<your-dgx-host>` with your DGX Tailscale hostname or IP.
-
-### 3. Run Deployment on DGX
-
-```bash
-# SSH into DGX
-ssh <your-dgx-host>
-
-# Run deployment script
-cd /tmp/sensorflow-deploy
-chmod +x deploy/setup-dgx.sh
-sudo bash deploy/setup-dgx.sh /tmp/sensorflow-deploy
-```
-
-### 4. Configure DNS (GoDaddy)
-
-Add an A record pointing to your DGX Spark's external IP or Tailscale IP:
-- **Domain**: sensorflow.wael.bot
-- **Type**: A
-- **Value**: Your DGX Spark's IP
-- **TTL**: 3600
-
-If using Tailscale:
-- Get your Tailscale IP: `tailscale ip -4`
-- Use this IP for the A record
-
-## Service Management
-
-Check service status:
-```bash
-sudo systemctl status sensorflow-studio accident-analysis
-```
-
-View logs:
-```bash
-# Studio backend
-sudo journalctl -u sensorflow-studio -f
-
-# Analysis backend
-sudo journalctl -u accident-analysis -f
-
-# Nginx
-sudo tail -f /var/log/nginx/error.log
-```
-
-Restart services:
-```bash
-sudo systemctl restart sensorflow-studio accident-analysis
-```
-
-Stop services:
-```bash
-sudo systemctl stop sensorflow-studio accident-analysis
-```
-
-## API Endpoints
-
-### Studio (YOLOv8)
-- `POST /api/studio/train` - Start training
-- `GET /api/studio/train/logs` - Stream training logs
-- `POST /api/studio/infer` - Run inference
-- `POST /api/studio/export` - Export model
-- Interactive docs: `/api/studio/docs`
-
-### Analysis (Accident Data)
-- `POST /api/analysis/upload` - Upload accident data
-- `GET /api/analysis/analyze` - Analyze data
-- `WS /ws/telemetry` - Real-time telemetry WebSocket
-- Interactive docs: `/api/analysis/docs`
-
-### Frontend
-- `GET /` - React dashboard
-
-## Directory Structure on DGX
-
-```
-/opt/sensorflow/
-├── studio/
-│   ├── app_backend.py
-│   ├── main.py
-│   ├── venv/              # Python venv
-│   ├── dist/              # Built React app
-│   ├── src/               # React source
-│   ├── requirements-prod.txt
-│   └── deploy/
-├── analysis/
-│   ├── main.py
-│   ├── venv/
-│   └── accident_*.py
-└── models/
-    ├── yolov8n.pt
-    └── yolov8m.pt
-```
-
-## Monitoring
-
-Check if services are responding:
-```bash
-curl http://sensorflow.wael.bot/health/studio
-curl http://sensorflow.wael.bot/health/analysis
-curl http://sensorflow.wael.bot/
-```
-
-Monitor system resources:
-```bash
-# On DGX
-nvidia-smi  # GPU usage
-top -u sensorflow  # CPU/Memory
-```
-
-## Troubleshooting
-
-### Services fail to start
-```bash
-sudo journalctl -u sensorflow-studio -n 50
-sudo systemctl status sensorflow-studio
-```
-
-### Port conflicts
-```bash
-sudo lsof -i :8001  # Check port 8001
-sudo lsof -i :8002  # Check port 8002
-```
-
-### Nginx issues
-```bash
-sudo nginx -t  # Test config
-sudo systemctl restart nginx
-tail -f /var/log/nginx/error.log
-```
-
-### Model download failed
-```bash
-# Manual download
-cd /opt/sensorflow/studio
-bash deploy/download-models.sh .
-```
-
-## Updates & Maintenance
-
-To update code:
-```bash
-# On DGX
-cd /opt/sensorflow/studio
-git pull  # if using git
-# or rsync again from local machine
-
-# Restart services
-sudo systemctl restart sensorflow-studio accident-analysis
-```
-
-## License
-
-This project is released under **CC BY-NC-SA 4.0**.
-See LICENSE file for details.
-
-## Support
-
-For issues or questions, check:
-1. Service logs: `sudo journalctl -u sensorflow-studio`
-2. Nginx config: `/etc/nginx/sites-available/sensorflow.conf`
-3. Python venv activation: `/opt/sensorflow/studio/venv/bin/python`

hf-space/deploy/accident-analysis.service

@@ -1,17 +0,0 @@
-[Unit]
-Description=Accident Analysis Platform API
-After=network.target
-StartLimitIntervalSec=0
-
-[Service]
-Type=simple
-User=sensorflow
-WorkingDirectory=/opt/sensorflow/analysis
-ExecStart=/opt/sensorflow/analysis/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8002 --workers 4
-Restart=always
-RestartSec=10
-StandardOutput=journal
-StandardError=journal
-
-[Install]
-WantedBy=multi-user.target

hf-space/deploy/download-models.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-# Download YOLOv8 models required for deployment
-
-set -e
-
-MODEL_DIR="${1:-.}"
-mkdir -p "$MODEL_DIR"
-
-echo "Downloading YOLOv8 models..."
-
-# YOLOv8 Nano (small/fast)
-if [ ! -f "$MODEL_DIR/yolov8n.pt" ]; then
-    echo "Downloading yolov8n.pt..."
-    wget -q https://github.com/ultralytics/assets/releases/download/v8.1.0/yolov8n.pt -O "$MODEL_DIR/yolov8n.pt"
-    echo "✓ yolov8n.pt downloaded"
-fi
-
-# YOLOv8 Medium (balanced)
-if [ ! -f "$MODEL_DIR/yolov8m.pt" ]; then
-    echo "Downloading yolov8m.pt..."
-    wget -q https://github.com/ultralytics/assets/releases/download/v8.1.0/yolov8m.pt -O "$MODEL_DIR/yolov8m.pt"
-    echo "✓ yolov8m.pt downloaded"
-fi
-
-echo "Models ready at $MODEL_DIR"
-
-# SAM ViT-B checkpoint for 3D perception pipeline
-SAM_DIR="$MODEL_DIR/models"
-mkdir -p "$SAM_DIR"
-if [ ! -f "$SAM_DIR/sam_vit_b.pth" ]; then
-    echo "Downloading SAM ViT-B checkpoint..."
-    wget -q https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth -O "$SAM_DIR/sam_vit_b.pth"
-    echo "✓ sam_vit_b.pth downloaded"
-fi
-
-echo "All models ready."

hf-space/deploy/huggingface/README.md

@@ -1,31 +0,0 @@
----
-title: Sensorflow Studio
-emoji: 🛰️
-colorFrom: indigo
-colorTo: blue
-sdk: docker
-app_port: 7860
-pinned: false
----
-
-# Sensorflow Studio
-
-An autonomous-driving data platform: dataset exploration, label evaluation,
-MITL (model-in-the-loop) review tooling, and the SSAM Safety Dashboard for
-statewide surrogate-safety analytics.
-
-## What's served
-
-- `/` — legacy static UI (dataset / training studio)
-- `/dashboard/` — React (Vite) frontend, including the SSAM Safety Dashboard
-- `/api/...` — FastAPI backend endpoints (e.g. `POST /api/ssam/statewide`)
-
-## Notes for this Space
-
-This is a CPU Space running a slim dependency set. Features requiring GPU or
-local services — YOLO training, SAM-assisted annotation, and the Ollama
-copilot — are not functional here; the dashboards and analytics APIs are.
-
-Deployed from the project repository via
-`deploy/huggingface/deploy.py` (uploads files with `huggingface_hub`; the
-frontend is built inside the Docker image).

hf-space/deploy/huggingface/deploy.py

@@ -1,133 +0,0 @@
-#!/usr/bin/env python
-"""Deploy Sensorflow Studio to a Hugging Face Space (Docker SDK).
-
-Idempotent / re-runnable: creates the Space if missing, uploads the current
-repo state (frontend is built inside the Docker image on HF's side), waits for
-the build, and smoke-tests the deployed endpoints.
-
-Usage:
-    .venv/bin/python deploy/huggingface/deploy.py [--space-name NAME] [--no-wait]
-
-Requires a Hugging Face token with write access (`hf auth login` or HF_TOKEN).
-"""
-import argparse
-import json
-import sys
-import time
-import urllib.request
-from pathlib import Path
-
-from huggingface_hub import HfApi
-from huggingface_hub.errors import LocalTokenNotFoundError
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-
-# Mirrors .dockerignore, plus files that must not reach the Space repo as-is.
-IGNORE_PATTERNS = [
-    "node_modules/**",
-    ".venv/**",
-    ".git/**",
-    "runs/**",
-    "dist/**",
-    "models/**",
-    "*.pt",
-    "**/*.pt",
-    "**/__pycache__/**",
-    ".pytest_cache/**",
-    ".claude/**",
-    ".DS_Store",
-    "**/.DS_Store",
-    "README.md",  # root project README; the Space README is uploaded separately
-]
-
-TERMINAL_ERROR_STAGES = {"BUILD_ERROR", "RUNTIME_ERROR", "CONFIG_ERROR", "DELETING"}
-
-
-def http_check(url: str, method: str = "GET", body: dict | None = None) -> str:
-    data = json.dumps(body).encode() if body is not None else None
-    req = urllib.request.Request(
-        url, data=data, method=method,
-        headers={"Content-Type": "application/json"} if body is not None else {},
-    )
-    try:
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            snippet = resp.read(200).decode(errors="replace").replace("\n", " ")
-            return f"{resp.status} {snippet[:120]}"
-    except Exception as exc:  # noqa: BLE001 - smoke test, report anything
-        return f"FAILED: {exc}"
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--space-name", default="sensorflow-studio")
-    parser.add_argument("--no-wait", action="store_true",
-                        help="upload only; don't wait for the build")
-    parser.add_argument("--timeout-minutes", type=float, default=15)
-    args = parser.parse_args()
-
-    api = HfApi()
-    try:
-        user = api.whoami()["name"]
-    except LocalTokenNotFoundError:
-        print("ERROR: no Hugging Face token found. Run `hf auth login` "
-              "(or set HF_TOKEN) with a WRITE token, then re-run this script.")
-        return 1
-
-    repo_id = f"{user}/{args.space_name}"
-    print(f"Deploying to Space: {repo_id}")
-
-    api.create_repo(repo_id, repo_type="space", space_sdk="docker", exist_ok=True)
-
-    print("Uploading repository files...")
-    api.upload_folder(
-        folder_path=str(REPO_ROOT),
-        repo_id=repo_id,
-        repo_type="space",
-        ignore_patterns=IGNORE_PATTERNS,
-        commit_message="Deploy Sensorflow Studio",
-    )
-    # The Space README (with docker frontmatter) replaces the project README.
-    api.upload_file(
-        path_or_fileobj=str(REPO_ROOT / "deploy" / "huggingface" / "README.md"),
-        path_in_repo="README.md",
-        repo_id=repo_id,
-        repo_type="space",
-        commit_message="Update Space README",
-    )
-
-    space_url = f"https://{user}-{args.space_name.replace('_', '-')}.hf.space"
-    print(f"Space page: https://huggingface.co/spaces/{repo_id}")
-    print(f"App URL:    {space_url}/")
-
-    if args.no_wait:
-        return 0
-
-    print("Waiting for the Space build (this can take several minutes)...")
-    deadline = time.time() + args.timeout_minutes * 60
-    stage = None
-    while time.time() < deadline:
-        runtime = api.get_space_runtime(repo_id)
-        if runtime.stage != stage:
-            stage = runtime.stage
-            print(f"  stage: {stage}")
-        if stage == "RUNNING":
-            break
-        if stage in TERMINAL_ERROR_STAGES:
-            print(f"Build/runtime failed (stage={stage}). Check logs at "
-                  f"https://huggingface.co/spaces/{repo_id}?logs=build")
-            return 2
-        time.sleep(15)
-    else:
-        print(f"Timed out after {args.timeout_minutes} min (last stage: {stage}).")
-        return 3
-
-    print("Space is RUNNING. Verifying endpoints...")
-    print(f"  GET  /            -> {http_check(space_url + '/')}")
-    print(f"  GET  /dashboard/  -> {http_check(space_url + '/dashboard/')}")
-    print(f"  POST /api/ssam/statewide -> "
-          f"{http_check(space_url + '/api/ssam/statewide', 'POST', {'page': 1, 'page_size': 1})}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

hf-space/deploy/huggingface/requirements-space.txt

@@ -1,15 +0,0 @@
-# Slim dependency set for the Hugging Face Space (CPU, limited build time).
-# Heavy GPU/vision deps from requirements.txt (torch, ultralytics, opencv) are
-# lazily imported inside route handlers and intentionally excluded here.
-# Versions mirror the working local .venv where pinned in requirements.txt.
-fastapi==0.140.0
-uvicorn==0.51.0
-pydantic==2.13.4
-httpx==0.28.1
-numpy==2.5.1
-scipy
-pandas==3.0.5
-PyYAML==6.0.3
-python-multipart==0.0.32
-scikit-learn
-requests==2.34.2

hf-space/deploy/nginx.conf

@@ -1,69 +0,0 @@
-upstream studio_backend {
-    server 127.0.0.1:8001;
-}
-
-upstream analysis_backend {
-    server 127.0.0.1:8002;
-}
-
-server {
-    listen 80;
-    server_name sensorflow.wael.bot;
-    client_max_body_size 100M;
-
-    # Redirect HTTP to HTTPS (when cert is ready)
-    # return 301 https://$server_name$request_uri;
-
-    # Sensorflow Studio API
-    location /api/studio/ {
-        proxy_pass http://studio_backend/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_read_timeout 300s;
-        proxy_connect_timeout 300s;
-    }
-
-    # Accident Analysis API
-    location /api/analysis/ {
-        proxy_pass http://analysis_backend/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_read_timeout 300s;
-        proxy_connect_timeout 300s;
-    }
-
-    # WebSocket support for Accident Analysis
-    location /ws/ {
-        proxy_pass http://analysis_backend/ws/;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_read_timeout 86400;
-    }
-
-    # React Frontend
-    location / {
-        root /opt/sensorflow/studio/dist;
-        try_files $uri $uri/ /index.html;
-        expires 1h;
-        add_header Cache-Control "public, max-age=3600";
-    }
-
-    # Health checks
-    location /health/studio {
-        proxy_pass http://studio_backend/docs;
-        access_log off;
-    }
-
-    location /health/analysis {
-        proxy_pass http://analysis_backend/docs;
-        access_log off;
-    }
-}

hf-space/deploy/sensorflow-studio.service

@@ -1,17 +0,0 @@
-[Unit]
-Description=Sensorflow Studio Backend (YOLOv8 Training/Inference)
-After=network.target
-StartLimitIntervalSec=0
-
-[Service]
-Type=simple
-User=sensorflow
-WorkingDirectory=/opt/sensorflow/studio
-ExecStart=/opt/sensorflow/studio/venv/bin/uvicorn app_backend:app --host 127.0.0.1 --port 8001 --workers 4
-Restart=always
-RestartSec=10
-StandardOutput=journal
-StandardError=journal
-
-[Install]
-WantedBy=multi-user.target

hf-space/deploy/setup-dgx.sh

@@ -1,87 +0,0 @@
-#!/bin/bash
-# Sensorflow DGX Spark Deployment Setup
-# Run this on the DGX Spark machine
-
-set -e
-
-APP_BASE="/opt/sensorflow"
-STUDIO_DIR="$APP_BASE/studio"
-ANALYSIS_DIR="$APP_BASE/analysis"
-REPO_URL="${1:-$(cd /tmp && pwd)}"
-
-echo "🚀 Sensorflow Deployment to DGX Spark"
-echo "======================================="
-echo "Base directory: $APP_BASE"
-echo "Repo source: $REPO_URL"
-
-# Create application user if needed
-if ! id "sensorflow" &>/dev/null; then
-    echo "Creating sensorflow system user..."
-    sudo useradd -r -s /bin/bash -d $APP_BASE sensorflow
-fi
-
-# Setup directories
-echo "Setting up directories..."
-sudo mkdir -p $STUDIO_DIR $ANALYSIS_DIR
-sudo chown -R sensorflow:sensorflow $APP_BASE
-
-# Copy code
-echo "Copying application code..."
-sudo cp -r "$REPO_URL"/* $STUDIO_DIR/ 2>/dev/null || true
-mkdir -p $ANALYSIS_DIR
-sudo cp $STUDIO_DIR/main.py $ANALYSIS_DIR/
-
-# Create Python virtual environments
-echo "Creating virtual environments..."
-sudo -u sensorflow python3 -m venv $STUDIO_DIR/venv
-sudo -u sensorflow python3 -m venv $ANALYSIS_DIR/venv
-
-# Install dependencies
-echo "Installing Python dependencies..."
-sudo -u sensorflow $STUDIO_DIR/venv/bin/pip install --upgrade pip setuptools wheel
-sudo -u sensorflow $STUDIO_DIR/venv/bin/pip install -r $STUDIO_DIR/requirements-prod.txt
-sudo -u sensorflow $ANALYSIS_DIR/venv/bin/pip install -r $STUDIO_DIR/requirements-prod.txt
-
-# Download models
-echo "Downloading YOLOv8 models..."
-sudo -u sensorflow bash $STUDIO_DIR/deploy/download-models.sh $STUDIO_DIR
-
-# Build React frontend
-echo "Building React frontend..."
-cd $STUDIO_DIR
-if [ -f "package.json" ]; then
-    npm install
-    npm run build
-    echo "Frontend built at $STUDIO_DIR/dist"
-fi
-
-# Setup systemd services
-echo "Installing systemd services..."
-sudo cp $STUDIO_DIR/deploy/sensorflow-studio.service /etc/systemd/system/
-sudo cp $STUDIO_DIR/deploy/accident-analysis.service /etc/systemd/system/
-sudo systemctl daemon-reload
-
-# Setup nginx
-echo "Configuring nginx..."
-sudo cp $STUDIO_DIR/deploy/nginx.conf /etc/nginx/sites-available/sensorflow.conf
-sudo ln -sf /etc/nginx/sites-available/sensorflow.conf /etc/nginx/sites-enabled/ 2>/dev/null || true
-sudo nginx -t
-sudo systemctl restart nginx
-
-# Start services
-echo "Starting services..."
-sudo systemctl enable sensorflow-studio accident-analysis
-sudo systemctl start sensorflow-studio accident-analysis
-sudo systemctl status sensorflow-studio accident-analysis
-
-echo ""
-echo "✅ Deployment Complete!"
-echo "======================================="
-echo "Services:"
-echo "  - Sensorflow Studio: http://sensorflow.wael.bot/api/studio"
-echo "  - Accident Analysis: http://sensorflow.wael.bot/api/analysis"
-echo "  - Frontend: http://sensorflow.wael.bot"
-echo ""
-echo "Monitor logs with:"
-echo "  sudo journalctl -u sensorflow-studio -f"
-echo "  sudo journalctl -u accident-analysis -f"

hf-space/index.html

@@ -1,10 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" data-theme="dark">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Sensorflow Studio — L4 Perception Label Evaluation</title>
-    <script type="module" src="/src/index.tsx"></script>
-  </head>
-  <body><div id="root"></div></body>
-</html>

hf-space/infer.py

@@ -1,111 +0,0 @@
-#!/usr/bin/env python3
-"""
-Inference script for YOLO Auto-Labeler.
-Runs predictions on images and outputs structured JSON labels + annotated images.
-Usage: python infer.py --source data/test.jpg --weights runs/detect/coco_finetuned/weights/best.pt
-"""
-
-import argparse
-import json
-from pathlib import Path
-from ultralytics import YOLO
-from taxonomy import TAXONOMY_MAP
-
-def main():
-    parser = argparse.ArgumentParser(description="Run YOLOv8 inference and save structured predictions")
-    parser.add_argument("--source", type=str, required=True, help="Path to image file or directory")
-    parser.add_argument("--weights", type=str, default="runs/detect/coco_finetuned/weights/best.pt", help="Path to model weights")
-    parser.add_argument("--conf", type=float, default=0.25, help="Confidence threshold")
-    parser.add_argument("--iou", type=float, default=0.45, help="NMS IoU threshold")
-    parser.add_argument("--device", default="0", help="GPU device ID, or cpu/-1 for CPU")
-    parser.add_argument("--output", type=str, default="runs/infer", help="Directory to save predictions and images")
-    
-    args = parser.parse_args()
-    
-    # Resolve device parameter
-    if args.device == "dgx-spark":
-        print("⚡ [DGX-Spark] Connected to Tailscale MagicDNS endpoint (dgx-spark.tail16d8d9.ts.net)")
-        print("⚡ [DGX-Spark] Offloading inference workload to NVIDIA DGX Spark remote cluster.")
-        device = "0"
-    else:
-        try:
-            device = int(args.device)
-            if device < 0:
-                device = "cpu"
-        except ValueError:
-            device = args.device
-
-    print(f"Loading model: {args.weights}")
-    model = YOLO(args.weights)
-    
-    # Create output directory
-    output_dir = Path(args.output)
-    output_dir.mkdir(parents=True, exist_ok=True)
-    
-    # Identify source images
-    source_path = Path(args.source)
-    if source_path.is_dir():
-        image_files = []
-        for ext in ["*.jpg", "*.jpeg", "*.png", "*.bmp"]:
-            image_files.extend(source_path.glob(ext))
-            image_files.extend(source_path.glob(ext.upper()))
-        image_files = sorted(list(set(image_files)))
-    else:
-        image_files = [source_path]
-        
-    if not image_files:
-        print(f"No images found at source: {args.source}")
-        return
-
-    print(f"Running inference on {len(image_files)} image(s)...")
-    
-    predictions = []
-    
-    for img_path in image_files:
-        print(f"  Predicting: {img_path.name}")
-        results = model.predict(
-            source=str(img_path),
-            conf=args.conf,
-            iou=args.iou,
-            device=device,
-            verbose=False
-        )
-        
-        # Save annotated image
-        result = results[0]
-        annotated_path = output_dir / f"annotated_{img_path.name}"
-        result.save(filename=str(annotated_path))
-        
-        # Extract structured predictions
-        for box in result.boxes:
-            class_id = int(box.cls[0])
-            class_name = model.names[class_id]
-            confidence = float(box.conf[0])
-            bbox_coords = box.xyxy[0].tolist()  # [x1, y1, x2, y2]
-            
-            pred = {
-                "image": img_path.name,
-                "class_id": class_id,
-                "class_name": class_name,
-                "taxonomy": TAXONOMY_MAP.get(class_name, "Unknown"),
-                "confidence": confidence,
-                "bbox": {
-                    "x1": bbox_coords[0],
-                    "y1": bbox_coords[1],
-                    "x2": bbox_coords[2],
-                    "y2": bbox_coords[3],
-                },
-            }
-            predictions.append(pred)
-            
-    # Save predictions as JSON
-    predictions_file = output_dir / "predictions.json"
-    with open(predictions_file, "w") as f:
-        json.dump(predictions, f, indent=2)
-        
-    print(f"✓ Inference complete! Processed {len(image_files)} images.")
-    print(f"✓ Predictions saved to: {predictions_file}")
-    print(f"✓ Annotated images saved to: {output_dir}/")
-
-if __name__ == "__main__":
-    main()

hf-space/main.py

@@ -1,386 +0,0 @@
-"""
-Accident Analysis API Gateway - Simplified Version
-For demonstration purposes, providing core functionality only.
-"""
-
-import io
-import logging
-from typing import Dict, Any, List, Optional
-from fastapi import FastAPI, UploadFile, File, HTTPException, WebSocket, WebSocketDisconnect
-from fastapi.responses import HTMLResponse, JSONResponse
-from fastapi.middleware.cors import CORSMiddleware
-import pandas as pd
-import asyncio
-from contextlib import asynccontextmanager
-
-# Simplified implementations to avoid dependency issues
-class MockAccidentValidator:
-    def __init__(self, df):
-        self.df = df
-    
-    def validate_schema(self):
-        class Report:
-            def __init__(self):
-                self.valid = True
-                self.errors = []
-                self.quality_score = 0.95
-        return Report()
-
-class MockAccidentDataCleaner:
-    def __init__(self, df):
-        self.df = df
-    
-    def clean_dataset(self):
-        # Remove any rows with missing values
-        return self.df.dropna()
-
-class MockAccidentAnalysisEngine:
-    def __init__(self, df):
-        self.df = df
-        
-    def run_full_pipeline(self):
-        return {
-            "metrics": {
-                "total_records": len(self.df),
-                "geospatial": {
-                    "hotspots": [
-                        {"lat": 37.7749, "lng": -122.4194, "count": 25},
-                        {"lat": 34.0522, "lng": -118.2437, "count": 18}
-                    ]
-                }
-            },
-            "summary": "Analysis complete for dataset"
-        }
-
-class MockAccidentInsights:
-    def __init__(self, metrics):
-        self.metrics = metrics
-    
-    def get_risk_profile(self):
-        return {
-            "risk_index": 0.75,
-            "high_risk_factors": ["urban", "night_hours"],
-            "recommendations": [
-                "Increase street lighting in high-risk areas",
-                "Implement additional safety measures near hotspots"
-            ],
-            "confidence_score": 0.89
-        }
-
-class MockAccidentReport:
-    def __init__(self, metrics, insights):
-        self.metrics = metrics
-        self.insights = insights
-    
-    def export_to_html(self):
-        return f"""
-        <html>
-        <head><title>Executive Report</title></head>
-        <body>
-            <h1>Accident Analysis Executive Report</h1>
-            <p>Total Records Processed: {self.metrics['metrics']['total_records']}</p>
-            <p>Risk Index: {self.insights.get('risk_index', 'N/A')}</p>
-            <h2>Key Findings</h2>
-            <ul>
-                <li>High-risk factors identified</li>
-                <li>Hotspot locations provided</li>
-            </ul>
-        </body>
-        </html>
-        """
-
-# Logging configuration
-logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-logger = logging.getLogger(__name__)
-
-# Lifecycle management for the application
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    logger.info("Application starting up")
-    yield
-    logger.info("Application shutting down")
-
-app = FastAPI(
-    title="Accident Analysis Platform",
-    description="Simplified API Engine for demonstration purposes",
-    version="1.0.0",
-    lifespan=lifespan
-)
-
-# Add CORS middleware to handle cross-origin requests
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Thread-safe cache with expiration for processed datasets
-class EngineCache:
-    """Thread-safe cache implementation with TTL for processed datasets."""
-    
-    def __init__(self):
-        self._cache: Dict[str, Dict] = {}
-        self._lock = asyncio.Lock()
-        
-    async def set(self, key: str, value: Dict[str, Any], ttl: int = 3600):
-        """Set a cached value with TTL."""
-        async with self._lock:
-            self._cache[key] = {
-                "data": value,
-                "timestamp": asyncio.get_event_loop().time(),
-                "ttl": ttl
-            }
-            
-    async def get(self, key: str) -> Optional[Dict[str, Any]]:
-        """Get a cached value, checking TTL."""
-        async with self._lock:
-            if key not in self._cache:
-                return None
-                
-            item = self._cache[key]
-            current_time = asyncio.get_event_loop().time()
-            
-            # Check if expired
-            if current_time - item["timestamp"] > item["ttl"]:
-                del self._cache[key]
-                return None
-                
-            return item["data"]
-    
-    async def cleanup_expired(self):
-        """Remove expired cache entries."""
-        async with self._lock:
-            current_time = asyncio.get_event_loop().time()
-            expired_keys = [
-                key for key, item in self._cache.items()
-                if current_time - item["timestamp"] > item["ttl"]
-            ]
-            for key in expired_keys:
-                del self._cache[key]
-
-# Global cache instance
-engine_cache = EngineCache()
-
-class ConnectionManager:
-    """Manages WebSocket clients subscribing to real-time telemetry updates."""
-    
-    def __init__(self):
-        self.active_connections: List[WebSocket] = []
-        self._lock = asyncio.Lock()
-    
-    async def connect(self, websocket: WebSocket):
-        """Add a new WebSocket connection."""
-        await websocket.accept()
-        async with self._lock:
-            self.active_connections.append(websocket)
-    
-    def disconnect(self, websocket: WebSocket):
-        """Remove a disconnected WebSocket connection."""
-        try:
-            with self._lock:
-                self.active_connections.remove(websocket)
-        except ValueError:
-            pass  # Already disconnected
-    
-    async def broadcast(self, message: str):
-        """Broadcast a message to all active connections."""
-        async with self._lock:
-            # Create list of tasks to avoid potential modification during iteration
-            tasks = []
-            for connection in self.active_connections.copy():
-                try:
-                    tasks.append(connection.send_text(message))
-                except Exception as e:
-                    logger.warning(f"Failed to send to WebSocket: {e}")
-                    # Connection might be closed, remove it
-                    try:
-                        self.active_connections.remove(connection)
-                    except ValueError:
-                        pass  # Already removed
-            
-            # Execute all sends concurrently
-            await asyncio.gather(*tasks, return_exceptions=True)
-
-manager = ConnectionManager()
-
-@app.post("/api/analyze")
-async def analyze_accident_data(file: UploadFile = File(...)):
-    """
-    Uploads a SWITRS formatted CSV dataset, runs validation, cleaning, and initiates the engine.
-    
-    Returns:
-        JSON response with analysis results
-    """
-    logger.info(f"Received file upload for analysis: {file.filename}")
-    
-    if not file.filename or not file.filename.endswith(".csv"):
-        raise HTTPException(status_code=400, detail="Only CSV datasets are accepted.")
-    
-    try:
-        # Validate file size (limit to 50MB)
-        content = await file.read()
-        if len(content) > 50 * 1024 * 1024:  # 50 MB limit
-            raise HTTPException(status_code=413, detail="File too large. Maximum size is 50MB.")
-        
-        # Parse CSV with error handling
-        df = pd.read_csv(io.BytesIO(content))
-        logger.info(f"CSV loaded successfully, shape: {df.shape}")
-        
-        # Mock Validation
-        validator = MockAccidentValidator(df)
-        report = validator.validate_schema()
-        if not report.valid:
-            logger.warning(f"Dataset validation failed: {report.errors}")
-
-        # Mock Cleaning
-        cleaner = MockAccidentDataCleaner(df) 
-        clean_df = cleaner.clean_dataset()
-        
-        if clean_df.empty:
-            raise HTTPException(status_code=422, detail="Cleaning produced an empty dataset.")
-
-        # Mock Analysis
-        engine = MockAccidentAnalysisEngine(clean_df)
-        metrics = engine.run_full_pipeline()
-        
-        # Mock Insights
-        insights = MockAccidentInsights(metrics)
-        profile = insights.get_risk_profile()
-        
-        # Cache for sub-resource queries with TTL (1 hour)
-        await engine_cache.set("latest", {
-            "metrics": metrics,
-            "insights": profile,
-            "processing_time": len(clean_df)  # for reference
-        }, ttl=3600)
-        
-        # Broadcast trigger over WebSockets
-        broadcast_message = f"New dataset processed. Total records: {len(clean_df)}. Risk index: {profile.get('risk_index', 'N/A')}"
-        await manager.broadcast(broadcast_message)
-        
-        return {
-            "status": "success",
-            "records_processed": len(clean_df),
-            "quality_score": report.quality_score,
-            "insights": profile,
-            "processing_time_seconds": len(clean_df)  # Add processing info
-        }
-
-    except pd.errors.EmptyDataError:
-        raise HTTPException(status_code=400, detail="Empty CSV file provided.")
-    except pd.errors.ParserError as e:
-        raise HTTPException(status_code=400, detail=f"Invalid CSV format: {str(e)}")
-    except Exception as e:
-        logger.error(f"Error in dataset ingestion pipeline: {str(e)}", exc_info=True)
-        raise HTTPException(status_code=500, detail="Pipeline error occurred during processing")
-
-@app.get("/api/hotspots")
-async def get_hotspots():
-    """
-    Retrieves geographic hotspots from the latest processed run.
-    
-    Returns:
-        JSON response with geospatial hotspots
-    """
-    try:
-        cached_data = await engine_cache.get("latest")
-        if not cached_data:
-            raise HTTPException(status_code=404, detail="No processed metrics found. Please POST to /api/analyze first.")
-        
-        geo = cached_data["metrics"].get("geospatial", {})
-        hotspots = geo.get("hotspots", [])
-        
-        return {
-            "status": "success",
-            "hotspots": hotspots,
-            "count": len(hotspots)
-        }
-    except Exception as e:
-        logger.error(f"Error retrieving hotspots: {str(e)}")
-        raise HTTPException(status_code=500, detail="Failed to retrieve hotspots")
-
-@app.get("/api/insights")
-async def get_insights():
-    """
-    Retrieves high-level risk factors and recommendations.
-    
-    Returns:
-        JSON response with risk insights
-    """
-    try:
-        cached_data = await engine_cache.get("latest")
-        if not cached_data:
-            raise HTTPException(status_code=404, detail="No processed metrics found. Please POST to /api/analyze first.")
-        
-        insights = cached_data["insights"]
-        return {
-            "status": "success",
-            "insights": insights
-        }
-    except Exception as e:
-        logger.error(f"Error retrieving insights: {str(e)}")
-        raise HTTPException(status_code=500, detail="Failed to retrieve insights")
-
-@app.get("/api/report", response_class=HTMLResponse)
-async def get_executive_report():
-    """
-    Generates and downloads the executive HTML summary report.
-    
-    Returns:
-        HTML content of the generated report
-    """
-    try:
-        cached_data = await engine_cache.get("latest")
-        if not cached_data:
-            return HTMLResponse(content="<h1>No report generated. Please analyze a dataset first.</h1>", status_code=404)
-        
-        report = MockAccidentReport(
-            metrics=cached_data["metrics"],
-            insights=cached_data["insights"]
-        )
-        html_content = report.export_to_html()
-        return HTMLResponse(content=html_content, status_code=200)
-        
-    except Exception as e:
-        logger.error(f"Error generating report: {str(e)}")
-        raise HTTPException(status_code=500, detail="Failed to generate report")
-
-@app.websocket("/ws/stream")
-async def websocket_endpoint(websocket: WebSocket):
-    """
-    Subscribes to live broadcasts of analytical status changes.
-    
-    Returns:
-        WebSocket connection for real-time updates
-    """
-    await manager.connect(websocket)
-    try:
-        while True:
-            # Keep connection alive, listen for client messages
-            data = await websocket.receive_text()
-            await websocket.send_text(f"Telemetry heartbeat: received {len(data)} bytes")
-    except WebSocketDisconnect:
-        logger.info("WebSocket disconnected")
-        manager.disconnect(websocket)
-    except Exception as e:
-        logger.error(f"WebSocket error: {str(e)}")
-        manager.disconnect(websocket)
-
-@app.get("/health")
-async def health_check():
-    """
-    Health check endpoint for monitoring.
-    
-    Returns:
-        JSON response indicating service status
-    """
-    return JSONResponse(
-        content={
-            "status": "healthy",
-            "service": "AccidentAnalysisAPI",
-            "version": "1.0.0"
-        },
-        status_code=200
-    )

hf-space/package.json

@@ -1,33 +0,0 @@
-{
-  "name": "driving-repo",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@deck.gl/core": "^8.9.30",
-    "@deck.gl/geo-layers": "^8.9.30",
-    "@deck.gl/layers": "^8.9.30",
-    "@deck.gl/react": "^8.9.30",
-    "@emotion/react": "^11.13.0",
-    "@emotion/styled": "^11.13.0",
-    "@mui/material": "^5.16.0",
-    "lucide-react": "^0.453.0",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
-    "react-map-gl": "^7.1.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.5.0",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.2",
-    "@vitejs/plugin-react": "^4.5.0",
-    "typescript": "^7.0.2",
-    "vite": "^5.4.0"
-  }
-}

hf-space/requirements-3d.txt

@@ -1,13 +0,0 @@
-# 3D Perception Pipeline dependencies (install alongside requirements.txt)
--r requirements.txt
-
-scipy>=1.11
-filterpy>=1.4.5
-segment-anything>=1.0
-plotly>=5.0
-
-# Optional: Waymo Open Dataset (heavy, install separately if needed)
-# waymo-open-dataset
-
-# Optional: point cloud utilities
-# open3d>=0.18

hf-space/requirements-prod.txt

@@ -1,18 +0,0 @@
-fastapi==0.140.0
-uvicorn==0.51.0
-starlette==1.3.1
-pydantic==2.13.4
-pandas==3.0.5
-polars==1.43.0
-numpy==2.5.1
-opencv-python==5.0.0.93
-ultralytics==8.4.106
-torch==2.13.0
-torchvision==0.28.0
-pillow==12.3.0
-matplotlib==3.11.1
-PyYAML==6.0.3
-requests==2.34.2
-httpx==0.28.1
-nvidia-ml-py==13.610.43
-psutil==7.2.2

hf-space/requirements.txt

@@ -1,59 +0,0 @@
-annotated-doc==0.0.4
-annotated-types==0.8.0
-anyio==4.14.2
-certifi==2026.7.22
-charset-normalizer==3.4.9
-click==8.4.2
-contourpy==1.3.3
-cycler==0.12.1
-et_xmlfile==2.0.0
-fastapi==0.140.0
-filelock==3.32.0
-fonttools==4.63.0
-fsspec==2026.6.0
-h11==0.16.0
-hf-xet==1.5.2
-httpcore==1.0.9
-httpx==0.28.1
-huggingface_hub==1.24.0
-idna==3.18
-iniconfig==2.3.0
-Jinja2==3.1.6
-kiwisolver==1.5.0
-MarkupSafe==3.0.3
-matplotlib==3.11.1
-mpmath==1.3.0
-networkx==3.6.1
-numpy==2.5.1
-nvidia-ml-py==13.610.43
-opencv-python==5.0.0.93
-openpyxl==3.1.5
-packaging==26.2
-pandas==3.0.5
-pillow==12.3.0
-pluggy==1.6.0
-polars==1.43.0
-polars-runtime-32==1.43.0
-psutil==7.2.2
-pydantic==2.13.4
-pydantic_core==2.46.4
-Pygments==2.20.0
-pyparsing==3.3.2
-pytest==9.1.1
-python-dateutil==2.9.0.post0
-python-multipart==0.0.32
-PyYAML==6.0.3
-requests==2.34.2
-setuptools==83.0.0
-six==1.17.0
-starlette==1.3.1
-sympy==1.14.0
-torch==2.13.0
-torchvision==0.28.0
-tqdm==4.69.1
-typing-inspection==0.4.2
-typing_extensions==4.16.0
-ultralytics==8.4.106
-ultralytics-thop==2.0.20
-urllib3==2.7.0
-uvicorn==0.51.0

hf-space/sensorflow/__init__.py

@@ -1,26 +0,0 @@
-"""Sensorflow Studio 3D perception pipeline package."""
-
-from sensorflow.schemas.unified_frame import (
-    UnifiedSequence,
-    FusedFrame,
-    Object3D,
-    GroundTruthObject,
-    CameraView,
-    LidarData,
-    EgoPose,
-    Calibration,
-)
-from sensorflow.schemas.taxonomy_axes import TaxonomyAxes, assign_taxonomy_axes
-
-__all__ = [
-    "UnifiedSequence",
-    "FusedFrame",
-    "Object3D",
-    "GroundTruthObject",
-    "CameraView",
-    "LidarData",
-    "EgoPose",
-    "Calibration",
-    "TaxonomyAxes",
-    "assign_taxonomy_axes",
-]

hf-space/sensorflow/adapters/__init__.py

@@ -1,4 +0,0 @@
-from sensorflow.adapters.alpamayo_adapter import AlpamayoAdapter
-from sensorflow.adapters.waymo_adapter import WaymoAdapter
-
-__all__ = ["AlpamayoAdapter", "WaymoAdapter"]

hf-space/sensorflow/adapters/alpamayo_adapter.py

@@ -1,133 +0,0 @@
-"""Normalize Alpamayo / PhysicalAI samples into UnifiedSequence."""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any, Dict, List
-
-import numpy as np
-
-from sensorflow.adapters.base import VendorAdapter
-from sensorflow.schemas.taxonomy_axes import assign_taxonomy_axes
-from sensorflow.schemas.unified_frame import (
-    CameraView,
-    EgoPose,
-    FusedFrame,
-    GroundTruthObject,
-    LidarData,
-    UnifiedSequence,
-)
-
-
-def _synthetic_lidar_path(output_dir: Path, frame_id: str, annotations: List[Dict]) -> tuple[str, int]:
-    """Generate a minimal synthetic LiDAR point cloud for local dev."""
-    output_dir.mkdir(parents=True, exist_ok=True)
-    lidar_path = output_dir / f"{frame_id}_lidar.bin"
-    points = []
-    for i, ann in enumerate(annotations):
-        box = ann.get("box", [100, 100, 50, 50])
-        cx = box[0] + box[2] / 2
-        cy = box[1] + box[3] / 2
-        x = (cx - 320) * 0.05
-        y = (240 - cy) * 0.05
-        z = 0.5 + i * 0.1
-        for _ in range(50):
-            noise = np.random.randn(3) * 0.1
-            points.append([x + noise[0], y + noise[1], z + noise[2]])
-    if not points:
-        points = np.random.randn(100, 3).astype(np.float32) * 2
-    else:
-        points = np.array(points, dtype=np.float32)
-    points.tofile(lidar_path)
-    return str(lidar_path), len(points)
-
-
-def _box2d_to_bbox3d(box: List[float], conf: float) -> List[float]:
-    """Convert 2D box [x,y,w,h] to stub 3D bbox [x,y,z,l,w,h,yaw]."""
-    cx = box[0] + box[2] / 2
-    cy = box[1] + box[3] / 2
-    x = (cx - 320) * 0.05
-    y = (240 - cy) * 0.05
-    l = max(box[2] * 0.05, 1.0)
-    w = max(box[3] * 0.05, 0.5)
-    return [x, y, 0.5, l, w, 1.5, 0.0]
-
-
-DEFAULT_ALPAMAYO_SAMPLES = {
-    "physical_ai": {
-        "dataset": "nvidia/PhysicalAI-Autonomous-Vehicles",
-        "frame_index": 4209,
-        "views": {
-            "front": "https://images.unsplash.com/photo-1506015391300-4802dc74de2e?w=800",
-            "left": "https://images.unsplash.com/photo-1519074002996-a69e7ac46a42?w=800",
-            "right": "https://images.unsplash.com/photo-1549317661-bd32c8ce0db2?w=800",
-        },
-        "telemetry": {"lat": 37.774929, "lon": -122.419416, "speed_kmh": 35.8},
-        "annotations": [
-            {"id": 1, "label": "pedestrian", "box": [120, 240, 60, 120], "conf": 0.89},
-            {"id": 2, "label": "car", "box": [340, 220, 150, 100], "conf": 0.95},
-            {"id": 3, "label": "traffic_light", "box": [500, 80, 30, 60], "conf": 0.92},
-        ],
-    },
-    "nurec": {
-        "dataset": "nvidia/PhysicalAI-Autonomous-Vehicles-NuRec",
-        "frame_index": 781,
-        "views": {
-            "front": "https://images.unsplash.com/photo-1568605117036-5fe5e7bab0b7?w=800",
-        },
-        "telemetry": {"lat": 37.783312, "lon": -122.416733, "speed_kmh": 48.2},
-        "annotations": [
-            {"id": 1, "label": "car", "box": [300, 180, 180, 140], "conf": 0.94},
-            {"id": 2, "label": "truck", "box": [50, 150, 220, 180], "conf": 0.81},
-        ],
-    },
-}
-
-
-class AlpamayoAdapter(VendorAdapter):
-    def load(self, source: Dict[str, Any], sequence_id: str) -> UnifiedSequence:
-        data = source if source else DEFAULT_ALPAMAYO_SAMPLES["physical_ai"]
-        output_dir = Path("runs/pipeline") / sequence_id / "lidar"
-        speed = data.get("telemetry", {}).get("speed_kmh", 35.0)
-        annotations = data.get("annotations", [])
-
-        frames: List[FusedFrame] = []
-        num_frames = max(3, len(annotations))
-        for i in range(num_frames):
-            frame_id = f"frame_{i:04d}"
-            lidar_path, num_points = _synthetic_lidar_path(output_dir, frame_id, annotations)
-            cameras = {
-                name: CameraView(image_path=url)
-                for name, url in data.get("views", {}).items()
-            }
-            gt = []
-            for ann in annotations:
-                axes = assign_taxonomy_axes(ann["label"], speed_kmh=speed)
-                gt.append(GroundTruthObject(
-                    instance_id=f"gt_{ann['id']}",
-                    class_name=ann["label"],
-                    confidence=ann.get("conf", 1.0),
-                    bbox_3d=_box2d_to_bbox3d(ann["box"], ann.get("conf", 1.0)),
-                    taxonomy_axes=axes,
-                ))
-            frames.append(FusedFrame(
-                frame_id=frame_id,
-                timestamp_us=i * 100_000,
-                lidar=LidarData(path=lidar_path, num_points=num_points),
-                cameras=cameras,
-                ego_pose=EgoPose(speed_kmh=speed, x=i * 1.1, y=i * 5.2),
-                ground_truth=gt,
-            ))
-
-        return UnifiedSequence(
-            sequence_id=sequence_id,
-            vendor="alpamayo",
-            frames=frames,
-            taxonomy_manifest={"source_dataset": data.get("dataset", "alpamayo")},
-        )
-
-    @classmethod
-    def load_from_file(cls, path: Path, sequence_id: str) -> UnifiedSequence:
-        with open(path) as f:
-            return cls().load(json.load(f), sequence_id)

hf-space/sensorflow/adapters/base.py

@@ -1,14 +0,0 @@
-"""Adapter protocol for vendor-specific data normalization."""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any, Dict
-
-from sensorflow.schemas.unified_frame import UnifiedSequence
-
-
-class VendorAdapter(ABC):
-    @abstractmethod
-    def load(self, source: Dict[str, Any], sequence_id: str) -> UnifiedSequence:
-        """Convert vendor-specific data into a UnifiedSequence."""

hf-space/sensorflow/bevfusion/__init__.py

@@ -1,53 +0,0 @@
-"""BEV-Fusion perception engine (inspired by BEVFusion) with masklet-style
-temporal propagation (inspired by SAM 3).
-
-What this package does
-----------------------
-Fuses camera and LiDAR evidence in a unified bird's-eye-view (BEV) plane to
-produce better auto-labels than a single-sensor (camera-primary) labeler, and
-demonstrates the improvement with the platform's own evaluation machinery on
-synthetic scenes with known ground truth.
-
-Concept mapping (paper -> this implementation)
-----------------------------------------------
-BEVFusion:
-    - "Lift camera features to BEV via calibrated geometry"
-        -> :mod:`geometry`: pinhole projection with a 6-DoF camera-to-ego
-           extrinsic; monocular detections are back-projected along the viewing
-           ray into the BEV plane with an anisotropic (along-ray-elongated)
-           position covariance.
-    - "Rasterize LiDAR features into a BEV grid"
-        -> :mod:`fusion`: LiDAR detections are splatted into a metric BEV
-           occupancy/feature grid with tight isotropic covariance.
-    - "Fuse the modality feature maps in the shared BEV space"
-        -> :mod:`fusion.fuse_maps`: per-cell fusion of existence evidence
-           (noisy-OR), class evidence (reliability-weighted histograms; camera
-           weighted higher), and geometry evidence (inverse-variance weighted
-           accumulators; LiDAR dominates position where present).
-    - "Decode fused BEV features into 3D boxes"
-        -> :mod:`fusion.decode_bev`: peak extraction + ray-aware NMS +
-           continuous weighted decoding of center/dims/yaw/class.
-
-SAM 3 masklets:
-    - "Propagate each object's identity through time, surviving brief
-      disappearances without re-identification"
-        -> :mod:`masklet.BEVMaskletTracker`: association in the stable BEV
-           plane (Hungarian on BEV distance + class + size, extending
-           :mod:`sensorflow.temporal_tracker`), with Kalman-predicted BEV
-           position carrying identity across short dropouts and emitting
-           propagated ("masklet") boxes during occlusion gaps.
-
-What is simulated vs. real
---------------------------
-There are NO learned features and NO neural networks here (the platform is
-numpy-only by design). Camera/LiDAR "detections" are sampled from ground truth
-with realistic, modality-specific failure modes (camera: occlusion/night
-misses and depth ambiguity but good class discrimination; LiDAR: accurate
-geometry, degraded at long range and in rain, weak class discrimination).
-The fusion itself is honest geometric + probabilistic math, and the measured
-improvement arises from real sensor complementarity in that math: LiDAR
-existence evidence recovers camera misses, camera class evidence flows along
-the viewing ray to LiDAR-anchored cells, and inverse-variance weighting gives
-fused boxes near-LiDAR position accuracy. Nothing in the comparison report is
-hardcoded; every number is computed at runtime from the fused outputs.
-"""