Models API

Models implement `BaseModel.forward(Batch) -> ModelOutput`. The built-in fusion models cover feature-level fusion, prediction-level fusion, and gated variants. They are commonly assembled through the `MODELS` registry from configuration; encoders, heads, and submodels are supplied as constructor dependencies. See Models for task-oriented setup.

Model contract

chimera_ml.models.base.BaseModel

Bases: Module, ABC

Abstract model contract for uni- and multimodal components.

Implementations receive a Batch and return a ModelOutput. They may consume any subset of the modality keys present in Batch.inputs, but should raise a clear error when no usable input is available.

Feature and prediction fusion

`FeatureFusionModel` concatenates encoder embeddings before the head. `PredictionFusionModel` combines per-modality predictions using mean, sum, or weighted averaging.

chimera_ml.models.fusion.FeatureFusionModel

Bases: BaseModel

Fuse modality embeddings, then apply a prediction head.

Each available modality is encoded, optionally zeroed by its presence mask, concatenated along the feature dimension, and passed to head.

Parameters:

Name	Type	Description	Default
encoders	dict[str, Module]	Modality name to encoder module.	required
head	Module	Module receiving the concatenated embedding.	required
dropout	float	Dropout probability applied after concatenation.	0.0
use_mask	bool	Whether modality masks suppress missing branches.	True

chimera_ml.models.fusion.feature_fusion_model

feature_fusion_model(*, encoders, head, dropout=0.0, use_mask=True)

Factory for feature-level fusion model.

chimera_ml.models.fusion.PredictionFusionModel

Bases: BaseModel

Fuse predictions from independent per-modality submodels.

The fusion strategy is mean, sum, or weighted averaging. Missing modality inputs are skipped.

Parameters:

Name	Type	Description	Default
submodels	dict[str, BaseModel]	Modality name to BaseModel mapping.	required
fusion	str	Combination strategy: mean, sum, or weighted.	'mean'
weights	dict[str, float] | None	Optional modality weights used by weighted fusion.	None

chimera_ml.models.fusion.prediction_fusion_model

prediction_fusion_model(*, submodels, fusion='mean', weights=None)

Factory for prediction-level fusion model.

Gated fusion

The gated models learn per-modality weights and honor optional modality masks. `GatedFusionModel` gates embeddings before the head; `GatedPredictionFusionModel` gates logits and requires a known class count.

chimera_ml.models.gating.GatedFusionModel

Bases: BaseModel

Learn per-modality gates over shared encoder embeddings.

Encoded modalities are projected to shared_dim, scored by gate_net, and combined with a softmax. Presence masks suppress unavailable modalities.

Parameters:

Name	Type	Description	Default
encoders	dict[str, Module]	Modality name to encoder module.	required
head	Module	Module receiving the gated shared embedding.	required
shared_dim	int	Required embedding width after projection.	required
gate_hidden	int	Hidden width of the gate network.	64
dropout	float	Dropout applied before scoring and in the head.	0.0
use_mask	bool	Whether modality masks suppress missing branches.	True

set_projection

set_projection(modality, layer)

Allow user to set projection explicitly to ensure shared_dim compatibility.

chimera_ml.models.gating.gated_fusion_model

gated_fusion_model(*, encoders, head, shared_dim, gate_hidden=64, dropout=0.0, use_mask=True)

Factory for gated feature-fusion model.

chimera_ml.models.gated_prediction_fusion.GatedPredictionFusionModel

Bases: BaseModel

Learn gates over logits produced by per-modality submodels.

Each submodel must return a two-dimensional logits tensor with num_classes columns. The gates are normalized across available modalities.

Parameters:

Name	Type	Description	Default
submodels	dict[str, BaseModel]	Modality name to BaseModel mapping.	required
num_classes	int	Number of logits expected from every submodel.	required
gate_hidden	int	Hidden width of the gate network.	64
dropout	float	Dropout applied to submodel logits.	0.0
use_mask	bool	Whether modality masks suppress missing branches.	True

chimera_ml.models.gated_prediction_fusion.gated_prediction_fusion_model

gated_prediction_fusion_model(*, submodels, num_classes=None, gate_hidden=64, dropout=0.0, use_mask=True)

Factory for gated prediction-fusion model.