feat: add YOLOv8 object detection API

- FastAPI application with /health and /detect endpoints
- YOLO model loaded at startup via lifespan
- Docker support for Hugging Face Spaces deployment
- Dev tooling: ruff, mypy, pytest with configurations
- CI workflow for lint, typecheck, tests and lockfile check
- HF sync workflow with commitizen for releases
- Test suite for API endpoints

.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  lockfile:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release a new version') && !startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    name: Check lockfile
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Check uv.lock is up to date
+        run: uv lock --check
+
+  lint:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release a new version') && !startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    name: Lint (ruff)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Restore uv cache
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+  typecheck:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release a new version') && !startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    name: Type check (mypy)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Restore uv cache
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run mypy
+        run: uv run mypy app.py
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+  test:
+    if: "!startsWith(github.event.head_commit.message, 'chore: release a new version') && !startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    name: Test (pytest)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Restore uv cache
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests with coverage
+        run: uv run pytest -v --cov=app --cov-report=term-missing
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/hf-sync.yml

@@ -0,0 +1,46 @@
+name: Sync to Hugging Face Hub
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  bump_version:
+    if: "startsWith(github.event.head_commit.message, 'chore: release a new version') && !startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    environment: release
+    name: Bump version, create changelog and sync to HF
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: commitizen-tools/commitizen-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          changelog_increment_filename: changes.md
+          changelog: true
+          debug: false
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: changes.md
+          tag_name: v${{ env.REVISION }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Sync to Hugging Face Hub
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_REPO_ID: ${{ vars.HF_REPO_ID }}
+          HF_USER: ${{ vars.HF_USER }}
+        run: |
+          git remote add hf "https://${HF_USER}:${HF_TOKEN}@huggingface.co/spaces/${HF_REPO_ID}"
+          git push hf main --force
+          git push hf --tags --force

.gitignore

@@ -0,0 +1,85 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.python-version
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# YOLO model weights
+*.pt
+*.onnx
+*.engine
+
+# UV
+.uv/

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    UV_SYSTEM_PYTHON=1
+
+WORKDIR /app
+
+# Dépendances système nécessaires à YOLO / OpenCV
+RUN apt-get update && apt-get install -y \
+    curl \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Installer uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# Copier les fichiers de dépendances
+COPY pyproject.toml uv.lock ./
+
+# Installer les deps (prod only)
+RUN uv sync --no-dev
+
+# Copier le code
+COPY app.py .
+
+EXPOSE 7860
+
+CMD ["uv", "run", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,198 @@
+---
+title: Reachy Vision API
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+---
+
+# Reachy Vision API
+
+**FastAPI-based YOLOv8 vision API for Reachy robots.**
+
+Reachy Vision API is a lightweight object detection service built with **FastAPI** and **YOLOv8**, designed to run on **Hugging Face Spaces (Docker)** or locally, and to be easily integrated with **Reachy robots** or any backend.
+
+---
+
+## ✨ Features
+
+- 🔍 Object detection powered by **YOLOv8**
+- ⚡ FastAPI HTTP API (simple & stateless)
+- 🐳 Hugging Face **Docker Space** compatible
+- 🧠 CPU-friendly (`yolov8n` by default)
+- 🤖 Ready to integrate with **Reachy Mini**
+- 📦 Dependency management with **uv**
+
+---
+
+## 📡 API Endpoints
+
+### Health check
+```
+GET /health
+```
+
+Response:
+```json
+{ "status": "ok" }
+```
+
+---
+
+### Object detection
+```
+POST /detect
+```
+
+**Request**
+- `multipart/form-data`
+- Field: `file` (image)
+
+**Example**
+```bash
+curl -X POST \
+  -F "file=@image.jpg" \
+  http://localhost:7860/detect
+```
+
+**Response**
+```json
+{
+  "num_detections": 2,
+  "detections": [
+    {
+      "class_id": 0,
+      "class_name": "person",
+      "confidence": 0.92,
+      "bbox_xyxy": [120.3, 45.1, 380.7, 620.9]
+    }
+  ]
+}
+```
+
+---
+
+## 🚀 Deployment (Hugging Face Space)
+
+Recommended setup:
+
+- **Space type**: `Docker`
+- **Hardware**: CPU (default) or GPU
+- **Exposed port**: `7860`
+
+### Repository structure
+
+```
+reachy-vision-api/
+├── app.py              # FastAPI application
+├── Dockerfile          # Docker image definition
+├── pyproject.toml      # Project configuration and dependencies
+├── uv.lock             # Lockfile for reproducible builds
+├── .gitignore          # Git ignore rules
+├── tests/              # Test suite
+│   ├── __init__.py
+│   ├── conftest.py     # Pytest fixtures
+│   └── test_api.py     # API tests
+└── README.md
+```
+
+Once pushed, the Space will automatically build and expose:
+```
+https://<username>-<space-name>.hf.space
+```
+
+---
+
+## 🐳 Docker (local run)
+
+```bash
+docker build -t reachy-vision-api .
+docker run -p 7860:7860 reachy-vision-api
+```
+
+---
+
+## 📦 Dependencies
+
+Dependencies are managed using **uv**.
+
+Main dependencies:
+- `fastapi`
+- `uvicorn`
+- `ultralytics`
+- `pillow`
+- `python-multipart`
+
+The lockfile (`uv.lock`) ensures reproducible builds.
+
+---
+
+## 🛠️ Development
+
+Install dev dependencies:
+```bash
+uv sync --extra dev
+```
+
+### Tools
+
+- **ruff** - Linter and formatter
+- **mypy** - Static type checker
+- **pytest** - Testing framework
+- **pytest-cov** - Code coverage
+
+### Run tests
+```bash
+uv run pytest
+```
+
+Coverage report is generated in `htmlcov/` and displayed in terminal.
+
+### Lint and format
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+### Type checking
+```bash
+uv run mypy app.py
+```
+
+### Release workflow
+
+This project uses [commitizen](https://commitizen-tools.github.io/commitizen/) for versioning and changelog generation.
+
+To trigger a new release, push a commit to `main` with the message `chore: release a new version`:
+
+```bash
+git commit --allow-empty -m "chore: release a new version"
+git push origin main
+```
+
+This will:
+1. Bump the version based on conventional commits
+2. Generate/update the CHANGELOG
+3. Create a GitHub Release
+4. Sync to Hugging Face Space
+
+---
+
+## 🤖 Usage with Reachy
+
+This API is designed to be called from:
+- Reachy Mini
+- A central VPS backend
+- Another Hugging Face Space
+
+Typical flow:
+1. Capture image from Reachy camera
+2. Send image to `/detect`
+3. Use detections for interaction, navigation, or reasoning
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

app.py

@@ -0,0 +1,54 @@
+import io
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, File, UploadFile
+from PIL import Image
+from ultralytics import YOLO
+
+logger = logging.getLogger("uvicorn.error")
+
+model: YOLO | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global model
+    logger.info("Loading YOLO model...")
+    model = YOLO("yolov8n.pt")
+    logger.info("Model loaded successfully!")
+    yield
+    logger.info("Shutting down...")
+
+
+app = FastAPI(title="Reachy Vision API", lifespan=lifespan)
+
+
+@app.get("/health", include_in_schema=False)
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/detect")
+async def detect(file: UploadFile = File(...)):
+    if model is None:
+        raise RuntimeError("Model not loaded")
+
+    image_bytes = await file.read()
+    image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+
+    results = model(image)
+
+    detections = []
+    for r in results:
+        for box in r.boxes:
+            detections.append(
+                {
+                    "class_id": int(box.cls),
+                    "class_name": model.names[int(box.cls)],
+                    "confidence": float(box.conf),
+                    "bbox_xyxy": [float(x) for x in box.xyxy[0]],
+                }
+            )
+
+    return {"num_detections": len(detections), "detections": detections}

pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "reachy-vision-api"
+version = "0.0.0"
+description = " Lightweight YOLOv8 vision API for real-time object detection on Reachy robots."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "fastapi",
+  "uvicorn",
+  "ultralytics",
+  "pillow",
+  "python-multipart"
+]
+
+[project.optional-dependencies]
+dev = [
+  "ruff",
+  "mypy",
+  "pytest",
+  "pytest-cov",
+  "httpx",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=app --cov-report=term-missing --cov-report=html"
+
+[tool.coverage.run]
+source = ["app"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if __name__ == .__main__.:",
+]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.0.0"
+version_files = ["pyproject.toml:^version"]
+tag_format = "v$version"
+update_changelog_on_bump = true

tests/conftest.py

@@ -0,0 +1,10 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from app import app
+
+
+@pytest.fixture(scope="session")
+def client():
+    with TestClient(app) as c:
+        yield c

tests/test_api.py

@@ -0,0 +1,137 @@
+import io
+from unittest.mock import MagicMock
+
+import pytest
+import torch
+from PIL import Image
+
+import app as app_module
+
+
+def test_health(client):
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+def test_detect_returns_detections(client):
+    img = Image.new("RGB", (640, 480), color="red")
+    buffer = io.BytesIO()
+    img.save(buffer, format="PNG")
+    buffer.seek(0)
+
+    response = client.post("/detect", files={"file": ("test.png", buffer, "image/png")})
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "num_detections" in data
+    assert "detections" in data
+    assert isinstance(data["detections"], list)
+
+
+def test_detect_with_jpeg(client):
+    img = Image.new("RGB", (640, 480), color="blue")
+    buffer = io.BytesIO()
+    img.save(buffer, format="JPEG")
+    buffer.seek(0)
+
+    response = client.post(
+        "/detect", files={"file": ("test.jpg", buffer, "image/jpeg")}
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "num_detections" in data
+    assert "detections" in data
+
+
+def test_detect_missing_file(client):
+    response = client.post("/detect")
+    assert response.status_code == 422
+
+
+def test_detect_response_structure(client):
+    img = Image.new("RGB", (100, 100), color="green")
+    buffer = io.BytesIO()
+    img.save(buffer, format="PNG")
+    buffer.seek(0)
+
+    response = client.post("/detect", files={"file": ("test.png", buffer, "image/png")})
+
+    assert response.status_code == 200
+    data = response.json()
+    assert isinstance(data["num_detections"], int)
+    assert data["num_detections"] >= 0
+    assert data["num_detections"] == len(data["detections"])
+
+    for detection in data["detections"]:
+        assert "class_id" in detection
+        assert "class_name" in detection
+        assert "confidence" in detection
+        assert "bbox_xyxy" in detection
+        assert isinstance(detection["class_id"], int)
+        assert isinstance(detection["class_name"], str)
+        assert 0 <= detection["confidence"] <= 1
+        assert len(detection["bbox_xyxy"]) == 4
+
+
+def test_detect_model_not_loaded(client):
+    """Test that detect raises error when model is not loaded."""
+    original_model = app_module.model
+    app_module.model = None
+
+    try:
+        img = Image.new("RGB", (100, 100), color="red")
+        buffer = io.BytesIO()
+        img.save(buffer, format="PNG")
+        buffer.seek(0)
+
+        with pytest.raises(RuntimeError, match="Model not loaded"):
+            client.post("/detect", files={"file": ("test.png", buffer, "image/png")})
+    finally:
+        app_module.model = original_model
+
+
+def test_detect_with_detections(client):
+    """Test detection with mocked YOLO results containing detections."""
+    original_model = app_module.model
+
+    # Create mock model
+    mock_model = MagicMock()
+    mock_model.names = {0: "person", 1: "car"}
+
+    # Create mock box
+    mock_box = MagicMock()
+    mock_box.cls = torch.tensor([0])
+    mock_box.conf = torch.tensor([0.95])
+    mock_box.xyxy = torch.tensor([[100.0, 150.0, 300.0, 400.0]])
+
+    # Create mock result
+    mock_result = MagicMock()
+    mock_result.boxes = [mock_box]
+
+    mock_model.return_value = [mock_result]
+    app_module.model = mock_model
+
+    try:
+        img = Image.new("RGB", (640, 480), color="red")
+        buffer = io.BytesIO()
+        img.save(buffer, format="PNG")
+        buffer.seek(0)
+
+        response = client.post(
+            "/detect", files={"file": ("test.png", buffer, "image/png")}
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["num_detections"] == 1
+        assert len(data["detections"]) == 1
+        assert data["detections"][0]["class_id"] == 0
+        assert data["detections"][0]["class_name"] == "person"
+        assert data["detections"][0]["confidence"] == pytest.approx(0.95)
+        assert data["detections"][0]["bbox_xyxy"] == pytest.approx(
+            [100.0, 150.0, 300.0, 400.0]
+        )
+    finally:
+        app_module.model = original_model