feature_meta

feature_meta

Feature metadata for typed feature validation across the encoding-decoding pipeline.

FeatureType

Bases: StrEnum

Feature shape types for pipeline validation.

Determines how downstream modules (fusion, decoder) handle a feature tensor. The type is set explicitly by each encoder and fusion module, not inferred from dimension tuples.

FeatureMetadata dataclass

FeatureMetadata(key, feature_type, dimension)

Typed descriptor for a named feature produced by an encoder or fusion module.

Travels through the pipeline: encoder/fusion → pipeline registry → decoder validation.

Parameters:

Name	Type	Description	Default
key	str	Feature name (e.g. "rgb", "language", "fused_rgb_language").	required
feature_type	str	One of FeatureType values.	required
dimension	tuple[int, ...]	Shape excluding batch and time dimensions. Always a tuple: FLAT (D,), SEQUENTIAL (S, D), SPATIAL (C, H, W).	required

infer_feature_type

infer_feature_type(dimension)

Infer feature type from dimension tuple length.

Parameters:

Name	Type	Description	Default
dimension	tuple[int, ...]	Feature dimension tuple excluding batch and time.	required

Returns:

Type	Description
str	Feature type string value.

Raises:

Type	Description
ValueError	If the dimension tuple length does not match any known type.

Source code in src/versatil/models/feature_meta.py

def infer_feature_type(dimension: tuple[int, ...]) -> str:
    """Infer feature type from dimension tuple length.

    Args:
        dimension: Feature dimension tuple excluding batch and time.

    Returns:
        Feature type string value.

    Raises:
        ValueError: If the dimension tuple length does not match any known type.
    """
    match len(dimension):
        case 3:
            return FeatureType.SPATIAL.value
        case 2:
            return FeatureType.SEQUENTIAL.value
        case 1:
            return FeatureType.FLAT.value
        case _:
            raise ValueError(f"Cannot infer feature type from dimension: {dimension}")