Feature/ramp

.github/workflows/k8s-integration.yml

@@ -35,6 +35,8 @@ jobs:
           enable-cache: true
 
       - uses: extractions/setup-just@v2
+        with:
+          just-version: "1.39.0"
 
       - uses: helm/kind-action@v1
         with:

.github/workflows/validate-stac.yml

@@ -36,6 +36,8 @@ jobs:
           enable-cache: true
       - name: Install just
         uses: extractions/setup-just@v2
+        with:
+          just-version: "1.39.0"
       - name: Install dependencies
         run: uv sync --group dev
       - name: Validate STAC items

.gitignore

@@ -225,11 +225,19 @@ implementation.md
 
 # data
 data/sample/predict/predictions
+data/sample/ramp_work
+data/sample/yolo_work
 stac_catalog
 
 # hatch-vcs generated version file
 fair/_version.py
 
+
+# runs
+runs/
+
+# weights
+yolov8s_v2-seg.pt
 # dev infra
 infra/dev/.port-forward.pids
 infra/dev/.pf-logs/

fair/zenml/config.py

@@ -241,6 +241,7 @@ def generate_training_config(
     if k8s:
         config.setdefault("steps", {}).setdefault("train_model", {}).setdefault("settings", {}).update(k8s)
         config.setdefault("steps", {}).setdefault("evaluate_model", {}).setdefault("settings", {}).update(k8s)
+        config.setdefault("steps", {}).setdefault("export_onnx", {}).setdefault("settings", {}).update(k8s)
 
     return config
 

models/ramp/Dockerfile

@@ -0,0 +1,109 @@
+# syntax=docker/dockerfile:1.7
+
+# Base image: ghcr.io/hotosm/fair-utilities-ramp:gpu-latest (override BASE_IMAGE for CPU builds).
+# Build from the fAIr-models repo root:
+#   docker build -f models/ramp/Dockerfile --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --build-arg BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:gpu-latest --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --build-arg BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:cpu-latest --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --target runtime -t ramp:runtime .
+#   docker build -f models/ramp/Dockerfile --target inference -t ramp:inference .
+ARG BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:gpu-latest
+
+# ---------------------------------------------------------------------------
+# Builder stage: install model-pack deps into the base image venv
+# ---------------------------------------------------------------------------
+FROM ${BASE_IMAGE} AS builder
+
+ENV UV_LINK_MODE=copy
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+WORKDIR /workspace
+
+COPY pyproject.toml README.md fair_zenml_patch.pth /tmp/fair-src/
+COPY fair /tmp/fair-src/fair
+
+# The fair-utilities-ramp image already provides hot_fair_utilities, ramp-fair,
+# segmentation_models, and TensorFlow under /app/.venv. Add the fAIr model-pack
+# deps (fair itself, STAC validation, fairpredictor, onnx tooling) into that
+# same venv so training, tests, and inference share one interpreter.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 \
+    uv pip install --python /app/.venv/bin/python \
+    "pystac[validation]>=1.14.3" \
+    "universal-pathlib" \
+    "fairpredictor>=0.5.1" \
+    "onnx>=1.16" \
+    "tf2onnx>=1.16" \
+    /tmp/fair-src[k8s]
+
+# ---------------------------------------------------------------------------
+# Runtime stage: production image (no test deps)
+# ---------------------------------------------------------------------------
+FROM ${BASE_IMAGE} AS runtime
+
+WORKDIR /workspace
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    MPLBACKEND=Agg \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    RAMP_HOME=/app \
+    SM_FRAMEWORK=tf.keras \
+    NVIDIA_VISIBLE_DEVICES=all \
+    NVIDIA_DRIVER_CAPABILITIES=compute,utility
+
+COPY --from=builder /app/.venv /app/.venv
+
+COPY models/ramp models/ramp
+COPY models/conftest.py models/conftest.py
+COPY models/test_integration.py models/test_integration.py
+
+ENTRYPOINT ["/app/.venv/bin/python"]
+
+# ---------------------------------------------------------------------------
+# Test stage: add pytest + ZenML server deps for step & integration tests
+# ---------------------------------------------------------------------------
+FROM runtime AS test
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY --from=builder /tmp/fair-src /tmp/fair-src
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 \
+    uv pip install --python /app/.venv/bin/python /tmp/fair-src[test]
+
+# ---------------------------------------------------------------------------
+# Inference builder stage: distroless-ready venv with serving deps
+# ---------------------------------------------------------------------------
+FROM ghcr.io/astral-sh/uv:bookworm-slim AS inference-builder
+ENV UV_PYTHON_INSTALL_DIR=/python UV_PYTHON_PREFERENCE=only-managed
+RUN uv python install 3.13
+WORKDIR /app
+COPY pyproject.toml README.md fair_zenml_patch.pth /tmp/fair-src/
+COPY fair /tmp/fair-src/fair
+RUN --mount=type=cache,target=/root/.cache/uv \
+    export SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 && \
+    uv venv && uv pip install \
+    /tmp/fair-src[serve] \
+    rasterio \
+    pyproj \
+    numpy \
+    Pillow \
+    onnx \
+    onnxruntime
+COPY models/ramp/pipeline.py /app/models/ramp/pipeline.py
+
+# ---------------------------------------------------------------------------
+# Inference stage: distroless runtime for live serving
+# ---------------------------------------------------------------------------
+FROM gcr.io/distroless/python3-debian12:nonroot AS inference
+WORKDIR /app
+COPY --from=inference-builder /python /python
+COPY --from=inference-builder /app/.venv /app/.venv
+COPY --from=inference-builder /app/models /app/models
+ENV PATH="/app/.venv/bin:$PATH" PYTHONPATH=/app \
+    ZENML_CONFIG_PATH=/tmp/zenml
+EXPOSE 8080
+ENTRYPOINT ["/app/.venv/bin/python", "-m", "uvicorn"]
+CMD ["fair.serve.base:create_app", "--factory", "--host", "0.0.0.0", "--port", "8080"]

models/ramp/README.md

@@ -0,0 +1,83 @@
+# RAMP EfficientNetB0 + U-Net Building Segmentation
+
+## Overview
+
+RAMP is a semantic-segmentation model that extracts **building footprints** from **RGB very-high-resolution aerial/satellite imagery**. In this repository it is packaged as a **global** base model (worldwide STAC footprint) intended for **fine-tuning on a target area** and for **ONNX-based inference** within the fAIr pipeline.
+
+## Architecture
+
+- **Model**: `EffUnet` (EfficientNetB0 encoder + U-Net decoder)
+- **Task**: semantic segmentation
+- **Input**: \([-1, 256, 256, 3]\) float32 RGB chips (channels-last)
+- **Output**: \([-1, 256, 256, 4]\) float32 per-class scores for 4 classes
+  - **0**: background
+  - **1**: building
+  - **2**: boundary (helps separate adjacent buildings)
+  - **3**: contact (helps separate close neighbouring buildings)
+
+The boundary (class 2) and contact (class 3) channels help the model cleanly separate adjacent buildings at inference time, even when they share a wall. The `predict()` helper collapses the 4-class softmax to a binary building mask before vectorization.
+
+## Pretrained Source
+
+Pretrained artifacts for this model pack are declared in `models/ramp/stac-item.json`:
+
+- **Checkpoint (zipped TF SavedModel)**: `https://huggingface.co/hotosm/ramp/resolve/74daea54694f2e4924f1222520c614c7f5c029fe/v1-baseline.zip`
+- **ONNX model**: `https://huggingface.co/hotosm/ramp/resolve/83c77a7e5feb3af62e3604d7bb96c6c6e9ff1a96/ramp-v1.onnx`
+
+Upstream RAMP resources:
+
+- **Project documentation**: `https://rampml.global/`
+- **Upstream codebase**: `https://github.com/devglobalpartners/ramp-code`
+- **Training data**: RAMP datasets on Radiant MLHub (see `https://rampml.global/training-data/`). Per upstream docs, labels are **manually annotated** building footprints; the published RAMP training datasets are released under **CC BY-NC 4.0**.
+
+Published paper reference: none is included in this repository; cite the upstream project documentation/repository.
+
+## Limitations
+
+- **Domain shift**: performance may degrade on imagery with different sensors, resolutions, or preprocessing than the training distribution.
+- **Challenging imagery**: haze, blur, strong color casts, or off-nadir views can reduce quality.
+- **Dense/attached roofs**: polygonization may still merge neighbouring buildings in dense urban areas.
+
+## Usage
+
+### Inference (Docker)
+
+```bash
+docker build -f models/ramp/Dockerfile --target inference -t ramp:inference .
+docker run --rm -p 8080:8080 -e MODEL_MODULE=models.ramp.pipeline ramp:inference
+
+curl -s http://localhost:8080/health
+```
+
+Example request (server downloads tiles into chips, runs ONNX, returns GeoJSON FeatureCollection):
+
+```bash
+curl -s http://localhost:8080/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model_uri": "https://huggingface.co/hotosm/ramp/resolve/83c77a7e5feb3af62e3604d7bb96c6c6e9ff1a96/ramp-v1.onnx",
+    "image_uri": "https://example.com/tiles/{z}/{x}/{y}.png",
+    "bbox": [0.0, 0.0, 0.01, 0.01],
+    "zoom": 18,
+    "params": { "confidence_threshold": 0.5, "min_class_value": 1 }
+  }'
+```
+
+### Fine-tuning (Python)
+
+Fine-tuning is implemented as a ZenML pipeline in `models/ramp/pipeline.py` and is exercised end-to-end in `models/test_integration.py` via `fair.client.FairClient` (register → finetune → promote → predict).
+
+## Citation
+
+```bibtex
+@misc{ramp_docs,
+  title        = {Replicable AI for Microplanning (ramp)},
+  author       = {{DevGlobal Partners}},
+  howpublished = {\\url{https://rampml.global/}},
+  note         = {Accessed 2026-05-25}
+}
+```
+
+## License
+
+Apache-2.0