fAIr-models
July 22, 2026 ยท View on GitHub
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 |
