Merge pull request #57 from amrit110/feat/simplify-model-config-interface

feat: simplify model_config interface to direct keyword arguments

Author: Dinghye

docs/api.md

@@ -34,12 +34,11 @@ Most users only need these public functions:
 
 Model-specific configuration:
 
-- `get_embedding(...)` and `get_embeddings_batch(...)` accept `model_config`
-- `export_batch(...)` supports per-model `model_config` via `ExportModelRequest(...)`
-- currently documented model-level `model_config` usage includes `dofa`, `anysat`, `thor`, and `satmaepp_s2_10b`
-- for the currently documented variant-aware models, use a unified field: `model_config={"variant": "..."}`
-- valid `variant` values still depend on the selected model and currently exposed published checkpoints, so check the corresponding model detail page
-- unsupported `model_config` usage raises `ModelError` instead of being ignored silently
+- `get_embedding(...)` and `get_embeddings_batch(...)` accept model-specific settings as direct keyword arguments (e.g. `variant="large"`)
+- `export_batch(...)` supports per-model settings via `ExportModelRequest.configure("model", variant="large")`
+- currently documented variant-aware models: `dofa`, `anysat`, `thor`, `prithvi`, and `satmaepp_s2_10b`
+- valid `variant` values depend on the model — check the corresponding model detail page or call `describe_model(model_id)`
+- passing unsupported keyword arguments raises `ModelError`
 
 Sampling / fetch configuration:
 

docs/api_embedding.md

@@ -42,12 +42,12 @@ get_embedding(
     temporal: Optional[TemporalSpec] = None,
     sensor: Optional[SensorSpec] = None,
     fetch: Optional[FetchSpec] = None,
-    model_config: Optional[dict[str, Any]] = None,
     modality: Optional[str] = None,
     output: OutputSpec = OutputSpec.pooled(),
     backend: str = "auto",
     device: str = "auto",
     input_prep: InputPrepSpec | str = "resize",
+    **model_kwargs,
 ) -> Embedding
 ```
 
@@ -60,7 +60,7 @@ Computes the embedding for a single ROI.
 - `temporal`: `TemporalSpec` or `None`
 - `sensor`: input descriptor for on-the-fly models; for most precomputed models this can be `None`
 - `fetch`: lightweight sampling override for common cases such as `scale_m`, `cloudy_pct`, `composite`, and `fill_value`
-- `model_config`: optional model-specific runtime settings; for the currently documented variant-aware models, use it mainly as `{"variant": ...}`
+- `**model_kwargs`: model-specific settings passed as direct keyword arguments (e.g. `variant="large"`); the accepted keys depend on the model — call `describe_model(model_id)` to see the schema
 - `modality`: optional model-facing modality selector (for example `s1`, `s2`, `s2_l2a`) for models that expose multiple input branches
 - `output`: `OutputSpec.pooled()` or `OutputSpec.grid(...)`
 - `backend`: access backend. `backend="auto"` is the public default and the recommended choice. For provider-backed on-the-fly models it resolves to a compatible provider backend; for precomputed models it lets rs-embed choose the model-compatible access path.
@@ -79,17 +79,18 @@ Modality contract:
 - Only models that explicitly expose a given modality can use it.
 - Unsupported modality selections raise a `ModelError`.
 
-`model_config` contract:
+Model-specific settings contract:
 
-- `model_config` is optional and model-specific
-- for the currently documented variant-aware models, the public field is unified as `variant`
-- examples currently documented in model pages include:
-  - `dofa`: `{"variant": "base" | "large"}`
-  - `anysat`: `{"variant": "base"}`
-  - `thor`: `{"variant": "tiny" | "small" | "base" | "large"}`
-  - `satmaepp_s2_10b`: `{"variant": "large"}`
-- if a model does not document `model_config`, leave it unset; unsupported usage raises `ModelError`
-- when available, `describe()["model_config"]` is the machine-readable schema for supported keys and values
+- model settings are optional and vary per model
+- pass them as direct keyword arguments rather than a dict (e.g. `variant="large"`)
+- variant-aware models currently documented:
+  - `dofa`: `variant="base"` or `variant="large"`
+  - `anysat`: `variant="base"`
+  - `thor`: `variant="tiny"`, `"small"`, `"base"`, or `"large"`
+  - `satmaepp_s2_10b`: `variant="large"`
+  - `prithvi`: `variant="prithvi_eo_v2_100_tl"`, `"prithvi_eo_v2_300_tl"`, or `"prithvi_eo_v2_600_tl"`
+- if a model does not accept any keyword arguments, passing unknown keys raises `ModelError`
+- `describe_model(model_id)["model_config"]` is the machine-readable schema for supported keys and values
 
 **Returns**
 
@@ -113,7 +114,7 @@ emb = get_embedding(
 vec = emb.data  # (D,)
 ```
 
-**Example with `model_config`**
+**Example with variant selection**
 
 ```python
 from rs_embed import PointBuffer, TemporalSpec, OutputSpec, get_embedding
@@ -124,7 +125,7 @@ emb = get_embedding(
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
     output=OutputSpec.pooled(),
     backend="gee",
-    model_config={"variant": "large"},
+    variant="large",
 )
 ```
 
@@ -140,12 +141,12 @@ get_embeddings_batch(
     temporal: Optional[TemporalSpec] = None,
     sensor: Optional[SensorSpec] = None,
     fetch: Optional[FetchSpec] = None,
-    model_config: Optional[dict[str, Any]] = None,
     modality: Optional[str] = None,
     output: OutputSpec = OutputSpec.pooled(),
     backend: str = "auto",
     device: str = "auto",
     input_prep: InputPrepSpec | str = "resize",
+    **model_kwargs,
 ) -> List[Embedding]
 ```
 
@@ -182,7 +183,7 @@ embs = get_embeddings_batch(
 )
 ```
 
-**Batch example with `model_config`**
+**Batch example with variant selection**
 
 ```python
 from rs_embed import PointBuffer, TemporalSpec, OutputSpec, get_embeddings_batch
@@ -198,7 +199,7 @@ embs = get_embeddings_batch(
     temporal=TemporalSpec.range("2022-01-01", "2023-01-01"),
     output=OutputSpec.pooled(),
     backend="gee",
-    model_config={"variant": "base"},
+    variant="base",
 )
 ```
 

docs/api_export.md

@@ -197,14 +197,14 @@ models=[
 ]
 ```
 
-`ExportModelRequest(...)` also carries per-model `model_config`, for example:
+`ExportModelRequest.configure(...)` also accepts model-specific settings as keyword arguments, for example:
 
 ```python
 from rs_embed import ExportModelRequest
 
 models=[
     "remoteclip",
-    ExportModelRequest("thor", model_config={"variant": "large"}),
+    ExportModelRequest.configure("thor", variant="large"),
 ]
 ```
 
@@ -213,7 +213,7 @@ Typical use cases:
 - one model needs a different `FetchSpec`
 - one model needs `modality="s1"`
 - one model needs a different `SensorSpec`
-- one model needs a different `model_config` such as `{"variant": "large"}`
+- one model needs a different variant (e.g. `variant="large"`)
 - one model should override the shared export settings
 
 This also matches the implementation path: string model IDs are first converted into `ExportModelRequest(name=...)`, then resolved.
@@ -224,11 +224,11 @@ Modality rules:
 - one model can override it via `ExportModelRequest(...)`
 - unsupported modality choices raise `ModelError`
 
-`model_config` rules:
+Per-model settings rules:
 
-- `export_batch(...)` does not have one global `model_config` shared across all models
-- pass per-model runtime settings through `ExportModelRequest(..., model_config=...)`
-- unsupported `model_config` usage raises `ModelError`
+- `export_batch(...)` does not have a global model settings parameter shared across all models
+- pass per-model settings through `ExportModelRequest.configure("model", variant=...)`
+- unsupported keyword arguments raise `ModelError`
 
 ---
 
@@ -328,7 +328,7 @@ from rs_embed import (
 export_batch(
     spatials=[PointBuffer(121.5, 31.2, 2048)],
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
-    models=[ExportModelRequest("thor", model_config={"variant": "large"})],
+    models=[ExportModelRequest.configure("thor", variant="large")],
     target=ExportTarget.combined("exports/thor_large_run"),
     backend="gee",
 )
@@ -356,6 +356,6 @@ If provider-backed export is used and both `save_inputs=True` and `save_embeddin
 
 !!! tip "Simple rule"
     Start with `ExportTarget.combined(...)` + `ExportConfig()`.
-    Add `ExportModelRequest(...)` only for the few models that need per-model sensor, modality, or `model_config` overrides.
+    Add `ExportModelRequest.configure(...)` only for the few models that need per-model sensor, modality, or variant overrides.
 
 ---

docs/api_specs.md

@@ -355,12 +355,12 @@ ExportConfig(
 
 ExportModelRequest("remoteclip")
 ExportModelRequest("terrafm", modality="s1", sensor=my_s1_sensor)
-ExportModelRequest("thor", model_config={"variant": "large"})
+ExportModelRequest.configure("thor", variant="large")
 ```
 
 - `ExportTarget`: where outputs should be written
 - `ExportConfig`: how the export should run
-- `ExportModelRequest`: optional per-model overrides when one export job mixes different model-specific settings such as sensor, modality, or `model_config`
+- `ExportModelRequest`: optional per-model overrides when one export job mixes different model-specific settings such as sensor, modality, or variant; use `ExportModelRequest.configure(...)` to pass model settings as keyword arguments
 
 Legacy `out + layout`, `out_dir` / `out_path`, and per-model dict overrides are still accepted for backward compatibility.
 

docs/extending.md

@@ -104,7 +104,7 @@ class EmbedderBase:
     If your model exposes public `model_config` keys, document them in `describe()["model_config"]`
     with a JSON-serializable schema.
     For model detail docs, surface those public keys near the top as well, for example in the
-    `Quick Facts` table as `Model config keys | model_config["variant"]`.
+    `Quick Facts` table as `Model config keys | \`variant\` (default: \`base\`; choices: \`base\`, \`large\`)`.
 
 ---
 

docs/models/anysat.md

@@ -14,7 +14,7 @@
 | Default resolution | 10m default provider fetch (`sensor.scale_m`) |
 | Temporal mode | `range` in practice (adapter normalizes `year`/`None` to range) |
 | Output modes | `pooled`, `grid` |
-| Model config keys | `model_config["variant"]` (default: `base`; choices: `base`) |
+| Model config keys | `variant` (default: `base`; choices: `base`) |
 | Extra side inputs | **required** `s2_dates` (per-frame DOY values) |
 | Training alignment (adapter path) | Medium (depends on frame count, normalization mode, and image size) |
 

docs/models/dofa.md

@@ -14,7 +14,7 @@
 | Default resolution | 10m default provider fetch (`sensor.scale_m`) |
 | Temporal mode | provider path requires `TemporalSpec.range(...)` |
 | Output modes | `pooled`, `grid` |
-| Model config keys | `model_config["variant"]` (default: `base`; choices: `base`, `large`) |
+| Model config keys | `variant` (default: `base`; choices: `base`, `large`) |
 | Extra side inputs | **required** wavelength vector (`wavelengths_um`) |
 | Training alignment (adapter path) | Medium-High (when wavelengths and band semantics are correct) |
 
@@ -110,19 +110,16 @@ Fixed adapter behavior:
 
 Non-env model selection knobs:
 
-- `model_config["variant"]`: `base` / `large` (default: `base`)
+- `variant`: `base` / `large` (default: `base`)
 - `sensor.bands`: channel semantics for provider fetch and wavelength inference
 - `sensor.wavelengths`: explicit wavelength vector (µm)
 
-If `model_config["variant"]` is omitted, rs-embed uses the `base` DOFA checkpoint by default. Set `model_config={"variant": "large"}` to switch to the larger model.
+If `variant` is omitted, rs-embed uses the `base` DOFA checkpoint by default. Pass `variant="large"` to switch to the larger model.
 
 Quick reminder:
 
-- DOFA supports `variant` directly through `model_config`
-- current public usage is:
-  - `model_config={"variant": "base"}`
-  - `model_config={"variant": "large"}`
-- for export jobs, pass the same setting via `ExportModelRequest("dofa", model_config={"variant": ...})`
+- pass `variant` as a keyword argument directly: `get_embedding("dofa", ..., variant="base")`
+- for export jobs, use `ExportModelRequest.configure("dofa", variant="large")`
 
 ---
 
@@ -152,7 +149,6 @@ emb = get_embedding(
     "dofa",
     spatial=PointBuffer(lon=121.5, lat=31.2, buffer_m=2048),
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
-    model_config={"variant": "base"},
     output=OutputSpec.pooled(),
     backend="gee",
 )
@@ -167,9 +163,9 @@ emb = get_embedding(
     "dofa",
     spatial=PointBuffer(lon=121.5, lat=31.2, buffer_m=2048),
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
-    model_config={"variant": "large"},
     output=OutputSpec.pooled(),
     backend="gee",
+    variant="large",
 )
 ```
 

docs/models/prithvi.md

@@ -1,6 +1,6 @@
 # Prithvi-EO v2 (`prithvi`)
 
-> Vendored Prithvi runtime for Sentinel-2 6-band inputs, with required temporal/location coordinate side inputs derived by rs-embed and `model_config["variant"]` support for TL checkpoints.
+> Vendored Prithvi runtime for Sentinel-2 6-band inputs, with required temporal/location coordinate side inputs derived by rs-embed and `variant` keyword support for TL checkpoints.
 
 ## Quick Facts
 
@@ -15,7 +15,7 @@
 | Default resolution | 30m default provider fetch (`sensor.scale_m`) |
 | Temporal mode | `range` preferred; adapter normalizes `year`/`None` to a range |
 | Output modes | `pooled`, `grid` |
-| Model config keys | `model_config["variant"]` (default: `prithvi_eo_v2_100_tl`) |
+| Model config keys | `variant` (default: `prithvi_eo_v2_100_tl`) |
 | Extra side inputs | **required** temporal coords + location coords (derived by adapter) |
 | Training alignment (adapter path) | Medium (depends on preprocessing mode and resize/pad choices) |
 
@@ -95,15 +95,15 @@ Default `SensorSpec` if omitted:
 
 ---
 
-## `model_config`
+## Model-specific Settings
 
 | Key | Type | Default | Choices |
 |---|---|---|---|
 | `variant` | `string` | `prithvi_eo_v2_100_tl` | `prithvi_eo_v2_100_tl`, `prithvi_eo_v2_300_tl`, `prithvi_eo_v2_600_tl` |
 
 Notes:
 
-- `model_config["variant"]` overrides `RS_EMBED_PRITHVI_KEY`.
+- `variant` overrides `RS_EMBED_PRITHVI_KEY`.
 - Short aliases `100_tl`, `300_tl`, and `600_tl` are also accepted in code.
 
 ---
@@ -148,7 +148,7 @@ emb = get_embedding(
 # export RS_EMBED_PRITHVI_PRETRAINED=1
 ```
 
-### With `model_config["variant"]`
+### With variant selection
 
 ```python
 from rs_embed import get_embedding, PointBuffer, TemporalSpec, OutputSpec
@@ -159,7 +159,7 @@ emb = get_embedding(
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
     output=OutputSpec.pooled(),
     backend="gee",
-    model_config={"variant": "prithvi_eo_v2_300_tl"},
+    variant="prithvi_eo_v2_300_tl",
 )
 ```
 

docs/models/satmaepp.md

@@ -14,7 +14,7 @@
 | Default resolution | 10m default provider fetch (`sensor.scale_m`) | 10m default provider fetch (`sensor.scale_m`) |
 | Temporal mode | range window + single composite | range window + single composite |
 | Output modes | `pooled`, `grid` | `pooled`, `grid` |
-| Model config keys | none | `model_config["variant"]` (default: `large`; choices: `large`) |
+| Model config keys | none | `variant` (default: `large`; choices: `large`) |
 | Core extraction | `forward_encoder(mask_ratio=0.0)` | `forward_encoder(mask_ratio=0.0)` |
 
 ---
@@ -185,7 +185,7 @@ emb_s2 = get_embedding(
 # export RS_EMBED_SATMAEPP_S2_GRID_REDUCE=mean
 ```
 
-### Example with `model_config`
+### Example with variant selection
 
 ```python
 from rs_embed import get_embedding, PointBuffer, TemporalSpec, OutputSpec
@@ -199,12 +199,12 @@ emb_s2 = get_embedding(
     temporal=temporal,
     output=OutputSpec.grid(),
     backend="gee",
-    model_config={"variant": "large"},
+    variant="large",
 )
 ```
 
 For export jobs, the same setting goes through
-`ExportModelRequest("satmaepp_s2_10b", model_config={"variant": "large"})`.
+`ExportModelRequest.configure("satmaepp_s2_10b", variant="large")`.
 
 ---
 

docs/models/thor.md

@@ -15,7 +15,7 @@
 | Default resolution | 10m default provider fetch (`sensor.scale_m`) |
 | Temporal mode | `range` in practice (composite window) |
 | Output modes | `pooled`, `grid` |
-| Model config keys | `model_config["variant"]` (default: `base`; choices: `tiny`, `small`, `base`, `large`) |
+| Model config keys | `variant` (default: `base`; choices: `tiny`, `small`, `base`, `large`) |
 | Extra side inputs | none required in current adapter |
 | Training alignment (adapter path) | High when `thor_stats` normalization and default S2 SR setup are preserved |
 
@@ -99,10 +99,10 @@ Notes:
 - `RS_EMBED_THOR_PATCH_SIZE` and `RS_EMBED_THOR_IMG` jointly affect token layout and `ground_cover_m`.
 - Changing `group_merge` changes grid channel semantics and dimensionality (especially `concat`).
 
-## `model_config`
+## Model-specific Settings
 
-- `model_config["variant"]`: `tiny` / `small` / `base` / `large`
-- for export jobs, pass it via `ExportModelRequest("thor", model_config={"variant": ...})`
+- `variant`: `tiny` / `small` / `base` / `large`
+- for export jobs, pass it via `ExportModelRequest.configure("thor", variant=...)`
 
 Example:
 
@@ -115,7 +115,7 @@ emb = get_embedding(
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
     output=OutputSpec.pooled(),
     backend="gee",
-    model_config={"variant": "large"},
+    variant="large",
 )
 ```
 
@@ -163,7 +163,7 @@ emb = get_embedding(
 # export RS_EMBED_THOR_PATCH_SIZE=16
 ```
 
-### Example with `model_config`
+### Example with variant selection
 
 ```python
 from rs_embed import get_embedding, PointBuffer, TemporalSpec, OutputSpec
@@ -174,7 +174,7 @@ emb = get_embedding(
     temporal=TemporalSpec.range("2022-06-01", "2022-09-01"),
     output=OutputSpec.grid(pooling="mean"),
     backend="gee",
-    model_config={"variant": "small"},
+    variant="small",
 )
 ```