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.
Prerequisites: Docker, uv, just.
git clone https://github.com/hotosm/fAIr-models.git
cd fAIr-models
just setup
just build
just examplejust setup installs Python deps, brings up the full stack via Docker Compose (Postgres + MinIO + STAC + MLflow + ZenML), and registers the ZenML stack. just build builds the model Docker images that the local_docker orchestrator runs each pipeline step in. just example runs all example 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.
- 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
Reference implementations demonstrate the full workflow:
| Example | Task | Model | Run |
|---|---|---|---|
| Building footprints | Semantic segmentation | DINOv3 ViT-S/16 + UperNet (PyTorch) | just example dinov3s_buildings |
| Solid waste grid | Semantic segmentation | YOLO26x classifier (ultralytics) | just example yolo_swag_waste_grid_segmentation |
| RGB pixels (minimal) | Semantic segmentation | Logistic regression (scikit-learn) | just example sklearn_rgb_segmentation |
Run just to see all 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 + ty
just test # pytest
just validate # validate STAC items + model pipelines
just docs # serve documentation locally
just commit # run pre-commit hooks + commitizen| 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 |
