Standardize output pipleine

osipy/__init__.py

@@ -82,7 +82,7 @@
     from osipy.common.dataset import PerfusionDataset
     from osipy.common.io import export_bids, load_dicom, load_nifti, load_perfusion
     from osipy.common.parameter_map import ParameterMap
-    from osipy.common.types import AIFType, FittingMethod, LabelingType, Modality
+    from osipy.common.types import AIFType, AnalysisResult, FittingMethod, LabelingType, Modality
     from osipy.dce import (
         ExtendedToftsModel,
         PatlakModel,
@@ -122,6 +122,8 @@
     "ASLPipeline",
     # AIF
     "ArterialInputFunction",
+    # Result contract
+    "AnalysisResult",
     # Pipelines
     "DCEPipeline",
     "DSCPipeline",
@@ -217,6 +219,7 @@
     "ParameterMap": ("osipy.common.parameter_map", "ParameterMap"),
     # Types
     "AIFType": ("osipy.common.types", "AIFType"),
+    "AnalysisResult": ("osipy.common.types", "AnalysisResult"),
     "FittingMethod": ("osipy.common.types", "FittingMethod"),
     "LabelingType": ("osipy.common.types", "LabelingType"),
     "Modality": ("osipy.common.types", "Modality"),

osipy/common/__init__.py

@@ -59,6 +59,7 @@
     AcquisitionParams,
     AIFType,
     ASLAcquisitionParams,
+    AnalysisResult,
     DCEAcquisitionParams,
     DSCAcquisitionParams,
     FittingMethod,
@@ -73,6 +74,8 @@
     "ASLAcquisitionParams",
     # Acquisition parameters
     "AcquisitionParams",
+    # Result contract
+    "AnalysisResult",
     "DCEAcquisitionParams",
     "DSCAcquisitionParams",
     "DataValidationError",

osipy/common/types.py

@@ -256,3 +256,38 @@ class IVIMAcquisitionParams(AcquisitionParams):
     | ASLAcquisitionParams
     | IVIMAcquisitionParams
 )
+
+
+@dataclass
+class AnalysisResult:
+    """Standardised pipeline output contract.
+
+    Every call to :func:`osipy.pipeline.run_analysis` returns this object,
+    regardless of modality.  Downstream consumers (CLI tools, batch scripts,
+    visualisation code) only need to know this single class — they never have
+    to branch on modality to extract parameter maps or masks.
+
+    Attributes
+    ----------
+    modality : Modality
+        Source pipeline (DCE, DSC, ASL, or IVIM).
+    parameter_maps : dict[str, ParameterMap]
+        All output parameter maps keyed by OSIPI CAPLEX name
+        (e.g. ``'Ktrans'``, ``'CBF'``, ``'D'``).
+        **Guaranteed**: always a non-empty dict, never ``None``.
+    quality_mask : NDArray[np.bool_]
+        Boolean array marking valid voxels, same spatial shape as
+        the parameter maps.  **Guaranteed**: always present, never ``None``.
+    provenance : dict[str, Any]
+        Audit trail for reproducibility.  Contains at minimum:
+
+        * ``osipy_version`` – library version string
+        * ``captured_at``  – ISO-8601 UTC timestamp of the analysis run
+        * ``modality``     – modality value string
+        * ``config``       – serialised pipeline configuration dict
+    """
+
+    modality: Modality
+    parameter_maps: "dict[str, ParameterMap]"
+    quality_mask: "NDArray[np.bool_]"
+    provenance: "dict[str, Any]" = field(default_factory=dict)

osipy/pipeline/__init__.py

@@ -29,11 +29,12 @@
 from osipy.pipeline.dce_pipeline import DCEPipeline, DCEPipelineConfig
 from osipy.pipeline.dsc_pipeline import DSCPipeline, DSCPipelineConfig
 from osipy.pipeline.ivim_pipeline import IVIMPipeline, IVIMPipelineConfig
-from osipy.pipeline.runner import PipelineResult, run_analysis
+from osipy.pipeline.runner import AnalysisResult, PipelineResult, run_analysis
 
 __all__ = [
     "ASLPipeline",
     "ASLPipelineConfig",
+    "AnalysisResult",
     "DCEPipeline",
     "DCEPipelineConfig",
     "DSCPipeline",