Skip to content

Getting Started

Prerequisites

Required tools

Installation

Clone and bring up the stack
git clone https://github.com/hotosm/fAIr-models.git
cd fAIr-models
just setup

just setup installs Python deps with uv, brings up Postgres, MinIO, STAC, MLflow, and ZenML via Docker Compose, and registers the compose ZenML stack as active.

Add to your project
uv add fair-py-ops

Running the Example Pipelines

Example pipelines demonstrate the full workflow: register a base model, finetune on sample data, promote the best version, and run inference.

Example Task Model
just example dinov3s_buildings Semantic segmentation DINOv3 ViT-S/16 + UperNet (PyTorch)
just example yolo_swag_waste_grid_segmentation Semantic segmentation YOLO26x classifier (ultralytics)
just example sklearn_rgb_segmentation Semantic segmentation Logistic regression (scikit-learn)

Run All Pipelines

just build
just example

just build builds the model Docker images before any pipeline runs, since the compose ZenML stack executes each step in the model image via the local_docker orchestrator.

Running a single example 
AWS_ENDPOINT_URL=http://localhost:9000 \
AWS_ACCESS_KEY_ID=minioadmin \
AWS_SECRET_ACCESS_KEY=minioadmin \
FAIR_STAC_API_URL=http://localhost:8082 \
FAIR_DSN=postgresql://postgres:postgres@localhost:5432/fair_models \
    uv run python examples/run.py dinov3s_buildings

Verifying Results

After the pipeline completes

What Where
ZenML pipelines, steps, artifacts http://localhost:8080 (login: default / empty)
STAC collections http://localhost:8082/collections
MLflow runs http://localhost:5000
MinIO objects http://localhost:9001 (login: minioadmin / minioadmin)
Trained weights artifacts/
Predictions data/sample/test/predictions/

Project Structure

  • fair/ is the core library (pip-installable as fair-py-ops): STAC catalog management, builders, and validators under stac/, data helpers under utils/, and ZenML config generation, promotion, and steps under zenml/.
  • models/ holds base model contributions, one subdirectory per model.
  • examples/ holds the example pipeline runner for the models under models/.
  • infra/ holds the production stack (Kubernetes via helmfile); the local dev stack that just setup uses is under infra/compose/.
  • stacks/compose.yaml is the ZenML stack definition for the compose stack.
  • tests/ holds the pytest suite.

Development Commands

Available recipes
just setup     # install deps + bring up stack + register ZenML stack
just example   # run all 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 check + format + ty check
just test      # pytest
just validate  # validate STAC items + model pipelines
just docs      # serve documentation locally
just commit    # run pre-commit hooks + commitizen

Next Steps

Tip