churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/temporal/data_preparer.py

@@ -0,0 +1,178 @@
+"""Unified data preparation for leakage-safe ML pipelines.
+
+This module provides the main entry point for preparing raw data for
+ML training with point-in-time correctness. It combines timestamp
+management, snapshot creation, and validation into a single workflow.
+
+Example:
+    >>> from customer_retention.stages.temporal import (
+    ...     ScenarioDetector, UnifiedDataPreparer
+    ... )
+    >>> from datetime import datetime
+    >>>
+    >>> # Detect scenario and get config
+    >>> detector = ScenarioDetector()
+    >>> scenario, config, _ = detector.detect(df, "churn")
+    >>>
+    >>> # Prepare data
+    >>> preparer = UnifiedDataPreparer(output_path, config)
+    >>> prepared_df = preparer.prepare_from_raw(df, "churn", "customer_id")
+    >>>
+    >>> # Create training snapshot
+    >>> snapshot_df, meta = preparer.create_training_snapshot(
+    ...     prepared_df,
+    ...     cutoff_date=datetime(2024, 6, 1)
+    ... )
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+import pandas as pd
+
+from .point_in_time_join import PointInTimeJoiner
+from .snapshot_manager import SnapshotManager
+from .timestamp_manager import TimestampConfig, TimestampManager
+
+
+@dataclass
+class PreparedData:
+    """Container for prepared data with validation results.
+
+    Attributes:
+        unified_df: The prepared DataFrame with timestamps
+        snapshot_metadata: Metadata about the training snapshot
+        timestamp_strategy: Strategy used for timestamp handling
+        validation_report: Report from temporal integrity validation
+    """
+    unified_df: pd.DataFrame
+    snapshot_metadata: dict[str, Any]
+    timestamp_strategy: str
+    validation_report: dict[str, Any]
+
+
+class UnifiedDataPreparer:
+    """Unified entry point for preparing data with temporal correctness.
+
+    The UnifiedDataPreparer combines timestamp management, data validation,
+    and snapshot creation into a single workflow. It ensures all data
+    passes through proper point-in-time handling before being used for
+    training or inference.
+
+    Example:
+        >>> preparer = UnifiedDataPreparer(output_path, config)
+        >>> df = preparer.prepare_from_raw(df, "churn", "customer_id")
+        >>> snapshot_df, meta = preparer.create_training_snapshot(df, cutoff)
+    """
+
+    def __init__(self, output_path: Path, timestamp_config: TimestampConfig, storage=None):
+        """Initialize the UnifiedDataPreparer.
+
+        Args:
+            output_path: Directory for output files (unified data, snapshots)
+            timestamp_config: Configuration for timestamp handling
+            storage: Optional DeltaStorage backend
+        """
+        self.output_path = Path(output_path)
+        self.timestamp_manager = TimestampManager(timestamp_config)
+        self.snapshot_manager = SnapshotManager(output_path, storage=storage)
+        self.timestamp_config = timestamp_config
+        self.pit_joiner = PointInTimeJoiner()
+        self.storage = storage or _get_storage()
+
+    def prepare_from_raw(
+        self, df: pd.DataFrame, target_column: str, entity_column: str
+    ) -> pd.DataFrame:
+        df = self.timestamp_manager.ensure_timestamps(df)
+        self.timestamp_manager.validate_point_in_time(df)
+
+        df = df.rename(columns={target_column: "target", entity_column: "entity_id"})
+
+        unified_dir = self.output_path / "unified" / "unified_dataset"
+        unified_dir.parent.mkdir(parents=True, exist_ok=True)
+        if self.storage and len(df) > 0:
+            self.storage.write(df, str(unified_dir))
+        else:
+            parquet_path = self.output_path / "unified" / "unified_dataset.parquet"
+            df.to_parquet(parquet_path, index=False)
+
+        return df
+
+    def create_training_snapshot(
+        self, df: pd.DataFrame, cutoff_date: datetime, snapshot_name: str = "training",
+        timestamp_series: Optional[pd.Series] = None,
+    ) -> tuple[pd.DataFrame, dict[str, Any]]:
+        metadata = self.snapshot_manager.create_snapshot(
+            df=df, cutoff_date=cutoff_date, target_column="target",
+            snapshot_name=snapshot_name, timestamp_series=timestamp_series,
+        )
+        snapshot_df, _ = self.snapshot_manager.load_snapshot(metadata.snapshot_id)
+        return snapshot_df, self._metadata_to_dict(metadata)
+
+    def load_for_eda(self, snapshot_id: str) -> pd.DataFrame:
+        df, metadata = self.snapshot_manager.load_snapshot(snapshot_id)
+        print(f"Loaded snapshot: {snapshot_id}")
+        print(f"  Rows: {metadata.row_count:,}")
+        print(f"  Cutoff: {metadata.cutoff_date}")
+        print(f"  Hash: {metadata.data_hash}")
+        return df
+
+    def load_for_inference(self, df: pd.DataFrame, as_of_date: Optional[datetime] = None) -> pd.DataFrame:
+        as_of_date = as_of_date or datetime.now()
+        df = self.timestamp_manager.ensure_timestamps(df)
+        df = df[df["feature_timestamp"] <= as_of_date].copy()
+        df["label_available_flag"] = False
+        df["label_timestamp"] = as_of_date
+        return df
+
+    def prepare_with_validation(
+        self, df: pd.DataFrame, target_column: str, entity_column: str, cutoff_date: datetime
+    ) -> PreparedData:
+        unified_df = self.prepare_from_raw(df, target_column, entity_column)
+        validation_report = self.pit_joiner.validate_temporal_integrity(unified_df)
+        snapshot_df, snapshot_metadata = self.create_training_snapshot(unified_df, cutoff_date)
+
+        return PreparedData(
+            unified_df=snapshot_df,
+            snapshot_metadata=snapshot_metadata,
+            timestamp_strategy=self.timestamp_config.strategy.value,
+            validation_report=validation_report,
+        )
+
+    def list_available_snapshots(self) -> list[str]:
+        return self.snapshot_manager.list_snapshots()
+
+    def get_snapshot_summary(self, snapshot_id: str) -> dict[str, Any]:
+        _, metadata = self.snapshot_manager.load_snapshot(snapshot_id)
+        return {
+            "snapshot_id": metadata.snapshot_id,
+            "version": metadata.version,
+            "created_at": metadata.created_at.isoformat(),
+            "cutoff_date": metadata.cutoff_date.isoformat(),
+            "row_count": metadata.row_count,
+            "feature_count": len(metadata.feature_columns),
+            "data_hash": metadata.data_hash,
+        }
+
+    def _metadata_to_dict(self, metadata) -> dict[str, Any]:
+        return {
+            "snapshot_id": metadata.snapshot_id,
+            "version": metadata.version,
+            "created_at": metadata.created_at.isoformat(),
+            "cutoff_date": metadata.cutoff_date.isoformat(),
+            "row_count": metadata.row_count,
+            "column_count": metadata.column_count,
+            "data_hash": metadata.data_hash,
+            "feature_columns": metadata.feature_columns,
+            "target_column": metadata.target_column,
+        }
+
+
+def _get_storage():
+    try:
+        from customer_retention.integrations.adapters.factory import get_delta
+        return get_delta(force_local=True)
+    except ImportError:
+        return None

customer_retention/stages/temporal/point_in_time_join.py

@@ -0,0 +1,134 @@
+"""Point-in-time correct joins for feature engineering.
+
+This module provides utilities for joining feature tables while maintaining
+temporal correctness. It ensures that features from the future are never
+used to predict past events, preventing data leakage.
+
+Key functions:
+    - join_features: Join feature tables with PIT correctness
+    - asof_join: Pandas merge_asof wrapper for temporal joins
+    - validate_no_future_data: Check for temporal violations
+    - validate_temporal_integrity: Comprehensive integrity check
+
+Example:
+    >>> from customer_retention.stages.temporal import PointInTimeJoiner
+    >>> joiner = PointInTimeJoiner()
+    >>> merged = joiner.join_features(
+    ...     base_df=customers,
+    ...     feature_df=transactions_agg,
+    ...     entity_key="customer_id"
+    ... )
+"""
+
+from typing import Any
+
+import pandas as pd
+
+
+class PointInTimeJoiner:
+    """Utility class for point-in-time correct feature joins.
+
+    The PointInTimeJoiner ensures that when joining feature tables,
+    only features that were available at the time of the base record
+    are included. This prevents temporal leakage.
+
+    Example:
+        >>> joiner = PointInTimeJoiner()
+        >>> # Only features from before base_df's feature_timestamp are included
+        >>> merged = joiner.join_features(base_df, feature_df, "customer_id")
+    """
+    @staticmethod
+    def join_features(
+        base_df: pd.DataFrame, feature_df: pd.DataFrame, entity_key: str,
+        base_timestamp_col: str = "feature_timestamp", feature_timestamp_col: str = "feature_timestamp"
+    ) -> pd.DataFrame:
+        if base_timestamp_col not in base_df.columns:
+            raise ValueError(f"Base df missing timestamp column: {base_timestamp_col}")
+        if feature_timestamp_col not in feature_df.columns:
+            raise ValueError(f"Feature df missing timestamp column: {feature_timestamp_col}")
+
+        feature_df = feature_df.rename(columns={feature_timestamp_col: "_feature_ts"})
+        merged = base_df.merge(feature_df, on=entity_key, how="left")
+        valid_mask = merged["_feature_ts"] <= merged[base_timestamp_col]
+
+        merged = (
+            merged[valid_mask]
+            .sort_values([entity_key, "_feature_ts"])
+            .groupby(entity_key)
+            .last()
+            .reset_index()
+            .drop(columns=["_feature_ts"])
+        )
+        return merged
+
+    @staticmethod
+    def validate_no_future_data(
+        df: pd.DataFrame, reference_timestamp_col: str, check_columns: list[str]
+    ) -> dict[str, Any]:
+        issues: dict[str, Any] = {}
+        for col in check_columns:
+            if pd.api.types.is_datetime64_any_dtype(df[col]):
+                future_rows = df[df[col] > df[reference_timestamp_col]]
+                if len(future_rows) > 0:
+                    issues[col] = {
+                        "violation_count": len(future_rows),
+                        "example_ids": future_rows.index[:5].tolist()
+                    }
+        return issues
+
+    @staticmethod
+    def asof_join(
+        left_df: pd.DataFrame, right_df: pd.DataFrame, entity_key: str,
+        left_time_col: str, right_time_col: str, direction: str = "backward"
+    ) -> pd.DataFrame:
+        left_sorted = left_df.sort_values(left_time_col).reset_index(drop=True)
+        right_sorted = right_df.sort_values(right_time_col).reset_index(drop=True)
+
+        return pd.merge_asof(
+            left_sorted, right_sorted, left_on=left_time_col, right_on=right_time_col,
+            by=entity_key, direction=direction
+        )
+
+    @staticmethod
+    def create_training_labels(
+        df: pd.DataFrame, label_column: str, entity_key: str = "entity_id"
+    ) -> pd.DataFrame:
+        if "label_available_flag" not in df.columns:
+            raise ValueError("DataFrame must have label_available_flag column")
+
+        training_df = df[df["label_available_flag"] == True].copy()
+        if label_column not in training_df.columns:
+            raise ValueError(f"Label column '{label_column}' not found")
+
+        return training_df[[entity_key, "feature_timestamp", "label_timestamp", label_column]]
+
+    @staticmethod
+    def validate_temporal_integrity(df: pd.DataFrame) -> dict[str, Any]:
+        report = {"valid": True, "issues": []}
+
+        if "feature_timestamp" in df.columns and "label_timestamp" in df.columns:
+            violations = df[df["feature_timestamp"] > df["label_timestamp"]]
+            if len(violations) > 0:
+                report["valid"] = False
+                report["issues"].append({
+                    "type": "feature_after_label",
+                    "count": len(violations),
+                    "message": f"{len(violations)} rows have feature_timestamp > label_timestamp"
+                })
+
+        datetime_cols = df.select_dtypes(include=["datetime64"]).columns
+        for col in datetime_cols:
+            if col in ["feature_timestamp", "label_timestamp"]:
+                continue
+            if "feature_timestamp" in df.columns:
+                future = df[df[col] > df["feature_timestamp"]]
+                if len(future) > 0:
+                    report["valid"] = False
+                    report["issues"].append({
+                        "type": "future_data",
+                        "column": col,
+                        "count": len(future),
+                        "message": f"Column {col} has {len(future)} values after feature_timestamp"
+                    })
+
+        return report

customer_retention/stages/temporal/point_in_time_registry.py

@@ -0,0 +1,148 @@
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class DatasetSnapshot:
+    dataset_name: str
+    snapshot_id: str
+    cutoff_date: datetime
+    source_path: str
+    row_count: int
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict:
+        return {
+            "dataset_name": self.dataset_name,
+            "snapshot_id": self.snapshot_id,
+            "cutoff_date": self.cutoff_date.isoformat(),
+            "source_path": self.source_path,
+            "row_count": self.row_count,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DatasetSnapshot":
+        return cls(
+            dataset_name=data["dataset_name"],
+            snapshot_id=data["snapshot_id"],
+            cutoff_date=datetime.fromisoformat(data["cutoff_date"]),
+            source_path=data["source_path"],
+            row_count=data["row_count"],
+            created_at=datetime.fromisoformat(data["created_at"]),
+        )
+
+
+@dataclass
+class ConsistencyReport:
+    is_consistent: bool
+    reference_cutoff: Optional[datetime]
+    inconsistent_datasets: list[str]
+    message: str
+
+
+class PointInTimeRegistry:
+    REGISTRY_FILENAME = "point_in_time_registry.json"
+
+    def __init__(self, output_dir: Path):
+        self.output_dir = Path(output_dir)
+        self.registry_path = self.output_dir / self.REGISTRY_FILENAME
+        self.snapshots: dict[str, DatasetSnapshot] = {}
+        self._load()
+
+    def _load(self) -> None:
+        if self.registry_path.exists():
+            with open(self.registry_path) as f:
+                data = json.load(f)
+                self.snapshots = {
+                    name: DatasetSnapshot.from_dict(snap) for name, snap in data.get("snapshots", {}).items()
+                }
+
+    def _save(self) -> None:
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        data = {"snapshots": {name: snap.to_dict() for name, snap in self.snapshots.items()}}
+        with open(self.registry_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def get_reference_cutoff(self) -> Optional[datetime]:
+        if not self.snapshots:
+            return None
+        return next(iter(self.snapshots.values())).cutoff_date
+
+    def check_consistency(self) -> ConsistencyReport:
+        if not self.snapshots:
+            return ConsistencyReport(
+                is_consistent=True, reference_cutoff=None, inconsistent_datasets=[], message="No datasets registered"
+            )
+
+        reference_cutoff = self.get_reference_cutoff()
+        inconsistent = [
+            name for name, snap in self.snapshots.items() if snap.cutoff_date.date() != reference_cutoff.date()
+        ]
+
+        if inconsistent:
+            return ConsistencyReport(
+                is_consistent=False,
+                reference_cutoff=reference_cutoff,
+                inconsistent_datasets=inconsistent,
+                message=f"Inconsistent cutoff dates detected. Reference: {reference_cutoff.date()}. "
+                f"Out of sync: {', '.join(inconsistent)}. Re-run exploration for these datasets.",
+            )
+
+        return ConsistencyReport(
+            is_consistent=True,
+            reference_cutoff=reference_cutoff,
+            inconsistent_datasets=[],
+            message=f"All {len(self.snapshots)} datasets use consistent cutoff: {reference_cutoff.date()}",
+        )
+
+    def validate_cutoff(self, proposed_cutoff: datetime) -> tuple[bool, str]:
+        reference = self.get_reference_cutoff()
+        if reference is None:
+            return True, "First dataset - cutoff date will be set as reference"
+
+        if proposed_cutoff.date() != reference.date():
+            return False, (
+                f"Cutoff date mismatch. Existing datasets use {reference.date()}. "
+                f"Proposed: {proposed_cutoff.date()}. Change will require re-exploration of all datasets."
+            )
+
+        return True, f"Cutoff date matches reference: {reference.date()}"
+
+    def register_snapshot(
+        self, dataset_name: str, snapshot_id: str, cutoff_date: datetime, source_path: str, row_count: int
+    ) -> DatasetSnapshot:
+        snapshot = DatasetSnapshot(
+            dataset_name=dataset_name,
+            snapshot_id=snapshot_id,
+            cutoff_date=cutoff_date,
+            source_path=source_path,
+            row_count=row_count,
+        )
+        self.snapshots[dataset_name] = snapshot
+        self._save()
+        return snapshot
+
+    def get_snapshot(self, dataset_name: str) -> Optional[DatasetSnapshot]:
+        return self.snapshots.get(dataset_name)
+
+    def list_snapshots(self) -> list[DatasetSnapshot]:
+        return list(self.snapshots.values())
+
+    def get_out_of_sync_datasets(self, reference_cutoff: datetime) -> list[str]:
+        return [name for name, snap in self.snapshots.items() if snap.cutoff_date.date() != reference_cutoff.date()]
+
+    def clear_registry(self) -> None:
+        self.snapshots = {}
+        if self.registry_path.exists():
+            self.registry_path.unlink()
+
+    def update_cutoff_for_all(self, new_cutoff: datetime) -> list[str]:
+        affected = list(self.snapshots.keys())
+        for name in affected:
+            self.snapshots[name].cutoff_date = new_cutoff
+        self._save()
+        return affected

customer_retention/stages/temporal/scenario_detector.py

@@ -0,0 +1,163 @@
+"""Automatic timestamp scenario detection for ML datasets.
+
+This module provides high-level scenario detection that determines the
+appropriate timestamp strategy for a given dataset. It wraps the
+TimestampDiscoveryEngine and translates its results into actionable
+configurations.
+
+Scenarios:
+    - production: Dataset has explicit feature and label timestamps
+    - production_derived: Timestamps exist but need derivation
+    - partial: Only feature timestamp found, label derived from window
+    - derived: Timestamps can be computed from other columns (e.g., tenure)
+    - synthetic: No temporal information, must use synthetic timestamps
+
+Example:
+    >>> from customer_retention.stages.temporal import ScenarioDetector
+    >>> detector = ScenarioDetector()
+    >>> scenario, config, discovery = detector.detect(df, "churn")
+    >>> print(f"Scenario: {scenario}")  # e.g., "production"
+    >>> print(f"Strategy: {config.strategy.value}")  # e.g., "production"
+"""
+
+from datetime import datetime
+from typing import Optional
+
+import pandas as pd
+
+from .timestamp_discovery import TimestampDiscoveryEngine, TimestampDiscoveryResult
+from .timestamp_manager import TimestampConfig, TimestampStrategy
+
+
+class ScenarioDetector:
+    """Detects the timestamp scenario for a dataset and provides configuration.
+
+    The ScenarioDetector analyzes a dataset to determine which timestamp
+    handling strategy is appropriate, returning both a human-readable scenario
+    name and a TimestampConfig ready for use with TimestampManager.
+
+    Example:
+        >>> detector = ScenarioDetector()
+        >>> scenario, config, result = detector.detect(df, "churn")
+        >>> # Use config with TimestampManager
+        >>> from customer_retention.stages.temporal import TimestampManager
+        >>> manager = TimestampManager(config)
+        >>> df_with_timestamps = manager.ensure_timestamps(df)
+    """
+    def __init__(self, reference_date: Optional[datetime] = None, label_window_days: int = 180):
+        self.label_window_days = label_window_days
+        self.discovery_engine = TimestampDiscoveryEngine(reference_date, label_window_days)
+
+    def detect(
+        self, df: pd.DataFrame, target_column: str
+    ) -> tuple[str, TimestampConfig, TimestampDiscoveryResult]:
+        discovery_result = self.discovery_engine.discover(df, target_column)
+
+        has_explicit_feature = discovery_result.feature_timestamp and not discovery_result.feature_timestamp.is_derived
+        has_explicit_label = discovery_result.label_timestamp and not discovery_result.label_timestamp.is_derived
+        label_derived_from_feature = (
+            discovery_result.label_timestamp and
+            discovery_result.label_timestamp.is_derived and
+            discovery_result.feature_timestamp and
+            discovery_result.feature_timestamp.column_name in discovery_result.label_timestamp.source_columns
+        )
+
+        if has_explicit_feature and has_explicit_label:
+            return self._configure_production_scenario(discovery_result)
+        elif has_explicit_feature and label_derived_from_feature:
+            return self._configure_partial_scenario(discovery_result)
+        elif discovery_result.feature_timestamp and discovery_result.label_timestamp:
+            return self._configure_production_scenario(discovery_result)
+        elif discovery_result.feature_timestamp:
+            return self._configure_partial_scenario(discovery_result)
+        elif discovery_result.derivable_options:
+            return self._configure_derivable_scenario(discovery_result)
+        return self._configure_synthetic_scenario(discovery_result)
+
+    def _configure_production_scenario(
+        self, result: TimestampDiscoveryResult
+    ) -> tuple[str, TimestampConfig, TimestampDiscoveryResult]:
+        feature_col = result.feature_timestamp.column_name if result.feature_timestamp else None
+        label_col = result.label_timestamp.column_name if result.label_timestamp else None
+
+        derivation_config = {}
+        if result.feature_timestamp and result.feature_timestamp.is_derived:
+            derivation_config["feature_derivation"] = {
+                "formula": result.feature_timestamp.derivation_formula,
+                "sources": result.feature_timestamp.source_columns,
+            }
+        if result.label_timestamp and result.label_timestamp.is_derived:
+            derivation_config["label_derivation"] = {
+                "formula": result.label_timestamp.derivation_formula,
+                "sources": result.label_timestamp.source_columns,
+            }
+
+        config = TimestampConfig(
+            strategy=TimestampStrategy.PRODUCTION,
+            feature_timestamp_column=feature_col if not (result.feature_timestamp and result.feature_timestamp.is_derived) else None,
+            label_timestamp_column=label_col if not (result.label_timestamp and result.label_timestamp.is_derived) else None,
+            observation_window_days=self.label_window_days,
+            derivation_config=derivation_config if derivation_config else None,
+        )
+
+        scenario = "production" if not derivation_config else "production_derived"
+        return (scenario, config, result)
+
+    def _configure_partial_scenario(
+        self, result: TimestampDiscoveryResult
+    ) -> tuple[str, TimestampConfig, TimestampDiscoveryResult]:
+        config = TimestampConfig(
+            strategy=TimestampStrategy.PRODUCTION,
+            feature_timestamp_column=result.feature_timestamp.column_name if result.feature_timestamp else None,
+            label_timestamp_column=None,
+            observation_window_days=self.label_window_days,
+            derive_label_from_feature=True,
+        )
+        return ("partial", config, result)
+
+    def _configure_derivable_scenario(
+        self, result: TimestampDiscoveryResult
+    ) -> tuple[str, TimestampConfig, TimestampDiscoveryResult]:
+        best_derivable = max(result.derivable_options, key=lambda c: c.confidence)
+
+        config = TimestampConfig(
+            strategy=TimestampStrategy.DERIVED,
+            derivation_config={
+                "feature_derivation": {
+                    "formula": best_derivable.derivation_formula,
+                    "sources": best_derivable.source_columns,
+                }
+            },
+            observation_window_days=self.label_window_days,
+        )
+        return ("derived", config, result)
+
+    def _configure_synthetic_scenario(
+        self, result: TimestampDiscoveryResult
+    ) -> tuple[str, TimestampConfig, TimestampDiscoveryResult]:
+        config = TimestampConfig(
+            strategy=TimestampStrategy.SYNTHETIC_INDEX,
+            observation_window_days=self.label_window_days,
+            synthetic_base_date="2024-01-01",
+        )
+        return ("synthetic", config, result)
+
+    def get_scenario_summary(self, scenario: str, config: TimestampConfig, result: TimestampDiscoveryResult) -> dict:
+        return {
+            "scenario": scenario,
+            "strategy": config.strategy.value,
+            "feature_timestamp_column": config.feature_timestamp_column,
+            "label_timestamp_column": config.label_timestamp_column,
+            "observation_window_days": config.observation_window_days,
+            "requires_derivation": config.derivation_config is not None,
+            "requires_synthetic": result.requires_synthetic,
+            "recommendation": result.recommendation,
+            "datetime_columns_found": result.discovery_report.get("datetime_columns_found", 0),
+            "derivable_timestamps_found": result.discovery_report.get("derivable_timestamps_found", 0),
+        }
+
+
+def auto_detect_and_configure(df: pd.DataFrame, target_column: str) -> tuple[str, TimestampConfig]:
+    detector = ScenarioDetector()
+    scenario, config, _ = detector.detect(df, target_column)
+    return scenario, config