churnkit 1.2.8a6__tar.gz → 1.2.8a8__tar.gz

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: churnkit
-Version: 1.2.8a6
+Version: 1.2.8a8
 Summary: Structured ML framework for customer churn prediction -- from exploration notebooks to production pipelines, locally or on Databricks.
 Project-URL: Homepage, https://github.com/aladjov/CR
 Project-URL: Documentation, https://github.com/aladjov/CR/wiki

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/apps/databricks_app/src/accounts_view.py

@@ -6,9 +6,10 @@ available — click a header to resort.
 """
 from __future__ import annotations
 
+import pandas as pd
 import streamlit as st
 
-from . import data, state
+from . import auth, data, state
 
 _TIER_GLYPH = {"Low": "● ", "Medium": "● ", "High": "● "}  # dot prefix, coloured via column_config? Streamlit doesn't style per-row — use unicode dots.
 
@@ -20,6 +21,25 @@ def _tier_label(tier) -> str:
     return f"{glyph}  {tier}"
 
 
+def _assignment_label(assigned_to, me: str | None) -> str:
+    """Render the ``assigned_to`` cell.
+
+    ``Mine`` is reserved for the current user so a CSM can scan their own
+    column at a glance; everyone else surfaces the local-part of their
+    email (``jane.doe`` from ``jane.doe@churnkit.com``) for compactness.
+    Returns an empty string for unassigned rows so the column visually
+    recedes when most rows are blank.
+    """
+    if assigned_to is None or (isinstance(assigned_to, float) and pd.isna(assigned_to)):
+        return ""
+    text = str(assigned_to).strip()
+    if not text:
+        return ""
+    if me and text.lower() == me.lower():
+        return "Mine"
+    return text.split("@", 1)[0] if "@" in text else text
+
+
 def render() -> None:
     pb = state.get("selected_playbook")
     ar = state.get("selected_archetype")
@@ -29,13 +49,34 @@ def render() -> None:
         st.info("No accounts in this scope.")
         return
 
+    # Left-merge the cached assignments frame so the In-scope table can
+    # surface "Mine" / owner handle / blank without modifying the upstream
+    # ``v_eligible_all_playbooks`` view. Empty assignments DataFrame leaves
+    # every row unassigned.
+    me = auth.current_user_email()
+    try:
+        assigns = data.assignments()
+    except Exception:
+        assigns = pd.DataFrame(columns=["entity_id", "assigned_to"])
+    if assigns is None or assigns.empty:
+        df = df.assign(assigned_to=None)
+    else:
+        df = df.merge(
+            assigns[["entity_id", "assigned_to"]],
+            on="entity_id",
+            how="left",
+        )
+
     display = df[[
         "entity_id", "churn_probability", "expected_loss", "value_at_risk",
         "risk_tier", "archetype_name",
         "policy_rank_among_eligible", "eligible_playbook_count",
-        "recommended", "is_holdout",
+        "recommended", "is_holdout", "assigned_to",
     ]].copy()
     display["risk_tier"] = display["risk_tier"].map(_tier_label)
+    display["assigned_to"] = display["assigned_to"].map(
+        lambda v: _assignment_label(v, me)
+    )
 
     display = display.rename(columns={
         "entity_id":                  "Entity",
@@ -48,6 +89,7 @@ def render() -> None:
         "eligible_playbook_count":    "Plays",
         "recommended":                "Rec.",
         "is_holdout":                 "Holdout",
+        "assigned_to":                "Assigned to",
     })
 
     col_config = {
@@ -61,6 +103,10 @@ def render() -> None:
         "Plays":         st.column_config.NumberColumn(format="%d", width="small"),
         "Rec.":          st.column_config.CheckboxColumn(width="small"),
         "Holdout":       st.column_config.CheckboxColumn(width="small"),
+        "Assigned to":   st.column_config.TextColumn(
+            width="small",
+            help="CSM who has self-assigned this account. 'Mine' = you.",
+        ),
     }
 
     event = st.dataframe(

churnkit-1.2.8a8/apps/databricks_app/src/auth.py

@@ -0,0 +1,71 @@
+"""Identity helpers for the Streamlit app.
+
+Databricks Apps inject the OAuth-authenticated user's identity into every
+inbound request as ``X-Forwarded-*`` headers. Streamlit exposes those via
+``st.context.headers`` (>=1.37). The notebook-side ``get_current_username``
+in ``customer_retention.analysis.auto_explorer.session`` is NOT reusable
+here -- it reads ``DATABRICKS_USERNAME`` (set only inside notebook tasks)
+and falls back to ``getpass.getuser`` (the App service principal, identical
+for everyone). The App needs request-scoped resolution.
+
+Resolution order for ``current_user_email``:
+  1. ``X-Forwarded-Email`` request header  (production)
+  2. ``st.experimental_user.email``         (Streamlit-native fallback)
+  3. ``CR_USER`` env var                    (local dev / tests)
+  4. ``None``                               (caller decides whether to block)
+
+``current_user_handle`` returns the local-part of the email (``jane.doe``
+from ``jane.doe@churnkit.com``) for compact display in tables and button
+labels. Falls back to ``getpass.getuser()`` when no email is resolvable so
+local dev still works without setting any env vars.
+
+Streamlit is imported lazily so this module loads cleanly in the test
+venv (which intentionally omits the live-app dependencies).
+"""
+from __future__ import annotations
+
+import getpass
+import os
+
+
+def _from_request_header() -> str | None:
+    try:
+        import streamlit as st  # noqa: PLC0415 - lazy so the module imports without streamlit
+        email = st.context.headers.get("X-Forwarded-Email")
+    except Exception:
+        return None
+    return email.strip().lower() if email else None
+
+
+def _from_streamlit_user() -> str | None:
+    try:
+        import streamlit as st  # noqa: PLC0415
+        email = getattr(st.experimental_user, "email", None)
+    except Exception:
+        return None
+    return email.strip().lower() if email else None
+
+
+def _from_env() -> str | None:
+    raw = os.environ.get("CR_USER")
+    return raw.strip().lower() if raw else None
+
+
+def current_user_email() -> str | None:
+    """Return the logged-in user's email, or ``None`` when not resolvable."""
+    return _from_request_header() or _from_streamlit_user() or _from_env()
+
+
+def current_user_handle() -> str:
+    """Short display handle for the logged-in user.
+
+    ``jane.doe@churnkit.com`` -> ``jane.doe``. Falls back to the OS username
+    when no email is available so local dev without ``CR_USER`` still
+    renders something deterministic.
+    """
+    email = current_user_email()
+    if email and "@" in email:
+        return email.split("@", 1)[0]
+    if email:
+        return email
+    return getpass.getuser()

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/apps/databricks_app/src/data.py

@@ -320,3 +320,169 @@ def run_history() -> pd.DataFrame:
         ORDER BY as_of_date DESC
         LIMIT 20
     """)
+
+
+# ---------------------------------------------------------------------------
+# Self-assignment — ``account_assignments`` Delta table
+# ---------------------------------------------------------------------------
+# A CSM clicks "Assign to me" on the L4 customer profile to claim ownership
+# of an account. One row per assigned entity: no row means unassigned. The
+# table is additive (no view modification, no schema migration) and lazy-
+# created on first read or write so the dashboard can drop into existing
+# deployments without an out-of-band DDL step.
+#
+# Race semantics: two CSMs clicking the same unassigned entity within the
+# same second land on a Delta MERGE with ``WHEN NOT MATCHED THEN INSERT``,
+# so exactly one INSERT wins and the loser's next rerun reads the winner's
+# row and renders "Claimed by …". Unassign is restricted to the current
+# owner -- you cannot clear someone else's claim from the UI.
+_ASSIGNMENTS_TABLE = "account_assignments"
+
+_TOGGLE_ASSIGNED = "assigned"
+_TOGGLE_UNASSIGNED = "unassigned"
+_TOGGLE_CLAIMED_BY_OTHER = "claimed_by_other"
+
+
+def _assignments_fqn(cfg: AppConfig) -> str:
+    return f"{cfg.fqn_prefix}.{_ASSIGNMENTS_TABLE}"
+
+
+def _ensure_assignments_table(cfg: AppConfig) -> None:
+    """Idempotent ``CREATE TABLE IF NOT EXISTS`` for the assignments table.
+
+    Runs once per process — the Streamlit session keeps a flag so we don't
+    fire DDL on every rerun. Safe to call concurrently: ``CREATE TABLE IF
+    NOT EXISTS`` is a no-op on a pre-existing table.
+    """
+    flag_key = f"_assignments_table_ready::{cfg.fqn_prefix}"
+    try:
+        if st.session_state.get(flag_key):
+            return
+    except Exception:
+        pass
+    with _connect(cfg) as conn:
+        cur = conn.cursor()
+        try:
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {_assignments_fqn(cfg)} (
+                    entity_id    STRING NOT NULL,
+                    assigned_to  STRING NOT NULL,
+                    assigned_at  TIMESTAMP NOT NULL
+                ) USING DELTA
+            """)
+        finally:
+            cur.close()
+    try:
+        st.session_state[flag_key] = True
+    except Exception:
+        pass
+
+
+@st.cache_data(ttl=10, show_spinner=False)
+def assignments() -> pd.DataFrame:
+    """Return all current account assignments.
+
+    Two columns: ``entity_id`` and ``assigned_to`` (the owner's email).
+    Cached for 10s so the In-scope table stays fresh without hammering the
+    warehouse on every rerun. Bust the cache via ``data.assignments.clear()``
+    after a toggle so the UI reflects the change immediately.
+
+    Returns an empty DataFrame on the first call before any rows exist —
+    callers can safely left-merge against it.
+    """
+    cfg = load_config()
+    _ensure_assignments_table(cfg)
+    return _query(
+        cfg,
+        f"SELECT entity_id, assigned_to FROM {_assignments_fqn(cfg)}",
+    )
+
+
+def toggle_assignment(entity_id: str, user_email: str) -> str:
+    """Self-assign or unassign ``entity_id`` for ``user_email``.
+
+    Returns one of:
+      - ``"assigned"``           — row was inserted (entity now owned by user)
+      - ``"unassigned"``         — row was deleted (user released their own claim)
+      - ``"claimed_by_other"``   — entity is owned by someone else; no DML
+
+    The MERGE-on-INSERT path protects against the read-then-write race
+    where another CSM claimed the entity between our SELECT and our
+    INSERT: ``WHEN NOT MATCHED`` collapses to a no-op and we surface
+    ``claimed_by_other`` on the next rerun via the cached read.
+    """
+    if not entity_id or not user_email:
+        raise ValueError("entity_id and user_email are required")
+    cfg = load_config()
+    _ensure_assignments_table(cfg)
+    fqn = _assignments_fqn(cfg)
+    user = user_email.strip().lower()
+
+    with _connect(cfg) as conn:
+        cur = conn.cursor()
+        try:
+            cur.execute(
+                f"SELECT assigned_to FROM {fqn} WHERE entity_id = :eid LIMIT 1",
+                {"eid": entity_id},
+            )
+            rows = cur.fetchall()
+            current = rows[0][0] if rows else None
+
+            if current is not None and current.strip().lower() != user:
+                return _TOGGLE_CLAIMED_BY_OTHER
+
+            if current is not None:
+                cur.execute(
+                    f"DELETE FROM {fqn} WHERE entity_id = :eid AND assigned_to = :user",
+                    {"eid": entity_id, "user": user},
+                )
+                return _TOGGLE_UNASSIGNED
+
+            # No prior row -- MERGE so a concurrent claim by another CSM
+            # cannot produce a duplicate row. The source row carries the
+            # candidate (entity, user, now()); the target only inserts when
+            # ``entity_id`` is still absent.
+            cur.execute(
+                f"""
+                MERGE INTO {fqn} t
+                USING (
+                    SELECT :eid AS entity_id, :user AS assigned_to, current_timestamp() AS assigned_at
+                ) s
+                ON t.entity_id = s.entity_id
+                WHEN NOT MATCHED THEN INSERT (entity_id, assigned_to, assigned_at)
+                                  VALUES (s.entity_id, s.assigned_to, s.assigned_at)
+                """,
+                {"eid": entity_id, "user": user},
+            )
+
+            cur.execute(
+                f"SELECT assigned_to FROM {fqn} WHERE entity_id = :eid LIMIT 1",
+                {"eid": entity_id},
+            )
+            verify = cur.fetchall()
+            winner = verify[0][0] if verify else None
+            if winner is None:
+                return _TOGGLE_CLAIMED_BY_OTHER
+            if winner.strip().lower() == user:
+                return _TOGGLE_ASSIGNED
+            return _TOGGLE_CLAIMED_BY_OTHER
+        finally:
+            cur.close()
+
+
+def assignment_for(entity_id: str) -> str | None:
+    """Return the current owner email for ``entity_id``, or ``None``.
+
+    Reads through the cached ``assignments()`` frame so the L4 button can
+    label itself ("Assign to me" / "Unassign" / "Claimed") without firing
+    its own SQL on every rerun.
+    """
+    if not entity_id:
+        return None
+    df = assignments()
+    if df is None or df.empty or "entity_id" not in df.columns:
+        return None
+    hit = df[df["entity_id"].astype(str) == str(entity_id)]
+    if hit.empty:
+        return None
+    return str(hit.iloc[0]["assigned_to"])

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "churnkit"
-version = "1.02.8a6"
+version = "1.02.8a8"
 description = "Structured ML framework for customer churn prediction -- from exploration notebooks to production pipelines, locally or on Databricks."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/src/customer_retention/__init__.py

@@ -17,7 +17,7 @@ Main module categories:
                 llm_context, iteration)
 """
 
-__version__ = "1.02.8a6"
+__version__ = "1.02.8a8"
 
 # Environment utilities (always available)
 from .core.compat import (

{churnkit-1.2.8a6 → churnkit-1.2.8a8}/src/customer_retention/generators/pipeline_generator/databricks_renderer.py

@@ -30,10 +30,12 @@ def render_spark_step_call(step: TransformationStep) -> str:
 
 
 def _impute_null(col, p):
+    # Guard against recommendations that target a column not in this stage's
+    # input — same rationale as the per-column transforms below.
     value = p.get("value", 0)
     if isinstance(value, str):
-        return f'df.fillna("{value}", subset=["{col}"])'
-    return f'df.fillna({value}, subset=["{col}"])'
+        return f'(df.fillna("{value}", subset=["{col}"]) if "{col}" in df.columns else df)'
+    return f'(df.fillna({value}, subset=["{col}"]) if "{col}" in df.columns else df)'
 
 
 def _cap_outlier(col, p):
@@ -100,8 +102,9 @@ def _derived_ratio(col, p):
     num = p.get("numerator", "")
     den = p.get("denominator", "")
     return (
-        f'df.withColumn("{col}", '
-        f'F.col("{num}") / F.when(F.col("{den}") != 0, F.col("{den}")).otherwise(F.lit(None)))'
+        f'(df.withColumn("{col}", '
+        f'F.col("{num}") / F.when(F.col("{den}") != 0, F.col("{den}")).otherwise(F.lit(None))) '
+        f'if all(c in df.columns for c in ["{num}", "{den}"]) else df)'
     )
 
 
@@ -109,7 +112,10 @@ def _derived_interaction(col, p):
     features = p.get("features", [])
     col_a = features[0] if len(features) > 0 else p.get("col_a", "")
     col_b = features[1] if len(features) > 1 else p.get("col_b", "")
-    return f'df.withColumn("{col}", F.col("{col_a}") * F.col("{col_b}"))'
+    return (
+        f'(df.withColumn("{col}", F.col("{col_a}") * F.col("{col_b}")) '
+        f'if all(c in df.columns for c in ["{col_a}", "{col_b}"]) else df)'
+    )
 
 
 def _derived_composite(col, p):
@@ -117,23 +123,31 @@ def _derived_composite(col, p):
     if not columns:
         raise ValueError(f"Composite derived column '{col}' requires non-empty 'columns' parameter")
     expr_parts = " + ".join(f'F.col("{c}")' for c in columns)
-    return f'df.withColumn("{col}", ({expr_parts}) / {len(columns)})'
+    cols_repr = "[" + ", ".join(f'"{c}"' for c in columns) + "]"
+    return (
+        f'(df.withColumn("{col}", ({expr_parts}) / {len(columns)}) '
+        f'if all(c in df.columns for c in {cols_repr}) else df)'
+    )
 
 
 def _segment_aware_cap(col, p):
     n_segments = p.get("n_segments", 2)
-    return f'_segment_aware_cap(df, "{col}", n_segments={n_segments})'
+    return (
+        f'(_segment_aware_cap(df, "{col}", n_segments={n_segments}) '
+        f'if "{col}" in df.columns else df)'
+    )
 
 
 def _zero_inflation_handling(col, _p):
     return (
-        f'df.withColumn("{col}_is_zero", F.when(F.col("{col}") == 0, 1).otherwise(0))'
-        f'.withColumn("{col}_log", F.when(F.col("{col}") > 0, F.log1p(F.col("{col}"))).otherwise(0))'
+        f'(df.withColumn("{col}_is_zero", F.when(F.col("{col}") == 0, 1).otherwise(0))'
+        f'.withColumn("{col}_log", F.when(F.col("{col}") > 0, F.log1p(F.col("{col}"))).otherwise(0)) '
+        f'if "{col}" in df.columns else df)'
     )
 
 
 def _cap_then_log(col, _p):
-    return f'_cap_then_log(df, "{col}")'
+    return f'(_cap_then_log(df, "{col}") if "{col}" in df.columns else df)'
 
 
 def _type_cast(col, p):
@@ -208,10 +222,11 @@ def _derived_recency(col, p):
         return f'df  # silver_derived recency {col!r}: source unresolvable'
     src = sources[0]
     return (
-        f'df.withColumn("{col}", '
+        f'(df.withColumn("{col}", '
         f'F.when(F.col("{src}").isNotNull() & F.col("as_of_date").isNotNull(), '
         f'F.datediff(F.col("as_of_date"), F.to_date(F.col("{src}"))).cast("double"))'
-        f'.otherwise(F.lit(None)))'
+        f'.otherwise(F.lit(None))) '
+        f'if "{src}" in df.columns else df)'
     )
 
 
@@ -221,10 +236,11 @@ def _derived_duration(col, p):
         return f'df  # silver_derived duration {col!r}: source unresolvable'
     a, b = sources[0], sources[1]
     return (
-        f'df.withColumn("{col}", '
+        f'(df.withColumn("{col}", '
         f'F.when(F.col("{a}").isNotNull() & F.col("{b}").isNotNull(), '
         f'F.datediff(F.to_date(F.col("{b}")), F.to_date(F.col("{a}"))).cast("double"))'
-        f'.otherwise(F.lit(None)))'
+        f'.otherwise(F.lit(None))) '
+        f'if all(c in df.columns for c in ["{a}", "{b}"]) else df)'
     )
 
 
@@ -243,12 +259,13 @@ def _derived_cyclical(col, p):
         return f'df  # silver_derived cyclical {col!r}: source unresolvable'
     src = sources[0]
     return (
-        f'df.withColumn("{src}_month_sin", '
+        f'(df.withColumn("{src}_month_sin", '
         f'F.when(F.col("{src}").isNotNull(), '
         f'F.sin(2 * 3.141592653589793 * F.month(F.col("{src}")) / 12)).otherwise(F.lit(None)))'
         f'.withColumn("{src}_month_cos", '
         f'F.when(F.col("{src}").isNotNull(), '
-        f'F.cos(2 * 3.141592653589793 * F.month(F.col("{src}")) / 12)).otherwise(F.lit(None)))'
+        f'F.cos(2 * 3.141592653589793 * F.month(F.col("{src}")) / 12)).otherwise(F.lit(None))) '
+        f'if "{src}" in df.columns else df)'
     )
 
 
@@ -258,10 +275,11 @@ def _derived_tenure(col, p):
         return f'df  # silver_derived tenure {col!r}: source unresolvable'
     src = sources[0]
     return (
-        f'df.withColumn("{col}", '
+        f'(df.withColumn("{col}", '
         f'F.when(F.col("{src}").isNotNull() & F.col("as_of_date").isNotNull(), '
         f'(F.datediff(F.col("as_of_date"), F.to_date(F.col("{src}"))) / 365.25).cast("double"))'
-        f'.otherwise(F.lit(None)))'
+        f'.otherwise(F.lit(None))) '
+        f'if "{src}" in df.columns else df)'
     )
 
 
@@ -276,12 +294,16 @@ def _derived_extraction(col, p):
     if not sources:
         return f'df  # silver_derived extraction {col!r}: source unresolvable'
     src = sources[0]
+    # Three-way fall-through: passthrough if `{col}` is already present
+    # (landing emitted it), derive from `{src}` when present, otherwise no-op
+    # so a missing source from a phantom rec doesn't crash the stage.
     return (
-        f'df if "{col}" in df.columns else '
-        f'df.withColumn("{col}", '
+        f'(df if "{col}" in df.columns else '
+        f'(df.withColumn("{col}", '
         f'F.when(F.col("{src}").isNotNull(), '
         f'F.when(F.dayofweek(F.to_date(F.col("{src}"))).isin(1, 7), 1.0).otherwise(0.0))'
-        f'.otherwise(F.lit(None)))'
+        f'.otherwise(F.lit(None))) '
+        f'if "{src}" in df.columns else df))'
     )