dataeval-flow 0.1.0__py3-none-any.whl

dataeval_flow/workflows/cleaning/workflow.py

@@ -0,0 +1,794 @@
+"""Data Cleaning Workflow — orchestration + processor + factory helpers."""
+
+__all__ = ["DataCleaningWorkflow"]
+
+import contextlib
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+import polars as pl
+from dataeval import Metadata
+from dataeval.flags import ImageStats
+from dataeval.protocols import AnnotatedDataset
+from dataeval.quality import Duplicates, DuplicatesOutput, Outliers
+from pydantic import BaseModel
+
+from dataeval_flow.cache import active_cache, get_or_compute_metadata
+from dataeval_flow.embeddings import build_extractor
+from dataeval_flow.workflow import WorkflowContext, WorkflowProtocol, WorkflowResult
+from dataeval_flow.workflow.base import Reportable
+from dataeval_flow.workflows.cleaning.outputs import (
+    ClasswisePivotDict,
+    ClasswiseRowDict,
+    DataCleaningMetadata,
+    DataCleaningOutputs,
+    DataCleaningRawOutputs,
+    DataCleaningReport,
+    DetectionDict,
+    DuplicatesDict,
+    IndexValue,
+    LabelStatsDict,
+    OutlierIssuesDict,
+    SourceIndexDict,
+)
+from dataeval_flow.workflows.cleaning.params import DataCleaningParameters
+from dataeval_flow.workflows.cleaning.report import build_findings, collect_flagged_indices
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Protocols for private DataEval types
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Factory helpers
+# ---------------------------------------------------------------------------
+
+FLAG_MAP: dict[str, ImageStats] = {
+    "dimension": ImageStats.DIMENSION,
+    "pixel": ImageStats.PIXEL,
+    "visual": ImageStats.VISUAL,
+}
+
+HASH_FLAG_MAP: dict[str, ImageStats] = {
+    "hash_basic": ImageStats.HASH_DUPLICATES_BASIC,
+    "hash_d4": ImageStats.HASH_DUPLICATES_D4,
+}
+
+
+def _build_outliers(
+    params: DataCleaningParameters,
+    extractor: Callable | None = None,
+) -> Outliers:
+    """Build Outliers evaluator from cleaning parameters."""
+    flags = ImageStats.NONE
+    for name in params.outlier_flags:
+        flags |= FLAG_MAP[name]
+
+    # Validate cluster params require an extractor
+    has_cluster = (
+        params.outlier_cluster_threshold is not None
+        or params.outlier_cluster_algorithm is not None
+        or params.outlier_n_clusters is not None
+    )
+    if has_cluster and extractor is None:
+        raise ValueError(
+            "Cluster-based outlier detection requires an extractor. "
+            "Configure a model/extractor or remove cluster params."
+        )
+
+    return Outliers(
+        flags=flags,
+        outlier_threshold=(params.outlier_method, params.outlier_threshold),
+        cluster_threshold=params.outlier_cluster_threshold,
+        cluster_algorithm=params.outlier_cluster_algorithm,
+        n_clusters=params.outlier_n_clusters,
+        extractor=extractor,
+    )
+
+
+def _build_duplicates(
+    params: DataCleaningParameters,
+    extractor: Callable | None = None,
+    batch_size: int | None = None,
+) -> Duplicates:
+    """Build Duplicates evaluator from cleaning parameters."""
+    # Build hash flags
+    flags = ImageStats.NONE
+    if params.duplicate_flags is not None:
+        for name in params.duplicate_flags:
+            flags |= HASH_FLAG_MAP[name]
+
+    # Validate cluster params require an extractor
+    has_cluster = (
+        params.duplicate_cluster_sensitivity is not None
+        or params.duplicate_cluster_algorithm is not None
+        or params.duplicate_n_clusters is not None
+    )
+    if has_cluster and extractor is None:
+        raise ValueError(
+            "Cluster-based duplicate detection requires an extractor. "
+            "Configure a model/extractor or remove cluster params."
+        )
+
+    # Pass flags only if explicitly configured; otherwise let DataEval use its default.
+    kwargs: dict[str, object] = {
+        "merge_near_duplicates": params.duplicate_merge_near,
+        "cluster_sensitivity": params.duplicate_cluster_sensitivity,
+        "cluster_algorithm": params.duplicate_cluster_algorithm,
+        "n_clusters": params.duplicate_n_clusters,
+        "extractor": extractor,
+        "batch_size": batch_size,
+    }
+    if params.duplicate_flags is not None:
+        kwargs["flags"] = flags
+
+    return Duplicates(**kwargs)  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# Result serialization helpers
+# ---------------------------------------------------------------------------
+
+
+def _serialize_outlier_issues(issues: "pl.DataFrame") -> "OutlierIssuesDict":
+    """Serialize outlier issues Polars DataFrame to plain dict.
+
+    Parameters
+    ----------
+    issues : polars.DataFrame
+        Polars DataFrame with columns: item_index, metric_name, metric_value,
+        and optionally target_index.
+    """
+    return {
+        # to_dicts() returns list[dict[str, Any]]; rows match OutlierIssueRecord shape at runtime.
+        "issues": issues.to_dicts(),  # type: ignore[typeddict-item]
+        "count": len(issues),
+    }
+
+
+def _serialize_duplicates(result: "DuplicatesOutput") -> "DuplicatesDict":
+    """Serialize DuplicatesOutput to plain dict from its DataFrame.
+
+    DuplicatesOutput wraps a DataFrame with columns: group_id, level,
+    dup_type, item_indices, target_indices, methods, orientation.
+    """
+
+    def _indices_from_row(row: dict[str, Any]) -> list[IndexValue]:
+        """Build index list from a DataFrame row, using SourceIndexDict for targets."""
+        items = row["item_indices"]
+        targets = row.get("target_indices")
+        if targets is not None:
+            return [SourceIndexDict(item=i, target=t, channel=None) for i, t in zip(items, targets, strict=True)]
+        return [int(i) for i in items]
+
+    def _detection_from_df(df: "pl.DataFrame") -> "DetectionDict":
+        out: DetectionDict = {}
+        exact_df = df.filter(pl.col("dup_type") == "exact")
+        if len(exact_df) > 0:
+            out["exact"] = [_indices_from_row(row) for row in exact_df.iter_rows(named=True)]
+
+        near_df = df.filter(pl.col("dup_type") == "near")
+        if len(near_df) > 0:
+            out["near"] = [
+                {
+                    "indices": _indices_from_row(row),
+                    "methods": sorted(row["methods"]),
+                    "orientation": row.get("orientation"),
+                }
+                for row in near_df.iter_rows(named=True)
+            ]
+        return out
+
+    items_df = result.data().filter(pl.col("level") == "item")
+    targets_df = result.data().filter(pl.col("level") == "target")
+    return {
+        "items": _detection_from_df(items_df),
+        "targets": _detection_from_df(targets_df),
+    }
+
+
+def _compute_label_stats(metadata: Metadata) -> "LabelStatsDict":
+    """Compute label statistics from Metadata instance."""
+    _, _, label_counts = _build_class_labels_df(metadata)
+
+    return {
+        "item_count": metadata.item_count,
+        "class_count": len(metadata.index2label),
+        "index2label": dict(metadata.index2label),
+        "label_counts_per_class": label_counts,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Processor (internal — not exported)
+# ---------------------------------------------------------------------------
+
+
+def _resolve_flags(params: DataCleaningParameters) -> tuple[ImageStats, ImageStats]:
+    """Resolve outlier and hash flags from cleaning parameters."""
+    outlier_flags = ImageStats.NONE
+    for name in params.outlier_flags:
+        outlier_flags |= FLAG_MAP[name]
+
+    hash_flags = ImageStats.NONE
+    if params.duplicate_flags is not None:
+        for name in params.duplicate_flags:
+            hash_flags |= HASH_FLAG_MAP[name]
+    else:
+        # DataEval default when no flags are specified
+        hash_flags = ImageStats.HASH_DUPLICATES_BASIC
+
+    return outlier_flags, hash_flags
+
+
+def _split_outlier_issues(
+    issues_df: "pl.DataFrame",
+) -> tuple["pl.DataFrame", "pl.DataFrame | None"]:
+    """Split outlier issues into image-level and target-level DataFrames."""
+    if "target_index" in issues_df.columns:
+        img_issues = issues_df.filter(issues_df["target_index"].is_null())
+        target_issues = issues_df.filter(issues_df["target_index"].is_not_null())
+    else:
+        img_issues = issues_df
+        target_issues = None
+    return img_issues, target_issues
+
+
+def _validate_cluster_params(params: DataCleaningParameters, extractor: Callable | None) -> None:
+    """Validate that cluster-based detection params have an accompanying extractor."""
+    has_outlier_cluster = (
+        params.outlier_cluster_threshold is not None
+        or params.outlier_cluster_algorithm is not None
+        or params.outlier_n_clusters is not None
+    )
+    if has_outlier_cluster and extractor is None:
+        raise ValueError(
+            "Cluster-based outlier detection requires an extractor. "
+            "Configure a model/extractor or remove cluster params."
+        )
+
+    has_dup_cluster = (
+        params.duplicate_cluster_sensitivity is not None
+        or params.duplicate_cluster_algorithm is not None
+        or params.duplicate_n_clusters is not None
+    )
+    if has_dup_cluster and extractor is None:
+        raise ValueError(
+            "Cluster-based duplicate detection requires an extractor. "
+            "Configure a model/extractor or remove cluster params."
+        )
+
+
+@dataclass(frozen=True)
+class CleaningRunContext:
+    """Extractor plumbing passed from execute() to _run_cleaning()."""
+
+    extractor_config: Any = None
+    transforms: Callable | None = None
+    batch_size: int | None = None
+
+
+def _build_class_labels_df(
+    metadata: "Metadata",
+) -> tuple[pl.DataFrame, list[str], dict[str, int]]:
+    """Build a DataFrame mapping items/targets to class names and label counts.
+
+    Returns
+    -------
+    labels_df
+        DataFrame with ``item_index``, optionally ``target_index``, and ``class_name``.
+    id_cols
+        Column names to use as join keys (``["item_index"]`` or
+        ``["item_index", "target_index"]``).
+    label_counts
+        Number of items/targets per class name.
+    """
+    index2label = metadata.index2label
+    has_targets = metadata.has_targets()
+
+    label_counts: dict[str, int] = {}
+    for lbl in metadata.class_labels:
+        name = index2label.get(lbl, str(lbl))
+        label_counts[name] = label_counts.get(name, 0) + 1
+
+    if has_targets and hasattr(metadata, "target_data"):
+        td = metadata.target_data.select("item_index", "target_index", "class_label")
+        names = [index2label.get(int(c), str(c)) for c in td["class_label"].to_list()]
+        labels_df = td.with_columns(pl.Series("class_name", names)).select("item_index", "target_index", "class_name")
+        id_cols = ["item_index", "target_index"]
+    else:
+        item_ids = getattr(metadata, "item_indices", list(range(len(metadata.class_labels))))
+        names = [index2label.get(lbl, str(lbl)) for lbl in metadata.class_labels]
+        labels_df = pl.DataFrame({"item_index": item_ids, "class_name": names})
+        id_cols = ["item_index"]
+
+    return labels_df, id_cols, label_counts
+
+
+def _compute_classwise_pivot(
+    target_issues: "pl.DataFrame | None",
+    img_issues: "pl.DataFrame",
+    metadata: "Metadata | None",
+) -> "ClasswisePivotDict | None":
+    """Compute classwise outlier pivot from the globally-detected outlier issues.
+
+    Groups the same target (or image) outlier issues used for the headline
+    count by class, so the per-class rows sum to the headline total.
+
+    Returns a simplified summary with count and % of labels flagged per class.
+    """
+    if metadata is None:
+        return None
+    try:
+        # Use target-level issues for OD datasets, image-level otherwise
+        has_targets = metadata.has_targets()
+        if has_targets:
+            if target_issues is None or target_issues.shape[0] == 0:
+                return None
+            issues_df = target_issues
+        else:
+            if img_issues.shape[0] == 0:
+                return None
+            issues_df = img_issues
+
+        labels_df, id_cols, label_counts = _build_class_labels_df(metadata)
+        total_labels = sum(label_counts.values())
+
+        for col in id_cols:
+            if col in issues_df.columns and issues_df[col].dtype != labels_df[col].dtype:
+                labels_df = labels_df.with_columns(pl.col(col).cast(issues_df[col].dtype))
+
+        # Count unique outlier items/targets per class (not per metric flag)
+        unique_per_class = (
+            issues_df.join(labels_df, on=id_cols, how="left")
+            .select(id_cols + ["class_name"])
+            .unique()
+            .group_by("class_name")
+            .len()
+            .sort("len", descending=True)
+        )
+
+        rows: list[ClasswiseRowDict] = []
+        grand_total = 0
+        for row_dict in unique_per_class.to_dicts():
+            name = str(row_dict.get("class_name", ""))
+            count = int(row_dict.get("len", 0))
+            grand_total += count
+            denom = label_counts.get(name, 0)
+            pct = round((count / denom) * 100, 1) if denom > 0 else 0.0
+            rows.append({"class_name": name, "count": count, "pct": pct})
+
+        total_pct = round((grand_total / total_labels) * 100, 1) if total_labels > 0 else 0.0
+        rows.append({"class_name": "Total", "count": grand_total, "pct": total_pct})
+
+        return ClasswisePivotDict(
+            level="target" if has_targets else "image",
+            rows=rows,
+        )
+    except Exception:  # noqa: BLE001
+        logger.warning("Classwise pivot unavailable", exc_info=True)
+    return None
+
+
+def _compute_embeddings(
+    dataset: AnnotatedDataset[Any],
+    extractor: Callable,
+    run_ctx: CleaningRunContext | None,
+) -> Any:
+    """Compute or load cached embeddings for cluster-based detection."""
+    import time as _time
+
+    logger.info("  [4c] Loading embeddings for cluster-based detection…")
+    _t0 = _time.monotonic()
+    if run_ctx is not None and run_ctx.extractor_config is not None:
+        from dataeval_flow.cache import get_or_compute_embeddings
+
+        embeddings_array = get_or_compute_embeddings(
+            dataset,
+            run_ctx.extractor_config,
+            run_ctx.transforms,
+            run_ctx.batch_size,
+        )
+    else:
+        from dataeval.utils.arrays import flatten_samples, to_numpy
+
+        images = [item[0] if isinstance(item, tuple) else item for item in dataset]
+        embeddings = extractor(images)  # type: ignore[misc]
+        embeddings_array = flatten_samples(to_numpy(embeddings))
+    logger.info("  [4c] Embeddings ready in %.1fs", _time.monotonic() - _t0)
+    return embeddings_array
+
+
+def _merge_outlier_outputs(
+    outliers_eval: Outliers,
+    stats_output: Any,
+    embeddings_array: Any,
+    params: DataCleaningParameters,
+    run_ctx: CleaningRunContext | None,
+) -> Any:
+    """Run cluster-based outlier detection and merge with stats-based results.
+
+    Returns the merged OutliersOutput combining stats-based and cluster-based issues.
+    """
+    import time as _time
+
+    from dataeval.quality import OutliersOutput
+
+    from dataeval_flow.cache import get_or_compute_cluster_result
+
+    logger.info("  [4d] Running cluster-based outlier detection…")
+    _t0 = _time.monotonic()
+    outlier_cluster_result = get_or_compute_cluster_result(
+        embeddings_array,
+        algorithm=params.outlier_cluster_algorithm or "hdbscan",
+        n_clusters=params.outlier_n_clusters,
+        extractor_config=run_ctx.extractor_config if run_ctx else None,
+        transforms=run_ctx.transforms if run_ctx else None,
+    )
+    cluster_outlier_output = outliers_eval.from_clusters(
+        embeddings_array,
+        outlier_cluster_result,
+        cluster_threshold=params.outlier_cluster_threshold,
+    )
+    logger.info("  [4d] Cluster-based outlier detection done in %.1fs", _time.monotonic() - _t0)
+
+    # Merge stats-based + cluster-based issues via concat
+    column_order = ["item_index", "target_index", "metric_name", "metric_value"]
+    stats_issues = stats_output.data()
+    cluster_issues = cluster_outlier_output.data()
+    dfs: list[pl.DataFrame] = []
+    for df in [stats_issues, cluster_issues]:
+        if "target_index" not in df.columns:
+            df = df.with_columns(pl.lit(None, dtype=pl.Int64).alias("target_index"))
+        dfs.append(df.select(column_order))
+    merged_issues = pl.concat(dfs).sort(["item_index", "metric_name"])
+    if merged_issues["target_index"].null_count() == len(merged_issues):
+        merged_issues = merged_issues.drop("target_index")
+    return OutliersOutput(merged_issues)
+
+
+def _run_duplicate_detection(
+    params: DataCleaningParameters,
+    hash_flags: ImageStats,
+    calc_result: Any,
+    embeddings_array: Any | None,
+    run_ctx: CleaningRunContext | None,
+) -> DuplicatesOutput:
+    """Run hash-based and optionally cluster-based duplicate detection.
+
+    Returns the final DuplicatesOutput (merged if cluster-based detection is used).
+    """
+    import time as _time
+
+    logger.info("  [4e] Running duplicate detection…")
+    _t0 = _time.monotonic()
+
+    # Hash-based duplicate detection (always, using cached stats)
+    dup_kwargs: dict[str, object] = {"merge_near_duplicates": params.duplicate_merge_near}
+    if params.duplicate_flags is not None:
+        dup_kwargs["flags"] = hash_flags
+    duplicates_eval = Duplicates(**dup_kwargs)  # type: ignore[arg-type]
+    hash_dup_result = duplicates_eval.from_stats(calc_result)  # type: ignore[arg-type]
+
+    has_dup_cluster = embeddings_array is not None and params.duplicate_cluster_sensitivity is not None
+    if has_dup_cluster:
+        duplicates_result = _merge_duplicate_results(hash_dup_result, embeddings_array, params, run_ctx)
+    else:
+        duplicates_result = hash_dup_result
+
+    logger.info("  [4e] Duplicate detection done in %.1fs", _time.monotonic() - _t0)
+    return duplicates_result
+
+
+def _merge_duplicate_results(
+    hash_dup_result: DuplicatesOutput,
+    embeddings_array: Any,
+    params: DataCleaningParameters,
+    run_ctx: CleaningRunContext | None,
+) -> DuplicatesOutput:
+    """Run cluster-based duplicate detection and merge with hash-based results."""
+    from dataeval_flow.cache import get_or_compute_cluster_result
+
+    dup_cluster_result = get_or_compute_cluster_result(
+        embeddings_array,
+        algorithm=params.duplicate_cluster_algorithm or "hdbscan",
+        n_clusters=params.duplicate_n_clusters,
+        extractor_config=run_ctx.extractor_config if run_ctx else None,
+        transforms=run_ctx.transforms if run_ctx else None,
+    )
+    dup_cluster_eval = Duplicates(
+        merge_near_duplicates=params.duplicate_merge_near,
+        cluster_sensitivity=params.duplicate_cluster_sensitivity,
+    )
+    cluster_dup_result = dup_cluster_eval.from_clusters(dup_cluster_result)
+
+    hash_df = hash_dup_result.data()
+    cluster_df = cluster_dup_result.data()
+    if len(cluster_df) == 0:
+        return hash_dup_result
+
+    # Re-number cluster group_ids to avoid collision with hash group_ids
+    max_group_id = cast(int, hash_df["group_id"].max()) + 1 if len(hash_df) > 0 else 0
+    cluster_df = cluster_df.with_columns(pl.col("group_id") + max_group_id)
+    # Align columns before concat
+    for col in hash_df.columns:
+        if col not in cluster_df.columns:
+            cluster_df = cluster_df.with_columns(pl.lit(None).alias(col).cast(hash_df[col].dtype))
+    for col in cluster_df.columns:
+        if col not in hash_df.columns:
+            hash_df = hash_df.with_columns(pl.lit(None).alias(col).cast(cluster_df[col].dtype))
+    merged_df = pl.concat([hash_df.select(sorted(hash_df.columns)), cluster_df.select(sorted(hash_df.columns))])
+    return DuplicatesOutput(merged_df)
+
+
+def _run_cleaning(
+    dataset: AnnotatedDataset[Any],
+    params: DataCleaningParameters,
+    extractor: Callable | None = None,
+    metadata: Metadata | None = None,
+    run_ctx: CleaningRunContext | None = None,
+) -> DataCleaningRawOutputs:
+    """Run outlier + duplicate detection on dataset.
+
+    Stats are obtained via :func:`~dataeval_flow.cache.get_or_compute_stats`,
+    which transparently handles caching via the :func:`active_cache` context.
+    Evaluators consume pre-computed stats via ``from_stats()``; cluster-based
+    detection (when an extractor is configured) is handled separately via
+    ``from_clusters()`` / ``evaluate()``.
+    """
+    import time as _time
+
+    from dataeval_flow.cache import get_or_compute_stats
+
+    _validate_cluster_params(params, extractor)
+
+    outlier_flags, hash_flags = _resolve_flags(params)
+
+    # --- Centralized stats: cache-aware load / compute / save ---
+    _t0 = _time.monotonic()
+    calc_result = get_or_compute_stats(
+        desired_flags=outlier_flags | hash_flags,
+        dataset=dataset,
+    )
+    logger.info("  [4a] Image stats ready in %.1fs", _time.monotonic() - _t0)
+
+    # --- Outlier detection via from_stats() ---
+    logger.info("  [4b] Running stats-based outlier detection…")
+    _t0 = _time.monotonic()
+    outliers_eval = Outliers(
+        flags=outlier_flags,
+        outlier_threshold=(params.outlier_method, params.outlier_threshold),
+    )
+    outlier_output = outliers_eval.from_stats(calc_result, per_target=True)  # type: ignore[arg-type]
+    logger.info("  [4b] Stats-based outlier detection done in %.1fs", _time.monotonic() - _t0)
+
+    # --- Shared embeddings for cluster-based detection ---
+    has_outlier_cluster = extractor is not None and params.outlier_cluster_threshold is not None
+    has_dup_cluster = extractor is not None and params.duplicate_cluster_sensitivity is not None
+    embeddings_array = None
+
+    if (has_outlier_cluster or has_dup_cluster) and extractor is not None:
+        embeddings_array = _compute_embeddings(dataset, extractor, run_ctx)
+
+    # --- Cluster-based outlier detection ---
+    if has_outlier_cluster and embeddings_array is not None:
+        outlier_output = _merge_outlier_outputs(outliers_eval, outlier_output, embeddings_array, params, run_ctx)
+
+    img_issues, target_issues = _split_outlier_issues(outlier_output.data())
+
+    # --- Classwise outlier pivot ---
+    classwise_pivot = _compute_classwise_pivot(target_issues, img_issues, metadata)
+
+    # --- Duplicate detection ---
+    duplicates_result = _run_duplicate_detection(params, hash_flags, calc_result, embeddings_array, run_ctx)
+
+    # Label stats
+    label_stats: LabelStatsDict = _compute_label_stats(metadata) if metadata else {}  # type: ignore[assignment]
+
+    return DataCleaningRawOutputs(
+        dataset_size=len(dataset),
+        img_outliers=_serialize_outlier_issues(img_issues),
+        target_outliers=_serialize_outlier_issues(target_issues)
+        if target_issues is not None and len(target_issues) > 0
+        else None,
+        duplicates=_serialize_duplicates(duplicates_result),
+        label_stats=label_stats,
+        classwise_outliers=classwise_pivot,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Workflow
+# ---------------------------------------------------------------------------
+
+
+class DataCleaningWorkflow(WorkflowProtocol[DataCleaningMetadata, DataCleaningOutputs]):
+    """Data cleaning workflow using DataEval evaluators."""
+
+    @property
+    def name(self) -> str:
+        """Workflow identifier."""
+        return "data-cleaning"
+
+    @property
+    def description(self) -> str:
+        """Human-readable description."""
+        return "Outlier and duplicate detection for image datasets"
+
+    @property
+    def params_schema(self) -> type[DataCleaningParameters]:
+        """Pydantic model for workflow parameters."""
+        return DataCleaningParameters
+
+    @property
+    def output_schema(self) -> type[DataCleaningOutputs]:
+        """Pydantic model for workflow output."""
+        return DataCleaningOutputs
+
+    def execute(
+        self,
+        context: WorkflowContext,
+        params: BaseModel | None = None,
+    ) -> WorkflowResult[DataCleaningMetadata, DataCleaningOutputs]:
+        """Run data cleaning workflow on dataset."""
+        from dataeval_flow.selection import build_selection
+
+        if not isinstance(context, WorkflowContext):
+            return WorkflowResult(
+                name=self.name,
+                success=False,
+                data=self._empty_outputs(),
+                errors=[f"Expected WorkflowContext, got {type(context).__name__}"],
+                metadata=DataCleaningMetadata(),
+            )
+
+        if params is None:
+            return WorkflowResult(
+                name=self.name,
+                success=False,
+                data=self._empty_outputs(),
+                errors=["DataCleaningParameters required (no defaults per CR-4.14-G-1)"],
+                metadata=DataCleaningMetadata(),
+            )
+
+        if not isinstance(params, DataCleaningParameters):
+            return WorkflowResult(
+                name=self.name,
+                success=False,
+                data=self._empty_outputs(),
+                errors=[f"Expected DataCleaningParameters, got {type(params).__name__}"],
+                metadata=DataCleaningMetadata(),
+            )
+
+        try:
+            import time as _time
+
+            # All arg-type suppressions in this block: MaiteDataset (and Select wrapper)
+            # conforms to DataEval's dataset protocol at runtime via duck typing;
+            # pyright can't verify cross-library structural conformance.
+            from dataeval_flow.cache import selection_repr as _sel_repr
+
+            # Resolve the single dataset context (cleaning is single-dataset)
+            dc = next(iter(context.dataset_contexts.values()))
+
+            # 1. Apply selection if configured
+            dataset = dc.dataset
+            if dc.selection_steps:
+                logger.info("[1/4] Applying selection (%d steps)…", len(dc.selection_steps))
+                _t0 = _time.monotonic()
+                dataset = build_selection(dataset, dc.selection_steps)  # type: ignore[arg-type]
+                logger.info("[1/4] Selection applied in %.1fs", _time.monotonic() - _t0)
+
+            # Compute selection key (shared by metadata + stats caching)
+            sel_key = _sel_repr(dataset)
+
+            # 2. Build extractor if configured
+            extractor = None
+            if dc.extractor:
+                logger.info("[2/4] Building extractor…")
+                _t0 = _time.monotonic()
+                extractor = build_extractor(
+                    extractor_config=dc.extractor,
+                    transforms=dc.transforms,
+                )
+                logger.info("[2/4] Extractor built in %.1fs", _time.monotonic() - _t0)
+
+            # 3–4. Activate cache context so all downstream get_or_compute_*
+            # calls automatically use the cache without explicit threading.
+            run_ctx = CleaningRunContext(
+                extractor_config=dc.extractor,
+                transforms=dc.transforms,
+                batch_size=dc.batch_size,
+            )
+            with contextlib.ExitStack() as stack:
+                if dc.cache is not None:
+                    stack.enter_context(active_cache(dc.cache, sel_key))
+
+                # 3. Build metadata for label stats (cache-aware via active_cache)
+                logger.info("[3/4] Loading metadata…")
+                _t0 = _time.monotonic()
+                metadata = get_or_compute_metadata(dataset)
+                logger.info("[3/4] Metadata ready in %.1fs", _time.monotonic() - _t0)
+
+                # 4. Run cleaning evaluators (cache-aware via active_cache)
+                logger.info("[4/4] Running outlier and duplicate detection on %d items…", len(dataset))
+                _t0 = _time.monotonic()
+                raw = _run_cleaning(
+                    dataset,
+                    params,
+                    extractor,
+                    metadata,  # type: ignore[arg-type]
+                    run_ctx,
+                )
+            logger.info(
+                "[4/4] Detection complete in %.1fs: %d outliers, %d exact dup groups, %d near dup groups",
+                _time.monotonic() - _t0,
+                raw.img_outliers.get("count", 0),
+                len(raw.duplicates.get("items", {}).get("exact", [])),
+                len(raw.duplicates.get("items", {}).get("near", [])),
+            )
+
+            # 5. Generate findings from raw results
+            findings = build_findings(raw, metadata, params.health_thresholds, label_source=dc.label_source)
+
+            # 6. Preparatory mode: compute clean indices (exclude flagged items)
+            result_metadata = DataCleaningMetadata(
+                mode=params.mode,
+                evaluators=["outliers", "duplicates"],
+            )
+            if params.mode == "preparatory":
+                flagged = collect_flagged_indices(raw)
+                all_indices = set(range(raw.dataset_size))
+                clean_indices = sorted(all_indices - flagged)
+                result_metadata.flagged_indices = sorted(flagged)
+                result_metadata.clean_indices = clean_indices
+                result_metadata.removed_count = len(flagged)
+                findings.append(
+                    Reportable(
+                        report_type="key_value",
+                        title="Preparatory Mode",
+                        data={
+                            "brief": f"{len(flagged)} flagged, {len(clean_indices)} retained",
+                            "flagged": len(flagged),
+                            "retained": len(clean_indices),
+                        },
+                        description=(
+                            f"Preparatory mode: {len(flagged)} items flagged for removal, "
+                            f"{len(clean_indices)} items retained."
+                        ),
+                    )
+                )
+
+            # 7. Build report
+            report = DataCleaningReport(
+                summary=f"Data cleaning complete. Dataset: {raw.dataset_size} items. Mode: {params.mode}.",
+                findings=findings,
+            )
+
+            return WorkflowResult(
+                name=self.name,
+                success=True,
+                data=DataCleaningOutputs(raw=raw, report=report),
+                metadata=result_metadata,
+                dataset=dataset,
+            )
+        except Exception as e:
+            logger.exception("Workflow '%s' failed", self.name)
+            return WorkflowResult(
+                name=self.name,
+                success=False,
+                data=self._empty_outputs(),
+                errors=[f"Workflow execution failed: {e}"],
+                metadata=DataCleaningMetadata(),
+            )
+
+    def _empty_outputs(self) -> DataCleaningOutputs:
+        return DataCleaningOutputs(
+            raw=DataCleaningRawOutputs(dataset_size=0),
+            report=DataCleaningReport(summary="Workflow failed", findings=[]),
+        )