Registry

agribound.registry is the single source of truth for source and engine metadata. It imports only the standard library.

registry

Source and engine registries: the single source of truth for Agribound metadata.

This module imports nothing heavy (standard library only) so it can be used by the configuration layer, the CLI and documentation tooling without pulling in GDAL, torch or Earth Engine.

Facts encoded here were checked against the upstream catalogues and packages on 2026-09-26 (GEE STAC entries and live collection queries, ftw-tools 2.0.0b5, Delineate-Anything v1/v2 model cards, geoai-py 0.43.1, terratorch 1.2.13, geotessera 0.10.2).

Registry entries

SOURCE_REGISTRY[name] keys (every source has all of them):

name, collection, resolution_m (default export resolution in metres, None when it depends on the input), native_resolution_m, all_bands (band order of the composite written by the builder, None for local files), canonical_bands (mapping of canonical names R, G, B, NIR, NIR_NARROW, SWIR1, SWIR2 to native band names, where available), value_scale (see below), year_range ((first, last); last is None for missions that are still acquiring; None for local files), coverage (free text), requires_gee and restricted.

value_scale is one of:

• "reflectance_x10000" -- float32 surface reflectance multiplied by 10000 (Sentinel-2, Landsat and HLS composites after the 1.0 harmonisation).
• "uint8" -- 8-bit digital numbers 0-255 (NAIP, USGS NAIP Plus).
• "dn" -- per-band medians (or greenest-pixel selections) of the scenes' raw integer digital numbers, exported as float32 (a median of an even number of scenes can be a half-integer); radiometry unverified (SPOT 6/7).
• "embedding" -- pre-computed embedding vectors (Google, TESSERA).
• "unknown" -- user-provided rasters.

ENGINE_REGISTRY[name] keys: name, approach, strengths, gpu_recommended, requires_bands, supported_sources, label_free (runs without a user-supplied or fine-tuned checkpoint), fine_tunable, reference, install_extra, notes (applies to every source) and source_notes (source name -> note that applies only to that source; use :func:engine_notes to get the notes for one source).

CANONICAL_BAND_NAMES module-attribute

CANONICAL_BAND_NAMES: tuple[str, ...] = ('R', 'G', 'B', 'NIR', 'NIR_NARROW', 'SWIR1', 'SWIR2')

Canonical band names understood by :func:agribound.engines.base.get_canonical_band_indices.

VALUE_SCALES module-attribute

VALUE_SCALES: tuple[str, ...] = ('reflectance_x10000', 'uint8', 'dn', 'embedding', 'unknown')

Allowed values of SOURCE_REGISTRY[...]["value_scale"].

SAM_REFINE_BACKENDS module-attribute

SAM_REFINE_BACKENDS: tuple[str, ...] = ('sam2', 'sam2.1', 'sam3', 'sam3-hf')

SAM backends accepted by AgriboundConfig.sam_backend for the refinement stage.

TESSERA_YEAR_RANGES module-attribute

TESSERA_YEAR_RANGES: dict[str, tuple[int, int]] = {'v1': (2017, 2025), 'v1.1': (2015, 2025), 'v2': (2017, 2025)}

Years with any published TESSERA tiles, per dataset version (geotessera 0.10.2 manifests).

ENSEMBLE_DEFAULT_MEMBERS module-attribute

ENSEMBLE_DEFAULT_MEMBERS: tuple[str, ...] = ('delineate-anything', 'ftw')

Members of engine="ensemble" when engine_params["engines"] is not set.

:data:agribound.engines.ensemble.DEFAULT_MEMBERS is this tuple; it lives here so that :mod:agribound.config can validate the defaults without importing the engine (and geopandas).

GEE_IMAGERY_SOURCES module-attribute

GEE_IMAGERY_SOURCES: tuple[str, ...] = tuple(_OPTICAL_GEE_SOURCES)

Imagery sources whose composites are built on Google Earth Engine.

EMBEDDING_SOURCES module-attribute

EMBEDDING_SOURCES: tuple[str, ...] = ('google-embedding', 'tessera-embedding')

Pre-computed embedding sources.

ENGINE_CLASSES module-attribute

ENGINE_CLASSES: dict[str, str] = {'delineate-anything': 'agribound.engines.delineate_anything:DelineateAnythingEngine', 'ftw': 'agribound.engines.ftw:FTWEngine', 'geoai': 'agribound.engines.geoai_field:GeoAIEngine', 'dinov3': 'agribound.engines.dinov3:DINOv3Engine', 'prithvi': 'agribound.engines.prithvi:PrithviEngine', 'embedding': 'agribound.engines.embedding:EmbeddingEngine', 'ensemble': 'agribound.engines.ensemble:EnsembleEngine'}

Engine name -> "module:Class" import path used by :func:agribound.engines.get_engine.

list_sources

list_sources() -> dict[str, dict[str, Any]]

List all satellite sources and their metadata.

Returns:

Type	Description
dict[str, dict]	Deep copy of :data:SOURCE_REGISTRY (safe to mutate).

Examples:

>>> from agribound import list_sources
>>> for name, info in list_sources().items():
...     print(name, info["resolution_m"], info["value_scale"])

Source code in agribound/registry.py

def list_sources() -> dict[str, dict[str, Any]]:
    """List all satellite sources and their metadata.

    Returns
    -------
    dict[str, dict]
        Deep copy of :data:`SOURCE_REGISTRY` (safe to mutate).

    Examples
    --------
    >>> from agribound import list_sources
    >>> for name, info in list_sources().items():
    ...     print(name, info["resolution_m"], info["value_scale"])
    """
    return copy.deepcopy(SOURCE_REGISTRY)

list_engines

list_engines() -> dict[str, dict[str, Any]]

List all delineation engines and their metadata.

Returns:

Type	Description
dict[str, dict]	Deep copy of :data:ENGINE_REGISTRY (safe to mutate).

Examples:

>>> from agribound import list_engines
>>> for name, info in list_engines().items():
...     print(name, info["approach"])

Source code in agribound/registry.py

def list_engines() -> dict[str, dict[str, Any]]:
    """List all delineation engines and their metadata.

    Returns
    -------
    dict[str, dict]
        Deep copy of :data:`ENGINE_REGISTRY` (safe to mutate).

    Examples
    --------
    >>> from agribound import list_engines
    >>> for name, info in list_engines().items():
    ...     print(name, info["approach"])
    """
    return copy.deepcopy(ENGINE_REGISTRY)

list_sam_backends

list_sam_backends() -> list[str]

Return the SAM backends accepted for the refinement stage.

Source code in agribound/registry.py

def list_sam_backends() -> list[str]:
    """Return the SAM backends accepted for the refinement stage."""
    return list(SAM_REFINE_BACKENDS)

engine_supports_source

engine_supports_source(engine: str, source: str) -> bool

Return True if engine accepts rasters from source.

Parameters:

Name	Type	Description	Default
engine	str	Engine name (case-insensitive).	required
source	str	Source name (case-insensitive).	required

Returns:

Type	Description
bool	False for unknown engine or source names.

Source code in agribound/registry.py

def engine_supports_source(engine: str, source: str) -> bool:
    """Return *True* if *engine* accepts rasters from *source*.

    Parameters
    ----------
    engine : str
        Engine name (case-insensitive).
    source : str
        Source name (case-insensitive).

    Returns
    -------
    bool
        *False* for unknown engine or source names.
    """
    info = ENGINE_REGISTRY.get(str(engine).lower().strip())
    if info is None:
        return False
    return str(source).lower().strip() in info["supported_sources"]

source_value_scale

source_value_scale(source: str) -> str

Return the pixel value scale of the composite built for source.

Parameters:

Name	Type	Description	Default
source	str	Source name.	required

Returns:

Type	Description
str	One of :data:VALUE_SCALES.

Raises:

Type	Description
ValueError	If the source is unknown.

Source code in agribound/registry.py

def source_value_scale(source: str) -> str:
    """Return the pixel value scale of the composite built for *source*.

    Parameters
    ----------
    source : str
        Source name.

    Returns
    -------
    str
        One of :data:`VALUE_SCALES`.

    Raises
    ------
    ValueError
        If the source is unknown.
    """
    return _source_info(source)["value_scale"]

source_year_range

source_year_range(source: str, tessera_version: str | None = None) -> tuple[int, int | None] | None

Return the (first, last) years with data for source.

Parameters:

Name	Type	Description	Default
source	str	Source name.	required
tessera_version	str or None	For "tessera-embedding" only: dataset version ("v1", "v1.1" or "v2"). None returns the registry default (v1).	None

Returns:

Type	Description
tuple[int, int or None] or None	last is None for missions that are still acquiring. None means no constraint (local files).

Raises:

Type	Description
ValueError	If the source or TESSERA version is unknown.

Source code in agribound/registry.py

def source_year_range(
    source: str, tessera_version: str | None = None
) -> tuple[int, int | None] | None:
    """Return the ``(first, last)`` years with data for *source*.

    Parameters
    ----------
    source : str
        Source name.
    tessera_version : str or None
        For ``"tessera-embedding"`` only: dataset version (``"v1"``, ``"v1.1"``
        or ``"v2"``). *None* returns the registry default (v1).

    Returns
    -------
    tuple[int, int or None] or None
        ``last`` is *None* for missions that are still acquiring. *None* means
        no constraint (local files).

    Raises
    ------
    ValueError
        If the source or TESSERA version is unknown.
    """
    info = _source_info(source)
    if str(source).lower().strip() == "tessera-embedding" and tessera_version is not None:
        if tessera_version not in TESSERA_YEAR_RANGES:
            raise ValueError(
                f"Unknown tessera_version {tessera_version!r}. "
                f"Choose from {tuple(TESSERA_YEAR_RANGES)}"
            )
        return TESSERA_YEAR_RANGES[tessera_version]
    return info["year_range"]

engine_notes

engine_notes(engine: str, source: str | None = None) -> list[str]

Return the notes of engine that apply to source.

Parameters:

Name	Type	Description	Default
engine	str	Engine name (case-insensitive).	required
source	str or None	Source name. None returns only the notes that apply to every source.	None

Returns:

Type	Description
list[str]	ENGINE_REGISTRY[engine]["notes"] followed by the entry of ENGINE_REGISTRY[engine]["source_notes"] for source, if any.

Raises:

Type	Description
ValueError	If the engine is unknown.

Source code in agribound/registry.py

def engine_notes(engine: str, source: str | None = None) -> list[str]:
    """Return the notes of *engine* that apply to *source*.

    Parameters
    ----------
    engine : str
        Engine name (case-insensitive).
    source : str or None
        Source name. *None* returns only the notes that apply to every source.

    Returns
    -------
    list[str]
        ``ENGINE_REGISTRY[engine]["notes"]`` followed by the entry of
        ``ENGINE_REGISTRY[engine]["source_notes"]`` for *source*, if any.

    Raises
    ------
    ValueError
        If the engine is unknown.
    """
    info = ENGINE_REGISTRY.get(str(engine).lower().strip())
    if info is None:
        raise ValueError(f"Unknown engine {engine!r}. Available: {list(ENGINE_REGISTRY)}")
    notes = [info["notes"]] if info.get("notes") else []
    if source is not None:
        extra = (info.get("source_notes") or {}).get(str(source).lower().strip())
        if extra:
            notes.append(extra)
    return notes

canonical_bands

canonical_bands(source: str) -> dict[str, str]

Return the canonical-name -> native-band mapping for source (empty if none).

Source code in agribound/registry.py

def canonical_bands(source: str) -> dict[str, str]:
    """Return the canonical-name -> native-band mapping for *source* (empty if none)."""
    return dict(_source_info(source).get("canonical_bands") or {})

supported_sources

supported_sources(engine: str) -> list[str]

Return the sources accepted by engine.

Raises:

Type	Description
ValueError	If the engine is unknown.

Source code in agribound/registry.py

def supported_sources(engine: str) -> list[str]:
    """Return the sources accepted by *engine*.

    Raises
    ------
    ValueError
        If the engine is unknown.
    """
    info = ENGINE_REGISTRY.get(str(engine).lower().strip())
    if info is None:
        raise ValueError(f"Unknown engine {engine!r}. Available: {list(ENGINE_REGISTRY)}")
    return list(info["supported_sources"])