omniloader.schema.spec¶

Declarative schema for features and targets across heterogeneous datasets.

The building blocks here let each dataset declare what it provides (features and targets, their shapes, dtypes and placeholder values) without committing to how those values are stored or what modality they represent. Everything is described in purely structural terms:

a vector value has no sequence axis — shape () (a scalar) or (F,);
a sequence value has a leading sequence axis of length T — shape (T,) or (T, F).

A spec is a sequence exactly when its time_dim is set; otherwise it is a vector. No modality (video/audio/text/…) or model concept appears anywhere. UnifiedSchema merges the per-dataset declarations into the single union schema that SampleUnifier uses to bring every raw sample into a common, masked format.

Classes¶

`TensorSpec`	Structural declaration of a single named value (a feature or a target).
`DatasetSchema`	The set of features and targets a single dataset provides.
`UnifiedSchema`	Union of several `DatasetSchema` objects into one shared schema.

Functions¶

resolve_dtype(→ torch.dtype)

Resolve a dtype given as a string or torch.dtype.

Module Contents¶

omniloader.schema.spec.resolve_dtype(dtype: str | torch.dtype) → torch.dtype[source]¶

Resolve a dtype given as a string or torch.dtype.

Parameters:: dtype – Either a torch.dtype or one of the string keys in _DTYPES (e.g. "float32").
Returns:: The corresponding torch.dtype.
Raises:: ValueError – If dtype is a string that is not a known dtype name.

class omniloader.schema.spec.TensorSpec[source]¶

Structural declaration of a single named value (a feature or a target).

The same spec type describes both inputs and supervision targets; its role is determined by whether it is placed in DatasetSchema.features or DatasetSchema.targets.

The shape is derived from two independent, optional axes plus an optional trailing shape:

time_dim — length T of the sequence axis. When None the value is a vector (no sequence axis); when set the value is a sequence.
feature_dim — size F of the trailing feature axis. When None the value is a scalar along that axis. Sugar for shape=(F,).
shape — the full trailing shape for structured values that are not a single flat feature axis, e.g. an image (C, H, W). Mutually exclusive with feature_dim.

So the representable shapes are (), (F,), (T,), (T, F) and, with shape set, (*shape,) or (T, *shape) — covering scalar labels, feature vectors, scalar sequences (e.g. one value per step), feature sequences, and structured (e.g. image) sequences:

TensorSpec(
    name="eye_image",
    time_dim=15,           # T
    shape=(3, 64, 64),     # C, H, W
    dtype=torch.float32,
)
# value_shape == (15, 3, 64, 64); mask_shape == (15,)

A structured value is masked exactly like a feature sequence: one flag per time step, valid or not as a whole (no per-pixel masking).

Parameters:

name – Unique key under which the value appears in a sample dict.
feature_dim – Size of the trailing feature axis F. None for a scalar along that axis. Mutually exclusive with shape.
shape – Full trailing (non-time) shape, for structured values such as images. Mutually exclusive with feature_dim.
time_dim – Length T of the sequence axis. None for a vector.
dtype – Element dtype, as a torch.dtype or string name.
placeholder – Fill value used when a dataset does not provide this key. Defaults to 0 (use e.g. -1 as an ignore index for class ids).

__post_init__() → None[source]¶: Validate and normalise field values.

property is_sequence: bool¶: Whether the value has a sequence axis (time_dim is set).

property trailing_shape: tuple[int, ...]¶

The non-time trailing shape, from shape or feature_dim.

Returns:: self.shape if set, else (feature_dim,) if set, else ().

property value_shape: tuple[int, ...]¶

Shape of the placeholder value tensor for a single sample.

Returns:: trailing_shape, prefixed with time_dim when the spec is a sequence.

property mask_shape: tuple[int, ...]¶

Shape of the boolean validity mask for a single sample.

Returns:: (T,) for a sequence value (one flag per step) and () for a vector value (one flag for the whole value).

placeholder_value() → torch.Tensor[source]¶: Build the placeholder value tensor filled with placeholder.

placeholder_mask() → torch.Tensor[source]¶: Build the all-False mask marking every position as invalid.

class omniloader.schema.spec.DatasetSchema[source]¶

The set of features and targets a single dataset provides.

A value is a feature or a target purely by which list it is placed in; both use the same TensorSpec.

Parameters:

features – Input feature specs the dataset supplies.
targets – Supervision target specs the dataset supplies.

property specs: list[TensorSpec]¶: All feature and target specs concatenated.

property keys: set[str]¶: Names of every feature and target the dataset provides.

class omniloader.schema.spec.UnifiedSchema(schemas: list[DatasetSchema])[source]¶

Union of several DatasetSchema objects into one shared schema.

The unified schema is the deduplicated union of every feature and target across the input datasets. Specs that share a name must agree on shape and dtype. Order is preserved: features/targets appear in the order they are first encountered.

Parameters:: schemas – Per-dataset schemas to merge.

property specs: list[TensorSpec]¶: All feature and target specs in the unified schema.

property feature_keys: list[str]¶: Names of the input features in schema order.

property target_keys: list[str]¶: Names of the supervision targets in schema order.

property keys: set[str]¶: Names of every feature and target in the unified schema.

spec(name: str) → TensorSpec[source]¶

Return the spec registered under name.

Parameters:: name – Feature or target name.
Returns:: The matching TensorSpec.
Raises:: KeyError – If no spec with that name exists.

__len__() → int[source]¶: Number of features plus targets in the unified schema.