Foundation Model Inference

Apply a pretrained foundation model from registry/models/ to raster input(s). Resolves the model record, downloads + hash-verifies the weights on first use, runs the inference pass via the model's declared framework (PyTorch/TerraTorch, ONNX, etc.), and emits a per-run RunRecord that the Evidence Bundle composes alongside the prediction.

ID	fm_inference
Domain	geo
Category	ml
Type	raster-model-to-raster
Version	0.1.0

view yaml ◦view github ◦

Outputs

prediction: raster · Primary prediction output. For segmentation heads: class labels (uint8). For probability heads: scaled to uint8 0-255. Use params.output_format to change.
probability: raster · Per-class probability map (one band per class). Emitted only when params.emit_probability is true. Useful for uncertainty propagation into Evidence Bundles.
embedding: raster_or_tensor · Per-tile or per-pixel embedding tensor. Emitted only when the model record's output.types includes `embedding` and params.emit_embedding is true. Shape determined by the backbone's embedding_dim.
run_record: provenance_record · Content-addressable record of the inference call. Carries: - model_id (registry/models/ slug) - model_hash (SHA256 of weights file) - input_hashes (SHA256s of each input raster) - params (canonicalized JSON of all params used) - engine (e.g. terratorch), engine_version (e.g. terratorch==0.99.7) - timestamp (UTC ISO-8601) - device (cpu | cuda:0 | mps) Consumed by `geo:evidence_bundle_emit` (separate ticket) as a signed input to the bundle's PROV-O graph.

Parameters

model: string · required · Model record slug (filename in registry/models/, without .yaml). Examples: prithvi-eo-2.0-300m, prithvi-eo-2.0-300m-burnscars, clay-v1.5, alphaearth-foundations-v1. The op fails fast with a clear error if the record is missing or its weights URL is unreachable.
device: string · default auto · Inference device: auto | cpu | cuda:0 | cuda:1 | mps. `auto` picks the most powerful available (cuda > mps > cpu). The choice is logged in RunRecord.device so re-runs can match.
engine: string · Inference engine override. Default reads the model record's `framework` field. Valid values: terratorch, pytorch, onnx, jax. The engine version is captured in RunRecord.
num_frames: integer · Number of temporal frames for temporal models (Prithvi). Default reads the model record's input.num_frames. Must match len(images) if `images` passed; ignored otherwise.
batch_size: integer · default 16 · Tiles per forward pass. Lower for memory-constrained runs.
tile_size: integer · Spatial tile edge (pixels). Default reads the model record's input.image_size (224 for Prithvi, 256 for Clay). Inputs larger than one tile are gridded; outputs are stitched.
tile_overlap: integer · default 0 · Pixels of overlap between tiles. Smooths boundaries when stitching segmentation outputs. Set to ~16 for thin-feature segmentation.
threshold: float · default 0.5 · Confidence threshold for binary segmentation heads. Pixels with probability >= threshold map to class 1.
output_format: string · default mask · mask | probability | embedding. `mask` returns a uint8 class label raster; `probability` returns the float32 probability raster; `embedding` returns the per-tile/per-pixel embedding tensor (only valid when the model supports it).
emit_probability: boolean · default false · Emit the float32 probability map alongside the primary prediction.
emit_embedding: boolean · default false · Emit the embedding tensor. Requires the model record's output.types to include `embedding`. Useful for downstream similarity / retrieval.
weights_cache_dir: string · Directory for cached weight downloads. Default $FOLIA_CACHE_DIR/models/ or ~/.folia/cache/models/. Weights are content-addressed by SHA256, so multiple recipes can share a cache safely.
reject_on_hash_mismatch: boolean · default true · If the downloaded weights file's SHA256 does not match the model record's weights_hash field, fail the run instead of using the weights. Set to false only for development against pre-release model records where the hash is not yet known.
license_acceptance: boolean · default false · Required to be true when the model record's license tier is `free_nc` (non-commercial) or `commercial`. Forces the recipe author to acknowledge license terms. Free / Apache / MIT / CC-BY models do not require this flag.