ML Detector

A Python application that filters images to keep only those containing the objects specified using YOLO object detection.

This project uses ruff (all rules) and basedpyright (strict mode). Run the full suite:

task lint

For faster iteration on Python-only checks:

uv run ruff check . && uv run basedpyright .

• uv: Fast Python package manager
• pre-commit: Git hooks framework
• Task: Task runner (optional)

• nvidia drivers (check with nvidia-smi)
• nvidia-container-toolkit

task sync -- cpu

For CUDA GPU acceleration:

task sync -- cuda

task pre-commit:init

source .venv/bin/activate

The application uses config/configuration.yaml for all settings, see for example configuration.

• CONFIG_PATH: Path to configuration file (default: config/configuration.yaml)

Example:

export CONFIG_PATH="/path/to/custom/config.yaml"

Available Model Sizes:

• nano: Fastest, lowest accuracy (~6MB)
• small: Good balance of speed/accuracy (~22MB) - Recommended
• medium: Higher accuracy, slower (~50MB)
• large: High accuracy, much slower (~100MB)
• xlarge: Highest accuracy, slowest (~220MB)

Device Options:

• cpu: Universal compatibility
• cuda: NVIDIA GPU acceleration
• mps: Apple Silicon GPU acceleration

Run the API server:

uv run src/inference.py

The API server will start at http://localhost:8000.

Service Information:

GET /

Returns service metadata including version and status.

Liveness Probe:

GET /livez

Kubernetes liveness probe. Returns 200 if the service process is alive.

Readiness Probe:

GET /readyz

Kubernetes readiness probe. Returns 200 when service is ready to handle requests. Returns 503 during initialization, shutdown, or when dependencies are unavailable.

Detect Person in Image:

POST /detect

Parameters:

• file: Image file (multipart/form-data)
• Supported formats: JPG, JPEG, PNG, BMP, TIFF

Example with curl:

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

Successful Detection:

{
  "filename": "image.jpg",
  "person_detected": true,
  "confidence": 0.89,
  "num_persons": 2,
  "person_boxes": [
    {
      "confidence": 0.89,
      "bbox": [120.5, 250.8, 380.2, 520.6]
    },
    {
      "confidence": 0.76,
      "bbox": [450.1, 180.3, 600.7, 480.9]
    }
  ]
}

No Person Detected:

{
  "filename": "image.jpg",
  "person_detected": false,
  "confidence": 0.0,
  "num_persons": 0,
  "person_boxes": []
}

Response Fields:

• filename: Original filename or "uploaded_image"
• person_detected: Boolean indicating if any person was found
• confidence: Highest confidence score among detected persons
• num_persons: Total number of persons detected
• person_boxes: Array of detection results with confidence and bounding box coordinates

Bounding Box Format: [x1, y1, x2, y2] where:

• x1, y1: Top-left corner coordinates
• x2, y2: Bottom-right corner coordinates

Basic health check:

curl http://localhost:8000/

Liveness probe:

curl http://localhost:8000/livez

Readiness probe:

curl http://localhost:8000/readyz

To run the unit test suite locally using pytest:

uv run pytest -v