churnkit 0.75.0a1__py3-none-any.whl

customer_retention/integrations/feature_store/registry.py

@@ -0,0 +1,412 @@
+"""Feature registry for centralized feature management.
+
+This module provides a central registry for all feature definitions,
+enabling consistent feature computation across training and inference.
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+from .definitions import (
+    FeatureComputationType,
+    FeatureGroup,
+    TemporalFeatureDefinition,
+)
+
+
+class FeatureRegistry:
+    """Central registry for feature definitions.
+
+    The FeatureRegistry provides a single source of truth for all feature
+    definitions, ensuring consistency between training and inference.
+
+    Example:
+        >>> registry = FeatureRegistry()
+        >>> registry.register(TemporalFeatureDefinition(
+        ...     name="tenure_months",
+        ...     description="Customer tenure in months",
+        ...     entity_key="customer_id",
+        ...     timestamp_column="feature_timestamp",
+        ... ))
+        >>> registry.get("tenure_months")
+        TemporalFeatureDefinition(name='tenure_months', ...)
+    """
+
+    def __init__(self):
+        """Initialize an empty registry."""
+        self._features: dict[str, TemporalFeatureDefinition] = {}
+        self._groups: dict[str, FeatureGroup] = {}
+        self._metadata: dict[str, Any] = {
+            "created_at": datetime.now().isoformat(),
+            "version": "1.0.0",
+        }
+
+    def register(
+        self,
+        feature: TemporalFeatureDefinition,
+        group_name: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Register a feature definition.
+
+        Args:
+            feature: Feature definition to register
+            group_name: Optional group to add the feature to
+            overwrite: If True, overwrite existing feature with same name
+
+        Raises:
+            ValueError: If feature already exists and overwrite=False
+        """
+        if feature.name in self._features and not overwrite:
+            raise ValueError(
+                f"Feature '{feature.name}' already registered. "
+                "Use overwrite=True to replace."
+            )
+
+        self._features[feature.name] = feature
+
+        if group_name:
+            if group_name not in self._groups:
+                self._groups[group_name] = FeatureGroup(
+                    name=group_name,
+                    description=f"Feature group: {group_name}",
+                    entity_key=feature.entity_key,
+                    timestamp_column=feature.timestamp_column,
+                )
+            self._groups[group_name].add_feature(feature)
+
+    def register_group(self, group: FeatureGroup, overwrite: bool = False) -> None:
+        """Register a feature group with all its features.
+
+        Args:
+            group: Feature group to register
+            overwrite: If True, overwrite existing features
+        """
+        self._groups[group.name] = group
+        for feature in group.features:
+            self.register(feature, overwrite=overwrite)
+
+    def get(self, name: str) -> Optional[TemporalFeatureDefinition]:
+        """Get a feature definition by name.
+
+        Args:
+            name: Feature name
+
+        Returns:
+            Feature definition or None if not found
+        """
+        return self._features.get(name)
+
+    def get_group(self, name: str) -> Optional[FeatureGroup]:
+        """Get a feature group by name.
+
+        Args:
+            name: Group name
+
+        Returns:
+            Feature group or None if not found
+        """
+        return self._groups.get(name)
+
+    def remove(self, name: str) -> bool:
+        """Remove a feature from the registry.
+
+        Args:
+            name: Feature name to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        if name in self._features:
+            del self._features[name]
+            # Also remove from groups
+            for group in self._groups.values():
+                group.features = [f for f in group.features if f.name != name]
+            return True
+        return False
+
+    def list_features(self) -> list[str]:
+        """List all registered feature names.
+
+        Returns:
+            List of feature names
+        """
+        return list(self._features.keys())
+
+    def list_groups(self) -> list[str]:
+        """List all registered group names.
+
+        Returns:
+            List of group names
+        """
+        return list(self._groups.keys())
+
+    def list_by_computation_type(
+        self, computation_type: FeatureComputationType
+    ) -> list[TemporalFeatureDefinition]:
+        """List features by computation type.
+
+        Args:
+            computation_type: Type to filter by
+
+        Returns:
+            List of matching feature definitions
+        """
+        return [
+            f for f in self._features.values()
+            if f.computation_type == computation_type
+        ]
+
+    def list_by_entity(self, entity_key: str) -> list[TemporalFeatureDefinition]:
+        """List features by entity key.
+
+        Args:
+            entity_key: Entity key to filter by
+
+        Returns:
+            List of matching feature definitions
+        """
+        return [
+            f for f in self._features.values()
+            if f.entity_key == entity_key
+        ]
+
+    def list_high_leakage_risk(self) -> list[TemporalFeatureDefinition]:
+        """List features with high leakage risk.
+
+        Returns:
+            List of high-risk feature definitions
+        """
+        return [
+            f for f in self._features.values()
+            if f.leakage_risk == "high"
+        ]
+
+    def validate_features(self, columns: list[str]) -> dict[str, list[str]]:
+        """Validate all features against available columns.
+
+        Args:
+            columns: Available columns in source data
+
+        Returns:
+            Dictionary mapping feature names to missing columns
+        """
+        issues = {}
+        for name, feature in self._features.items():
+            missing = feature.validate_against_schema(columns)
+            if missing:
+                issues[name] = missing
+        return issues
+
+    def get_feature_refs(
+        self,
+        feature_view_name: str,
+        feature_names: Optional[list[str]] = None,
+    ) -> list[str]:
+        """Get Feast-style feature references.
+
+        Args:
+            feature_view_name: Name of the feature view
+            feature_names: Specific features (all if None)
+
+        Returns:
+            List of feature references like "view:feature"
+        """
+        names = feature_names or self.list_features()
+        return [
+            self._features[name].get_feature_ref(feature_view_name)
+            for name in names
+            if name in self._features
+        ]
+
+    def save(self, path: Path) -> None:
+        """Save registry to JSON file.
+
+        Args:
+            path: Path to save to
+        """
+        data = {
+            "metadata": self._metadata,
+            "features": {name: f.to_dict() for name, f in self._features.items()},
+            "groups": {name: g.to_dict() for name, g in self._groups.items()},
+        }
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    @classmethod
+    def load(cls, path: Path) -> "FeatureRegistry":
+        """Load registry from JSON file.
+
+        Args:
+            path: Path to load from
+
+        Returns:
+            Loaded FeatureRegistry
+        """
+        with open(path) as f:
+            data = json.load(f)
+
+        registry = cls()
+        registry._metadata = data.get("metadata", {})
+
+        # Load features
+        for name, feature_data in data.get("features", {}).items():
+            feature = TemporalFeatureDefinition.from_dict(feature_data)
+            registry._features[name] = feature
+
+        # Load groups
+        for name, group_data in data.get("groups", {}).items():
+            group = FeatureGroup(
+                name=group_data["name"],
+                description=group_data["description"],
+                entity_key=group_data.get("entity_key", "customer_id"),
+                timestamp_column=group_data.get("timestamp_column", "feature_timestamp"),
+                source_table=group_data.get("source_table"),
+                tags=group_data.get("tags", {}),
+            )
+            # Link features to group
+            for feature_data in group_data.get("features", []):
+                feature_name = feature_data["name"]
+                if feature_name in registry._features:
+                    group.features.append(registry._features[feature_name])
+            registry._groups[name] = group
+
+        return registry
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert registry to dictionary.
+
+        Returns:
+            Dictionary representation
+        """
+        return {
+            "metadata": self._metadata,
+            "features": {name: f.to_dict() for name, f in self._features.items()},
+            "groups": {name: g.to_dict() for name, g in self._groups.items()},
+        }
+
+    def __len__(self) -> int:
+        """Return number of registered features."""
+        return len(self._features)
+
+    def __contains__(self, name: str) -> bool:
+        """Check if feature is registered."""
+        return name in self._features
+
+
+def create_standard_churn_features() -> FeatureRegistry:
+    """Create a registry with standard churn prediction features.
+
+    This provides a starting point for churn prediction projects
+    with commonly used features.
+
+    Returns:
+        FeatureRegistry with standard features
+    """
+    registry = FeatureRegistry()
+
+    # Demographic features
+    demographic_group = FeatureGroup(
+        name="demographic",
+        description="Customer demographic features",
+        entity_key="customer_id",
+    )
+
+    demographic_group.add_feature(TemporalFeatureDefinition(
+        name="tenure_months",
+        description="Customer tenure in months",
+        entity_key="customer_id",
+        source_columns=["tenure"],
+        computation_type=FeatureComputationType.PASSTHROUGH,
+        data_type="int64",
+        leakage_risk="low",
+    ))
+
+    demographic_group.add_feature(TemporalFeatureDefinition(
+        name="age",
+        description="Customer age",
+        entity_key="customer_id",
+        source_columns=["age"],
+        computation_type=FeatureComputationType.PASSTHROUGH,
+        data_type="int64",
+        leakage_risk="low",
+    ))
+
+    registry.register_group(demographic_group)
+
+    # Behavioral features
+    behavioral_group = FeatureGroup(
+        name="behavioral",
+        description="Customer behavioral features",
+        entity_key="customer_id",
+    )
+
+    behavioral_group.add_feature(TemporalFeatureDefinition(
+        name="total_spend_30d",
+        description="Total spend in last 30 days",
+        entity_key="customer_id",
+        source_columns=["amount"],
+        computation_type=FeatureComputationType.WINDOW,
+        aggregation=TemporalAggregation.SUM,
+        window_days=30,
+        data_type="float64",
+        fill_value=0.0,
+        leakage_risk="low",
+    ))
+
+    behavioral_group.add_feature(TemporalFeatureDefinition(
+        name="transaction_count_30d",
+        description="Number of transactions in last 30 days",
+        entity_key="customer_id",
+        source_columns=["transaction_id"],
+        computation_type=FeatureComputationType.WINDOW,
+        aggregation=TemporalAggregation.COUNT,
+        window_days=30,
+        data_type="int64",
+        fill_value=0,
+        leakage_risk="low",
+    ))
+
+    behavioral_group.add_feature(TemporalFeatureDefinition(
+        name="avg_transaction_amount",
+        description="Average transaction amount",
+        entity_key="customer_id",
+        source_columns=["amount"],
+        computation_type=FeatureComputationType.AGGREGATION,
+        aggregation=TemporalAggregation.MEAN,
+        data_type="float64",
+        leakage_risk="low",
+    ))
+
+    registry.register_group(behavioral_group)
+
+    # Engagement features
+    engagement_group = FeatureGroup(
+        name="engagement",
+        description="Customer engagement features",
+        entity_key="customer_id",
+    )
+
+    engagement_group.add_feature(TemporalFeatureDefinition(
+        name="days_since_last_activity",
+        description="Days since last activity",
+        entity_key="customer_id",
+        source_columns=["last_activity_date", "feature_timestamp"],
+        computation_type=FeatureComputationType.DERIVED,
+        derivation_formula="feature_timestamp - last_activity_date",
+        data_type="int64",
+        leakage_risk="medium",
+        leakage_notes="Ensure last_activity_date is before feature_timestamp",
+    ))
+
+    registry.register_group(engagement_group)
+
+    return registry
+
+
+# Import for convenience
+from .definitions import TemporalAggregation

customer_retention/integrations/iteration/__init__.py

@@ -0,0 +1,28 @@
+from .context import IterationContext, IterationContextManager, IterationStatus, IterationTrigger
+from .feedback_collector import FeatureInsight, ModelFeedback, ModelFeedbackCollector
+from .orchestrator import IterationOrchestrator
+from .recommendation_tracker import (
+    RecommendationStatus,
+    RecommendationTracker,
+    RecommendationType,
+    TrackedRecommendation,
+)
+from .signals import IterationSignal, SignalAggregator, SignalEvent
+
+__all__ = [
+    "IterationStatus",
+    "IterationTrigger",
+    "IterationContext",
+    "IterationContextManager",
+    "RecommendationStatus",
+    "RecommendationType",
+    "TrackedRecommendation",
+    "RecommendationTracker",
+    "ModelFeedback",
+    "FeatureInsight",
+    "ModelFeedbackCollector",
+    "IterationSignal",
+    "SignalEvent",
+    "SignalAggregator",
+    "IterationOrchestrator"
+]

customer_retention/integrations/iteration/context.py

@@ -0,0 +1,212 @@
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+
+class IterationStatus(Enum):
+    EXPLORING = "exploring"
+    TRAINING = "training"
+    EVALUATING = "evaluating"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class IterationTrigger(Enum):
+    INITIAL = "initial"
+    MANUAL = "manual"
+    DRIFT_DETECTED = "drift_detected"
+    PERFORMANCE_DROP = "performance_drop"
+    SCHEDULED = "scheduled"
+
+
+@dataclass
+class IterationContext:
+    iteration_id: str
+    iteration_number: int
+    parent_iteration_id: Optional[str]
+    started_at: datetime
+    status: IterationStatus
+    trigger: IterationTrigger
+    findings_path: str
+    recommendations_path: str
+    model_artifact_path: Optional[str] = None
+    model_metrics: Optional[Dict[str, float]] = None
+    feature_count: int = 0
+    applied_recommendations: List[str] = field(default_factory=list)
+    skipped_recommendations: List[str] = field(default_factory=list)
+    completed_at: Optional[datetime] = None
+
+    @classmethod
+    def create_new(cls, findings_dir: str, trigger: IterationTrigger,
+                   iteration_number: int = 1) -> "IterationContext":
+        iteration_id = str(uuid.uuid4())
+        findings_path = f"{findings_dir}/iterations/findings_{iteration_id}.yaml"
+        recommendations_path = f"{findings_dir}/iterations/recommendations_{iteration_id}.yaml"
+        return cls(
+            iteration_id=iteration_id,
+            iteration_number=iteration_number,
+            parent_iteration_id=None,
+            started_at=datetime.now(),
+            status=IterationStatus.EXPLORING,
+            trigger=trigger,
+            findings_path=findings_path,
+            recommendations_path=recommendations_path,
+            applied_recommendations=[],
+            skipped_recommendations=[]
+        )
+
+    def create_child(self, trigger: IterationTrigger) -> "IterationContext":
+        findings_dir = str(Path(self.findings_path).parent.parent)
+        child = IterationContext.create_new(
+            findings_dir=findings_dir,
+            trigger=trigger,
+            iteration_number=self.iteration_number + 1
+        )
+        child.parent_iteration_id = self.iteration_id
+        return child
+
+    def update_status(self, status: IterationStatus) -> None:
+        self.status = status
+        if status == IterationStatus.COMPLETED:
+            self.completed_at = datetime.now()
+
+    def set_model_metrics(self, metrics: Dict[str, float],
+                          artifact_path: Optional[str] = None) -> None:
+        self.model_metrics = metrics
+        if artifact_path:
+            self.model_artifact_path = artifact_path
+
+    def add_applied_recommendation(self, recommendation_id: str) -> None:
+        if recommendation_id not in self.applied_recommendations:
+            self.applied_recommendations.append(recommendation_id)
+
+    def add_skipped_recommendation(self, recommendation_id: str) -> None:
+        if recommendation_id not in self.skipped_recommendations:
+            self.skipped_recommendations.append(recommendation_id)
+
+    def get_iteration_filename(self) -> str:
+        short_id = self.iteration_id[:8]
+        return f"iteration_{self.iteration_number:03d}_{short_id}.yaml"
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {
+            "iteration_id": self.iteration_id,
+            "iteration_number": self.iteration_number,
+            "parent_iteration_id": self.parent_iteration_id,
+            "started_at": self.started_at.isoformat(),
+            "status": self.status.value,
+            "trigger": self.trigger.value,
+            "findings_path": self.findings_path,
+            "recommendations_path": self.recommendations_path,
+            "model_artifact_path": self.model_artifact_path,
+            "model_metrics": self.model_metrics,
+            "feature_count": self.feature_count,
+            "applied_recommendations": self.applied_recommendations,
+            "skipped_recommendations": self.skipped_recommendations,
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None
+        }
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "IterationContext":
+        return cls(
+            iteration_id=data["iteration_id"],
+            iteration_number=data["iteration_number"],
+            parent_iteration_id=data.get("parent_iteration_id"),
+            started_at=datetime.fromisoformat(data["started_at"]),
+            status=IterationStatus(data["status"]),
+            trigger=IterationTrigger(data["trigger"]),
+            findings_path=data["findings_path"],
+            recommendations_path=data["recommendations_path"],
+            model_artifact_path=data.get("model_artifact_path"),
+            model_metrics=data.get("model_metrics"),
+            feature_count=data.get("feature_count", 0),
+            applied_recommendations=data.get("applied_recommendations", []),
+            skipped_recommendations=data.get("skipped_recommendations", []),
+            completed_at=datetime.fromisoformat(data["completed_at"]) if data.get("completed_at") else None
+        )
+
+    def save(self, path: str) -> None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            yaml.dump(self.to_dict(), f, default_flow_style=False, sort_keys=False)
+
+    @classmethod
+    def load(cls, path: str) -> "IterationContext":
+        with open(path, "r") as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data)
+
+    def compare(self, other: "IterationContext") -> Dict[str, Any]:
+        comparison = {
+            "iteration_diff": self.iteration_number - other.iteration_number,
+            "metric_changes": {},
+            "feature_count_change": self.feature_count - other.feature_count,
+            "new_recommendations": [
+                r for r in self.applied_recommendations
+                if r not in other.applied_recommendations
+            ]
+        }
+        if self.model_metrics and other.model_metrics:
+            for metric, value in self.model_metrics.items():
+                if metric in other.model_metrics:
+                    comparison["metric_changes"][metric] = value - other.model_metrics[metric]
+        return comparison
+
+
+class IterationContextManager:
+    def __init__(self, iterations_dir: str):
+        self.iterations_dir = Path(iterations_dir)
+        self._current_path = self.iterations_dir / "current_iteration.yaml"
+
+    def list_iterations(self) -> List[IterationContext]:
+        iterations = []
+        for path in self.iterations_dir.glob("iteration_*.yaml"):
+            if path.name != "current_iteration.yaml":
+                iterations.append(IterationContext.load(str(path)))
+        iterations.sort(key=lambda x: x.iteration_number)
+        return iterations
+
+    def get_current(self) -> Optional[IterationContext]:
+        if not self._current_path.exists():
+            return None
+        with open(self._current_path, "r") as f:
+            data = yaml.safe_load(f)
+        current_id = data.get("current_iteration_id")
+        if current_id:
+            return self.get_by_id(current_id)
+        return None
+
+    def set_current(self, iteration_id: str) -> None:
+        with open(self._current_path, "w") as f:
+            yaml.dump({"current_iteration_id": iteration_id}, f)
+
+    def get_by_id(self, iteration_id: str) -> Optional[IterationContext]:
+        for path in self.iterations_dir.glob("iteration_*.yaml"):
+            if path.name == "current_iteration.yaml":
+                continue
+            ctx = IterationContext.load(str(path))
+            if ctx.iteration_id == iteration_id:
+                return ctx
+        return None
+
+    def get_iteration_history(self, iteration_id: str) -> List[IterationContext]:
+        history = []
+        current = self.get_by_id(iteration_id)
+        while current is not None:
+            history.insert(0, current)
+            if current.parent_iteration_id:
+                current = self.get_by_id(current.parent_iteration_id)
+            else:
+                current = None
+        return history
+
+    def save_iteration(self, ctx: IterationContext) -> str:
+        path = self.iterations_dir / ctx.get_iteration_filename()
+        ctx.save(str(path))
+        return str(path)