churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/profiling/temporal_quality_checks.py

@@ -0,0 +1,278 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+from customer_retention.core.compat import DataFrame, pd
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class TemporalQualityResult:
+    check_id: str
+    check_name: str
+    passed: bool
+    severity: Severity
+    message: str
+    details: dict = field(default_factory=dict)
+    recommendation: Optional[str] = None
+    duplicate_count: int = 0
+    gap_count: int = 0
+    max_gap_days: float = 0
+    future_count: int = 0
+    ambiguous_count: int = 0
+
+
+class TemporalQualityCheck:
+    def __init__(self, check_id: str, check_name: str, severity: Severity):
+        self.check_id = check_id
+        self.check_name = check_name
+        self.severity = severity
+
+    def run(self, df: DataFrame) -> TemporalQualityResult:
+        raise NotImplementedError
+
+
+class DuplicateEventCheck(TemporalQualityCheck):
+    def __init__(self, entity_column: str, time_column: str):
+        super().__init__("TQ001", "Duplicate Events", Severity.MEDIUM)
+        self.entity_column = entity_column
+        self.time_column = time_column
+
+    def run(self, df: DataFrame) -> TemporalQualityResult:
+        if len(df) == 0:
+            return self._pass_result("No data to check")
+
+        duplicates = df.duplicated(subset=[self.entity_column, self.time_column], keep=False)
+        duplicate_count = duplicates.sum() - df[duplicates].groupby([self.entity_column, self.time_column]).ngroups
+
+        if duplicate_count > 0:
+            examples = df[duplicates].head(10)[[self.entity_column, self.time_column]].to_dict('records')
+            return TemporalQualityResult(
+                check_id=self.check_id, check_name=self.check_name, passed=False, severity=self.severity,
+                message=f"Found {duplicate_count} duplicate events (same entity + timestamp)",
+                details={"duplicate_examples": examples, "affected_entities": df[duplicates][self.entity_column].nunique()},
+                recommendation="Review duplicates - may need deduplication logic", duplicate_count=duplicate_count)
+
+        return self._pass_result("No duplicate events found")
+
+    def _pass_result(self, message: str) -> TemporalQualityResult:
+        return TemporalQualityResult(
+            check_id=self.check_id, check_name=self.check_name, passed=True,
+            severity=Severity.INFO, message=message, duplicate_count=0)
+
+
+class TemporalGapCheck(TemporalQualityCheck):
+    FREQ_TO_DAYS = {"D": 1, "W": 7, "M": 30, "Q": 90, "Y": 365, "H": 1/24, "T": 1/1440, "min": 1/1440}
+
+    def __init__(self, time_column: str, expected_frequency: str = "D", max_gap_multiple: float = 3.0):
+        super().__init__("TQ002", "Temporal Gaps", Severity.MEDIUM)
+        self.time_column = time_column
+        self.expected_frequency = expected_frequency
+        self.max_gap_multiple = max_gap_multiple
+
+    def run(self, df: DataFrame) -> TemporalQualityResult:
+        if len(df) < 2:
+            return self._pass_result("Insufficient data to check gaps")
+
+        time_col = pd.to_datetime(df.sort_values(self.time_column)[self.time_column])
+        diffs_days = time_col.diff().dropna().dt.total_seconds() / 86400
+        expected_days = self.FREQ_TO_DAYS.get(self.expected_frequency, 1)
+        threshold_days = expected_days * self.max_gap_multiple
+
+        large_gaps = diffs_days[diffs_days > threshold_days]
+        max_gap = float(diffs_days.max()) if len(diffs_days) > 0 else 0
+
+        if len(large_gaps) > 0:
+            return TemporalQualityResult(
+                check_id=self.check_id, check_name=self.check_name, passed=False, severity=self.severity,
+                message=f"Found {len(large_gaps)} gaps exceeding {threshold_days:.1f} days",
+                details={"threshold_days": threshold_days, "expected_frequency": self.expected_frequency,
+                         "gap_locations": large_gaps.index.tolist()[:10]},
+                recommendation="Investigate data collection gaps or missing data",
+                gap_count=len(large_gaps), max_gap_days=max_gap)
+
+        return TemporalQualityResult(
+            check_id=self.check_id, check_name=self.check_name, passed=True, severity=Severity.INFO,
+            message="No significant temporal gaps detected", gap_count=0, max_gap_days=max_gap)
+
+    def _pass_result(self, message: str) -> TemporalQualityResult:
+        return TemporalQualityResult(
+            check_id=self.check_id, check_name=self.check_name, passed=True,
+            severity=Severity.INFO, message=message, gap_count=0, max_gap_days=0)
+
+
+class FutureDateCheck(TemporalQualityCheck):
+    def __init__(self, time_column: str, reference_date: Optional[pd.Timestamp] = None):
+        super().__init__("TQ003", "Future Dates", Severity.HIGH)
+        self.time_column = time_column
+        self.reference_date = reference_date or pd.Timestamp.now()
+
+    def run(self, df: DataFrame) -> TemporalQualityResult:
+        if len(df) == 0:
+            return self._pass_result("No data to check")
+
+        time_col = pd.to_datetime(df[self.time_column])
+        future_mask = time_col > self.reference_date
+        future_count = future_mask.sum()
+
+        if future_count > 0:
+            return TemporalQualityResult(
+                check_id=self.check_id, check_name=self.check_name, passed=False, severity=self.severity,
+                message=f"Found {future_count} events with future dates",
+                details={"reference_date": str(self.reference_date),
+                         "future_date_examples": [str(d) for d in time_col[future_mask].head(10).tolist()]},
+                recommendation="Review data entry or timestamp handling", future_count=future_count)
+
+        return self._pass_result("No future dates detected")
+
+    def _pass_result(self, message: str) -> TemporalQualityResult:
+        return TemporalQualityResult(
+            check_id=self.check_id, check_name=self.check_name, passed=True,
+            severity=Severity.INFO, message=message, future_count=0)
+
+
+class EventOrderCheck(TemporalQualityCheck):
+    def __init__(self, entity_column: str, time_column: str):
+        super().__init__("TQ004", "Event Ordering", Severity.LOW)
+        self.entity_column = entity_column
+        self.time_column = time_column
+
+    def run(self, df: DataFrame) -> TemporalQualityResult:
+        if len(df) < 2:
+            return self._pass_result("Insufficient data to check ordering")
+
+        df_check = df.assign(_parsed_time=pd.to_datetime(df[self.time_column]))
+        collision_counts = df_check.groupby([self.entity_column, "_parsed_time"]).size()
+        ambiguous = collision_counts[collision_counts > 1]
+        ambiguous_count = ambiguous.sum() - len(ambiguous)
+
+        if ambiguous_count > 0:
+            return TemporalQualityResult(
+                check_id=self.check_id, check_name=self.check_name, passed=True, severity=Severity.LOW,
+                message=f"{ambiguous_count} events have ambiguous ordering (same timestamp)",
+                details={"collision_groups": len(ambiguous), "total_ambiguous_events": int(ambiguous.sum())},
+                recommendation="Consider adding sequence numbers for same-timestamp events",
+                ambiguous_count=ambiguous_count)
+
+        return self._pass_result("Event ordering is unambiguous")
+
+    def _pass_result(self, message: str) -> TemporalQualityResult:
+        return TemporalQualityResult(
+            check_id=self.check_id, check_name=self.check_name, passed=True,
+            severity=Severity.INFO, message=message, ambiguous_count=0)
+
+
+@dataclass
+class TemporalQualityScore:
+    score: float
+    grade: str
+    check_scores: list
+    passed: int
+    total: int
+
+    @property
+    def grade_emoji(self) -> str:
+        return {"A": "🏆", "B": "✅", "C": "⚠️", "D": "❌"}.get(self.grade, "")
+
+    @property
+    def grade_message(self) -> str:
+        return {"A": "Excellent - ready for feature engineering", "B": "Good - minor issues, proceed with caution",
+                "C": "Fair - address issues before proceeding", "D": "Poor - significant investigation needed"}.get(self.grade, "")
+
+
+class TemporalQualityReporter:
+    ML_IMPACTS = {
+        "TQ001": {"impacts": [("Event counts", "Inflated metrics"), ("Aggregations", "Skewed"), ("Sequences", "Artificial patterns")],
+                  "fix": "df.drop_duplicates(subset=[entity, time], keep='first')"},
+        "TQ002": {"impacts": [("Rolling features", "Low during gaps"), ("Recency", "Inflated"), ("Seasonality", "Distorted")],
+                  "fix": "Document gaps; add df['has_gap'] indicator"},
+        "TQ003": {"impacts": [("Data leakage", "Future in training"), ("Time splits", "Broken"), ("Recency", "Negative values")],
+                  "fix": "df = df[df[time_col] <= reference_date]"},
+        "TQ004": {"impacts": [("Sequences", "Undefined order"), ("State tracking", "Ambiguous"), ("Lags", "Unclear")],
+                  "fix": "Add sequence: df['seq'] = df.groupby(entity).cumcount()"}
+    }
+
+    def __init__(self, results: list, total_rows: int):
+        self.results = results
+        self.total_rows = total_rows
+        self._calculate_scores()
+
+    def _calculate_scores(self):
+        self.check_scores = []
+        for r in self.results:
+            issue_count = r.duplicate_count or r.gap_count or r.future_count or r.ambiguous_count or 0
+            score = self._score_from_issues(issue_count, self.total_rows)
+            pct = (issue_count / self.total_rows * 100) if self.total_rows > 0 else 0
+            self.check_scores.append({
+                "check_id": r.check_id, "name": r.check_name, "result": r,
+                "issues": issue_count, "pct": pct, "score": score, "contribution": score * 0.25})
+        self.quality_score = sum(c["contribution"] for c in self.check_scores)
+        self.grade = "A" if self.quality_score >= 90 else "B" if self.quality_score >= 75 else "C" if self.quality_score >= 60 else "D"
+        self.passed = sum(1 for r in self.results if r.passed)
+
+    def _score_from_issues(self, issues: int, total: int) -> float:
+        if total == 0 or issues == 0:
+            return 100.0
+        pct = (issues / total) * 100
+        if pct < 0.1:
+            return 99.0
+        if pct < 1.0:
+            return 95.0 - (pct * 5)
+        if pct < 5.0:
+            return 90.0 - (pct * 4)
+        if pct < 20.0:
+            return 70.0 - (pct * 2)
+        return max(0, 30.0 - pct)
+
+    def get_score(self) -> TemporalQualityScore:
+        return TemporalQualityScore(
+            score=self.quality_score, grade=self.grade,
+            check_scores=self.check_scores, passed=self.passed, total=len(self.results))
+
+    def print_results(self):
+        severity_icons = {Severity.HIGH: "🔴", Severity.MEDIUM: "🟠", Severity.LOW: "🟡", Severity.INFO: "🔵"}
+        print("=" * 70 + "\nTEMPORAL QUALITY CHECK RESULTS\n" + "=" * 70)
+        print(f"\n📋 Summary: {self.passed}/{len(self.results)} checks passed\n")
+
+        for c in self.check_scores:
+            r = c["result"]
+            print(f"{'✅' if r.passed else '❌'} [{r.check_id}] {r.check_name}")
+            print(f"   {severity_icons.get(r.severity, '⚪')} Severity: {r.severity.value} | {r.message}")
+
+            if c["issues"] > 0 and r.check_id in self.ML_IMPACTS:
+                impact = self.ML_IMPACTS[r.check_id]
+                print(f"\n   📊 Impact ({c['issues']:,} issues = {c['pct']:.2f}%):")
+                for area, problem in impact["impacts"]:
+                    print(f"      • {area}: {problem}")
+                print(f"   🛠️ Fix: {impact['fix']}")
+            elif r.recommendation:
+                print(f"   💡 {r.recommendation}")
+            print()
+
+    def print_score(self, bar_width: int = 40):
+        grade_emoji = {"A": "🏆", "B": "✅", "C": "⚠️", "D": "❌"}[self.grade]
+        print("\n" + "=" * 70)
+        print(f"QUALITY SCORE: {self.quality_score:.0f}/100  {grade_emoji} Grade {self.grade}\n" + "=" * 70)
+
+        filled = int((self.quality_score / 100) * bar_width)
+        print(f"\n  Total: [{'█' * filled}{'░' * (bar_width - filled)}] {self.quality_score:.0f}%\n")
+
+        for c in self.check_scores:
+            filled = int((c["contribution"] / 25) * 20)
+            bar = f"[{'█' * filled}{'░' * (20 - filled)}] {c['contribution']:.1f}/25"
+            status = "✓" if c["issues"] == 0 else "△" if c["pct"] < 1 else "✗"
+            issues_str = f"{c['issues']:,} issues" if c["issues"] > 0 else "no issues"
+            print(f"  {status} {c['name']:<18} {bar}  ({issues_str})")
+
+        grade_messages = {"A": "Excellent - ready for feature engineering", "B": "Good - minor issues, proceed with caution",
+                         "C": "Fair - address issues before proceeding", "D": "Poor - significant investigation needed"}
+        print(f"\n  Grade {self.grade}: {grade_messages[self.grade]}")
+
+    def to_dict(self) -> dict:
+        return {
+            "temporal_quality_score": self.quality_score, "temporal_quality_grade": self.grade,
+            "checks_passed": self.passed, "checks_total": len(self.results),
+            "issues": {
+                "duplicate_events": self.results[0].duplicate_count if len(self.results) > 0 else 0,
+                "temporal_gaps": self.results[1].gap_count if len(self.results) > 1 else 0,
+                "future_dates": self.results[2].future_count if len(self.results) > 2 else 0,
+                "ambiguous_ordering": self.results[3].ambiguous_count if len(self.results) > 3 else 0}}

customer_retention/stages/profiling/temporal_target_analyzer.py

@@ -0,0 +1,241 @@
+"""Temporal feature analysis with respect to a binary target."""
+from dataclasses import dataclass
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+from customer_retention.core.compat import DataFrame, to_pandas
+
+
+@dataclass
+class TemporalTargetResult:
+    """Results from temporal-target analysis."""
+    datetime_col: str
+    target_col: str
+    min_date: pd.Timestamp
+    max_date: pd.Timestamp
+    n_valid_dates: int
+    overall_rate: float
+
+    # Yearly analysis
+    yearly_stats: pd.DataFrame  # year, count, retention_rate, lift
+    yearly_trend: str  # 'improving', 'declining', 'stable'
+
+    # Monthly analysis (seasonality)
+    monthly_stats: pd.DataFrame  # month, month_name, count, retention_rate, lift
+    best_month: Optional[str]
+    worst_month: Optional[str]
+    seasonal_spread: float  # difference between best and worst
+
+    # Day of week analysis
+    dow_stats: pd.DataFrame  # day_of_week, day_name, count, retention_rate, lift
+
+    # Quarterly analysis
+    quarterly_stats: pd.DataFrame
+
+
+class TemporalTargetAnalyzer:
+    """Analyzes relationship between datetime features and binary target.
+
+    Computes retention rates by:
+    - Year (cohort analysis)
+    - Month (seasonality)
+    - Day of week (weekly patterns)
+    - Quarter
+    """
+
+    MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+                   'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+    DOW_NAMES = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+
+    def __init__(self, min_samples_per_period: int = 10):
+        self.min_samples_per_period = min_samples_per_period
+
+    def analyze(
+        self,
+        df: DataFrame,
+        datetime_col: str,
+        target_col: str
+    ) -> TemporalTargetResult:
+        """Analyze relationship between datetime feature and binary target."""
+        df = to_pandas(df)
+
+        if len(df) == 0 or datetime_col not in df.columns or target_col not in df.columns:
+            return self._empty_result(datetime_col, target_col)
+
+        # Parse dates and prepare data
+        df_clean = df[[datetime_col, target_col]].copy()
+        df_clean[datetime_col] = pd.to_datetime(df_clean[datetime_col], errors='coerce')
+        df_clean = df_clean.dropna()
+
+        if len(df_clean) == 0:
+            return self._empty_result(datetime_col, target_col)
+
+        # Calculate overall retention rate
+        overall_rate = df_clean[target_col].mean()
+
+        # Extract temporal components
+        df_clean['_year'] = df_clean[datetime_col].dt.year
+        df_clean['_month'] = df_clean[datetime_col].dt.month
+        df_clean['_quarter'] = df_clean[datetime_col].dt.quarter
+        df_clean['_dow'] = df_clean[datetime_col].dt.dayofweek
+
+        # Calculate stats by time period
+        yearly_stats = self._calculate_period_stats(df_clean, '_year', target_col, overall_rate)
+        monthly_stats = self._calculate_monthly_stats(df_clean, target_col, overall_rate)
+        quarterly_stats = self._calculate_period_stats(df_clean, '_quarter', target_col, overall_rate)
+        dow_stats = self._calculate_dow_stats(df_clean, target_col, overall_rate)
+
+        # Determine yearly trend
+        yearly_trend = self._determine_yearly_trend(yearly_stats)
+
+        # Find best/worst months
+        best_month, worst_month, seasonal_spread = self._find_seasonal_extremes(monthly_stats)
+
+        return TemporalTargetResult(
+            datetime_col=datetime_col,
+            target_col=target_col,
+            min_date=df_clean[datetime_col].min(),
+            max_date=df_clean[datetime_col].max(),
+            n_valid_dates=len(df_clean),
+            overall_rate=overall_rate,
+            yearly_stats=yearly_stats,
+            yearly_trend=yearly_trend,
+            monthly_stats=monthly_stats,
+            best_month=best_month,
+            worst_month=worst_month,
+            seasonal_spread=seasonal_spread,
+            dow_stats=dow_stats,
+            quarterly_stats=quarterly_stats
+        )
+
+    def _calculate_period_stats(
+        self,
+        df: pd.DataFrame,
+        period_col: str,
+        target_col: str,
+        overall_rate: float
+    ) -> pd.DataFrame:
+        """Calculate retention stats for a time period."""
+        stats = df.groupby(period_col)[target_col].agg(['sum', 'count', 'mean']).reset_index()
+        stats.columns = ['period', 'retained_count', 'count', 'retention_rate']
+        stats['lift'] = stats['retention_rate'] / overall_rate if overall_rate > 0 else 0
+
+        # Filter small samples
+        stats = stats[stats['count'] >= self.min_samples_per_period]
+
+        return stats.sort_values('period').reset_index(drop=True)
+
+    def _calculate_monthly_stats(
+        self,
+        df: pd.DataFrame,
+        target_col: str,
+        overall_rate: float
+    ) -> pd.DataFrame:
+        """Calculate monthly retention stats with month names."""
+        stats = df.groupby('_month')[target_col].agg(['sum', 'count', 'mean']).reset_index()
+        stats.columns = ['month', 'retained_count', 'count', 'retention_rate']
+        stats['lift'] = stats['retention_rate'] / overall_rate if overall_rate > 0 else 0
+        stats['month_name'] = stats['month'].apply(
+            lambda x: self.MONTH_NAMES[int(x) - 1] if 1 <= x <= 12 else 'Unknown'
+        )
+
+        # Filter small samples
+        stats = stats[stats['count'] >= self.min_samples_per_period]
+
+        return stats.sort_values('month').reset_index(drop=True)
+
+    def _calculate_dow_stats(
+        self,
+        df: pd.DataFrame,
+        target_col: str,
+        overall_rate: float
+    ) -> pd.DataFrame:
+        """Calculate day-of-week retention stats."""
+        stats = df.groupby('_dow')[target_col].agg(['sum', 'count', 'mean']).reset_index()
+        stats.columns = ['day_of_week', 'retained_count', 'count', 'retention_rate']
+        stats['lift'] = stats['retention_rate'] / overall_rate if overall_rate > 0 else 0
+        stats['day_name'] = stats['day_of_week'].apply(
+            lambda x: self.DOW_NAMES[int(x)] if 0 <= x <= 6 else 'Unknown'
+        )
+
+        return stats.sort_values('day_of_week').reset_index(drop=True)
+
+    def _determine_yearly_trend(self, yearly_stats: pd.DataFrame) -> str:
+        """Determine if retention is improving, declining, or stable over years."""
+        if len(yearly_stats) < 2:
+            return 'stable'
+
+        rates = yearly_stats['retention_rate'].values
+        yearly_stats['period'].values
+
+        # Simple linear regression
+        if len(rates) >= 2:
+            slope = np.polyfit(range(len(rates)), rates, 1)[0]
+
+            if slope > 0.02:  # More than 2% improvement per year
+                return 'improving'
+            elif slope < -0.02:  # More than 2% decline per year
+                return 'declining'
+
+        return 'stable'
+
+    def _find_seasonal_extremes(
+        self,
+        monthly_stats: pd.DataFrame
+    ) -> tuple:
+        """Find best and worst months for retention."""
+        if len(monthly_stats) == 0:
+            return None, None, 0.0
+
+        best_idx = monthly_stats['retention_rate'].idxmax()
+        worst_idx = monthly_stats['retention_rate'].idxmin()
+
+        best_month = monthly_stats.loc[best_idx, 'month_name']
+        worst_month = monthly_stats.loc[worst_idx, 'month_name']
+        spread = monthly_stats.loc[best_idx, 'retention_rate'] - monthly_stats.loc[worst_idx, 'retention_rate']
+
+        return best_month, worst_month, float(spread)
+
+    def _empty_result(self, datetime_col: str, target_col: str) -> TemporalTargetResult:
+        """Return empty result for edge cases."""
+        empty_df = pd.DataFrame()
+
+        return TemporalTargetResult(
+            datetime_col=datetime_col,
+            target_col=target_col,
+            min_date=pd.NaT,
+            max_date=pd.NaT,
+            n_valid_dates=0,
+            overall_rate=0.0,
+            yearly_stats=empty_df,
+            yearly_trend='stable',
+            monthly_stats=empty_df,
+            best_month=None,
+            worst_month=None,
+            seasonal_spread=0.0,
+            dow_stats=empty_df,
+            quarterly_stats=empty_df
+        )
+
+    def analyze_multiple(
+        self,
+        df: DataFrame,
+        datetime_cols: List[str],
+        target_col: str
+    ) -> pd.DataFrame:
+        """Analyze multiple datetime columns and return summary."""
+        results = []
+        for col in datetime_cols:
+            result = self.analyze(df, col, target_col)
+            results.append({
+                'feature': col,
+                'n_valid': result.n_valid_dates,
+                'yearly_trend': result.yearly_trend,
+                'best_month': result.best_month,
+                'worst_month': result.worst_month,
+                'seasonal_spread': result.seasonal_spread
+            })
+
+        return pd.DataFrame(results)

customer_retention/stages/profiling/text_embedder.py

@@ -0,0 +1,87 @@
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+from customer_retention.core.compat import DataFrame
+
+EMBEDDING_MODELS: Dict[str, Dict[str, Any]] = {
+    "minilm": {
+        "model_name": "all-MiniLM-L6-v2",
+        "embedding_dim": 384,
+        "size_mb": 90,
+        "description": "Fast, lightweight model. Good for CPU and quick experimentation.",
+        "gpu_recommended": False,
+    },
+    "qwen3-0.6b": {
+        "model_name": "Qwen/Qwen3-Embedding-0.6B",
+        "embedding_dim": 1024,
+        "size_mb": 1200,
+        "description": "Higher quality embeddings, multilingual. Requires GPU for reasonable speed.",
+        "gpu_recommended": True,
+    },
+    "qwen3-4b": {
+        "model_name": "Qwen/Qwen3-Embedding-4B",
+        "embedding_dim": 2560,
+        "size_mb": 8000,
+        "description": "High quality, large model. Requires significant GPU memory (16GB+).",
+        "gpu_recommended": True,
+    },
+    "qwen3-8b": {
+        "model_name": "Qwen/Qwen3-Embedding-8B",
+        "embedding_dim": 4096,
+        "size_mb": 16000,
+        "description": "Highest quality, very large model. Requires 32GB+ GPU memory.",
+        "gpu_recommended": True,
+    },
+}
+
+
+def get_model_info(preset: str) -> Dict[str, Any]:
+    if preset not in EMBEDDING_MODELS:
+        raise ValueError(f"Unknown preset: {preset}. Available: {list(EMBEDDING_MODELS.keys())}")
+    return EMBEDDING_MODELS[preset].copy()
+
+
+def list_available_models() -> List[str]:
+    return list(EMBEDDING_MODELS.keys())
+
+
+class TextEmbedder:
+    DEFAULT_MODEL = "all-MiniLM-L6-v2"
+
+    def __init__(self, model_name: str = DEFAULT_MODEL):
+        self.model_name = model_name
+        self._model = None
+
+    @classmethod
+    def from_preset(cls, preset: str) -> "TextEmbedder":
+        if preset not in EMBEDDING_MODELS:
+            raise ValueError(f"Unknown preset: {preset}. Available: {list(EMBEDDING_MODELS.keys())}")
+        model_name = EMBEDDING_MODELS[preset]["model_name"]
+        return cls(model_name=model_name)
+
+    @property
+    def model(self):
+        if self._model is None:
+            from sentence_transformers import SentenceTransformer
+            self._model = SentenceTransformer(self.model_name)
+        return self._model
+
+    @property
+    def embedding_dim(self) -> int:
+        return self.model.get_sentence_embedding_dimension()
+
+    def embed(self, texts: List[Optional[str]], batch_size: int = 32,
+              show_progress: bool = False) -> np.ndarray:
+        clean_texts = [self._clean_text(t) for t in texts]
+        return self.model.encode(clean_texts, batch_size=batch_size,
+                                  show_progress_bar=show_progress)
+
+    def embed_column(self, df: DataFrame, column: str, batch_size: int = 32) -> np.ndarray:
+        texts = df[column].fillna("").astype(str).tolist()
+        return self.embed(texts, batch_size=batch_size)
+
+    def _clean_text(self, text: Optional[str]) -> str:
+        if not isinstance(text, str) or not text.strip():
+            return ""
+        return text