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

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

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

• intel-compute-runtime (aur/legacy or extra for latest)
• level-zero-headers
• level-zero-loader

task pre-commit:init

Development Dependencies:

uv sync --dev

For CPU inference:

uv sync --extra cpu

For Intel XPU inference:

uv sync --extra xpu

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