dataeval-flow 0.1.0__py3-none-any.whl

dataeval_flow/workflows/cleaning/__init__.py

@@ -0,0 +1,23 @@
+"""Data cleaning workflow - public re-exports."""
+
+from dataeval_flow.workflows.cleaning.outputs import (
+    DataCleaningMetadata,
+    DataCleaningOutputs,
+    DataCleaningRawOutputs,
+    DataCleaningReport,
+    DataCleaningResult,
+    is_cleaning_result,
+)
+from dataeval_flow.workflows.cleaning.params import DataCleaningParameters
+from dataeval_flow.workflows.cleaning.workflow import DataCleaningWorkflow
+
+__all__ = [
+    "DataCleaningMetadata",
+    "DataCleaningOutputs",
+    "DataCleaningParameters",
+    "DataCleaningRawOutputs",
+    "DataCleaningReport",
+    "DataCleaningResult",
+    "DataCleaningWorkflow",
+    "is_cleaning_result",
+]

dataeval_flow/workflows/cleaning/outputs.py

@@ -0,0 +1,200 @@
+"""Data cleaning workflow outputs."""
+
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias
+
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict, TypeIs
+
+from dataeval_flow.config.schemas import ResultMetadata
+from dataeval_flow.workflow.base import Reportable, WorkflowOutputsBase, WorkflowReportBase
+
+if TYPE_CHECKING:
+    from dataeval_flow.workflow import WorkflowResult
+
+__all__ = [
+    "ClasswisePivotDict",
+    "DataCleaningMetadata",
+    "DataCleaningOutputs",
+    "DataCleaningRawOutputs",
+    "DataCleaningReport",
+    "DataCleaningResult",
+    "DetectionDict",
+    "DuplicatesDict",
+    "LabelStatsDict",
+    "NearDuplicateGroupDict",
+    "OutlierIssueRecord",
+    "OutlierIssuesDict",
+    "SourceIndexDict",
+    "is_cleaning_result",
+]
+
+
+# ---------------------------------------------------------------------------
+# TypedDicts for serialized evaluator outputs
+# ---------------------------------------------------------------------------
+
+
+class _OutlierIssueRecordRequired(TypedDict):
+    """Required fields for an outlier issue record."""
+
+    item_index: int
+    metric_name: str
+    metric_value: float
+
+
+class OutlierIssueRecord(_OutlierIssueRecordRequired, total=False):
+    """Single outlier issue from DataEval OutliersOutput.
+
+    ``target_index`` is present for target-level outliers (object detection datasets)
+    and absent or ``None`` for image-level outliers.
+    """
+
+    target_index: int | None
+
+
+class OutlierIssuesDict(TypedDict):
+    """Serialized outlier issues (image or target level)."""
+
+    issues: list[OutlierIssueRecord]
+    count: int
+
+
+class SourceIndexDict(TypedDict):
+    """Serialized SourceIndex from DataEval — identifies an item, target, and channel."""
+
+    item: int
+    target: int | None
+    channel: int | None
+
+
+#: An index value is either a plain ``int`` (image-level) or a
+#: :class:`SourceIndexDict` (target/channel-level).
+IndexValue = int | SourceIndexDict
+
+
+class NearDuplicateGroupDict(TypedDict):
+    """Serialized near-duplicate group."""
+
+    indices: list[IndexValue]
+    methods: list[str]
+    orientation: str | None
+
+
+class DetectionDict(TypedDict, total=False):
+    """Serialized duplicate detection result (exact + near groups)."""
+
+    exact: list[list[IndexValue]]
+    near: list[NearDuplicateGroupDict]
+
+
+class DuplicatesDict(TypedDict):
+    """Serialized DuplicatesOutput (items + targets)."""
+
+    items: DetectionDict
+    targets: DetectionDict
+
+
+class LabelStatsDict(TypedDict, total=False):
+    """Label statistics derived from Metadata."""
+
+    item_count: int
+    class_count: int
+    index2label: dict[int, str]
+    label_counts_per_class: dict[str, int]
+
+
+class ClasswiseRowDict(TypedDict):
+    """Single row in the classwise outlier summary."""
+
+    class_name: str
+    count: int
+    pct: float  # percentage of that class's labels flagged
+
+
+class ClasswisePivotDict(TypedDict, total=False):
+    """Classwise outlier summary — count and % of labels flagged per class.
+
+    For classification datasets this summarises image outliers per class;
+    for object-detection datasets this summarises target-level outliers per
+    class (image-level entries are excluded since they cannot be attributed
+    to a single class).
+    """
+
+    level: str  # "image" or "target"
+    rows: list[ClasswiseRowDict]  # one per class + Total row
+
+
+# ---------------------------------------------------------------------------
+# Pydantic output models
+# ---------------------------------------------------------------------------
+
+
+class DataCleaningRawOutputs(WorkflowOutputsBase):
+    """Machine-readable results from data cleaning workflow."""
+
+    duplicates: DuplicatesDict = Field(
+        default_factory=lambda: {"items": {}, "targets": {}},
+        description="DuplicatesOutput from DataEval",
+    )
+    img_outliers: OutlierIssuesDict = Field(
+        default_factory=lambda: {"issues": [], "count": 0},
+        description="OutliersOutput for images from DataEval",
+    )
+    label_stats: LabelStatsDict = Field(
+        default_factory=dict,  # type: ignore[assignment]  # empty dict valid; all LabelStatsDict keys are optional (total=False)
+        description="Label statistics derived from Metadata (class_labels, index2label, item_count)",
+    )
+    target_outliers: OutlierIssuesDict | None = Field(
+        default=None,
+        description="OutliersOutput for bounding boxes (OD datasets only)",
+    )
+    classwise_outliers: ClasswisePivotDict | None = Field(
+        default=None,
+        description="Classwise outlier pivot — image-level for classification, target-level for OD",
+    )
+
+
+class DataCleaningReport(WorkflowReportBase):
+    """Human-readable report for data cleaning workflow."""
+
+    findings: list[Reportable] = Field(default_factory=list)
+
+
+class DataCleaningOutputs(BaseModel):
+    """Complete data cleaning workflow output."""
+
+    raw: DataCleaningRawOutputs
+    report: DataCleaningReport
+
+
+class DataCleaningMetadata(ResultMetadata):
+    """Metadata for the data-cleaning workflow."""
+
+    mode: Literal["advisory", "preparatory"] = "advisory"
+    evaluators: list[str] = Field(default_factory=list)
+    flagged_indices: list[int] = Field(default_factory=list)
+    clean_indices: list[int] = Field(default_factory=list)
+    removed_count: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Type alias and TypeIs guard for type narrowing
+# ---------------------------------------------------------------------------
+
+#: Fully typed result alias for the data-cleaning workflow.
+DataCleaningResult: TypeAlias = "WorkflowResult[DataCleaningMetadata, DataCleaningOutputs]"
+
+
+def is_cleaning_result(
+    result: "WorkflowResult[Any, Any]",
+) -> TypeIs["WorkflowResult[DataCleaningMetadata, DataCleaningOutputs]"]:
+    """Narrow a generic ``WorkflowResult`` to a data-cleaning result.
+
+    Useful in the CLI loop or any code that receives a generic result::
+
+        [result] = run_tasks(config, "my_task")
+        if is_cleaning_result(result):
+            result.metadata.flagged_indices  # ✓ typed
+            result.data.raw.img_outliers     # ✓ typed
+    """
+    return isinstance(result.metadata, DataCleaningMetadata)

dataeval_flow/workflows/cleaning/params.py

@@ -0,0 +1,160 @@
+"""Data cleaning workflow parameters."""
+
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from dataeval_flow.workflow.base import WorkflowParametersBase
+
+__all__ = ["DataCleaningParameters", "DataCleaningHealthThresholds"]
+
+
+class DataCleaningHealthThresholds(BaseModel):
+    """Configurable warning thresholds for data cleaning health status.
+
+    Each threshold is a percentage (0–100). When the detected rate exceeds the
+    threshold the corresponding finding is elevated to ``severity="warning"``;
+    otherwise it stays at ``severity="info"``.
+
+    Set a threshold to ``None`` to disable the warning for that metric.
+    """
+
+    exact_duplicates: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Max allowable % of images in exact-duplicate groups. "
+            "Exact duplicates are byte-identical images that inflate dataset size without "
+            "adding information. Default 0% — any exact duplicates trigger a warning. "
+            "Raise above 0 only if your pipeline intentionally includes repeated images "
+            "(e.g. augmentation-before-split workflows)."
+        ),
+    )
+    near_duplicates: float = Field(
+        default=5.0,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Max allowable % of images in near-duplicate groups. "
+            "Near duplicates are visually similar images (crops, resizes, minor edits) "
+            "that can bias model training toward repeated content. Default 5%. "
+            "Lower to 1–2% for curated benchmarks; raise to 10–15% for large-scale "
+            "web-scraped datasets where some redundancy is expected."
+        ),
+    )
+    image_outliers: float = Field(
+        default=3.0,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Max allowable % of images flagged as statistical outliers "
+            "(unusual dimensions, brightness, entropy, or visual statistics). Default 3%. "
+            "Lower to 1% for safety-critical datasets; raise to 5–10% for diverse "
+            "real-world collections where high visual variance is expected."
+        ),
+    )
+    target_outliers: float = Field(
+        default=3.0,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Max allowable % of targets (labels/annotations) flagged as outliers "
+            "(unusual bounding-box sizes, aspect ratios, or annotation counts). Default 3%. "
+            "Lower to 1% for annotation-quality audits; raise to 5–10% for datasets "
+            "with naturally high annotation variance (e.g. dense object detection)."
+        ),
+    )
+    classwise_outliers: float = Field(
+        default=3.0,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Max allowable % of items flagged as outliers within any single class. Default 3%. "
+            "This catches classes where outlier concentration is disproportionately high, "
+            "which may indicate labeling errors or class definition issues. "
+            "Lower to 1% for label-quality audits; raise to 5–10% for classes with "
+            "inherently high visual diversity."
+        ),
+    )
+    class_label_imbalance: float = Field(
+        default=5.0,
+        ge=1.0,
+        description=(
+            "Max allowable ratio between the largest and smallest class counts "
+            "(max_class / min_class). Default 5:1. "
+            "For binary classification, 3:1 is a common threshold for 'imbalanced'. "
+            "For large class hierarchies (25+ classes), the long tail naturally "
+            "increases this ratio — raise to 10–20:1 to avoid false warnings. "
+            "Set to 1.0 to require perfectly balanced classes."
+        ),
+    )
+
+
+class DataCleaningParameters(WorkflowParametersBase):
+    """Parameters for data cleaning workflow.
+
+    Required parameters must be explicitly set per CR-4.14-G-1
+    (avoid application-specific defaults).
+    """
+
+    # --- Outlier detection params ---
+    outlier_method: Literal["adaptive", "zscore", "modzscore", "iqr"] = Field(
+        description="Statistical method for outlier detection",
+    )
+    outlier_flags: Sequence[Literal["dimension", "pixel", "visual"]] = Field(
+        min_length=1,
+        description="Image statistics groups for outlier detection. At least one required.",
+    )
+    outlier_threshold: float | None = Field(
+        default=None,
+        ge=0.0,
+        description="Custom threshold (None = use DataEval default for chosen method)",
+    )
+    outlier_cluster_threshold: float | None = Field(
+        default=None,
+        description=(
+            "Std devs from cluster center to flag as outlier (requires extractor). None = skip cluster detection."
+        ),
+    )
+    outlier_cluster_algorithm: Literal["kmeans", "hdbscan"] | None = Field(
+        default=None,
+        description="Clustering algorithm for cluster-based outlier detection.",
+    )
+    outlier_n_clusters: int | None = Field(
+        default=None,
+        description="Expected number of clusters. None = auto-detect.",
+    )
+
+    # --- Duplicate detection params ---
+    duplicate_flags: Sequence[Literal["hash_basic", "hash_d4"]] | None = Field(
+        default=None,
+        description=(
+            "Hash flag groups for duplicate detection. None = DataEval default (hash_basic: xxhash + phash + dhash)."
+        ),
+    )
+    duplicate_merge_near: bool = Field(
+        default=True,
+        description="Merge overlapping near-duplicate groups from different detection methods.",
+    )
+    duplicate_cluster_sensitivity: float | None = Field(
+        default=None,
+        description=(
+            "Threshold for cluster-based near duplicate detection (requires extractor). None = skip cluster detection."
+        ),
+    )
+    duplicate_cluster_algorithm: Literal["kmeans", "hdbscan"] | None = Field(
+        default=None,
+        description="Clustering algorithm for cluster-based duplicate detection.",
+    )
+    duplicate_n_clusters: int | None = Field(
+        default=None,
+        description="Expected number of clusters for duplicate detection. None = auto-detect.",
+    )
+
+    # --- Health thresholds ---
+    health_thresholds: DataCleaningHealthThresholds = Field(
+        default_factory=DataCleaningHealthThresholds,
+        description="Warning thresholds for dataset health status. Findings are flagged as warnings.",
+    )

dataeval_flow/workflows/cleaning/report.py

@@ -0,0 +1,304 @@
+"""Findings builders for the data cleaning workflow."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from dataeval_flow.workflow.base import Reportable
+from dataeval_flow.workflows.cleaning.outputs import (
+    DataCleaningRawOutputs,
+    IndexValue,
+)
+from dataeval_flow.workflows.cleaning.params import DataCleaningHealthThresholds
+
+
+def _duplicate_finding(raw: DataCleaningRawOutputs, thresholds: DataCleaningHealthThresholds) -> Reportable | None:
+    """Build a Duplicates finding from raw results, or None if no duplicates."""
+    exact_groups = raw.duplicates.get("items", {}).get("exact", [])
+    near_groups = raw.duplicates.get("items", {}).get("near", [])
+    if not exact_groups and not near_groups:
+        return None
+
+    exact_affected = sum(len(g) for g in exact_groups)
+    near_affected = sum(len(g["indices"]) for g in near_groups)
+    # Collect methods and orientations from near groups
+    all_methods: set[str] = set()
+    orientations: dict[str, int] = {}
+    for g in near_groups:
+        all_methods.update(g.get("methods", []))
+        orient = g.get("orientation")
+        if orient is not None:
+            orientations[orient] = orientations.get(orient, 0) + 1
+    detail_lines: list[str] = []
+    if exact_groups:
+        detail_lines.append(f"{len(exact_groups)} exact-duplicate groups ({exact_affected} images)")
+    if near_groups:
+        detail_lines.append(f"{len(near_groups)} near-duplicate groups ({near_affected} images)")
+        if all_methods:
+            detail_lines.append(f"  Methods: {', '.join(sorted(all_methods))}")
+        if orientations:
+            parts = [f"{c} {o}" for o, c in sorted(orientations.items())]
+            detail_lines.append(f"  Orientations: {', '.join(parts)}")
+    # Determine severity from thresholds
+    exact_pct = (exact_affected / raw.dataset_size) * 100 if raw.dataset_size else 0.0
+    near_pct = (near_affected / raw.dataset_size) * 100 if raw.dataset_size else 0.0
+    severity: Literal["ok", "info", "warning"] = "info"
+    if exact_pct > thresholds.exact_duplicates or near_pct > thresholds.near_duplicates:
+        severity = "warning"
+
+    return Reportable(
+        report_type="key_value",
+        severity=severity,
+        title="Duplicates",
+        data={
+            "brief": (f"{exact_affected} exact ({round(exact_pct, 1)}%), {near_affected} near ({round(near_pct, 1)}%)"),
+            "detail_lines": detail_lines,
+            "exact_groups": len(exact_groups),
+            "near_groups": len(near_groups),
+            "exact_affected": exact_affected,
+            "near_affected": near_affected,
+            "near_methods": sorted(all_methods),
+            "near_orientations": orientations,
+        },
+        description=(f"{len(exact_groups)} exact duplicate groups, {len(near_groups)} near-duplicate groups found."),
+    )
+
+
+def _label_distribution_finding(
+    raw: DataCleaningRawOutputs,
+    thresholds: DataCleaningHealthThresholds,
+    label_source: str | None = None,
+) -> Reportable | None:
+    """Build a Label Distribution finding from raw results, or None if no label stats."""
+    if not raw.label_stats:
+        return None
+
+    class_count = raw.label_stats.get("class_count", 0)
+    if class_count == 0:
+        return None  # No labels — suppress finding
+
+    label_counts = raw.label_stats.get("label_counts_per_class", {})
+    item_count = raw.label_stats.get("item_count", 0)
+    counts_list = list(label_counts.values()) if label_counts else []
+    has_empty_class = bool(counts_list) and min(counts_list) == 0
+    imbalance_ratio = round(max(counts_list) / min(counts_list), 1) if counts_list and not has_empty_class else 0.0
+    footer_lines: list[str] = []
+    if label_source:
+        footer_lines.append(f"Labels {label_source}")
+    if has_empty_class:
+        footer_lines.append("Warning: one or more classes have zero items")
+    elif imbalance_ratio == 1.0:
+        footer_lines.append("Balanced: all classes have equal counts")
+    elif imbalance_ratio != 0.0:
+        footer_lines.append(f"Imbalance ratio: {imbalance_ratio} (max/min)")
+    severity: Literal["ok", "info", "warning"] = "info"
+    if has_empty_class or imbalance_ratio > thresholds.class_label_imbalance:
+        severity = "warning"
+
+    return Reportable(
+        report_type="table",
+        severity=severity,
+        title=("Label/Directory_Name Distribution" if label_source == "filepath" else "Label Distribution"),
+        data={
+            "brief": f"{class_count} classes, {item_count} items, imbalance {imbalance_ratio}:1",
+            "table_data": label_counts,
+            "table_headers": ("Class", "Count"),
+            "footer_lines": footer_lines,
+            # Keep existing keys for JSON/YAML consumers
+            "label_counts": label_counts,
+            "class_count": class_count,
+            "item_count": item_count,
+            "imbalance_ratio": imbalance_ratio,
+            "label_source": label_source,
+        },
+        description=(f"{class_count} classes, {item_count} items."),
+    )
+
+
+def _classwise_finding(raw: DataCleaningRawOutputs, thresholds: DataCleaningHealthThresholds) -> Reportable:
+    """Build a Classwise Outliers finding from raw results."""
+    pivot = raw.classwise_outliers
+    rows = pivot.get("rows", None) if pivot else None
+
+    if not rows:
+        return Reportable(
+            report_type="pivot_table",
+            severity="ok",
+            title="Classwise Outliers",
+            data={
+                "brief": "no outliers detected",
+                "level": "image",
+                "table_data": [],
+                "table_headers": ["Class Name", "Count", "%"],
+                "worst_class": None,
+                "worst_pct": 0.0,
+                "classes_over_threshold": 0,
+            },
+            description="No outliers detected — classwise breakdown not applicable.",
+        )
+
+    level = pivot.get("level", "image")  # type: ignore[union-attr]
+
+    # The last row is the "Total" row
+    total_row = rows[-1] if rows else {}
+    class_rows = rows[:-1] if len(rows) > 1 else rows
+    total_pct = total_row.get("pct", 0.0)
+
+    severity: Literal["ok", "info", "warning"] = "info"
+    if total_pct > thresholds.classwise_outliers:
+        severity = "warning"
+
+    # Identify the worst class and how many classes exceed the threshold
+    class_pcts = [r.get("pct", 0.0) for r in class_rows]
+    worst_row = max(class_rows, key=lambda r: r.get("pct", 0.0))
+    worst_name = worst_row.get("class_name", "?")
+    worst_pct = worst_row.get("pct", 0.0)
+    classes_over = sum(1 for p in class_pcts if p > thresholds.classwise_outliers)
+    brief_prefix = f"worst: {worst_name} ({worst_pct}%), "
+
+    # Brief: focus on concentration — which class is worst and how many are over threshold
+    if classes_over > 0:
+        brief = f"{brief_prefix}{classes_over}/{len(class_rows)} classes over {thresholds.classwise_outliers}%"
+    else:
+        brief = f"{brief_prefix}all classes within {thresholds.classwise_outliers}%"
+
+    return Reportable(
+        report_type="pivot_table",
+        severity=severity,
+        title="Classwise Outliers",
+        data={
+            "brief": brief,
+            "level": level,
+            "table_data": rows,
+            "table_headers": ["Class Name", "Count", "%"],
+            "worst_class": worst_name,
+            "worst_pct": worst_pct,
+            "classes_over_threshold": classes_over,
+        },
+        description=(
+            f"Most outliers in {worst_name} ({worst_pct}%). "
+            f"{classes_over}/{len(class_rows)} classes exceed {thresholds.classwise_outliers}% threshold."
+        ),
+    )
+
+
+def build_findings(
+    raw: DataCleaningRawOutputs,
+    metadata: Any,  # noqa: ARG001 - reserved for future metadata-based findings
+    thresholds: DataCleaningHealthThresholds,
+    label_source: str | None = None,
+) -> list[Reportable]:
+    """Generate human-readable findings from raw results."""
+    findings: list[Reportable] = []
+
+    # Outlier findings — count distinct images, not total flags
+    outlier_issues = raw.img_outliers.get("issues", [])
+    outlier_image_count = len({issue["item_index"] for issue in outlier_issues})
+    pct = (outlier_image_count / raw.dataset_size) * 100 if raw.dataset_size else 0
+    # Per-metric breakdown: count distinct images per metric
+    _per_metric_sets: dict[str, set[int]] = {}
+    for issue in outlier_issues:
+        _per_metric_sets.setdefault(issue["metric_name"], set()).add(issue["item_index"])
+    per_metric = {k: len(v) for k, v in _per_metric_sets.items()}
+    if outlier_image_count > 0:
+        img_severity: Literal["ok", "info", "warning"] = "warning" if pct > thresholds.image_outliers else "info"
+        img_description = f"{outlier_image_count} images ({pct:.1f}%) flagged as outliers."
+    else:
+        img_severity = "ok"
+        img_description = "No images flagged as outliers."
+    findings.append(
+        Reportable(
+            report_type="key_value",
+            severity=img_severity,
+            title="Image Outliers",
+            data={
+                "brief": f"{outlier_image_count} images ({round(pct, 1)}%)",
+                "multi_metric_subject": "images",
+                "count": outlier_image_count,
+                "percentage": round(pct, 1),
+                "per_metric": per_metric,
+                "total_flags": len(outlier_issues),
+                "dataset_size": raw.dataset_size,
+            },
+            description=img_description,
+        )
+    )
+
+    # Target outlier findings — count distinct (item, target) pairs
+    target_issues = raw.target_outliers.get("issues", []) if raw.target_outliers else []
+    target_pair_count = len({(issue["item_index"], issue.get("target_index")) for issue in target_issues})
+    if target_pair_count > 0:
+        # Total target count from label stats for percentage
+        total_targets = sum(raw.label_stats.get("label_counts_per_class", {}).values()) if raw.label_stats else 0
+        target_pct = round((target_pair_count / total_targets) * 100, 1) if total_targets > 0 else 0.0
+        # Per-metric breakdown for targets
+        _target_metric_sets: dict[str, set[tuple[int, int | None]]] = {}
+        for issue in target_issues:
+            key = (issue["item_index"], issue.get("target_index"))
+            _target_metric_sets.setdefault(issue["metric_name"], set()).add(key)
+        target_per_metric = {k: len(v) for k, v in _target_metric_sets.items()}
+        tgt_severity: Literal["ok", "info", "warning"] = (
+            "warning" if target_pct > thresholds.target_outliers else "info"
+        )
+        findings.append(
+            Reportable(
+                report_type="key_value",
+                severity=tgt_severity,
+                title="Target Outliers",
+                data={
+                    "brief": f"{target_pair_count} targets ({target_pct}%)",
+                    "multi_metric_subject": "targets",
+                    "count": target_pair_count,
+                    "percentage": target_pct,
+                    "per_metric": target_per_metric,
+                    "total_flags": len(target_issues),
+                    "total_targets": total_targets,
+                },
+                description=f"{target_pair_count} bounding-box targets ({target_pct}%) flagged as outliers.",
+            )
+        )
+
+    # Classwise outlier pivot — right after image/target outliers
+    findings.append(_classwise_finding(raw, thresholds))
+
+    # Duplicate findings
+    dup_finding = _duplicate_finding(raw, thresholds)
+    if dup_finding:
+        findings.append(dup_finding)
+
+    # Label distribution finding
+    label_finding = _label_distribution_finding(raw, thresholds, label_source=label_source)
+    if label_finding:
+        findings.append(label_finding)
+
+    return findings
+
+
+def _item_id_of(idx: IndexValue) -> int:
+    """Extract the item ID from an :class:`IndexValue`.
+
+    Returns the ``int`` directly for image-level indices, or the ``"item"``
+    field from a :class:`SourceIndexDict` for target-level indices.
+    """
+    if isinstance(idx, dict):
+        return idx["item"]
+    return idx
+
+
+def collect_flagged_indices(raw: DataCleaningRawOutputs) -> set[int]:
+    """Collect all unique item indices flagged by outlier or duplicate detection."""
+    flagged: set[int] = set()
+
+    # Outlier-flagged items
+    for issue in raw.img_outliers.get("issues", []):
+        flagged.add(issue["item_index"])
+
+    # Duplicate-flagged items (keep first in each group, flag the rest)
+    for group in raw.duplicates.get("items", {}).get("exact", []):
+        for idx in group[1:]:  # keep first, flag rest
+            flagged.add(_item_id_of(idx))
+    for group in raw.duplicates.get("items", {}).get("near", []):
+        for idx in group["indices"][1:]:
+            flagged.add(_item_id_of(idx))
+
+    return flagged