Upload folder using huggingface_hub

README.md

@@ -0,0 +1,92 @@
+# 🚀 Example Chute for Turbovision 🪂
+
+This repository demonstrates how to deploy a **Chute** via the **Turbovision CLI**, hosted on **Hugging Face Hub**.
+It serves as a minimal example showcasing the required structure and workflow for integrating machine learning models, preprocessing, and orchestration into a reproducible Chute environment.
+
+## Repository Structure 
+The following two files **must be present** (in their current locations) for a successful deployment — their content can be modified as needed:
+
+| File | Purpose |
+|------|----------|
+| `miner.py` | Defines the ML model type(s), orchestration, and all pre/postprocessing logic. |
+| `config.yml` | Specifies machine configuration (e.g., GPU type, memory, environment variables). |
+
+Other files — e.g., model weights, utility scripts, or dependencies — are **optional** and can be included as needed for your model. Note: Any required assets must be defined or contained **within this repo**, which is fully open-source, since all network-related operations (downloading challenge data, weights, etc.) are disabled **inside the Chute** 
+
+## Overview
+
+Below is a high-level diagram showing the interaction between Huggingface, Chutes and Turbovision:
+
+![](../images/miner.png)
+
+## Local Testing
+After editing the `config.yml` and `miner.py` and saving it into your Huggingface Repo, you will want to test it works locally. 
+
+1. Copy the file `scorevision/chute_tmeplate/turbovision_chute.py.j2` as a python file called `my_chute.py` and fill in the missing variables:
+```python
+HF_REPO_NAME = "{{ huggingface_repository_name }}"
+HF_REPO_REVISION = "{{ huggingface_repository_revision }}"
+CHUTES_USERNAME = "{{ chute_username }}"
+CHUTE_NAME = "{{ chute_name }}"
+```
+
+2. Run the following command to build the chute locally (Caution: there are known issues with the docker location when running this on a mac) 
+```bash
+chutes build my_chute:chute --local --public
+```
+
+3. Run the name of the docker image just built (i.e. `CHUTE_NAME`) and enter it
+```bash
+docker run -p 8000:8000 -e CHUTES_EXECUTION_CONTEXT=REMOTE -it <image-name> /bin/bash
+```
+
+4. Run the file from within the container
+```bash
+chutes run my_chute:chute --dev --debug
+```
+
+5. In another terminal, test the local endpoints to ensure there are no bugs
+```bash
+curl -X POST http://localhost:8000/health -d '{}'
+curl -X POST http://localhost:8000/predict -d '{"url": "https://scoredata.me/2025_03_14/35ae7a/h1_0f2ca0.mp4","meta": {}}'
+```
+
+## Live Testing
+1. If you have any chute with the same name (ie from a previous deployment), ensure you delete that first (or you will get an error when trying to build).
+```bash
+chutes chutes list
+```
+Take note of the chute id that you wish to delete (if any)
+```bash
+chutes chutes delete <chute-id>
+```
+
+You should also delete its associated image 
+```bash
+chutes images list
+```
+Take note of the chute image id
+```bash
+chutes images delete <chute-image-id>
+```
+
+2. Use Turbovision's CLI to build, deploy and commit on-chain (Note: you can skip the on-chain commit using `--no-commit`.  You can also specify a past huggingface revision to point to using `--revision` and/or the local files you want to upload to your huggingface repo using `--model-path`)
+```bash
+sv -vv push
+```
+
+3. When completed, warm up the chute (if its cold 🧊). (You can confirm its status using `chutes chutes list` or `chutes chutes get <chute-id>` if you already know its id). Note: Warming up can sometimes take a while but if the chute runs without errors (should be if you've tested locally first) and there are sufficient nodes (i.e. machines) available matching the `config.yml` you specified, the chute should become hot 🔥!
+```bash
+chutes warmup <chute-id>
+```
+
+4. Test the chute's endpoints
+```bash
+curl -X POST https://<YOUR-CHUTE-SLUG>.chutes.ai/health -d '{}' -H "Authorization: Bearer $CHUTES_API_KEY"
+curl -X POST https://<YOUR-CHUTE-SLUG>.chutes.ai/predict -d '{"url": "https://scoredata.me/2025_03_14/35ae7a/h1_0f2ca0.mp4","meta": {}}' -H "Authorization: Bearer $CHUTES_API_KEY"
+```
+
+5. Test what your chute would get on a validator (this also applies any validation/integrity checks which may fail if you did not use the Turbovision CLI above to deploy the chute)
+```bash
+sv -vv run-once
+```

config.yml

@@ -0,0 +1,28 @@
+Image:
+  from_base: parachutes/python:3.12
+  run_command:
+    - pip install --upgrade setuptools wheel
+    - pip install huggingface_hub==0.19.4 ultralytics==8.2.40 'torch<2.6' opencv-python-headless
+  set_workdir: /app
+
+NodeSelector:
+  gpu_count: 1
+  min_vram_gb_per_gpu: 16
+  include:
+    - a100
+    - a100_40gb
+    - "3090"
+    - a40
+    - a6000
+  exclude:
+    - "5090"
+    - b200
+    - h200
+    - h20
+    - mi300x
+
+Chute:
+  timeout_seconds: 300
+  concurrency: 4
+  max_instances: 5
+  scaling_threshold: 0.5

miner.py

@@ -0,0 +1,139 @@
+from pathlib import Path
+
+from ultralytics import YOLO
+from numpy import ndarray
+from pydantic import BaseModel
+
+
+class BoundingBox(BaseModel):
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+    cls_id: int
+    conf: float
+
+
+class TVFrameResult(BaseModel):
+    frame_id: int
+    boxes: list[BoundingBox]
+    keypoints: list[tuple[int, int]]
+
+
+class Miner:
+    """
+    This class is responsible for:
+    - Loading ML models.
+    - Running batched predictions on images.
+    - Parsing ML model outputs into structured results (TVFrameResult).
+
+    This class can be modified, but it must have the following to be compatible with the chute:
+        - be named `Miner`
+        - have a `predict_batch` function with the inputs and outputs specified
+        - be stored in a file called `miner.py` which lives in the root of the HFHub repo
+    """
+
+    def __init__(self, path_hf_repo: Path) -> None:
+        """
+        Loads all ML models from the repository.
+        -----(Adjust as needed)----
+
+        Args:
+            path_hf_repo (Path):
+                Path to the downloaded HuggingFace Hub repository
+
+        Returns:
+            None
+        """
+        self.bbox_model = YOLO(path_hf_repo / "football-player-detection.pt")
+        print(f"✅ BBox Model Loaded")
+        self.keypoints_model = YOLO(path_hf_repo / "football-pitch-detection.pt")
+        print(f"✅ Keypoints Model Loaded")
+
+    def __repr__(self) -> str:
+        """
+        Information about miner returned in the health endpoint
+        to inspect the loaded ML models (and their types)
+        -----(Adjust as needed)----
+        """
+        return f"BBox Model: {type(self.bbox_model).__name__}\nKeypoints Model: {type(self.keypoints_model).__name__}"
+
+    def predict_batch(
+        self,
+        batch_images: list[ndarray],
+        offset: int,
+        n_keypoints: int,
+    ) -> list[TVFrameResult]:
+        """
+        Miner prediction for a batch of images.
+        Handles the orchestration of ML models and any preprocessing and postprocessing
+        -----(Adjust as needed)----
+
+        Args:
+            batch_images (list[np.ndarray]):
+                A list of images (as NumPy arrays) to process in this batch.
+            offset (int):
+                The frame number corresponding to the first image in the batch.
+                Used to correctly index frames in the output results.
+            n_keypoints (int):
+                The number of keypoints expected for each frame in this challenge type.
+
+        Returns:
+            list[TVFrameResult]:
+                A list of predictions for each image in the batch
+        """
+
+        bboxes: dict[int, list[BoundingBox]] = {}
+        bbox_model_results = self.bbox_model.predict(batch_images)
+        if bbox_model_results is not None:
+            for frame_number_in_batch, detection in enumerate(bbox_model_results):
+                if not hasattr(detection, "boxes") or detection.boxes is None:
+                    continue
+                boxes = []
+                for box in detection.boxes.data:
+                    x1, y1, x2, y2, conf, cls_id = box.tolist()
+                    boxes.append(
+                        BoundingBox(
+                            x1=int(x1),
+                            y1=int(y1),
+                            x2=int(x2),
+                            y2=int(y2),
+                            cls_id=int(cls_id),
+                            conf=float(conf),
+                        )
+                    )
+                bboxes[offset + frame_number_in_batch] = boxes
+        print("✅ BBoxes predicted")
+
+        keypoints: dict[int, tuple[int, int]] = {}
+        keypoints_model_results = self.keypoints_model.predict(batch_images)
+        if keypoints_model_results is not None:
+            for frame_number_in_batch, detection in enumerate(keypoints_model_results):
+                if not hasattr(detection, "keypoints") or detection.keypoints is None:
+                    continue
+                frame_keypoints: list[tuple[int, int]] = []
+                for part_points in detection.keypoints.data:
+                    for x, y, _ in part_points:
+                        frame_keypoints.append((int(x), int(y)))
+                if len(frame_keypoints) < n_keypoints:
+                    frame_keypoints.extend(
+                        [(0, 0)] * (n_keypoints - len(frame_keypoints))
+                    )
+                else:
+                    frame_keypoints = frame_keypoints[:n_keypoints]
+                keypoints[offset + frame_number_in_batch] = frame_keypoints
+        print("✅ Keypoints predicted")
+
+        results: list[TVFrameResult] = []
+        for frame_number in range(offset, offset + len(batch_images)):
+            results.append(
+                TVFrameResult(
+                    frame_id=frame_number,
+                    boxes=bboxes.get(frame_number, []),
+                    keypoints=keypoints.get(
+                        frame_number, [(0, 0) for _ in range(n_keypoints)]
+                    ),
+                )
+            )
+        print("✅ Combined results as TVFrameResult")
+        return results