feat(fusion): add pydantic data contract for multi-modal fusion

src/fusion/types.py

@@ -0,0 +1,56 @@
+"""Pydantic data contract for the multi-modal fusion engine."""
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModalityClassProb(BaseModel):
+    label_text: str
+    probability: float = Field(..., ge=0.0, le=1.0)
+
+
+class ModalityPrediction(BaseModel):
+    """One modality's classifier output (MRI or EEG)."""
+    model_config = ConfigDict(protected_namespaces=())
+
+    label_text: str
+    label: int = Field(..., ge=0)
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    probabilities: list[ModalityClassProb] = Field(..., min_length=1)
+
+
+class ClinicalScores(BaseModel):
+    """Doctor-entered extra-test scores. Each is optional."""
+    mmse: Annotated[float, Field(ge=0.0, le=30.0)] | None = None
+    moca: Annotated[float, Field(ge=0.0, le=30.0)] | None = None
+    updrs: Annotated[float, Field(ge=0.0, le=199.0)] | None = None
+    gait_speed_m_s: Annotated[float, Field(ge=0.0, le=2.5)] | None = None
+    age_years: Annotated[float, Field(ge=0.0, le=120.0)] | None = None
+
+
+class FusionInput(BaseModel):
+    mri: ModalityPrediction | None = None
+    eeg: ModalityPrediction | None = None
+    clinical: ClinicalScores = Field(default_factory=ClinicalScores)
+
+
+class ModalityContribution(BaseModel):
+    """One row of the attribution table for a single disease score."""
+    modality: str  # "mri" | "eeg" | "clinical_<name>"
+    weight: float
+    signal: float = Field(..., ge=-1.0, le=1.0)
+    delta_logit: float
+
+
+class DiseaseScore(BaseModel):
+    disease: str
+    probability: float = Field(..., ge=0.0, le=1.0)
+    contributions: list[ModalityContribution]
+
+
+class FusionOutput(BaseModel):
+    diseases: list[DiseaseScore]
+    top_disease: str
+    missing_inputs: list[str] = Field(default_factory=list)

tests/fusion/test_types.py

@@ -0,0 +1,68 @@
+"""Tests for src.fusion.types — pydantic contract for fusion I/O."""
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.fusion.types import (
+    ClinicalScores,
+    DiseaseScore,
+    FusionInput,
+    FusionOutput,
+    ModalityContribution,
+    ModalityPrediction,
+)
+
+
+class TestModalityPrediction:
+    def test_minimal_round_trip(self) -> None:
+        pred = ModalityPrediction(
+            label_text="alzheimers", label=1, confidence=0.81,
+            probabilities=[
+                {"label_text": "control", "probability": 0.19},
+                {"label_text": "alzheimers", "probability": 0.81},
+            ],
+        )
+        assert pred.label == 1
+        assert pred.probabilities[1].probability == pytest.approx(0.81)
+
+    def test_probabilities_must_be_non_empty(self) -> None:
+        with pytest.raises(ValidationError):
+            ModalityPrediction(label_text="x", label=0, confidence=0.5, probabilities=[])
+
+
+class TestClinicalScores:
+    def test_all_optional(self) -> None:
+        s = ClinicalScores()
+        assert s.mmse is None and s.age_years is None
+
+    def test_rejects_out_of_range_mmse(self) -> None:
+        with pytest.raises(ValidationError):
+            ClinicalScores(mmse=42.0)
+
+
+class TestFusionInputOutput:
+    def test_fusion_input_allows_no_modalities(self) -> None:
+        # Caller may pass nothing — engine returns baseline scores.
+        f = FusionInput()
+        assert f.mri is None and f.eeg is None
+        assert f.clinical == ClinicalScores()
+
+    def test_fusion_output_round_trip(self) -> None:
+        out = FusionOutput(
+            diseases=[
+                DiseaseScore(
+                    disease="alzheimers",
+                    probability=0.7,
+                    contributions=[
+                        ModalityContribution(
+                            modality="mri", weight=0.35, signal=0.6, delta_logit=0.21,
+                        )
+                    ],
+                )
+            ],
+            top_disease="alzheimers",
+            missing_inputs=["eeg"],
+        )
+        assert out.top_disease == "alzheimers"
+        assert out.diseases[0].contributions[0].delta_logit == pytest.approx(0.21)