addreadme.

README.md

@@ -1,3 +1,56 @@
----
-license: mit
----
+---
+license: mit
+tags:
+- yolov8
+- object-detection
+- computer-vision
+- sports-analytics
+- football
+datasets:
+- roboflow
+---
+
+# ⚽ P.U.L.S.E AI Detection Models
+
+These are the official pre-trained object detection models for **[P.U.L.S.E AI (Positional & Universal Live Statistical Engine)](https://github.com/AurevinP/PULSE_AI)**. 
+
+They are based on the Ultralytics YOLOv8 architecture and fine-tuned specifically for football (soccer) analytics.
+
+## Available Models
+
+| Filename | Base Model | Purpose |
+|---|---|---|
+| [ball_tracker_200_epoch_92L_25M.pt](AurevinP/PULSE_AI_Models/ball_tracker_200_epoch_92L_25M.pt) | YOLOv8 | Detects and tracks the football on the pitch. |
+| [yolov8s_player_tracker.pt](AurevinP/PULSE_AI_Models/yolov8s_player_tracker.pt) | YOLOv8s | Detects players, goalkeepers, and referees. |
+
+> **Note:** The team clustering model (SigLIP + UMAP + KMeans) used by P.U.L.S.E AI is trained dynamically from the input video at runtime and does not require pre-downloaded weights.
+
+## How to Use with P.U.L.S.E AI
+
+If you are using the P.U.L.S.E AI repository, these models will be downloaded automatically when you run the pipeline setup, or you can download them manually using the built-in script:
+
+```bash
+# From the root of the PULSE AI repository:
+python download_models.py
+```
+
+## Manual Python Usage
+
+If you wish to use these weights independently of the main P.U.L.S.E AI pipeline, you can load them directly via the `ultralytics` library:
+
+```python
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
+
+# 1. Download the ball tracker
+ball_model_path = hf_hub_download(
+    repo_id="AurevinP/PULSE_AI_Models", 
+    filename="ball_tracker_200_epoch_92L_25M.pt"
+)
+
+# 2. Load into YOLO
+model = YOLO(ball_model_path)
+
+# 3. Run inference
+results = model("path/to/football_video.mp4")
+```