Skip to content

getting-started.md

Latest commit

 

History

History
111 lines (83 loc) · 3.97 KB

getting-started.md

File metadata and controls

111 lines (83 loc) · 3.97 KB
Raw
icon lucide/rocket

Getting Started

Prerequisites

!!! info "Required tools"

- :simple-docker: Docker
- :simple-astral: [uv](https://docs.astral.sh/uv/)
- [just](https://just.systems/)

Installation

=== ":lucide-laptop: Develop fAIr-models"

```bash title="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.

=== ":lucide-package: Use as a library"

```bash title="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.

??? example "Running a single example"

```bash
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

!!! success "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

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

- :lucide-blocks: Read the [Architecture](architecture.md) overview to understand the system
- :lucide-box: [Contribute a model](contributing/model.md) to fAIr
- :lucide-container: Stand up the [Kubernetes dev stack](development/k8s.md) for production-parity testing