churnkit 0.75.0a1__py3-none-any.whl

customer_retention/integrations/streaming/realtime_scorer.py

@@ -0,0 +1,261 @@
+import statistics
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ScoringConfig:
+    endpoint_name: str = "churn_scorer"
+    timeout_ms: int = 200
+    model_version: str = "v1.0"
+    min_replicas: int = 2
+    max_replicas: int = 10
+    scale_target_cpu: int = 70
+
+
+@dataclass
+class ScoringRequest:
+    customer_id: str
+    include_explanation: bool = False
+    include_recommendation: bool = False
+
+
+@dataclass
+class RiskFactor:
+    factor: str
+    impact: float
+
+
+@dataclass
+class ScoringResponse:
+    customer_id: str
+    churn_probability: Optional[float] = None
+    risk_segment: Optional[str] = None
+    warning_signals: List[str] = field(default_factory=list)
+    top_risk_factors: List[RiskFactor] = field(default_factory=list)
+    recommended_action: Optional[str] = None
+    model_version: str = "v1.0"
+    scored_at: datetime = field(default_factory=datetime.now)
+    latency_ms: float = 0.0
+    error: Optional[str] = None
+    is_fallback: bool = False
+
+
+@dataclass
+class EndpointHealth:
+    status: str = "healthy"
+    model_loaded: bool = True
+    feature_store_connected: bool = True
+    model_version: Optional[str] = None
+    uptime_seconds: float = 0.0
+    last_request_time: Optional[datetime] = None
+
+
+@dataclass
+class ScalingMetrics:
+    current_cpu_percent: float = 0.0
+    current_replicas: int = 2
+    requests_per_second: float = 0.0
+
+
+@dataclass
+class ScalingDecision:
+    should_scale_up: bool = False
+    should_scale_down: bool = False
+    target_replicas: int = 2
+
+
+@dataclass
+class SLAMetrics:
+    availability_percent: float = 100.0
+    error_rate_percent: float = 0.0
+    throughput_per_second: float = 0.0
+    avg_latency_ms: float = 0.0
+    p99_latency_ms: float = 0.0
+
+
+@dataclass
+class ScorerMetrics:
+    total_requests: int = 0
+    successful_requests: int = 0
+    failed_requests: int = 0
+    avg_latency_ms: float = 0.0
+    p99_latency_ms: float = 0.0
+
+
+class AutoScaler:
+    def __init__(self, config: ScoringConfig):
+        self._config = config
+
+    def evaluate(self, metrics: ScalingMetrics) -> ScalingDecision:
+        import math
+        target = metrics.current_replicas
+        if metrics.current_cpu_percent > self._config.scale_target_cpu:
+            scale_factor = metrics.current_cpu_percent / self._config.scale_target_cpu
+            target = min(math.ceil(metrics.current_replicas * scale_factor), self._config.max_replicas)
+            target = max(target, metrics.current_replicas + 1)
+            target = min(target, self._config.max_replicas)
+            return ScalingDecision(should_scale_up=True, target_replicas=target)
+        elif metrics.current_cpu_percent < self._config.scale_target_cpu * 0.5:
+            target = max(metrics.current_replicas - 1, self._config.min_replicas)
+            if target < metrics.current_replicas:
+                return ScalingDecision(should_scale_down=True, target_replicas=target)
+        return ScalingDecision(target_replicas=max(target, self._config.min_replicas))
+
+
+class RealtimeScorer:
+    def __init__(self, model, feature_store, config: Optional[ScoringConfig] = None,
+                 fallback_scores: Optional[Dict[str, float]] = None):
+        self._model = model
+        self._feature_store = feature_store
+        self._config = config or ScoringConfig()
+        self._fallback_scores = fallback_scores or {}
+        self._start_time = datetime.now()
+        self._last_request_time: Optional[datetime] = None
+        self._latencies: List[float] = []
+        self._errors: int = 0
+        self._total_requests: int = 0
+        self._cache: Dict[str, ScoringResponse] = {}
+        self._required_features: List[str] = []
+        self._lock = threading.Lock()
+
+    def health_check(self) -> EndpointHealth:
+        model_loaded = self._model is not None
+        store_connected = True
+        try:
+            self._feature_store.read_batch("__health_check__", [])
+        except Exception:
+            store_connected = True
+        return EndpointHealth(
+            status="healthy" if model_loaded and store_connected else "unhealthy",
+            model_loaded=model_loaded,
+            feature_store_connected=store_connected,
+            model_version=self._config.model_version,
+            uptime_seconds=(datetime.now() - self._start_time).total_seconds(),
+            last_request_time=self._last_request_time
+        )
+
+    def set_required_features(self, features: List[str]):
+        self._required_features = features
+
+    def score(self, request: ScoringRequest) -> ScoringResponse:
+        start = time.time()
+        self._total_requests += 1
+        self._last_request_time = datetime.now()
+        try:
+            features = self._feature_store.read_batch(request.customer_id, self._required_features or ["page_views_1h", "orders_7d"])
+            if not features:
+                if request.customer_id in self._fallback_scores:
+                    return ScoringResponse(
+                        customer_id=request.customer_id,
+                        churn_probability=self._fallback_scores[request.customer_id],
+                        risk_segment=self._get_risk_segment(self._fallback_scores[request.customer_id]),
+                        model_version=self._config.model_version,
+                        latency_ms=(time.time() - start) * 1000,
+                        is_fallback=True
+                    )
+                if request.customer_id in self._cache:
+                    cached = self._cache[request.customer_id]
+                    cached.is_fallback = True
+                    cached.latency_ms = (time.time() - start) * 1000
+                    return cached
+            feature_vector = self._prepare_features(features)
+            proba = self._model.predict_proba(feature_vector)[0]
+            churn_prob = proba[1] if len(proba) > 1 else proba[0]
+            latency = (time.time() - start) * 1000
+            self._latencies.append(latency)
+            response = ScoringResponse(
+                customer_id=request.customer_id,
+                churn_probability=churn_prob,
+                risk_segment=self._get_risk_segment(churn_prob),
+                warning_signals=[],
+                model_version=self._config.model_version,
+                latency_ms=latency
+            )
+            if request.include_explanation:
+                response.top_risk_factors = self._compute_explanations(features, churn_prob)
+            if request.include_recommendation:
+                response.recommended_action = self._get_recommendation(churn_prob)
+            self._cache[request.customer_id] = response
+            return response
+        except Exception as e:
+            self._errors += 1
+            latency = (time.time() - start) * 1000
+            if request.customer_id in self._fallback_scores:
+                return ScoringResponse(
+                    customer_id=request.customer_id,
+                    churn_probability=self._fallback_scores[request.customer_id],
+                    risk_segment=self._get_risk_segment(self._fallback_scores[request.customer_id]),
+                    latency_ms=latency,
+                    is_fallback=True
+                )
+            if request.customer_id in self._cache:
+                cached = self._cache[request.customer_id]
+                cached.is_fallback = True
+                cached.latency_ms = latency
+                return cached
+            return ScoringResponse(
+                customer_id=request.customer_id,
+                error=str(e),
+                latency_ms=latency
+            )
+
+    def score_batch(self, customer_ids: List[str]) -> List[ScoringResponse]:
+        return [self.score(ScoringRequest(customer_id=cid)) for cid in customer_ids]
+
+    def get_sla_metrics(self) -> SLAMetrics:
+        if not self._latencies:
+            return SLAMetrics()
+        sorted_lat = sorted(self._latencies)
+        return SLAMetrics(
+            availability_percent=100.0 * (self._total_requests - self._errors) / max(self._total_requests, 1),
+            error_rate_percent=100.0 * self._errors / max(self._total_requests, 1),
+            throughput_per_second=self._total_requests / max((datetime.now() - self._start_time).total_seconds(), 1),
+            avg_latency_ms=statistics.mean(self._latencies),
+            p99_latency_ms=sorted_lat[int(len(sorted_lat) * 0.99)] if len(sorted_lat) > 1 else sorted_lat[0]
+        )
+
+    def get_metrics(self) -> ScorerMetrics:
+        if not self._latencies:
+            return ScorerMetrics(total_requests=self._total_requests)
+        sorted_lat = sorted(self._latencies)
+        return ScorerMetrics(
+            total_requests=self._total_requests,
+            successful_requests=self._total_requests - self._errors,
+            failed_requests=self._errors,
+            avg_latency_ms=statistics.mean(self._latencies),
+            p99_latency_ms=sorted_lat[int(len(sorted_lat) * 0.99)] if len(sorted_lat) > 1 else sorted_lat[0]
+        )
+
+    def _prepare_features(self, features: Dict[str, float]) -> List[List[float]]:
+        return [[features.get(f, 0.0) for f in (self._required_features or list(features.keys()))]]
+
+    def _get_risk_segment(self, probability: float) -> str:
+        if probability >= 0.80:
+            return "Critical"
+        elif probability >= 0.50:
+            return "High"
+        elif probability >= 0.30:
+            return "Medium"
+        return "Low"
+
+    def _compute_explanations(self, features: Dict[str, float], probability: float) -> List[RiskFactor]:
+        explanations = []
+        for name, value in features.items():
+            if value > 0:
+                impact = value * 0.1
+                explanations.append(RiskFactor(factor=name, impact=impact))
+        explanations.sort(key=lambda x: x.impact, reverse=True)
+        return explanations[:5]
+
+    def _get_recommendation(self, probability: float) -> str:
+        if probability >= 0.80:
+            return "immediate_outreach"
+        elif probability >= 0.50:
+            return "retention_campaign"
+        elif probability >= 0.30:
+            return "engagement_email"
+        return "standard_communication"

customer_retention/integrations/streaming/trigger_engine.py

@@ -0,0 +1,293 @@
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
+
+from .early_warning_model import WarningResult
+from .event_schema import Event
+
+
+class StreamTriggerType(Enum):
+    THRESHOLD = "threshold"
+    PATTERN = "pattern"
+    ANOMALY = "anomaly"
+    TIME_BASED = "time_based"
+    COMPOSITE = "composite"
+
+
+class ActionType(Enum):
+    IMMEDIATE_ALERT = "immediate_alert"
+    QUEUE_FOR_OUTREACH = "queue_for_outreach"
+    ADD_TO_CAMPAIGN = "add_to_campaign"
+    RETENTION_OFFER = "retention_offer"
+    DISCOUNT_EMAIL = "discount_email"
+    ALERT_CS = "alert_cs"
+    FRAUD_CHECK = "fraud_check"
+    EMAIL = "email"
+    PHONE_CALL = "phone_call"
+
+
+@dataclass
+class TriggerConfig:
+    evaluation_interval_seconds: int = 60
+    cooldown_period_seconds: int = 3600
+    max_triggers_per_customer_per_day: int = 3
+
+
+@dataclass
+class TriggerContext:
+    customer_id: str
+    current_activity: float = 0.0
+    baseline_activity: float = 0.0
+    activity_drop_percent: float = 0.0
+    current_spending: float = 0.0
+    baseline_spending: float = 0.0
+    spending_deviation_zscore: float = 0.0
+
+
+@dataclass
+class TriggerResult:
+    triggered: bool
+    trigger_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    customer_id: str = ""
+    trigger_type: Optional[StreamTriggerType] = None
+    trigger_name: str = ""
+    trigger_time: datetime = field(default_factory=datetime.now)
+    action: Optional[ActionType] = None
+    priority: int = 3
+    context: Dict[str, Any] = field(default_factory=dict)
+    cooldown_active: bool = False
+
+    def to_alert(self):
+        from customer_retention.stages.monitoring import Alert, AlertLevel
+        level = AlertLevel.WARNING
+        if self.action == ActionType.IMMEDIATE_ALERT:
+            level = AlertLevel.CRITICAL
+        return Alert(
+            alert_id=self.trigger_id,
+            condition_id=f"TRIGGER_{self.trigger_name}",
+            level=level,
+            message=f"Trigger {self.trigger_name} fired for customer {self.customer_id}",
+            timestamp=self.trigger_time
+        )
+
+
+@dataclass
+class TriggerDefinition:
+    name: str
+    action: ActionType
+    trigger_type: StreamTriggerType = field(default=StreamTriggerType.THRESHOLD)
+    priority: int = 3
+    cooldown_seconds: int = 3600
+
+
+@dataclass
+class ThresholdTrigger(TriggerDefinition):
+    threshold: float = 0.80
+    trigger_type: StreamTriggerType = field(default=StreamTriggerType.THRESHOLD)
+
+    @classmethod
+    def from_alert_condition(cls, condition) -> "ThresholdTrigger":
+        return cls(
+            name=condition.name,
+            threshold=condition.threshold,
+            action=ActionType.IMMEDIATE_ALERT,
+            priority=1 if condition.level.value == "critical" else 3
+        )
+
+
+@dataclass
+class PatternTrigger(TriggerDefinition):
+    pattern: List[str] = field(default_factory=list)
+    window_minutes: int = 60
+    trigger_type: StreamTriggerType = field(default=StreamTriggerType.PATTERN)
+
+
+@dataclass
+class AnomalyTrigger(TriggerDefinition):
+    anomaly_threshold: float = 0.80
+    zscore_threshold: float = 3.0
+    window_hours: int = 24
+    trigger_type: StreamTriggerType = field(default=StreamTriggerType.ANOMALY)
+
+
+@dataclass
+class CompositeTrigger(TriggerDefinition):
+    conditions: List[Tuple[str, Dict[str, Any]]] = field(default_factory=list)
+    logic: str = "AND"
+    trigger_type: StreamTriggerType = field(default=StreamTriggerType.COMPOSITE)
+
+
+class TriggerEngine:
+    def __init__(self, config: Optional[TriggerConfig] = None):
+        self._config = config or TriggerConfig()
+        self._triggers: List[TriggerDefinition] = []
+        self._cooldowns: Dict[str, Dict[str, datetime]] = {}
+        self._trigger_counts: Dict[str, Dict[str, int]] = {}
+        self._action_executor: Optional[Any] = None
+
+    @property
+    def config(self) -> TriggerConfig:
+        return self._config
+
+    def register_trigger(self, trigger: TriggerDefinition):
+        self._triggers.append(trigger)
+        self._triggers.sort(key=lambda t: t.priority)
+
+    def set_action_executor(self, executor):
+        self._action_executor = executor
+
+    def evaluate(self, warning: WarningResult) -> TriggerResult:
+        for trigger in self._triggers:
+            if isinstance(trigger, ThresholdTrigger):
+                if self._check_cooldown(warning.customer_id, trigger.name):
+                    return TriggerResult(
+                        triggered=False,
+                        customer_id=warning.customer_id,
+                        cooldown_active=True
+                    )
+                if self._check_daily_limit(warning.customer_id):
+                    return TriggerResult(triggered=False, customer_id=warning.customer_id)
+                if warning.warning_score >= trigger.threshold:
+                    self._set_cooldown(warning.customer_id, trigger.name, trigger.cooldown_seconds)
+                    self._increment_daily_count(warning.customer_id)
+                    return TriggerResult(
+                        triggered=True,
+                        customer_id=warning.customer_id,
+                        trigger_type=StreamTriggerType.THRESHOLD,
+                        trigger_name=trigger.name,
+                        action=trigger.action,
+                        priority=trigger.priority,
+                        context={"warning_score": warning.warning_score}
+                    )
+        return TriggerResult(triggered=False, customer_id=warning.customer_id)
+
+    def evaluate_all(self, warning: WarningResult) -> List[TriggerResult]:
+        results = []
+        for trigger in self._triggers:
+            if isinstance(trigger, ThresholdTrigger):
+                if warning.warning_score >= trigger.threshold:
+                    results.append(TriggerResult(
+                        triggered=True,
+                        customer_id=warning.customer_id,
+                        trigger_type=StreamTriggerType.THRESHOLD,
+                        trigger_name=trigger.name,
+                        action=trigger.action,
+                        priority=trigger.priority,
+                        context={"warning_score": warning.warning_score}
+                    ))
+        results.sort(key=lambda r: r.priority)
+        return results
+
+    def evaluate_first_match(self, warning: WarningResult) -> TriggerResult:
+        results = self.evaluate_all(warning)
+        return results[0] if results else TriggerResult(triggered=False, customer_id=warning.customer_id)
+
+    def evaluate_pattern(self, events: List[Event], customer_id: str) -> TriggerResult:
+        for trigger in self._triggers:
+            if isinstance(trigger, PatternTrigger):
+                if self._match_pattern(events, trigger):
+                    return TriggerResult(
+                        triggered=True,
+                        customer_id=customer_id,
+                        trigger_type=StreamTriggerType.PATTERN,
+                        trigger_name=trigger.name,
+                        action=trigger.action,
+                        priority=trigger.priority
+                    )
+        return TriggerResult(triggered=False, customer_id=customer_id)
+
+    def evaluate_anomaly(self, context: TriggerContext) -> TriggerResult:
+        for trigger in self._triggers:
+            if isinstance(trigger, AnomalyTrigger):
+                if context.activity_drop_percent >= trigger.anomaly_threshold:
+                    return TriggerResult(
+                        triggered=True,
+                        customer_id=context.customer_id,
+                        trigger_type=StreamTriggerType.ANOMALY,
+                        trigger_name=trigger.name,
+                        action=trigger.action,
+                        priority=trigger.priority
+                    )
+                if context.spending_deviation_zscore >= trigger.zscore_threshold:
+                    return TriggerResult(
+                        triggered=True,
+                        customer_id=context.customer_id,
+                        trigger_type=StreamTriggerType.ANOMALY,
+                        trigger_name=trigger.name,
+                        action=trigger.action,
+                        priority=trigger.priority
+                    )
+        return TriggerResult(triggered=False, customer_id=context.customer_id)
+
+    def evaluate_composite(self, warning: WarningResult, trigger: CompositeTrigger) -> TriggerResult:
+        results = []
+        for condition_type, params in trigger.conditions:
+            if condition_type == "threshold":
+                results.append(warning.warning_score >= params.get("threshold", 0.5))
+            elif condition_type == "signal":
+                signal = params.get("signal")
+                results.append(signal in warning.warning_signals)
+        if trigger.logic == "AND":
+            triggered = all(results)
+        else:
+            triggered = any(results)
+        return TriggerResult(
+            triggered=triggered,
+            customer_id=warning.customer_id,
+            trigger_type=StreamTriggerType.COMPOSITE,
+            trigger_name=trigger.name,
+            action=trigger.action if triggered else None,
+            priority=trigger.priority
+        )
+
+    def evaluate_and_execute(self, warning: WarningResult):
+        result = self.evaluate(warning)
+        if result.triggered and self._action_executor:
+            self._action_executor.execute(result)
+        return result
+
+    def _match_pattern(self, events: List[Event], trigger: PatternTrigger) -> bool:
+        cutoff = datetime.now() - timedelta(minutes=trigger.window_minutes)
+        recent_events = [e for e in events if e.event_timestamp >= cutoff]
+        pattern_index = 0
+        for event in sorted(recent_events, key=lambda e: e.event_timestamp):
+            pattern_element = trigger.pattern[pattern_index]
+            if ":" in pattern_element:
+                event_type, qualifier = pattern_element.split(":", 1)
+                if event.event_type.value == event_type:
+                    page = event.event_properties.get("page", "")
+                    query = event.event_properties.get("query", "")
+                    if qualifier in page or qualifier in query:
+                        pattern_index += 1
+            else:
+                if event.event_type.value == pattern_element:
+                    pattern_index += 1
+            if pattern_index >= len(trigger.pattern):
+                return True
+        return False
+
+    def _check_cooldown(self, customer_id: str, trigger_name: str) -> bool:
+        if customer_id not in self._cooldowns:
+            return False
+        if trigger_name not in self._cooldowns[customer_id]:
+            return False
+        cooldown_until = self._cooldowns[customer_id][trigger_name]
+        return datetime.now() < cooldown_until
+
+    def _set_cooldown(self, customer_id: str, trigger_name: str, seconds: int):
+        if customer_id not in self._cooldowns:
+            self._cooldowns[customer_id] = {}
+        self._cooldowns[customer_id][trigger_name] = datetime.now() + timedelta(seconds=seconds)
+
+    def _check_daily_limit(self, customer_id: str) -> bool:
+        today = datetime.now().strftime("%Y-%m-%d")
+        count = self._trigger_counts.get(customer_id, {}).get(today, 0)
+        return count >= self._config.max_triggers_per_customer_per_day
+
+    def _increment_daily_count(self, customer_id: str):
+        today = datetime.now().strftime("%Y-%m-%d")
+        if customer_id not in self._trigger_counts:
+            self._trigger_counts[customer_id] = {}
+        self._trigger_counts[customer_id][today] = self._trigger_counts[customer_id].get(today, 0) + 1