Metadata-Version: 2.4
Name: fair-py-ops
Version: 0.3.0
Summary: Model registry and ML pipeline orchestration for fAIr
Project-URL: Homepage, https://github.com/hotosm/fAIr-models
Project-URL: Documentation, https://hotosm.github.io/fAIr-models
Project-URL: Repository, https://github.com/hotosm/fAIr-models
Project-URL: Issues, https://github.com/hotosm/fAIr-models/issues
Project-URL: Changelog, https://github.com/hotosm/fAIr-models/blob/master/CHANGELOG.md
Author-email: HOTOSM <sysadmin@hotosm.org>
Maintainer-email: Kshitij Raj Sharma <krschap@duck.com>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: geospatial,humanitarian,machine-learning,mlops,model-registry,openstreetmap,stac
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: mlflow<4,>=2.1.1
Requires-Dist: onnxruntime>=1.24.4
Requires-Dist: pystac[validation]<2,>=1.14.3
Requires-Dist: universal-pathlib>=0.3.10
Requires-Dist: zenml==0.94.2
Provides-Extra: k8s
Requires-Dist: opentelemetry-proto>=1.25.0; extra == 'k8s'
Requires-Dist: pypgstac[psycopg]>=0.9; extra == 'k8s'
Requires-Dist: pystac-client<1,>=0.9; extra == 'k8s'
Requires-Dist: zenml[connectors-aws,connectors-kubernetes,s3fs,server]==0.94.2; extra == 'k8s'
Provides-Extra: serve
Requires-Dist: geomltoolkits>=2.0.2; extra == 'serve'
Requires-Dist: s3fs>=2025.3.0; extra == 'serve'
Requires-Dist: starlette<0.46,>=0.40; extra == 'serve'
Requires-Dist: uvicorn[standard]>=0.34; extra == 'serve'
Provides-Extra: test
Requires-Dist: kubernetes; extra == 'test'
Requires-Dist: pytest-cov>=6.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: zenml[server]==0.94.2; extra == 'test'
Description-Content-Type: text/markdown

# fAIr-models

[![codecov](https://codecov.io/gh/hotosm/fAIr-models/branch/master/graph/badge.svg)](https://codecov.io/gh/hotosm/fAIr-models)

Model registry and ML pipeline orchestration for [fAIr](https://github.com/hotosm/fAIr).

**`fair-py-ops`** is the Python package for building [ZenML](https://zenml.io/) pipelines, validating [STAC](https://stacspec.org/) items, and testing locally. The `models/` directory is the single source of truth for base model contributions.

## Quick Start

Prerequisites: Docker, [uv](https://docs.astral.sh/uv/), [just](https://just.systems/).

```bash
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](docs/getting-started.md) for the full guide. For Kubernetes parity or production deploys, see [`infra/README.md`](infra/README.md).

## Documentation

- **[Getting Started](docs/getting-started.md)** : Installation and running the examples
- **[Architecture](docs/architecture.md)** : STAC catalog structure, flows, identity model, infrastructure
- **[Contributing a Model](docs/contributing/model.md)** : Guide for adding base models to fAIr
- **[API Reference](docs/reference/index.md)** : Python package documentation
- **[Changelog](docs/changelog.md)** : 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/`](examples/segmentation/) |
| Classification | Binary classification | ResNet18 (torchvision) | [`examples/classification/`](examples/classification/) |
| Detection | Object detection | YOLOv11n (ultralytics) | [`examples/detection/`](examples/detection/) |

## Commands

Run `just` to see all recipes.

```bash
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](https://github.com/stac-extensions/mlm) and [Version](https://github.com/stac-extensions/version) extensions |
| **ZenML pipeline** | Orchestrated training and inference workflows |
