Dockerfile + entrypoint for Hugging Face Spaces

The first deployable image: Python 3.12 base, full pip deps,
Ollama + granite4.1:3b baked in (~10 GB total), entrypoint starts
Ollama daemon in the background then uvicorn on port 7860.

helios_nyc.py is a small CLI probe for sanity-checking the
container locally — it walks the FSM end-to-end against a single
hard-coded address before any web traffic. Will get scrubbed once
agent.py covers the same role.

Dockerfile

@@ -0,0 +1,70 @@
+# Riprap — Hugging Face Spaces (Docker SDK) deployment.
+#
+# Bakes:
+#   - Python 3.12 + pip deps (~2.5 GB once torch is in)
+#   - Ollama + granite4.1:3b model (~2 GB)
+#   - All pre-computed fixtures in data/ + corpus/
+#
+# Runtime:
+#   - Ollama daemon serves Granite 4.1
+#   - Granite Embedding 278M auto-downloads via sentence-transformers
+#     on first FastAPI startup (~280 MB) — cached to /home/user/.cache
+#   - uvicorn FastAPI on port 7860 (HF default)
+
+FROM python:3.12-slim AS base
+
+# OS deps for geo libs + curl for ollama installer
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl ca-certificates \
+        gdal-bin libgdal-dev libgeos-dev libproj-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces convention: run as a non-root "user" account at /home/user/app.
+# Granite Embedding cache lives in /home/user/.cache/huggingface — it
+# survives container restarts when persistent storage is mounted there.
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/home/user/.cache/huggingface \
+    OLLAMA_HOST=127.0.0.1:11434 \
+    OLLAMA_NUM_PARALLEL=2 \
+    OLLAMA_KEEP_ALIVE=24h
+
+# Install Ollama (single-binary install)
+RUN curl -fsSL https://ollama.com/install.sh | sh
+
+WORKDIR /home/user/app
+
+# Python deps (cache the layer)
+COPY --chown=user:user requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Pull Granite 4.1:3b into the image. The official Ollama installer
+# stores models under /usr/share/ollama/.ollama by default; we point at a
+# user-writable location so the runtime container can also serve.
+ENV OLLAMA_MODELS=/home/user/.ollama/models
+RUN mkdir -p $OLLAMA_MODELS && \
+    (ollama serve &) && \
+    sleep 3 && \
+    ollama pull granite4.1:3b && \
+    sleep 1 && \
+    pkill -f "ollama serve" || true
+
+# App code + fixtures
+COPY --chown=user:user app/ ./app/
+COPY --chown=user:user web/ ./web/
+COPY --chown=user:user scripts/ ./scripts/
+COPY --chown=user:user data/ ./data/
+COPY --chown=user:user corpus/ ./corpus/
+COPY --chown=user:user agent.py helios_nyc.py ./
+COPY --chown=user:user entrypoint.sh ./
+RUN chmod +x ./entrypoint.sh
+
+# Hand off to a non-root user the way HF Spaces expects
+RUN chown -R user:user /home/user
+USER user
+
+EXPOSE 7860
+CMD ["./entrypoint.sh"]

entrypoint.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# Start Ollama daemon in the background, wait for it to be ready,
+# then launch uvicorn on the HF Spaces default port.
+set -e
+
+ollama serve > /tmp/ollama.log 2>&1 &
+OLLAMA_PID=$!
+
+# Wait for Ollama to be reachable (up to 30 s)
+for i in $(seq 1 30); do
+  if curl -sf http://127.0.0.1:11434/ > /dev/null 2>&1; then
+    echo "[entrypoint] ollama up (pid $OLLAMA_PID)"
+    break
+  fi
+  sleep 1
+done
+
+# Sanity check: Granite 4.1 model is present
+ollama list | grep -q "granite4.1:3b" || {
+  echo "[entrypoint] WARNING: granite4.1:3b not found in ollama; pulling..."
+  ollama pull granite4.1:3b || true
+}
+
+exec uvicorn web.main:app --host 0.0.0.0 --port 7860 --log-level info

helios_nyc.py

@@ -0,0 +1,89 @@
+"""HeliOS-NYC — flood exposure register driver.
+
+Phase 1 MVP: schools × (Sandy + DEP Stormwater scenarios) → ranked CSV.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import warnings
+from pathlib import Path
+
+warnings.filterwarnings("ignore")
+
+import pandas as pd  # noqa: E402
+
+from app.assets import schools  # noqa: E402
+from app.flood_layers import dep_stormwater, sandy_inundation  # noqa: E402
+from app.score import WEIGHTS, score_frame  # noqa: E402
+
+OUT = Path(__file__).resolve().parent / "outputs"
+OUT.mkdir(exist_ok=True)
+
+
+def build_schools_register() -> pd.DataFrame:
+    print("loading schools...", file=sys.stderr)
+    s = schools.load()
+    print(f"  {len(s)} schools loaded", file=sys.stderr)
+
+    print("joining Sandy Inundation Zone...", file=sys.stderr)
+    s["sandy"] = sandy_inundation.join(s).astype(int)
+    print(f"  {int(s['sandy'].sum())} schools inside Sandy zone", file=sys.stderr)
+
+    for scen in ["dep_extreme_2080", "dep_moderate_2050", "dep_moderate_current"]:
+        print(f"joining {scen}...", file=sys.stderr)
+        j = dep_stormwater.join(s, scen)
+        s[scen] = (j["depth_class"] > 0).astype(int)
+        s[f"{scen}_depth_class"] = j["depth_class"].values
+        s[f"{scen}_depth_label"] = j["depth_label"].values
+        print(f"  {int(s[scen].sum())} schools inside {scen}", file=sys.stderr)
+
+    s = score_frame(s)
+
+    # drop geometry for CSV; keep lat/lon for journalist usability
+    s["lat"] = s.geometry.to_crs("EPSG:4326").y
+    s["lon"] = s.geometry.to_crs("EPSG:4326").x
+    cols = ["loc_code", "name", "address", "borough", "bbl", "bin",
+            "geo_district", "lat", "lon",
+            "sandy",
+            "dep_extreme_2080", "dep_extreme_2080_depth_label",
+            "dep_moderate_2050", "dep_moderate_2050_depth_label",
+            "dep_moderate_current", "dep_moderate_current_depth_label",
+            "score", "tier"]
+    return pd.DataFrame(s[cols])
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="HeliOS-NYC flood exposure register")
+    ap.add_argument("--asset-class", default="schools")
+    ap.add_argument("--out", default=None)
+    ap.add_argument("--top", type=int, default=20, help="rows to print to stdout")
+    args = ap.parse_args()
+
+    if args.asset_class != "schools":
+        print(f"asset class '{args.asset_class}' not yet implemented", file=sys.stderr)
+        return 2
+
+    df = build_schools_register()
+    df = df.sort_values(["score", "name"], ascending=[False, True])
+
+    out_path = Path(args.out) if args.out else OUT / "schools_register.csv"
+    df.to_csv(out_path, index=False)
+    print(f"\nwrote {len(df)} rows -> {out_path}", file=sys.stderr)
+
+    print(f"\n=== top {args.top} ===")
+    print(df.head(args.top).to_string(index=False))
+
+    print("\n=== tier distribution ===")
+    print(df["tier"].value_counts().sort_index().to_string())
+
+    print("\n=== signal totals ===")
+    for k in WEIGHTS:
+        if k in df.columns:
+            print(f"  {k:24s}: {int(df[k].sum()):4d} schools")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())