sleap-nn 0.0.5__py3-none-any.whl → 0.1.0a0__py3-none-any.whl

sleap_nn/inference/predictors.py

@@ -21,9 +21,6 @@ from sleap_nn.data.resizing import (
     apply_sizematcher,
     apply_resizer,
 )
-from sleap_nn.data.normalization import (
-    apply_normalization,
-)
 from sleap_nn.config.utils import get_model_type_from_cfg
 from sleap_nn.inference.paf_grouping import PAFScorer
 from sleap_nn.training.lightning_modules import (
@@ -61,6 +58,47 @@ from rich.progress import (
 from time import time
 
 
+def _filter_user_labeled_frames(
+    labels: sio.Labels,
+    video: sio.Video,
+    frames: Optional[list],
+    exclude_user_labeled: bool,
+) -> Optional[list]:
+    """Filter out user-labeled frames from a frame list.
+
+    This function is used when running inference with VideoReader (video_index specified)
+    to implement the exclude_user_labeled functionality.
+
+    Args:
+        labels: The Labels object containing labeled frames.
+        video: The video to filter frames for.
+        frames: List of frame indices to filter. If None, builds list of all frames.
+        exclude_user_labeled: If True, filter out user-labeled frames.
+
+    Returns:
+        Filtered list of frame indices excluding user-labeled frames if
+        exclude_user_labeled is True. Returns original frames if exclude_user_labeled
+        is False or if there are no user-labeled frames.
+    """
+    if not exclude_user_labeled:
+        return frames
+
+    # Get user-labeled frame indices for this video
+    user_frame_indices = {
+        lf.frame_idx for lf in labels.find(video=video) if lf.has_user_instances
+    }
+
+    if not user_frame_indices:
+        return frames
+
+    # Build full frame list if frames is None
+    if frames is None:
+        frames = list(range(len(video)))
+
+    # Filter out user-labeled frames
+    return [f for f in frames if f not in user_frame_indices]
+
+
 class RateColumn(rich.progress.ProgressColumn):
     """Renders the progress rate."""
 
@@ -321,6 +359,8 @@ class Predictor(ABC):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -393,7 +433,6 @@ class Predictor(ABC):
                         if frame["image"] is None:
                             done = True
                             break
-                        frame["image"] = apply_normalization(frame["image"])
                         frame["image"], eff_scale = apply_sizematcher(
                             frame["image"],
                             self.preprocess_config["max_height"],
@@ -671,9 +710,6 @@ class TopDownPredictor(Predictor):
                 max_stride=max_stride,
                 input_scale=self.confmap_config.data_config.preprocessing.scale,
             )
-            centroid_crop_layer.precrop_resize = (
-                self.confmap_config.data_config.preprocessing.scale
-            )
 
         if self.centroid_config is None and self.confmap_config is not None:
             self.instances_key = (
@@ -788,6 +824,7 @@ class TopDownPredictor(Predictor):
                     learning_rate=centroid_config.trainer_config.optimizer.lr,
                     amsgrad=centroid_config.trainer_config.optimizer.amsgrad,
                     map_location=device,
+                    weights_only=False,
                 )
             else:
                 # Load the converted model
@@ -904,6 +941,7 @@ class TopDownPredictor(Predictor):
                     amsgrad=confmap_config.trainer_config.optimizer.amsgrad,
                     backbone_type=centered_instance_backbone_type,
                     map_location=device,
+                    weights_only=False,
                 )
             else:
                 # Load the converted model
@@ -1073,6 +1111,8 @@ class TopDownPredictor(Predictor):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -1085,6 +1125,8 @@ class TopDownPredictor(Predictor):
             frames: (list) List of frames indices. If `None`, all frames in the video are used. Default: None.
             only_labeled_frames: (bool) `True` if inference should be run only on user-labeled frames. Default: `False`.
             only_suggested_frames: (bool) `True` if inference should be run only on unlabeled suggested frames. Default: `False`.
+            exclude_user_labeled: (bool) `True` to skip frames that have user-labeled instances. Default: `False`.
+            only_predicted_frames: (bool) `True` to run inference only on frames that already have predictions. Default: `False`.
             video_index: (int) Integer index of video in .slp file to predict on. To be used
                 with an .slp path as an alternative to specifying the video path.
             video_dataset: (str) The dataset for HDF5 videos.
@@ -1119,6 +1161,8 @@ class TopDownPredictor(Predictor):
                 instances_key=self.instances_key,
                 only_labeled_frames=only_labeled_frames,
                 only_suggested_frames=only_suggested_frames,
+                exclude_user_labeled=exclude_user_labeled,
+                only_predicted_frames=only_predicted_frames,
             )
             self.videos = self.pipeline.labels.videos
 
@@ -1136,10 +1180,15 @@ class TopDownPredictor(Predictor):
 
             if isinstance(inference_object, sio.Labels) and video_index is not None:
                 labels = inference_object
+                video = labels.videos[video_index]
+                # Filter out user-labeled frames if requested
+                filtered_frames = _filter_user_labeled_frames(
+                    labels, video, frames, exclude_user_labeled
+                )
                 self.pipeline = provider.from_video(
-                    video=labels.videos[video_index],
+                    video=video,
                     queue_maxsize=queue_maxsize,
-                    frames=frames,
+                    frames=filtered_frames,
                 )
 
             else:  # for mp4 or hdf5 videos
@@ -1394,6 +1443,7 @@ class SingleInstancePredictor(Predictor):
                 learning_rate=confmap_config.trainer_config.optimizer.lr,
                 amsgrad=confmap_config.trainer_config.optimizer.amsgrad,
                 map_location=device,
+                weights_only=False,
             )
         else:
             confmap_converted_model = load_legacy_model(
@@ -1491,6 +1541,8 @@ class SingleInstancePredictor(Predictor):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -1503,6 +1555,8 @@ class SingleInstancePredictor(Predictor):
             frames: List of frames indices. If `None`, all frames in the video are used. Default: None.
             only_labeled_frames: (bool) `True` if inference should be run only on user-labeled frames. Default: `False`.
             only_suggested_frames: (bool) `True` if inference should be run only on unlabeled suggested frames. Default: `False`.
+            exclude_user_labeled: (bool) `True` to skip frames that have user-labeled instances. Default: `False`.
+            only_predicted_frames: (bool) `True` to run inference only on frames that already have predictions. Default: `False`.
             video_index: (int) Integer index of video in .slp file to predict on. To be used
                 with an .slp path as an alternative to specifying the video path.
             video_dataset: (str) The dataset for HDF5 videos.
@@ -1536,6 +1590,8 @@ class SingleInstancePredictor(Predictor):
                 frame_buffer=frame_buffer,
                 only_labeled_frames=only_labeled_frames,
                 only_suggested_frames=only_suggested_frames,
+                exclude_user_labeled=exclude_user_labeled,
+                only_predicted_frames=only_predicted_frames,
             )
             self.videos = self.pipeline.labels.videos
 
@@ -1544,10 +1600,15 @@ class SingleInstancePredictor(Predictor):
 
             if isinstance(inference_object, sio.Labels) and video_index is not None:
                 labels = inference_object
+                video = labels.videos[video_index]
+                # Filter out user-labeled frames if requested
+                filtered_frames = _filter_user_labeled_frames(
+                    labels, video, frames, exclude_user_labeled
+                )
                 self.pipeline = provider.from_video(
-                    video=labels.videos[video_index],
+                    video=video,
                     queue_maxsize=queue_maxsize,
-                    frames=frames,
+                    frames=filtered_frames,
                 )
 
             else:  # for mp4 or hdf5 videos
@@ -1833,6 +1894,7 @@ class BottomUpPredictor(Predictor):
                 backbone_type=backbone_type,
                 model_type="bottomup",
                 map_location=device,
+                weights_only=False,
             )
         else:
             bottomup_converted_model = load_legacy_model(
@@ -1929,6 +1991,8 @@ class BottomUpPredictor(Predictor):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -1941,6 +2005,8 @@ class BottomUpPredictor(Predictor):
             frames: List of frames indices. If `None`, all frames in the video are used. Default: None.
             only_labeled_frames: (bool) `True` if inference should be run only on user-labeled frames. Default: `False`.
             only_suggested_frames: (bool) `True` if inference should be run only on unlabeled suggested frames. Default: `False`.
+            exclude_user_labeled: (bool) `True` to skip frames that have user-labeled instances. Default: `False`.
+            only_predicted_frames: (bool) `True` to run inference only on frames that already have predictions. Default: `False`.
             video_index: (int) Integer index of video in .slp file to predict on. To be used
                 with an .slp path as an alternative to specifying the video path.
             video_dataset: (str) The dataset for HDF5 videos.
@@ -1974,6 +2040,8 @@ class BottomUpPredictor(Predictor):
                 frame_buffer=frame_buffer,
                 only_labeled_frames=only_labeled_frames,
                 only_suggested_frames=only_suggested_frames,
+                exclude_user_labeled=exclude_user_labeled,
+                only_predicted_frames=only_predicted_frames,
             )
 
             self.videos = self.pipeline.labels.videos
@@ -1983,10 +2051,15 @@ class BottomUpPredictor(Predictor):
 
             if isinstance(inference_object, sio.Labels) and video_index is not None:
                 labels = inference_object
+                video = labels.videos[video_index]
+                # Filter out user-labeled frames if requested
+                filtered_frames = _filter_user_labeled_frames(
+                    labels, video, frames, exclude_user_labeled
+                )
                 self.pipeline = provider.from_video(
-                    video=labels.videos[video_index],
+                    video=video,
                     queue_maxsize=queue_maxsize,
-                    frames=frames,
+                    frames=filtered_frames,
                 )
 
             else:  # for mp4 or hdf5 videos
@@ -2260,6 +2333,7 @@ class BottomUpMultiClassPredictor(Predictor):
                 optimizer=bottomup_config.trainer_config.optimizer_name,
                 learning_rate=bottomup_config.trainer_config.optimizer.lr,
                 amsgrad=bottomup_config.trainer_config.optimizer.amsgrad,
+                weights_only=False,
             )
         else:
             bottomup_converted_model = load_legacy_model(
@@ -2364,6 +2438,8 @@ class BottomUpMultiClassPredictor(Predictor):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -2376,6 +2452,8 @@ class BottomUpMultiClassPredictor(Predictor):
             frames: List of frames indices. If `None`, all frames in the video are used. Default: None.
             only_labeled_frames: (bool) `True` if inference should be run only on user-labeled frames. Default: `False`.
             only_suggested_frames: (bool) `True` if inference should be run only on unlabeled suggested frames. Default: `False`.
+            exclude_user_labeled: (bool) `True` to skip frames that have user-labeled instances. Default: `False`.
+            only_predicted_frames: (bool) `True` to run inference only on frames that already have predictions. Default: `False`.
             video_index: (int) Integer index of video in .slp file to predict on. To be used
                 with an .slp path as an alternative to specifying the video path.
             video_dataset: (str) The dataset for HDF5 videos.
@@ -2411,6 +2489,8 @@ class BottomUpMultiClassPredictor(Predictor):
                 frame_buffer=frame_buffer,
                 only_labeled_frames=only_labeled_frames,
                 only_suggested_frames=only_suggested_frames,
+                exclude_user_labeled=exclude_user_labeled,
+                only_predicted_frames=only_predicted_frames,
             )
 
             self.videos = self.pipeline.labels.videos
@@ -2420,10 +2500,15 @@ class BottomUpMultiClassPredictor(Predictor):
 
             if isinstance(inference_object, sio.Labels) and video_index is not None:
                 labels = inference_object
+                video = labels.videos[video_index]
+                # Filter out user-labeled frames if requested
+                filtered_frames = _filter_user_labeled_frames(
+                    labels, video, frames, exclude_user_labeled
+                )
                 self.pipeline = provider.from_video(
-                    video=labels.videos[video_index],
+                    video=video,
                     queue_maxsize=queue_maxsize,
-                    frames=frames,
+                    frames=filtered_frames,
                 )
 
             else:  # for mp4 or hdf5 videos
@@ -2682,9 +2767,6 @@ class TopDownMultiClassPredictor(Predictor):
             max_stride=max_stride,
             input_scale=self.confmap_config.data_config.preprocessing.scale,
         )
-        centroid_crop_layer.precrop_resize = (
-            self.confmap_config.data_config.preprocessing.scale
-        )
 
         if self.centroid_config is None:
             self.instances_key = (
@@ -2805,6 +2887,7 @@ class TopDownMultiClassPredictor(Predictor):
                     learning_rate=centroid_config.trainer_config.optimizer.lr,
                     amsgrad=centroid_config.trainer_config.optimizer.amsgrad,
                     map_location=device,
+                    weights_only=False,
                 )
 
             else:
@@ -2929,6 +3012,7 @@ class TopDownMultiClassPredictor(Predictor):
                     learning_rate=confmap_config.trainer_config.optimizer.lr,
                     amsgrad=confmap_config.trainer_config.optimizer.amsgrad,
                     map_location=device,
+                    weights_only=False,
                 )
             else:
                 confmap_converted_model = load_legacy_model(
@@ -3109,6 +3193,8 @@ class TopDownMultiClassPredictor(Predictor):
         frames: Optional[list] = None,
         only_labeled_frames: bool = False,
         only_suggested_frames: bool = False,
+        exclude_user_labeled: bool = False,
+        only_predicted_frames: bool = False,
         video_index: Optional[int] = None,
         video_dataset: Optional[str] = None,
         video_input_format: str = "channels_last",
@@ -3121,6 +3207,8 @@ class TopDownMultiClassPredictor(Predictor):
             frames: (list) List of frames indices. If `None`, all frames in the video are used. Default: None.
             only_labeled_frames: (bool) `True` if inference should be run only on user-labeled frames. Default: `False`.
             only_suggested_frames: (bool) `True` if inference should be run only on unlabeled suggested frames. Default: `False`.
+            exclude_user_labeled: (bool) `True` to skip frames that have user-labeled instances. Default: `False`.
+            only_predicted_frames: (bool) `True` to run inference only on frames that already have predictions. Default: `False`.
             video_index: (int) Integer index of video in .slp file to predict on. To be used
                 with an .slp path as an alternative to specifying the video path.
             video_dataset: (str) The dataset for HDF5 videos.
@@ -3155,6 +3243,8 @@ class TopDownMultiClassPredictor(Predictor):
                 instances_key=self.instances_key,
                 only_labeled_frames=only_labeled_frames,
                 only_suggested_frames=only_suggested_frames,
+                exclude_user_labeled=exclude_user_labeled,
+                only_predicted_frames=only_predicted_frames,
             )
             self.videos = self.pipeline.labels.videos
 
@@ -3172,10 +3262,15 @@ class TopDownMultiClassPredictor(Predictor):
 
             if isinstance(inference_object, sio.Labels) and video_index is not None:
                 labels = inference_object
+                video = labels.videos[video_index]
+                # Filter out user-labeled frames if requested
+                filtered_frames = _filter_user_labeled_frames(
+                    labels, video, frames, exclude_user_labeled
+                )
                 self.pipeline = provider.from_video(
-                    video=labels.videos[video_index],
+                    video=video,
                     queue_maxsize=queue_maxsize,
-                    frames=frames,
+                    frames=filtered_frames,
                 )
 
             else:  # for mp4 or hdf5 videos

sleap_nn/inference/provenance.py

@@ -0,0 +1,292 @@
+"""Provenance metadata utilities for inference outputs.
+
+This module provides utilities for building and managing provenance metadata
+that is stored in SLP files produced during inference. Provenance metadata
+helps track where predictions came from and how they were generated.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional, Union
+
+import sleap_io as sio
+
+import sleap_nn
+from sleap_nn.system_info import get_system_info_dict
+
+
+def build_inference_provenance(
+    model_paths: Optional[list[str]] = None,
+    model_type: Optional[str] = None,
+    start_time: Optional[datetime] = None,
+    end_time: Optional[datetime] = None,
+    input_labels: Optional[sio.Labels] = None,
+    input_path: Optional[Union[str, Path]] = None,
+    frames_processed: Optional[int] = None,
+    frames_total: Optional[int] = None,
+    frame_selection_method: Optional[str] = None,
+    inference_params: Optional[dict[str, Any]] = None,
+    tracking_params: Optional[dict[str, Any]] = None,
+    device: Optional[str] = None,
+    cli_args: Optional[dict[str, Any]] = None,
+    include_system_info: bool = True,
+) -> dict[str, Any]:
+    """Build provenance metadata dictionary for inference output.
+
+    This function creates a comprehensive provenance dictionary that captures
+    all relevant metadata about an inference run, enabling reproducibility
+    and tracking of prediction origins.
+
+    Args:
+        model_paths: List of paths to model checkpoints used for inference.
+        model_type: Type of model used (e.g., "top_down", "bottom_up",
+            "single_instance").
+        start_time: Datetime when inference started.
+        end_time: Datetime when inference finished.
+        input_labels: Input Labels object if inference was run on an SLP file.
+            The provenance from this object will be preserved.
+        input_path: Path to input file (SLP or video).
+        frames_processed: Number of frames that were processed.
+        frames_total: Total number of frames in the input.
+        frame_selection_method: Method used to select frames (e.g., "all",
+            "labeled", "suggested", "range").
+        inference_params: Dictionary of inference parameters (peak_threshold,
+            integral_refinement, batch_size, etc.).
+        tracking_params: Dictionary of tracking parameters if tracking was run.
+        device: Device used for inference (e.g., "cuda:0", "cpu", "mps").
+        cli_args: Command-line arguments if available.
+        include_system_info: If True, include detailed system information.
+            Set to False for lighter-weight provenance.
+
+    Returns:
+        Dictionary containing provenance metadata suitable for storing in
+        Labels.provenance.
+
+    Example:
+        >>> from datetime import datetime
+        >>> provenance = build_inference_provenance(
+        ...     model_paths=["/path/to/model.ckpt"],
+        ...     model_type="top_down",
+        ...     start_time=datetime.now(),
+        ...     end_time=datetime.now(),
+        ...     device="cuda:0",
+        ... )
+        >>> labels.provenance = provenance
+        >>> labels.save("predictions.slp")
+    """
+    provenance: dict[str, Any] = {}
+
+    # Timestamps
+    if start_time is not None:
+        provenance["inference_start_timestamp"] = start_time.isoformat()
+    if end_time is not None:
+        provenance["inference_end_timestamp"] = end_time.isoformat()
+    if start_time is not None and end_time is not None:
+        runtime_seconds = (end_time - start_time).total_seconds()
+        provenance["inference_runtime_seconds"] = runtime_seconds
+
+    # Version information
+    provenance["sleap_nn_version"] = sleap_nn.__version__
+    provenance["sleap_io_version"] = sio.__version__
+
+    # Model information
+    if model_paths is not None:
+        # Store as absolute POSIX paths for cross-platform compatibility
+        provenance["model_paths"] = [
+            Path(p).resolve().as_posix() if isinstance(p, (str, Path)) else str(p)
+            for p in model_paths
+        ]
+    if model_type is not None:
+        provenance["model_type"] = model_type
+
+    # Input data lineage
+    if input_path is not None:
+        provenance["source_file"] = (
+            Path(input_path).resolve().as_posix()
+            if isinstance(input_path, (str, Path))
+            else str(input_path)
+        )
+
+    # Preserve input provenance if available
+    if input_labels is not None and hasattr(input_labels, "provenance"):
+        input_prov = dict(input_labels.provenance)
+        if input_prov:
+            provenance["input_provenance"] = input_prov
+            # Also set source_labels for compatibility with sleap-io conventions
+            if "filename" in input_prov:
+                provenance["source_labels"] = input_prov["filename"]
+
+    # Frame selection information
+    if frames_processed is not None or frames_total is not None:
+        frame_info: dict[str, Any] = {}
+        if frame_selection_method is not None:
+            frame_info["method"] = frame_selection_method
+        if frames_processed is not None:
+            frame_info["frames_processed"] = frames_processed
+        if frames_total is not None:
+            frame_info["frames_total"] = frames_total
+        if frame_info:
+            provenance["frame_selection"] = frame_info
+
+    # Inference parameters
+    if inference_params is not None:
+        # Filter out None values and convert paths
+        clean_params = {}
+        for key, value in inference_params.items():
+            if value is not None:
+                if isinstance(value, Path):
+                    clean_params[key] = value.as_posix()
+                else:
+                    clean_params[key] = value
+        if clean_params:
+            provenance["inference_config"] = clean_params
+
+    # Tracking parameters
+    if tracking_params is not None:
+        clean_tracking = {k: v for k, v in tracking_params.items() if v is not None}
+        if clean_tracking:
+            provenance["tracking_config"] = clean_tracking
+
+    # Device information
+    if device is not None:
+        provenance["device"] = device
+
+    # CLI arguments
+    if cli_args is not None:
+        # Filter out None values
+        clean_cli = {k: v for k, v in cli_args.items() if v is not None}
+        if clean_cli:
+            provenance["cli_args"] = clean_cli
+
+    # System information (can be disabled for lighter provenance)
+    if include_system_info:
+        try:
+            system_info = get_system_info_dict()
+            # Extract key fields for provenance (avoid excessive nesting)
+            provenance["system_info"] = {
+                "python_version": system_info.get("python_version"),
+                "platform": system_info.get("platform"),
+                "pytorch_version": system_info.get("pytorch_version"),
+                "cuda_version": system_info.get("cuda_version"),
+                "accelerator": system_info.get("accelerator"),
+                "gpu_count": system_info.get("gpu_count"),
+            }
+            # Include GPU names if available
+            if system_info.get("gpus"):
+                provenance["system_info"]["gpus"] = [
+                    gpu.get("name") for gpu in system_info["gpus"]
+                ]
+        except Exception:
+            # Don't fail inference if system info collection fails
+            pass
+
+    return provenance
+
+
+def build_tracking_only_provenance(
+    input_labels: Optional[sio.Labels] = None,
+    input_path: Optional[Union[str, Path]] = None,
+    start_time: Optional[datetime] = None,
+    end_time: Optional[datetime] = None,
+    tracking_params: Optional[dict[str, Any]] = None,
+    frames_processed: Optional[int] = None,
+    include_system_info: bool = True,
+) -> dict[str, Any]:
+    """Build provenance metadata for tracking-only pipeline.
+
+    This is a simplified version of build_inference_provenance for when
+    only tracking is run without model inference.
+
+    Args:
+        input_labels: Input Labels object with existing predictions.
+        input_path: Path to input SLP file.
+        start_time: Datetime when tracking started.
+        end_time: Datetime when tracking finished.
+        tracking_params: Dictionary of tracking parameters.
+        frames_processed: Number of frames that were tracked.
+        include_system_info: If True, include system information.
+
+    Returns:
+        Dictionary containing provenance metadata.
+    """
+    provenance: dict[str, Any] = {}
+
+    # Timestamps
+    if start_time is not None:
+        provenance["tracking_start_timestamp"] = start_time.isoformat()
+    if end_time is not None:
+        provenance["tracking_end_timestamp"] = end_time.isoformat()
+    if start_time is not None and end_time is not None:
+        runtime_seconds = (end_time - start_time).total_seconds()
+        provenance["tracking_runtime_seconds"] = runtime_seconds
+
+    # Version information
+    provenance["sleap_nn_version"] = sleap_nn.__version__
+    provenance["sleap_io_version"] = sio.__version__
+
+    # Note that this is tracking-only
+    provenance["pipeline_type"] = "tracking_only"
+
+    # Input data lineage
+    if input_path is not None:
+        provenance["source_file"] = (
+            Path(input_path).resolve().as_posix()
+            if isinstance(input_path, (str, Path))
+            else str(input_path)
+        )
+
+    # Preserve input provenance if available
+    if input_labels is not None and hasattr(input_labels, "provenance"):
+        input_prov = dict(input_labels.provenance)
+        if input_prov:
+            provenance["input_provenance"] = input_prov
+            if "filename" in input_prov:
+                provenance["source_labels"] = input_prov["filename"]
+
+    # Frame information
+    if frames_processed is not None:
+        provenance["frames_processed"] = frames_processed
+
+    # Tracking parameters
+    if tracking_params is not None:
+        clean_tracking = {k: v for k, v in tracking_params.items() if v is not None}
+        if clean_tracking:
+            provenance["tracking_config"] = clean_tracking
+
+    # System information
+    if include_system_info:
+        try:
+            system_info = get_system_info_dict()
+            provenance["system_info"] = {
+                "python_version": system_info.get("python_version"),
+                "platform": system_info.get("platform"),
+                "pytorch_version": system_info.get("pytorch_version"),
+                "accelerator": system_info.get("accelerator"),
+            }
+        except Exception:
+            pass
+
+    return provenance
+
+
+def merge_provenance(
+    base_provenance: dict[str, Any],
+    additional: dict[str, Any],
+    overwrite: bool = True,
+) -> dict[str, Any]:
+    """Merge additional provenance fields into base provenance.
+
+    Args:
+        base_provenance: Base provenance dictionary.
+        additional: Additional fields to merge.
+        overwrite: If True, additional fields overwrite base fields.
+            If False, base fields take precedence.
+
+    Returns:
+        Merged provenance dictionary.
+    """
+    result = dict(base_provenance)
+    for key, value in additional.items():
+        if key not in result or overwrite:
+            result[key] = value
+    return result