Metadata-Version: 2.4
Name: fair-py-ops
Version: 0.2.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.93.3
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]==0.93.3; 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.93.3; 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

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

See [Getting Started](docs/getting-started.md) for detailed setup, environment options, and running individual examples.

## Documentation

- **[Getting Started](docs/getting-started.md)** : Installation, local setup, Kubernetes, and running 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/) |

## Available Commands

Run `just` to see all recipes. Common commands:

```bash
just setup          # Install dependencies and set up environment
just example        # Run all three example pipelines
just lint           # Run Ruff linting and type checking (ty)
just test           # Run unit tests
just k8s            # Set up Kubernetes dev environment
just local          # Switch back to local mode
```

## 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 |
