README.md

metadata

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:

{ "status": "ok" }

---

Object detection

POST /detect

Request

• multipart/form-data
• Field: file (image)

Example

curl -X POST \
  -F "file=@image.jpg" \
  http://localhost:7860/detect

Response

{
  "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)

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:

uv sync --extra dev

Tools

• ruff - Linter and formatter
• mypy - Static type checker
• pytest - Testing framework
• pytest-cov - Code coverage

Run tests

uv run pytest

Coverage report is generated in htmlcov/ and displayed in terminal.

Lint and format

uv run ruff check .
uv run ruff format .

Type checking

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:

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 file for details.