README.package.md

PRO materialization service

This worker turns a place on the map into the evidence bundle that NU:TONIC's satellite intelligence stack can reason about. It fetches or prepares imagery, Sentinel-2 inputs, VLM-ready PNGs, and TiM-ready arrays so the app can move from "look at this area" to "explain what may be changing here."

For competition reviewers, this is the practical bridge between the public demo and the AI stack:

1. Pick an area.
2. Materialize the imagery and satellite context.
3. Feed the VLM and TiM paths.
4. Return a PRO-style bundle for human inspection.

HTTP worker for PRO_MATERIALIZATION_SERVICE_URL / NUTONIC_PRO_MATERIALIZATION_SERVICE_URL (docs/SERVER-AND-INFERENCE-ARCHITECTURE.md §5.3, plans/2026-04-12-pro-materialization-fetch-and-downscale-service.md). Kotlin clients do not call this URL (rules/13-client-cache-and-data-plane.md); the thin server/ may orchestrate POST /api/v1/pro/jobs → POST …/internal/v1/materialize.

Implemented

P0–P1

• GET /health, GET /internal/v1/healthz (s2_asset_mapping_version from packaged YAML).
• POST /internal/v1/materialize with sentinel_fetch_mode": "MINIMAL_RGB" (default): Mapbox pin → vlm_contract_id PNG (mapbox_rgb inline base64) + optional RGB_mapbox TiM NPZ ([1,3,224,224] BGR 0–255).
• vlm_contract_id: nutonic.pro.vlm.v1_512 → roles mapbox_rgb only. nutonic.pro.vlm.v1_512_fc_scl (plan §6.4) adds sentinel_fc (SWIR2/NIR/red false-color PNG) + cloud_mask_thumb (SCL → semi-transparent RGBA PNG); requires TERRAMIND_SPECTRAL or FULL_STAC and optional [s2] deps. nutonic.pro.vlm.v1_512_s2_only ships the same Sentinel-derived PNGs without mapbox_rgb; spectral modes do not require a Mapbox token for this contract.
• POST /api/v1/materialize/stub — backward-compatible wrapper.

P2 (Sentinel-2 + TerraMind spectral path)

• sentinel_fetch_mode: TERRAMIND_SPECTRAL or FULL_STAC runs STAC (Earth Search default) + 12-band patch at 224×224 (same asset key order as terramind_tim_local.s2_stac), reflectance scaled like TerraMind, merged into run_manifest.stac.
• enable_tim + tim_branch": "S2L2A_full" → NPZ key S2L2A [1,12,224,224] float32.
• FULL_STAC + RGB_mapbox TiM still uses Mapbox-derived RGB NPZ while STAC stack is fetched for manifest/audit.
• TERRAMIND_SPECTRAL + enable_tim requires S2L2A_full (422 TIM_BRANCH_REQUIRES_S2L2A_FULL if RGB_mapbox).
• data/s2_asset_allowlist.yaml: version + ordered assets (12 keys); drives cache key + STAC reads.
• Sentinel/STAC (pystac-client, rasterio) are core dependencies (since 0.3.1). Spectral modes still return 503 S2_DEPENDENCIES_MISSING only if imports fail at runtime (e.g. missing GDAL system libs — the service Dockerfile installs gdal-bin / libgdal-dev).

Constraints

• No torch / no terratorch in this package (plan §3.2).
• MAPBOX_ACCESS_TOKEN required when the resolved VLM contract includes mapbox_rgb (including MINIMAL_RGB and nutonic.pro.vlm.v1_512_fc_scl on spectral modes). Sentinel-only contracts (nutonic.pro.vlm.v1_512_s2_only) skip Mapbox entirely.

Competition-facing role

The service is deliberately separate from the app client and from GPU-heavy TiM/VLM inference. That separation makes the product story stronger:

• The app stays easy to install from CI artifacts.
• The materialization worker handles data preparation.
• TiM and VLM workers can scale independently.
• The same workflow can support conservation review, flood triage, wildfire monitoring, and climate adaptation use cases.

Environment

Variable	Purpose
MAPBOX_ACCESS_TOKEN	Mapbox Static Images token (omit only for Sentinel-only VLM contracts on TERRAMIND_SPECTRAL / FULL_STAC).
NUTONIC_INFERENCE_REQUIRE_INBOUND_HMAC	When 1, require signed requests.
NUTONIC_INFERENCE_HMAC_SECRET	Shared HMAC secret.

Run locally

pip install -e "./inference/pro_materialization_service[dev]"
set MAPBOX_ACCESS_TOKEN=your_token
uvicorn pro_materialization_service.main:app --host 127.0.0.1 --port 7865

From the monorepo root, tests should pick up this package’s src first (or use an editable install). If imports resolve to an older site-packages copy, set PYTHONPATH to inference/pro_materialization_service/src before running pytest.

Docker

docker build -t nutonic-pro-materialization inference/pro_materialization_service

The packaged Dockerfile installs gdal-bin and libgdal-dev (rasterio needs GDAL/PROJ/GEOS at runtime on Debian slim), then pip install ., and fails the build if import rasterio / pystac_client do not work.