fair-py-ops 0.3.0

Model registry and ML pipeline orchestration for fAIr

fAIr-models

Model registry and ML pipeline orchestration for fAIr.

fair-py-ops is the Python package for building ZenML pipelines, validating STAC items, and testing locally. The models/ directory is the single source of truth for base model contributions.

Quick Start

Prerequisites: Docker, uv, just.

git clone https://github.com/hotosm/fAIr-models.git
cd fAIr-models
just setup
just example

just setup installs Python deps, brings up the full stack via Docker Compose (Postgres + MinIO + STAC + MLflow + ZenML), and registers the ZenML stack. just example runs all three reference pipelines end-to-end.

Service	URL	Credentials
ZenML dashboard	http://localhost:8080	default / (empty)
MLflow	http://localhost:5000	none
STAC API	http://localhost:8082	none
MinIO console	http://localhost:9001	minioadmin / minioadmin

See Getting Started for the full guide. For Kubernetes parity or production deploys, see infra/README.md.

Documentation

• Getting Started : Installation and running the examples
• Architecture : STAC catalog structure, flows, identity model, infrastructure
• Contributing a Model : Guide for adding base models to fAIr
• API Reference : Python package documentation
• Changelog : Release history

Examples

Three reference implementations demonstrate the full workflow for each supported task:

Example	Task	Model	Path
Segmentation	Semantic segmentation	UNet (torchgeo)	examples/segmentation/
Classification	Binary classification	ResNet18 (torchvision)	examples/classification/
Detection	Object detection	YOLOv11n (ultralytics)	examples/detection/

Commands

Run just to see all recipes.

just setup     # install deps + bring up stack + register ZenML stack
just example   # run all 3 example pipelines
just down      # stop the stack (state preserved, fast restart)
just up        # restart after `just down`
just tear      # destroy stack + volumes + local ZenML state
just lint      # ruff + ty
just test      # pytest
just validate  # validate STAC items + model pipelines
just docs      # serve documentation locally
just commit    # run pre-commit hooks + commitizen

Key Concepts

Concept	Description
Base model	Reusable ML blueprint (weights, code, Docker image, STAC item)
Local model	Finetuned model produced by ZenML pipeline on user data
STAC catalog	Model/dataset registry with MLM and Version extensions
ZenML pipeline	Orchestrated training and inference workflows