churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/deployment/model_registry.py

@@ -0,0 +1,182 @@
+import os
+import tempfile
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
+
+import mlflow
+import mlflow.sklearn
+
+
+class ModelStage(Enum):
+    NONE = "None"
+    STAGING = "Staging"
+    PRODUCTION = "Production"
+    ARCHIVED = "Archived"
+
+
+@dataclass
+class ModelMetadata:
+    run_id: str
+    model_name: str
+    version: str
+    stage: ModelStage
+    training_date: Optional[str] = None
+    feature_table_version: Optional[str] = None
+    training_data_range: Optional[Tuple[str, str]] = None
+    tags: Dict[str, str] = field(default_factory=dict)
+    description: Optional[str] = None
+
+
+@dataclass
+class RegistrationResult:
+    success: bool
+    version: Optional[str] = None
+    model_uri: Optional[str] = None
+    metadata: Optional[ModelMetadata] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class ValidationResult:
+    is_valid: bool
+    artifacts_present: bool = True
+    metrics_meet_threshold: bool = True
+    errors: List[str] = field(default_factory=list)
+
+
+class ModelRegistry:
+    def __init__(self, tracking_uri: Optional[str] = None):
+        if tracking_uri:
+            mlflow.set_tracking_uri(tracking_uri)
+        self._client = None
+
+    @property
+    def client(self):
+        if self._client is None:
+            self._client = mlflow.tracking.MlflowClient()
+        return self._client
+
+    def register_model(self, model: Any, model_name: str, run_id: str,
+                       scaler: Any = None, feature_manifest: Optional[Dict] = None,
+                       threshold: Optional[float] = None, metrics: Optional[Dict] = None,
+                       tags: Optional[Dict[str, str]] = None, description: Optional[str] = None,
+                       config: Optional[Dict] = None) -> RegistrationResult:
+        try:
+            with mlflow.start_run(run_id=run_id) if run_id else mlflow.start_run():
+                if metrics:
+                    mlflow.log_metrics(metrics)
+                if tags:
+                    mlflow.set_tags(tags)
+                mlflow.sklearn.log_model(model, "model")
+                if scaler is not None:
+                    with tempfile.NamedTemporaryFile(suffix=".pkl", delete=False) as f:
+                        import pickle
+                        pickle.dump(scaler, f)
+                        scaler_path = f.name
+                    mlflow.log_artifact(scaler_path, "scaler")
+                    os.unlink(scaler_path)
+                if feature_manifest:
+                    mlflow.log_dict(feature_manifest, "feature_manifest.json")
+                if threshold is not None:
+                    mlflow.log_param("optimal_threshold", threshold)
+                if config:
+                    mlflow.log_dict(config, "config.json")
+                active_run = mlflow.active_run()
+                current_run_id = active_run.info.run_id if active_run else run_id
+                model_uri = f"runs:/{current_run_id}/model"
+                result = mlflow.register_model(model_uri, model_name)
+                metadata = ModelMetadata(
+                    run_id=current_run_id,
+                    model_name=model_name,
+                    version=str(result.version),
+                    stage=ModelStage.NONE,
+                    tags=tags or {},
+                    description=description
+                )
+                return RegistrationResult(
+                    success=True,
+                    version=str(result.version),
+                    model_uri=model_uri,
+                    metadata=metadata
+                )
+        except Exception as e:
+            return RegistrationResult(success=False, error=str(e))
+
+    def transition_stage(self, model_name: str, version: str, stage: ModelStage,
+                         archive_existing: bool = True) -> bool:
+        self.client.transition_model_version_stage(
+            name=model_name,
+            version=version,
+            stage=stage.value,
+            archive_existing_versions=archive_existing
+        )
+        return True
+
+    def load_model(self, model_name: str, stage: Optional[ModelStage] = None,
+                   version: Optional[str] = None) -> Any:
+        if version:
+            model_uri = f"models:/{model_name}/{version}"
+        elif stage:
+            model_uri = f"models:/{model_name}/{stage.value}"
+        else:
+            model_uri = f"models:/{model_name}/Production"
+        return mlflow.pyfunc.load_model(model_uri)
+
+    def get_metadata(self, model_name: str, version: str) -> ModelMetadata:
+        model_version = self.client.get_model_version(model_name, version)
+        return ModelMetadata(
+            run_id=model_version.run_id,
+            model_name=model_name,
+            version=model_version.version,
+            stage=ModelStage(model_version.current_stage),
+            tags=dict(model_version.tags) if model_version.tags else {}
+        )
+
+    def list_versions(self, model_name: str) -> List[ModelMetadata]:
+        versions = self.client.search_model_versions(f"name='{model_name}'")
+        return [
+            ModelMetadata(
+                run_id=v.run_id,
+                model_name=model_name,
+                version=v.version,
+                stage=ModelStage(v.current_stage),
+                tags=dict(v.tags) if v.tags else {}
+            )
+            for v in versions
+        ]
+
+    def validate_for_promotion(self, model_name: str, version: str,
+                               required_metrics: Optional[Dict[str, float]] = None,
+                               required_artifacts: Optional[List[str]] = None) -> ValidationResult:
+        errors = []
+        artifacts_present = True
+        metrics_meet_threshold = True
+        try:
+            model_version = self.client.get_model_version(model_name, version)
+            run_id = model_version.run_id
+            if required_artifacts:
+                artifacts = self.client.list_artifacts(run_id)
+                artifact_paths = [a.path for a in artifacts]
+                for req_artifact in required_artifacts:
+                    if req_artifact not in artifact_paths:
+                        artifacts_present = False
+                        errors.append(f"Missing artifact: {req_artifact}")
+            if required_metrics:
+                run = self.client.get_run(run_id)
+                run_metrics = run.data.metrics
+                for metric_name, threshold in required_metrics.items():
+                    if metric_name not in run_metrics:
+                        metrics_meet_threshold = False
+                        errors.append(f"Missing metric: {metric_name}")
+                    elif run_metrics[metric_name] < threshold:
+                        metrics_meet_threshold = False
+                        errors.append(f"Metric {metric_name} below threshold: {run_metrics[metric_name]} < {threshold}")
+        except Exception as e:
+            errors.append(str(e))
+        return ValidationResult(
+            is_valid=artifacts_present and metrics_meet_threshold and len(errors) == 0,
+            artifacts_present=artifacts_present,
+            metrics_meet_threshold=metrics_meet_threshold,
+            errors=errors
+        )

customer_retention/stages/deployment/retraining_trigger.py

@@ -0,0 +1,245 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+
+class RetrainingTriggerType(Enum):
+    PERFORMANCE_DEGRADATION = "performance_degradation"
+    SIGNIFICANT_DRIFT = "significant_drift"
+    SCHEDULED = "scheduled"
+    DATA_VOLUME_INCREASE = "data_volume_increase"
+    BUSINESS_REQUEST = "business_request"
+    NEW_FEATURES = "new_features"
+
+
+class TriggerPriority(Enum):
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+
+
+@dataclass
+class RetrainingConfig:
+    performance_drop_threshold: float = 0.15
+    drift_psi_threshold: float = 0.20
+    scheduled_interval_days: int = 90
+    data_volume_increase_threshold: float = 0.50
+    training_data_window_days: int = 365
+    validation_split: float = 0.20
+    min_performance_lift: float = 0.02
+    auto_deploy: bool = False
+    approval_required: bool = True
+
+
+@dataclass
+class RetrainingDecision:
+    should_retrain: bool
+    trigger_type: Optional[RetrainingTriggerType] = None
+    priority: Optional[TriggerPriority] = None
+    reason: Optional[str] = None
+    action: Optional[str] = None
+    requires_approval: bool = True
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class EvaluationResult:
+    triggered_conditions: List[RetrainingDecision]
+    final_decision: RetrainingDecision
+
+
+class RetrainingTrigger:
+    def __init__(self, config: Optional[RetrainingConfig] = None):
+        self.config = config or RetrainingConfig()
+        self._history: List[RetrainingDecision] = []
+
+    def evaluate_performance(self, metrics: Dict[str, Dict[str, float]]) -> RetrainingDecision:
+        if "pr_auc" in metrics:
+            current = metrics["pr_auc"].get("current", 0)
+            baseline = metrics["pr_auc"].get("baseline", 0)
+            drop = baseline - current
+            if drop >= self.config.performance_drop_threshold:
+                decision = RetrainingDecision(
+                    should_retrain=True,
+                    trigger_type=RetrainingTriggerType.PERFORMANCE_DEGRADATION,
+                    priority=TriggerPriority.HIGH,
+                    reason=f"PR-AUC dropped by {drop:.2%} (from {baseline:.3f} to {current:.3f})",
+                    action="immediate_retrain",
+                    requires_approval=self.config.approval_required
+                )
+                self._history.append(decision)
+                return decision
+        decision = RetrainingDecision(
+            should_retrain=False,
+            reason="Performance within acceptable range"
+        )
+        self._history.append(decision)
+        return decision
+
+    def evaluate_drift(self, drift_metrics: Dict[str, Dict[str, float]]) -> RetrainingDecision:
+        max_psi = 0
+        drifted_features = []
+        for feature, metrics in drift_metrics.items():
+            psi = metrics.get("psi", 0)
+            if psi > max_psi:
+                max_psi = psi
+            if psi >= self.config.drift_psi_threshold:
+                drifted_features.append(feature)
+        if drifted_features:
+            decision = RetrainingDecision(
+                should_retrain=True,
+                trigger_type=RetrainingTriggerType.SIGNIFICANT_DRIFT,
+                priority=TriggerPriority.HIGH,
+                reason=f"Significant drift detected in features: {', '.join(drifted_features)} (max PSI: {max_psi:.3f})",
+                action="immediate_retrain",
+                requires_approval=self.config.approval_required
+            )
+            self._history.append(decision)
+            return decision
+        decision = RetrainingDecision(
+            should_retrain=False,
+            reason="No significant drift detected"
+        )
+        self._history.append(decision)
+        return decision
+
+    def evaluate_schedule(self, last_training_date: datetime) -> RetrainingDecision:
+        days_since_training = (datetime.now() - last_training_date).days
+        if days_since_training >= self.config.scheduled_interval_days:
+            decision = RetrainingDecision(
+                should_retrain=True,
+                trigger_type=RetrainingTriggerType.SCHEDULED,
+                priority=TriggerPriority.MEDIUM,
+                reason=f"Scheduled retraining: {days_since_training} days since last training",
+                action="scheduled_retrain",
+                requires_approval=self.config.approval_required
+            )
+            self._history.append(decision)
+            return decision
+        return RetrainingDecision(
+            should_retrain=False,
+            reason=f"Next scheduled retraining in {self.config.scheduled_interval_days - days_since_training} days"
+        )
+
+    def evaluate_data_volume(self, training_data_size: int, current_data_size: int) -> RetrainingDecision:
+        increase_ratio = (current_data_size - training_data_size) / training_data_size
+        if increase_ratio >= self.config.data_volume_increase_threshold:
+            decision = RetrainingDecision(
+                should_retrain=True,
+                trigger_type=RetrainingTriggerType.DATA_VOLUME_INCREASE,
+                priority=TriggerPriority.MEDIUM,
+                reason=f"Data volume increased by {increase_ratio:.1%} ({training_data_size} -> {current_data_size})",
+                action="retrain_with_new_data",
+                requires_approval=self.config.approval_required
+            )
+            self._history.append(decision)
+            return decision
+        return RetrainingDecision(
+            should_retrain=False,
+            reason=f"Data volume increase ({increase_ratio:.1%}) below threshold"
+        )
+
+    def trigger_manual(self, reason: str) -> RetrainingDecision:
+        decision = RetrainingDecision(
+            should_retrain=True,
+            trigger_type=RetrainingTriggerType.BUSINESS_REQUEST,
+            priority=TriggerPriority.LOW,
+            reason=f"Business request: {reason}",
+            action="manual_retrain",
+            requires_approval=self.config.approval_required
+        )
+        self._history.append(decision)
+        return decision
+
+    def evaluate_new_features(self, current_features: List[str], new_features: List[str]) -> RetrainingDecision:
+        if new_features:
+            decision = RetrainingDecision(
+                should_retrain=True,
+                trigger_type=RetrainingTriggerType.NEW_FEATURES,
+                priority=TriggerPriority.LOW,
+                reason=f"New features available: {', '.join(new_features)}",
+                action="retrain_with_new_features",
+                requires_approval=self.config.approval_required
+            )
+            self._history.append(decision)
+            return decision
+        return RetrainingDecision(
+            should_retrain=False,
+            reason="No new features available"
+        )
+
+    def make_decision(self, performance_degraded: bool, drift_detected: bool) -> RetrainingDecision:
+        if performance_degraded and drift_detected:
+            return RetrainingDecision(
+                should_retrain=True,
+                priority=TriggerPriority.HIGH,
+                action="immediate_retrain",
+                reason="Both performance degradation and drift detected",
+                requires_approval=not self.config.auto_deploy
+            )
+        elif drift_detected:
+            return RetrainingDecision(
+                should_retrain=False,
+                priority=TriggerPriority.MEDIUM,
+                action="investigate_and_prepare",
+                reason="Drift detected but performance OK - investigate and prepare for retraining",
+                requires_approval=True
+            )
+        elif performance_degraded:
+            return RetrainingDecision(
+                should_retrain=False,
+                priority=TriggerPriority.MEDIUM,
+                action="investigate_possible_retrain",
+                reason="Performance degraded without drift - investigate root cause",
+                requires_approval=True
+            )
+        else:
+            return RetrainingDecision(
+                should_retrain=False,
+                priority=TriggerPriority.LOW,
+                action="continue_monitoring",
+                reason="Performance and drift within acceptable ranges",
+                requires_approval=False
+            )
+
+    def evaluate_all(self, performance_metrics: Optional[Dict] = None,
+                     drift_metrics: Optional[Dict] = None,
+                     last_training_date: Optional[datetime] = None,
+                     training_data_size: Optional[int] = None,
+                     current_data_size: Optional[int] = None) -> EvaluationResult:
+        triggered = []
+        if performance_metrics:
+            result = self.evaluate_performance(performance_metrics)
+            if result.should_retrain:
+                triggered.append(result)
+        if drift_metrics:
+            result = self.evaluate_drift(drift_metrics)
+            if result.should_retrain:
+                triggered.append(result)
+        if last_training_date:
+            result = self.evaluate_schedule(last_training_date)
+            if result.should_retrain:
+                triggered.append(result)
+        if training_data_size and current_data_size:
+            result = self.evaluate_data_volume(training_data_size, current_data_size)
+            if result.should_retrain:
+                triggered.append(result)
+        if triggered:
+            triggered.sort(key=lambda x: {"HIGH": 0, "MEDIUM": 1, "LOW": 2}.get(x.priority.value, 3))
+            final = triggered[0]
+        else:
+            final = RetrainingDecision(
+                should_retrain=False,
+                action="continue_monitoring",
+                reason="No retraining triggers activated"
+            )
+        return EvaluationResult(
+            triggered_conditions=triggered,
+            final_decision=final
+        )
+
+    def get_trigger_history(self, trigger_type: Optional[RetrainingTriggerType] = None) -> List[RetrainingDecision]:
+        if trigger_type:
+            return [h for h in self._history if h.trigger_type == trigger_type]
+        return self._history.copy()

customer_retention/stages/features/__init__.py

@@ -0,0 +1,73 @@
+"""
+Feature engineering module for customer retention analysis.
+
+This module provides classes for deriving features from transformed data.
+"""
+
+from customer_retention.stages.features.behavioral_features import (
+    BehavioralFeatureGenerator,
+    BehavioralFeatureResult,
+)
+from customer_retention.stages.features.customer_segmentation import (
+    CustomerSegmenter,
+    SegmentationResult,
+    SegmentationType,
+    SegmentDefinition,
+)
+from customer_retention.stages.features.feature_definitions import (
+    FeatureCatalog,
+    FeatureCategory,
+    FeatureDefinition,
+    LeakageRisk,
+)
+from customer_retention.stages.features.feature_engineer import (
+    FeatureEngineer,
+    FeatureEngineerConfig,
+    FeatureEngineerResult,
+)
+from customer_retention.stages.features.feature_manifest import (
+    FeatureManifest,
+    FeatureSet,
+    FeatureSetRegistry,
+)
+from customer_retention.stages.features.feature_selector import (
+    FeatureSelectionResult,
+    FeatureSelector,
+    SelectionMethod,
+)
+from customer_retention.stages.features.interaction_features import (
+    InteractionFeatureGenerator,
+    InteractionFeatureResult,
+)
+from customer_retention.stages.features.temporal_features import (
+    ReferenceDateSource,
+    TemporalFeatureGenerator,
+    TemporalFeatureResult,
+)
+
+__all__ = [
+    "TemporalFeatureGenerator",
+    "ReferenceDateSource",
+    "TemporalFeatureResult",
+    "BehavioralFeatureGenerator",
+    "BehavioralFeatureResult",
+    "InteractionFeatureGenerator",
+    "InteractionFeatureResult",
+    "FeatureDefinition",
+    "FeatureCategory",
+    "LeakageRisk",
+    "FeatureCatalog",
+    "FeatureEngineer",
+    "FeatureEngineerConfig",
+    "FeatureEngineerResult",
+    "FeatureSelector",
+    "SelectionMethod",
+    "FeatureSelectionResult",
+    "FeatureManifest",
+    "FeatureSet",
+    "FeatureSetRegistry",
+    "CustomerSegmenter",
+    "SegmentationType",
+    "SegmentDefinition",
+    "SegmentationResult",
+]