Feat/user data input

CHANGELOG.md

@@ -11,6 +11,11 @@ The format is based on Keep a Changelog, and the project follows Semantic Versio
 ### Fixed
 
 - **Warm-cache model loading no longer touches the Hugging Face Hub.** Every checkpoint download (`hf_hub_download`/`snapshot_download` across all embedders, plus the rshf `from_pretrained` loaders for satmae/scalemae/satmaepp) now resolves against the local HF cache first and only goes online on a cache miss. Previously each fresh process issued a HEAD request to huggingface.co even when weights were fully cached, so Hub outages, 429 rate limits, or blocked networks froze `get_embedding` indefinitely — hit hardest by agent integrations that spawn a new process per call. Consequence of cache-first: cached weights are never re-checked against the Hub; delete the cached file to force a re-download. Shared helpers: `hf_hub_download_cache_first` / `snapshot_download_cache_first` / `resolve_pretrained_source_cache_first` in `embedders/shared.py`.
+- **Clay batch prefetched-input path no longer acquires a provider.** `ClayEmbedder.get_embeddings_batch_from_inputs` unconditionally initialized the provider even though prefetched inputs never fetch — invisible in exports (the provider was already live) but it forced Earth Engine auth on machines without GEE when embedding user-provided data. The single-embedding path already followed the lazy-provider convention; the batch path now matches it, with a regression test.
+
+### Added
+
+- **Bring-your-own-data API** — compute embeddings from imagery you already have, without any provider fetch or provider auth. Register each piece of imagery once as `UserData(data, collection, spatial=None, bands=None, temporal=None, scale_m=None)` — the pixels plus everything that describes them: collection, one band name per channel (raw provider units, `[C,H,W]` or `[T,C,H,W]`), and where/when they were acquired — then embed with just a model name: `get_embedding_from_data("galileo", data)` / `get_embeddings_batch_from_data(model, datas, batch_size=None)` (batch items carry their own spatial/temporal; same-temporal items dispatch together, results return in input order; `batch_size` caps the per-forward batch for small GPUs, while each model's per-device internal default still applies as a further cap). User data follows the package-wide `input_prep` policy with the same `"tile"` default as the fetch path: arrays larger than a model's input size are cut into model-native tiles at their own resolution and the outputs stitched, so every model sees the full detail regardless of its input size (galileo's 64 px and clay's 256 px get equal treatment); `input_prep="resize"` opts into one-step downsampling, and arrays a single tile covers keep the efficient batched dispatch. Flexible-size models consume user data natively by default via the new `EmbedderBase.resolve_input_image_size(model_config, input_hw=...)` hook — `olmoearth` (FlexiViT) adapts to the input's own size (snapped up to a patch multiple), so any patch runs as one seamless native pass instead of a tile mosaic, with no user action needed; a native pass beyond 512 px warns (attention cost grows quadratically with token count), and an explicit `image_size` in `model_config` restores fixed-size behavior (larger inputs tile at it). Batch items are grouped by native size so same-size items still dispatch together. The declaration is matched against the model's input sensor: superset band sets are sliced and reordered into model band order automatically, while a collection mismatch or missing band refuses the request with a `ModelError` naming what is missing (precomputed models always refuse). `bands` may be omitted only for the canonical case (12-channel S2 L2A → canonical `B1..B12` order); band identity is never guessed otherwise. `spatial` is optional, but models whose forward pass conditions on geometry (new `_requires_georef` embedder flag: clay, prithvi) refuse declarations without it — coordinates are never fabricated. `list_models_for_data` reports, without loading weights, which catalog models a declaration can serve and why the rest cannot. Matching shares the provider band-alias vocabulary (`"RED"` → `"B4"`, `"NIR_NARROW"` → `"B8A"`), collection shorthand aliases (`"s2"`, `"s1"`) resolve to full ids, and S2 declarations whose values look already normalized (max ≤ 1.5) warn about the raw-DN contract. Results carry `meta["user_input"]` provenance (declared bands, bands used, channel indices). See [docs/user_data.md](docs/user_data.md).
 
 ## [0.2.1] — 2026-07-27
 

docs/models.md

@@ -39,25 +39,27 @@ Some detail-page filenames still use older names for compatibility, but the cano
 
 ### On-the-fly Foundation Models
 
-| Model ID          | Primary Input                    | Dim  | Default Resolution | Temporal style          | Notable requirements                                    | Detail                         |
-| ----------------- | -------------------------------- | ---- | ------------------ | ----------------------- | ------------------------------------------------------- | ------------------------------ |
-| `prithvi`         | S2 6-band                       | 768  | 30m                | multi-frame (auto, ≤4)  | required temporal + location side inputs                 | [detail](models/prithvi.md)    |
-| `olmoearth`       | S2 L2A 12-band / S1 VV/VH       | 128–1024 | 10m            | multi-frame (auto, ≤12) | FlexiViT; 4 sizes (nano/tiny/base/large) | [detail](models/olmoearth.md) |
-| `dofa`            | Multispectral + wavelengths     | 768  | 10m                | single composite        | wavelength vector required                              | [detail](models/dofa.md)       |
-| `clay`            | S2 L2A 10-band                  | 1024 | 10m                | single composite        | metadata conditioning (latlon/time/gsd/wavelengths)     | [detail](models/clay.md)       |
-| `terramind`       | S2 12-band                      | 384  | 10m                | single composite        | ViT-S class; strict z-score normalization               | [detail](models/terramind.md)  |
-| `terrafm`         | S2 12-band or S1 VV/VH          | 768  | 10m                | single composite        | dual-modality by channel count                          | [detail](models/terrafm.md)    |
-| `thor`            | S2 10-band or S1 VV/VH          | 768  | 10m                | single composite        | dual-modality; grouped tokens; native-snap              | [detail](models/thor.md)       |
-| `galileo`         | S2 10-band time series          | 128  | 10m                | multi-frame (auto, ≤12) | nano default; month tokens                              | [detail](models/galileo.md)    |
-| `anysat`          | S2 10-band time series          | 768  | 10m                | multi-frame (fixed `T`) | JEPA; `s2_dates` DOY side input                         | [detail](models/anysat.md)     |
-| `agrifm`          | S2 10-band time series          | 1024 | 10m                | multi-frame (fixed `T`) | Video Swin; fixed `T` frame stack                       | [detail](models/agrifm.md)     |
-| `fomo`            | S2 12-band                      | 768  | 10m                | single composite        | per-channel spectral modality keys                      | [detail](models/fomo.md)       |
-| `wildsat`         | S2 RGB                          | 256  | 10m                | single composite        | biodiversity training; image_head default               | [detail](models/wildsat.md)    |
-| `satvision`       | TOA 14-channel (MODIS)          | 4096 | 1000m              | single composite        | SwinV2 Giant; strict channel calibration                | [detail](models/satvision.md)  |
-| `remoteclip`      | S2 RGB (`B4,B3,B2`)             | 512  | 10m                | single composite        | CLIP projection; RGB preprocessing                      | [detail](models/remoteclip.md) |
-| `scalemae`        | S2 RGB + scale                  | 1024 | 10m                | single composite        | `sensor.scale_m` is a model input                       | [detail](models/scalemae.md)   |
-| `satmae`          | S2 RGB (`B4,B3,B2`)             | 1024 | 10m                | single composite        | ViT-L; MAE token/grid                                   | [detail](models/satmae.md)     |
-| `satmaepp`        | S2 RGB (`B4,B3,B2`) or S2 10-band | 1024 | 10m              | single composite        | `modality=rgb` (default) or `s2_10b`; ViT-L; fMoW eval preprocessing; 10-band uses strict band order + grouped-channel tokens | [detail](models/satmaepp.md)   |
+| Model ID          | Primary Input                    | Dim  | Default Resolution | Input size (px) | Temporal style          | Notable requirements                                    | Detail                         |
+| ----------------- | -------------------------------- | ---- | ------------------ | --------------- | ----------------------- | ------------------------------------------------------- | ------------------------------ |
+| `prithvi`         | S2 6-band                       | 768  | 30m                | 224             | multi-frame (auto, ≤4)  | required temporal + location side inputs                 | [detail](models/prithvi.md)    |
+| `olmoearth`       | S2 L2A 12-band / S1 VV/VH       | 128–1024 | 10m            | 256 (flexible)  | multi-frame (auto, ≤12) | FlexiViT; 4 sizes (nano/tiny/base/large) | [detail](models/olmoearth.md) |
+| `dofa`            | Multispectral + wavelengths     | 768  | 10m                | 224             | single composite        | wavelength vector required                              | [detail](models/dofa.md)       |
+| `clay`            | S2 L2A 10-band                  | 1024 | 10m                | 256             | single composite        | metadata conditioning (latlon/time/gsd/wavelengths)     | [detail](models/clay.md)       |
+| `terramind`       | S2 12-band                      | 384  | 10m                | 224             | single composite        | ViT-S class; strict z-score normalization               | [detail](models/terramind.md)  |
+| `terrafm`         | S2 12-band or S1 VV/VH          | 768  | 10m                | 224             | single composite        | dual-modality by channel count                          | [detail](models/terrafm.md)    |
+| `thor`            | S2 10-band or S1 VV/VH          | 768  | 10m                | 288             | single composite        | dual-modality; grouped tokens; native-snap              | [detail](models/thor.md)       |
+| `galileo`         | S2 10-band time series          | 128  | 10m                | 64              | multi-frame (auto, ≤12) | nano default; month tokens                              | [detail](models/galileo.md)    |
+| `anysat`          | S2 10-band time series          | 768  | 10m                | 24              | multi-frame (fixed `T`) | JEPA; `s2_dates` DOY side input                         | [detail](models/anysat.md)     |
+| `agrifm`          | S2 10-band time series          | 1024 | 10m                | 224             | multi-frame (fixed `T`) | Video Swin; fixed `T` frame stack                       | [detail](models/agrifm.md)     |
+| `fomo`            | S2 12-band                      | 768  | 10m                | 64              | single composite        | per-channel spectral modality keys                      | [detail](models/fomo.md)       |
+| `wildsat`         | S2 RGB                          | 256  | 10m                | 224             | single composite        | biodiversity training; image_head default               | [detail](models/wildsat.md)    |
+| `satvision`       | TOA 14-channel (MODIS)          | 4096 | 1000m              | 128             | single composite        | SwinV2 Giant; strict channel calibration                | [detail](models/satvision.md)  |
+| `remoteclip`      | S2 RGB (`B4,B3,B2`)             | 512  | 10m                | 224             | single composite        | CLIP projection; RGB preprocessing                      | [detail](models/remoteclip.md) |
+| `scalemae`        | S2 RGB + scale                  | 1024 | 10m                | 224             | single composite        | `sensor.scale_m` is a model input                       | [detail](models/scalemae.md)   |
+| `satmae`          | S2 RGB (`B4,B3,B2`)             | 1024 | 10m                | 224             | single composite        | ViT-L; MAE token/grid                                   | [detail](models/satmae.md)     |
+| `satmaepp`        | S2 RGB (`B4,B3,B2`) or S2 10-band | 1024 | 10m              | 224 (rgb) / 96 (s2_10b) | single composite | `modality=rgb` (default) or `s2_10b`; ViT-L; fMoW eval preprocessing; 10-band uses strict band order + grouped-channel tokens | [detail](models/satmaepp.md)   |
+
+**Input size (px)** is the fixed spatial size each model's encoder consumes: under the default `input_prep="tile"`, inputs larger than it are cut into tiles of this size at native resolution and the outputs stitched (both for provider fetches and user-provided data — see [User Data API](user_data.md)); under `input_prep="resize"` they are downsampled to it in one step. Together with Default Resolution it gives the native footprint of one forward pass, e.g. galileo 64 px × 10 m ≈ 640 m. `olmoearth` (FlexiViT) accepts any size divisible by its patch size — 256 is its training tile size; user-provided data is consumed natively at its own size by default (warning above 512 px), and an explicit `model_config` `image_size` restores fixed-size behavior. `anysat` and `prithvi` sizes are env-tunable (`RS_EMBED_ANYSAT_IMG`, `RS_EMBED_PRITHVI_IMG`).
 
 ---