CoolFace
Apppublic

goabonga/reachy-vision-api

sourceHugging Faceupdated 9mo agoView on Hugging Face
0likes
App README

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 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. 1.Bump the version based on conventional commits
  2. 2.Generate/update the CHANGELOG
  3. 3.Create a GitHub Release
  4. 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. 1.Capture image from Reachy camera
  2. 2.Send image to /detect
  3. 3.Use detections for interaction, navigation, or reasoning

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.