churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/visualization/console.py

@@ -0,0 +1,122 @@
+"""Console output utilities using Markdown for rich formatting."""
+
+from typing import Any, Dict, List, Optional
+
+try:
+    from IPython.display import Markdown, display
+    HAS_IPYTHON = True
+except ImportError:
+    HAS_IPYTHON = False
+
+_buffer: List[str] = []
+_auto_flush = True
+
+
+def _add(line: str) -> None:
+    if _auto_flush:
+        if HAS_IPYTHON:
+            display(Markdown(line))
+        else:
+            print(line)
+    else:
+        _buffer.append(line)
+
+
+def _bar(value: float, width: int = 20) -> str:
+    value = max(0, min(100, value))
+    filled = int(value / 100 * width)
+    if value >= 100:
+        return "█" * width
+    return "█" * filled + "░" * (width - filled)
+
+
+def start_section() -> None:
+    global _auto_flush
+    _auto_flush = False
+    _buffer.clear()
+
+
+def end_section() -> None:
+    global _auto_flush
+    if _buffer:
+        text = "  \n".join(_buffer)
+        if HAS_IPYTHON:
+            display(Markdown(text))
+        else:
+            print("\n".join(_buffer))
+    _buffer.clear()
+    _auto_flush = True
+
+
+def header(text: str) -> None:
+    _add(f"#### {text.upper()}")
+
+
+def subheader(text: str) -> None:
+    _add(f"**{text}**")
+
+
+def success(text: str) -> None:
+    _add(f"[OK] {text}")
+
+
+def warning(text: str) -> None:
+    _add(f"[!] {text}")
+
+
+def error(text: str) -> None:
+    _add(f"[X] {text}")
+
+
+def info(text: str) -> None:
+    _add(f"*(i) {text}*")
+
+
+def metric(label: str, value: Any) -> None:
+    _add(f"{label}: **{value}**")
+
+
+def kv(data: Dict[str, Any], inline: bool = False) -> None:
+    if inline:
+        parts = [f"{k}: **{v}**" for k, v in data.items()]
+        _add(" | ".join(parts))
+    else:
+        for k, v in data.items():
+            _add(f"{k}: **{v}**")
+
+
+def bullets(items: List[str]) -> None:
+    for item in items:
+        _add(f"- {item}")
+
+
+def numbers(items: List[str]) -> None:
+    for i, item in enumerate(items, 1):
+        _add(f"{i}. {item}")
+
+
+def score(value: float, label: str = "Score") -> None:
+    rating = "Excellent" if value >= 90 else "Good" if value >= 70 else "Fair" if value >= 50 else "Poor"
+    _add(f"{label}: `{_bar(value, 25)}` **{value:.0f}/100** ({rating})")
+
+
+def progress(label: str, value: float) -> None:
+    _add(f"{label}: `{_bar(value, 15)}` **{value:.1f}%**")
+
+
+def check(name: str, passed: bool, detail: Optional[str] = None) -> None:
+    icon = "[OK]" if passed else "[X]"
+    line = f"{icon} {name}"
+    if detail:
+        line += f" — {detail}"
+    _add(line)
+
+
+def overview(rows: int, cols: int, memory_mb: float, completeness: float,
+             target: Optional[str] = None) -> None:
+    _add(f"Rows: **{rows:,}**")
+    _add(f"Columns: **{cols}**")
+    _add(f"Memory: **{memory_mb:.1f} MB**")
+    _add(f"Completeness: `{_bar(completeness, 15)}` **{completeness:.1f}%**")
+    if target:
+        _add(f"Target: **{target}**")

customer_retention/analysis/visualization/display.py

@@ -0,0 +1,171 @@
+import os
+from typing import Any, Optional
+
+
+def get_ipython():
+    from IPython import get_ipython as _get_ipython
+    return _get_ipython()
+
+
+def detect_environment() -> str:
+    if "DATABRICKS_RUNTIME_VERSION" in os.environ:
+        return "databricks"
+    try:
+        shell = get_ipython()
+        if shell is not None:
+            shell_name = shell.__class__.__name__
+            if "ZMQInteractiveShell" in shell_name:
+                return "jupyter"
+            elif "TerminalInteractiveShell" in shell_name:
+                return "ipython"
+    except (ImportError, NameError, AttributeError):
+        pass
+    return "terminal"
+
+
+class DisplayManager:
+    @staticmethod
+    def detect_environment() -> str:
+        return detect_environment()
+
+    @staticmethod
+    def format_number(value: float, decimals: int = 0) -> str:
+        if decimals > 0:
+            return f"{value:,.{decimals}f}"
+        return f"{int(value):,}"
+
+    @staticmethod
+    def format_percentage(value: float, decimals: int = 1) -> str:
+        return f"{value * 100:.{decimals}f}%"
+
+    @staticmethod
+    def get_completeness_color(pct: float) -> str:
+        if pct >= 95:
+            return "#2ca02c"  # green
+        if pct >= 80:
+            return "#ff7f0e"  # orange
+        return "#d62728"  # red
+
+    @staticmethod
+    def format_memory(bytes_size: int) -> str:
+        if bytes_size >= 1024 ** 3:
+            return f"{bytes_size / (1024 ** 3):.1f} GB"
+        if bytes_size >= 1024 ** 2:
+            return f"{bytes_size / (1024 ** 2):.1f} MB"
+        if bytes_size >= 1024:
+            return f"{bytes_size / 1024:.1f} KB"
+        return f"{bytes_size} B"
+
+    @staticmethod
+    def create_summary_html(source_path: str, row_count: int, column_count: int,
+                            completeness_pct: float, memory_bytes: int) -> str:
+        completeness_color = DisplayManager.get_completeness_color(completeness_pct)
+        memory_str = DisplayManager.format_memory(memory_bytes)
+        return f"""
+        <div style="font-family: sans-serif; padding: 20px; color: #333;">
+            <h2 style="color: #222;">Data Exploration: {source_path}</h2>
+            <div style="display: flex; gap: 20px; margin-bottom: 20px;">
+                <div style="background: #f0f0f0; padding: 15px; border-radius: 8px;">
+                    <h4 style="margin: 0 0 8px 0; color: #555;">Rows</h4>
+                    <span style="font-size: 24px; font-weight: bold; color: #222;">{row_count:,}</span>
+                </div>
+                <div style="background: #f0f0f0; padding: 15px; border-radius: 8px;">
+                    <h4 style="margin: 0 0 8px 0; color: #555;">Columns</h4>
+                    <span style="font-size: 24px; font-weight: bold; color: #222;">{column_count}</span>
+                </div>
+                <div style="background: #f0f0f0; padding: 15px; border-radius: 8px;">
+                    <h4 style="margin: 0 0 8px 0; color: #555;">Completeness</h4>
+                    <span style="font-size: 24px; font-weight: bold; color: {completeness_color};">{completeness_pct:.1f}%</span>
+                </div>
+                <div style="background: #f0f0f0; padding: 15px; border-radius: 8px;">
+                    <h4 style="margin: 0 0 8px 0; color: #555;">Memory</h4>
+                    <span style="font-size: 24px; font-weight: bold; color: #222;">{memory_str}</span>
+                </div>
+            </div>
+        </div>
+        """
+
+
+def display_figure(fig: Any, title: Optional[str] = None, width: Optional[int] = None, height: Optional[int] = None):
+    env = detect_environment()
+    if hasattr(fig, "update_layout"):
+        if title:
+            fig.update_layout(title=title)
+        if width:
+            fig.update_layout(width=width)
+        if height:
+            fig.update_layout(height=height)
+        if env in ["databricks", "jupyter", "ipython"]:
+            # Disable responsive mode to respect explicit width/height
+            fig.show(config={"responsive": False})
+        else:
+            import tempfile
+            import webbrowser
+            with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as f:
+                fig.write_html(f.name, config={"responsive": False})
+                webbrowser.open(f"file://{f.name}")
+    elif hasattr(fig, "savefig"):
+        import matplotlib.pyplot as plt
+        if title:
+            fig.suptitle(title)
+        plt.show()
+
+
+def display_table(df: Any, max_rows: int = 50, title: Optional[str] = None):
+    """Display a pandas DataFrame in the appropriate format for the current environment."""
+    env = detect_environment()
+    if env in ["databricks", "jupyter", "ipython"]:
+        try:
+            from IPython.display import HTML, display
+            if title:
+                display(HTML(f"<h4>{title}</h4>"))
+            if hasattr(df, "to_html"):
+                html = df.head(max_rows).to_html(classes="table table-striped", index=False)
+                display(HTML(html))
+            else:
+                display(df)
+        except ImportError:
+            print(df.head(max_rows).to_string() if hasattr(df, "to_string") else str(df))
+    else:
+        if title:
+            print(f"\n{title}")
+            print("-" * len(title))
+        if hasattr(df, "to_string"):
+            print(df.head(max_rows).to_string())
+        else:
+            print(df)
+
+
+def display_summary(findings: Any, charts: Any):
+    env = detect_environment()
+
+    # Calculate completeness (average of non-null percentages across columns)
+    completeness_scores = []
+    for col in findings.columns.values():
+        null_pct = col.universal_metrics.get("null_percentage", 0)
+        completeness_scores.append(100 - null_pct)
+    completeness_pct = sum(completeness_scores) / len(completeness_scores) if completeness_scores else 100.0
+
+    # Get memory usage (stored in MB, convert to bytes for display formatting)
+    memory_mb = getattr(findings, 'memory_usage_mb', 0)
+    if memory_mb > 0:
+        memory_bytes = int(memory_mb * 1024 * 1024)
+    else:
+        # Rough estimate: row_count * column_count * 8 bytes average per cell
+        memory_bytes = findings.row_count * findings.column_count * 8
+
+    html = DisplayManager.create_summary_html(
+        findings.source_path,
+        findings.row_count,
+        findings.column_count,
+        completeness_pct,
+        memory_bytes
+    )
+    if env in ["databricks", "jupyter", "ipython"]:
+        try:
+            from IPython.display import HTML, display
+            display(HTML(html))
+        except ImportError:
+            print(html)
+    else:
+        print(html)

customer_retention/analysis/visualization/number_formatter.py

@@ -0,0 +1,36 @@
+from typing import Tuple
+
+
+class NumberFormatter:
+    SUFFIXES: Tuple[Tuple[float, str], ...] = (
+        (1e12, "T"),
+        (1e9, "B"),
+        (1e6, "M"),
+        (1e3, "K"),
+    )
+
+    def compact(self, value: float, precision: int = 2) -> str:
+        if value == 0:
+            return f"{value:.{precision}f}"
+
+        sign = "-" if value < 0 else ""
+        abs_value = abs(value)
+
+        for threshold, suffix in self.SUFFIXES:
+            if abs_value >= threshold:
+                scaled = abs_value / threshold
+                return f"{sign}{scaled:.{precision}f}{suffix}"
+
+        return f"{sign}{abs_value:.{precision}f}"
+
+    def percentage(self, value: float, precision: int = 2, show_sign: bool = True) -> str:
+        sign = "+" if value >= 0 and show_sign else ""
+        return f"{sign}{value:.{precision}f}%"
+
+    def rate(self, value: float, suffix: str, precision: int = 2) -> str:
+        sign = "+" if value >= 0 else ""
+        return f"{sign}{value:.{precision}f}{suffix}"
+
+    def plotly_format(self, precision: int = 2, show_sign: bool = True) -> str:
+        sign_char = "+" if show_sign else ""
+        return f"{sign_char}.{precision}f"

customer_retention/artifacts/__init__.py

@@ -0,0 +1,3 @@
+from .fit_artifact_registry import FitArtifact, FitArtifactRegistry
+
+__all__ = ["FitArtifact", "FitArtifactRegistry"]

customer_retention/artifacts/fit_artifact_registry.py

@@ -0,0 +1,146 @@
+import hashlib
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import joblib
+import numpy as np
+import yaml
+
+
+def _extract_transformer_params(transformer: Any) -> Dict[str, Any]:
+    params = {}
+    for attr in ["mean_", "scale_", "var_", "data_min_", "data_max_", "data_range_",
+                 "classes_", "n_features_in_", "components_", "explained_variance_ratio_",
+                 "explained_variance_", "singular_values_", "n_components_"]:
+        if hasattr(transformer, attr):
+            val = getattr(transformer, attr)
+            if isinstance(val, np.ndarray):
+                params[attr] = val.tolist()
+            else:
+                params[attr] = val
+    return params
+
+
+def _compute_params_hash(params: Dict[str, Any]) -> str:
+    serialized = str(sorted(params.items()))
+    return hashlib.sha256(serialized.encode()).hexdigest()[:16]
+
+
+@dataclass
+class FitArtifact:
+    artifact_id: str
+    artifact_type: str
+    target_column: str
+    transformer_class: str
+    fit_timestamp: str
+    fit_data_hash: str
+    parameters: Dict[str, Any]
+    file_path: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "artifact_id": self.artifact_id,
+            "artifact_type": self.artifact_type,
+            "target_column": self.target_column,
+            "transformer_class": self.transformer_class,
+            "fit_timestamp": self.fit_timestamp,
+            "fit_data_hash": self.fit_data_hash,
+            "parameters": self.parameters,
+            "file_path": self.file_path,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FitArtifact":
+        return cls(
+            artifact_id=data["artifact_id"],
+            artifact_type=data["artifact_type"],
+            target_column=data["target_column"],
+            transformer_class=data["transformer_class"],
+            fit_timestamp=data["fit_timestamp"],
+            fit_data_hash=data["fit_data_hash"],
+            parameters=data.get("parameters", {}),
+            file_path=data.get("file_path"),
+        )
+
+
+@dataclass
+class FitArtifactRegistry:
+    artifacts_dir: Path
+    _artifacts: Dict[str, FitArtifact] = field(default_factory=dict, repr=False)
+
+    ARTIFACT_SUBDIRS = {"scaler": "scalers", "encoder": "encoders", "reducer": "reducers"}
+
+    def __post_init__(self):
+        self.artifacts_dir = Path(self.artifacts_dir)
+        self.artifacts_dir.mkdir(parents=True, exist_ok=True)
+        for subdir in self.ARTIFACT_SUBDIRS.values():
+            (self.artifacts_dir / subdir).mkdir(exist_ok=True)
+
+    def register(self, artifact_type: str, target_column: str, transformer: Any,
+                 artifact_id: Optional[str] = None, overwrite: bool = False) -> str:
+        if artifact_type not in self.ARTIFACT_SUBDIRS:
+            raise ValueError(f"Unknown artifact type: {artifact_type}. Must be one of {list(self.ARTIFACT_SUBDIRS.keys())}")
+        generated_id = artifact_id or f"{target_column}_{artifact_type}"
+        if generated_id in self._artifacts and not overwrite:
+            raise ValueError(f"Artifact '{generated_id}' already exists. Use overwrite=True to replace.")
+        params = _extract_transformer_params(transformer)
+        subdir = self.ARTIFACT_SUBDIRS[artifact_type]
+        file_path = f"{subdir}/{generated_id}.pkl"
+        full_path = self.artifacts_dir / file_path
+        joblib.dump(transformer, full_path)
+        artifact = FitArtifact(
+            artifact_id=generated_id,
+            artifact_type=artifact_type,
+            target_column=target_column,
+            transformer_class=type(transformer).__name__,
+            fit_timestamp=datetime.now().isoformat(),
+            fit_data_hash=_compute_params_hash(params),
+            parameters=params,
+            file_path=file_path,
+        )
+        self._artifacts[generated_id] = artifact
+        return generated_id
+
+    def load(self, artifact_id: str) -> Any:
+        if artifact_id not in self._artifacts:
+            raise KeyError(f"Artifact '{artifact_id}' not found in registry")
+        artifact = self._artifacts[artifact_id]
+        full_path = self.artifacts_dir / artifact.file_path
+        return joblib.load(full_path)
+
+    def get_manifest(self) -> Dict[str, FitArtifact]:
+        return self._artifacts.copy()
+
+    def has_artifact(self, artifact_id: str) -> bool:
+        return artifact_id in self._artifacts
+
+    def get_artifact_info(self, artifact_id: str) -> FitArtifact:
+        if artifact_id not in self._artifacts:
+            raise KeyError(f"Artifact '{artifact_id}' not found")
+        return self._artifacts[artifact_id]
+
+    def save_manifest(self) -> None:
+        manifest_data = {
+            "version": "1.0",
+            "created_at": datetime.now().isoformat(),
+            "artifacts": {aid: a.to_dict() for aid, a in self._artifacts.items()},
+        }
+        manifest_path = self.artifacts_dir / "manifest.yaml"
+        with open(manifest_path, "w") as f:
+            yaml.dump(manifest_data, f, default_flow_style=False, sort_keys=False)
+
+    @classmethod
+    def load_manifest(cls, manifest_path: Path) -> "FitArtifactRegistry":
+        manifest_path = Path(manifest_path)
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"Manifest not found: {manifest_path}")
+        with open(manifest_path) as f:
+            data = yaml.safe_load(f)
+        artifacts_dir = manifest_path.parent
+        registry = cls(artifacts_dir=artifacts_dir)
+        registry._artifacts = {}
+        for aid, artifact_data in data.get("artifacts", {}).items():
+            registry._artifacts[aid] = FitArtifact.from_dict(artifact_data)
+        return registry

customer_retention/cli.py

@@ -0,0 +1,93 @@
+"""
+CLI commands for churnkit package.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def init_project() -> int:
+    """CLI entry point for project initialization."""
+    import argparse
+
+    from customer_retention.generators.notebook_generator import (
+        Platform,
+        ProjectInitializer,
+    )
+
+    parser = argparse.ArgumentParser(
+        description="Bootstrap a new customer retention project",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Create project in current directory
+    churnkit-init
+
+    # Create in specific directory
+    churnkit-init --output ./my_churn_analysis
+
+    # With customization
+    churnkit-init --output ./my_project --name "Customer Churn Analysis"
+        """,
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        default=Path.cwd(),
+        help="Output directory (default: current)",
+    )
+    parser.add_argument("--name", "-n", help="Project name")
+    parser.add_argument(
+        "--platform",
+        choices=["local", "databricks", "both"],
+        default="both",
+        help="Target platform (default: both)",
+    )
+
+    args = parser.parse_args()
+
+    print("\n" + "=" * 50)
+    print("Customer Retention Project Bootstrap")
+    print("=" * 50 + "\n")
+
+    output_dir = args.output.resolve()
+    print(f"Output: {output_dir}\n")
+
+    # Determine platforms
+    if args.platform == "both":
+        platforms = [Platform.LOCAL, Platform.DATABRICKS]
+    elif args.platform == "local":
+        platforms = [Platform.LOCAL]
+    else:
+        platforms = [Platform.DATABRICKS]
+
+    # Initialize project using library
+    try:
+        initializer = ProjectInitializer(output_dir)
+        initializer.initialize(
+            project_name=args.name,
+            platforms=platforms,
+        )
+
+        print("\n" + "=" * 50)
+        print("Done!")
+        print("=" * 50)
+        print("\nNext steps:")
+        print(f"  1. cd {output_dir}")
+        print("  2. Add your data to experiments/data/")
+        print("  3. Open exploration_notebooks/01_data_discovery.ipynb")
+        print("  4. Set DATA_PATH to your data file")
+        print("  5. Run all cells - auto-discovery will do the rest!")
+        print()
+
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(init_project())