gitlabds 2.2.2__tar.gz → 2.2.3__tar.gz

{gitlabds-2.2.2 → gitlabds-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.2.2
+Version: 2.2.3
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -827,10 +827,10 @@ Status label for a value vs. its peer median (+/- tolerance), not percentile ran
 #### Parameters:
 - _**value**_ : value(s) to evaluate, scalar or array-like
 - _**peer_median**_ : peer group median(s) to compare against
-- _**good_direction**_ : `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). Anything else is treated as increasing/default.
+- _**good_direction**_ : one of `"increasing"`, `"decreasing"`, `"both"`, `"none"` (scalar or array-like). `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). `"both"` and `"none"` mean the feature has no single good direction, so the output is positional only: no flip, and the `ceiling_label` upgrade is suppressed. `None` (the default) is treated as `"none"`. Any other value raises — a blank/NaN in a feature dictionary must be normalized to `"none"` first rather than silently defaulting to increasing.
 - _**tolerance**_ : relative distance from the peer median (as a fraction of the median) required to be classified above/below average rather than "average". Default is 0.15 (a value must be >15% above/below its peer median to leave the "average" band)
 - _**no_activity_value**_ : value that should always map to `labels[3]` ("No activity") regardless of tolerance
-- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`
+- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`. Only applies when `good_direction` is `"increasing"` or `"decreasing"`
 - _**ceiling_pct**_ : percentile threshold used with `peer_percentile` to detect a "tapped out" strength. Default is 0.95
 - _**ceiling_label**_ : label applied when the ceiling condition is met. Default is "near ceiling"
 - _**labels**_ : tuple of (below average, average, above average, no activity) labels
@@ -859,7 +859,7 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 `gitlabds.per_record_shap(model, df, feature_dict, unique_id="record_id", top_n=25, min_actionable=3, actionable_values=["Yes", "Partial"]):`
 
 #### Parameters:
-- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost)
+- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost). A raw `xgboost.Booster` (from `xgb.train`, or loaded back from a saved model file) works as well as the sklearn wrapper
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
 - _**feature_dict**_ : DataFrame or path to CSV with `field` and `actionable` columns
 - _**unique_id**_ : name to use for the record identifier column in the output. Default is "record_id"
@@ -870,6 +870,8 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `rank`, `feature`, `contribution`, `direction`, `feature_value`, `actionable`
 
+`direction` ("increases"/"decreases") describes the effect on the model's predicted probability of class 1, not on the business outcome. Where class 1 is a bad outcome (e.g. churn), "increases" means worse — any narrative or scorecard layer reading this column has to apply that polarity itself.
+
 #### Requirements
 This function requires the `shap` package (included in core dependencies).
 
@@ -889,27 +891,29 @@ shap_df = gitlabds.per_record_shap(
 <details><summary> Per-Record Counterfactuals </summary>
 
 #### Description
-"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
+"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes `gain` — the improvement in the model score, signed by `score_goal` so that bigger is always better. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, score_goal="maximize", actionable_values=["Yes", "Partial"], min_gain=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
-- _**model**_ : trained model (as in `per_record_shap`)
+- _**model**_ : trained model (as in `per_record_shap`). How probabilities are scored is chosen from the model object itself — `.predict_proba()` where available, otherwise a raw `xgboost.Booster` or `lightgbm.Booster` is scored natively. An unsupported type raises a `TypeError` naming it
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
-- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test
-- _**model_algo**_ : `"lgb"` or `"xgb"`/`"xgboost"`; controls how probabilities are scored
+- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test. Only numeric non-bool levers are evaluated — candidate values are peer-group quantiles, which need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning`. Marking them `'none'` in `direction` is the explicit way to express the same thing, and suppresses the warning
 - _**unique_id**_ : name of the record identifier column. Default is "record_id"
 - _**peer_group**_ : Series/DataFrame indexed by `unique_id`; numeric columns are auto-binned into `n_bins` quantile bands. `None` uses one global group
 - _**candidate_quantiles**_ : peer-group quantiles evaluated as candidate values
-- _**direction**_ : optional per-feature achievability constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` (dict or Series)
+- _**direction**_ : optional per-feature constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` | `'none'` (dict or Series). `'increasing'`/`'decreasing'` restrict candidates to moves in that direction (an achievability constraint); `'both'` allows either; `'none'` excludes the feature from lever evaluation entirely, for features with no meaningful good direction (categoricals, identifiers, context-only numerics). Features absent from the mapping, or `direction=None`, default to `'both'`. A blank/NaN raises — normalize it to `'none'` where the feature dictionary is read
+- _**score_goal**_ : `"maximize"` if a higher predicted probability of class 1 is the good outcome (e.g. class 1 = uptier), `"minimize"` if it is the bad one (e.g. class 1 = churn). Sets the sign of `gain`, which drives best-move selection, the `min_gain` filter, `impact_bucket`, and the output ordering. This is the outcome's polarity only — `direction` above is a separate, feature-level concept and is unaffected. Default is `"maximize"`
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
-- _**min_delta_p**_ : drop levers whose best achievable gain is below this
-- _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**min_gain**_ : drop levers whose best achievable gain is below this. Note this is a threshold on `gain`, not on raw `delta_p`: under `score_goal="minimize"` a good move has a negative `delta_p` but a positive `gain`, so this stays positive for both polarities. Negative values (or `-inf`) are allowed, and keep moves that make the outcome worse — useful for inspecting the full candidate distribution while tuning thresholds
+- _**impact_medium, impact_high**_ : `gain` thresholds bucketing each lever into Low/Medium/High `impact_bucket`. Only meaningful for `gain > 0` — under a negative `min_gain` the retained harmful moves stay `"Low"` (the level-crossing floor doesn't apply to them), so read `gain`'s sign rather than the bucket alone
+- _**levels**_ : dict mapping label -> upper bound on P(class 1) for that level (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter — levels are sorted by cutoff and labels follow that order — but the top level's cutoff must be `float("inf")`. Cutoffs are always in P(class 1) space regardless of `score_goal`, and `crosses_level` is a plain inequality, so name the labels for your own outcome: a churn model would pass something like `{"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")}`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact)
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `gain`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+
+`delta_p` is the raw signed change in P(class 1); `gain` is that change signed by `score_goal` so bigger is always better. For a `score_goal="minimize"` model, `delta_p` will be negative and `gain` positive.
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).
@@ -924,6 +928,17 @@ counterfactuals_df = gitlabds.per_record_counterfactuals(
     shap_df=shap_df,
     peer_group=peer_group_df,
 )
+
+# Churn model: class 1 = churn, so a lower score is the good outcome.
+counterfactuals_df = gitlabds.per_record_counterfactuals(
+    model=churn_model,
+    df=model_features,
+    shap_df=shap_df,
+    peer_group=peer_group_df,
+    score_goal="minimize",
+    direction=dict(zip(feature_dict["field"], feature_dict["good_direction"])),
+    levels={"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")},
+)
 ```
 
 </details>
@@ -944,6 +959,8 @@ Peer benchmarking. Each record's percentile for each feature within its peer gro
 - _**features**_ : optional explicit list of features to benchmark (used as-is, no actionable filter). If `None` (default), computed for every actionable feature in `df`
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
+Either way, only numeric non-bool columns are benchmarked — percentile ranks and quantiles need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning` naming them.
+
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `feature`, `record_value`, `peer_group`, `percentile`, `peer_p25`, `peer_p50`, `peer_p75`
 

{gitlabds-2.2.2 → gitlabds-2.2.3}/README.md

@@ -795,10 +795,10 @@ Status label for a value vs. its peer median (+/- tolerance), not percentile ran
 #### Parameters:
 - _**value**_ : value(s) to evaluate, scalar or array-like
 - _**peer_median**_ : peer group median(s) to compare against
-- _**good_direction**_ : `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). Anything else is treated as increasing/default.
+- _**good_direction**_ : one of `"increasing"`, `"decreasing"`, `"both"`, `"none"` (scalar or array-like). `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). `"both"` and `"none"` mean the feature has no single good direction, so the output is positional only: no flip, and the `ceiling_label` upgrade is suppressed. `None` (the default) is treated as `"none"`. Any other value raises — a blank/NaN in a feature dictionary must be normalized to `"none"` first rather than silently defaulting to increasing.
 - _**tolerance**_ : relative distance from the peer median (as a fraction of the median) required to be classified above/below average rather than "average". Default is 0.15 (a value must be >15% above/below its peer median to leave the "average" band)
 - _**no_activity_value**_ : value that should always map to `labels[3]` ("No activity") regardless of tolerance
-- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`
+- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`. Only applies when `good_direction` is `"increasing"` or `"decreasing"`
 - _**ceiling_pct**_ : percentile threshold used with `peer_percentile` to detect a "tapped out" strength. Default is 0.95
 - _**ceiling_label**_ : label applied when the ceiling condition is met. Default is "near ceiling"
 - _**labels**_ : tuple of (below average, average, above average, no activity) labels
@@ -827,7 +827,7 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 `gitlabds.per_record_shap(model, df, feature_dict, unique_id="record_id", top_n=25, min_actionable=3, actionable_values=["Yes", "Partial"]):`
 
 #### Parameters:
-- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost)
+- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost). A raw `xgboost.Booster` (from `xgb.train`, or loaded back from a saved model file) works as well as the sklearn wrapper
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
 - _**feature_dict**_ : DataFrame or path to CSV with `field` and `actionable` columns
 - _**unique_id**_ : name to use for the record identifier column in the output. Default is "record_id"
@@ -838,6 +838,8 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `rank`, `feature`, `contribution`, `direction`, `feature_value`, `actionable`
 
+`direction` ("increases"/"decreases") describes the effect on the model's predicted probability of class 1, not on the business outcome. Where class 1 is a bad outcome (e.g. churn), "increases" means worse — any narrative or scorecard layer reading this column has to apply that polarity itself.
+
 #### Requirements
 This function requires the `shap` package (included in core dependencies).
 
@@ -857,27 +859,29 @@ shap_df = gitlabds.per_record_shap(
 <details><summary> Per-Record Counterfactuals </summary>
 
 #### Description
-"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
+"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes `gain` — the improvement in the model score, signed by `score_goal` so that bigger is always better. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, score_goal="maximize", actionable_values=["Yes", "Partial"], min_gain=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
-- _**model**_ : trained model (as in `per_record_shap`)
+- _**model**_ : trained model (as in `per_record_shap`). How probabilities are scored is chosen from the model object itself — `.predict_proba()` where available, otherwise a raw `xgboost.Booster` or `lightgbm.Booster` is scored natively. An unsupported type raises a `TypeError` naming it
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
-- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test
-- _**model_algo**_ : `"lgb"` or `"xgb"`/`"xgboost"`; controls how probabilities are scored
+- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test. Only numeric non-bool levers are evaluated — candidate values are peer-group quantiles, which need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning`. Marking them `'none'` in `direction` is the explicit way to express the same thing, and suppresses the warning
 - _**unique_id**_ : name of the record identifier column. Default is "record_id"
 - _**peer_group**_ : Series/DataFrame indexed by `unique_id`; numeric columns are auto-binned into `n_bins` quantile bands. `None` uses one global group
 - _**candidate_quantiles**_ : peer-group quantiles evaluated as candidate values
-- _**direction**_ : optional per-feature achievability constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` (dict or Series)
+- _**direction**_ : optional per-feature constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` | `'none'` (dict or Series). `'increasing'`/`'decreasing'` restrict candidates to moves in that direction (an achievability constraint); `'both'` allows either; `'none'` excludes the feature from lever evaluation entirely, for features with no meaningful good direction (categoricals, identifiers, context-only numerics). Features absent from the mapping, or `direction=None`, default to `'both'`. A blank/NaN raises — normalize it to `'none'` where the feature dictionary is read
+- _**score_goal**_ : `"maximize"` if a higher predicted probability of class 1 is the good outcome (e.g. class 1 = uptier), `"minimize"` if it is the bad one (e.g. class 1 = churn). Sets the sign of `gain`, which drives best-move selection, the `min_gain` filter, `impact_bucket`, and the output ordering. This is the outcome's polarity only — `direction` above is a separate, feature-level concept and is unaffected. Default is `"maximize"`
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
-- _**min_delta_p**_ : drop levers whose best achievable gain is below this
-- _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**min_gain**_ : drop levers whose best achievable gain is below this. Note this is a threshold on `gain`, not on raw `delta_p`: under `score_goal="minimize"` a good move has a negative `delta_p` but a positive `gain`, so this stays positive for both polarities. Negative values (or `-inf`) are allowed, and keep moves that make the outcome worse — useful for inspecting the full candidate distribution while tuning thresholds
+- _**impact_medium, impact_high**_ : `gain` thresholds bucketing each lever into Low/Medium/High `impact_bucket`. Only meaningful for `gain > 0` — under a negative `min_gain` the retained harmful moves stay `"Low"` (the level-crossing floor doesn't apply to them), so read `gain`'s sign rather than the bucket alone
+- _**levels**_ : dict mapping label -> upper bound on P(class 1) for that level (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter — levels are sorted by cutoff and labels follow that order — but the top level's cutoff must be `float("inf")`. Cutoffs are always in P(class 1) space regardless of `score_goal`, and `crosses_level` is a plain inequality, so name the labels for your own outcome: a churn model would pass something like `{"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")}`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact)
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `gain`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+
+`delta_p` is the raw signed change in P(class 1); `gain` is that change signed by `score_goal` so bigger is always better. For a `score_goal="minimize"` model, `delta_p` will be negative and `gain` positive.
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).
@@ -892,6 +896,17 @@ counterfactuals_df = gitlabds.per_record_counterfactuals(
     shap_df=shap_df,
     peer_group=peer_group_df,
 )
+
+# Churn model: class 1 = churn, so a lower score is the good outcome.
+counterfactuals_df = gitlabds.per_record_counterfactuals(
+    model=churn_model,
+    df=model_features,
+    shap_df=shap_df,
+    peer_group=peer_group_df,
+    score_goal="minimize",
+    direction=dict(zip(feature_dict["field"], feature_dict["good_direction"])),
+    levels={"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")},
+)
 ```
 
 </details>
@@ -912,6 +927,8 @@ Peer benchmarking. Each record's percentile for each feature within its peer gro
 - _**features**_ : optional explicit list of features to benchmark (used as-is, no actionable filter). If `None` (default), computed for every actionable feature in `df`
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
+Either way, only numeric non-bool columns are benchmarked — percentile ranks and quantiles need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning` naming them.
+
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `feature`, `record_value`, `peer_group`, `percentile`, `peer_p25`, `peer_p50`, `peer_p75`
 

{gitlabds-2.2.2 → gitlabds-2.2.3}/gitlabds/record_benchmarking.py

@@ -11,10 +11,107 @@ whichever column identifies a row in your data. Includes:
 - per_record_peer_percentiles : per-record percentile standing within a peer group
 """
 
+import warnings
+
 import pandas as pd
 import numpy as np
 
 
+# The four accepted good_direction values, plus the shorthands the feature dictionaries
+# use in practice. Anything else raises -- a blank/NaN or a typo must not silently fall
+# through to a default, since "increasing" and "both" are very different assumptions.
+_DIRECTION_ALIASES = {
+    "increasing": "increasing", "increase": "increasing", "up": "increasing",
+    "decreasing": "decreasing", "decrease": "decreasing", "down": "decreasing",
+    "both": "both",
+    "none": "none",
+}
+
+
+def _norm_direction(value, context=""):
+    """
+    Normalize one good_direction value to 'increasing', 'decreasing', 'both', or 'none'.
+
+    Raises ValueError on anything unrecognized, including blank/NaN. Normalize blanks to
+    the explicit string "none" where the feature dictionary is read, not here -- a blank
+    means "nobody decided yet", which is a data problem, not a behavior to default.
+
+    Python None raises too, even though str(None) would spell "none": pandas reads an empty
+    cell as None or NaN depending on dtype, so accepting it would put the silent default
+    straight back in.
+    """
+    key = "" if value is None else str(value).strip().lower()
+    if key not in _DIRECTION_ALIASES:
+        raise ValueError(
+            f"{context}unrecognized direction {value!r}. Accepted values are 'increasing', "
+            "'decreasing', 'both', and 'none'. Blank/NaN values must be normalized to "
+            "'none' before calling."
+        )
+    return _DIRECTION_ALIASES[key]
+
+
+def _peer_quantile_eligible(df, cols, context, hint):
+    """
+    Split `cols` into those that support peer quantiles/percentile ranks and those that don't,
+    warning about the latter. Returns the eligible subset, order preserved.
+
+    Only genuinely numeric, non-bool columns qualify. The rest either raise or, worse, return
+    something misleading:
+
+    - unordered categorical : groupby.rank raises "Cannot perform rank with non-ordered
+      Categorical"
+    - bool                  : quantile raises "numpy boolean subtract ... is not supported",
+      even though pandas reports bool as a numeric dtype
+    - object / string        : quantile raises on the interpolation subtraction
+    - ordered categorical    : both succeed, but quantile returns the integer *category code*
+      (1.0 for the middle of three levels), so a p25/p50/p75 sitting next to a label-valued
+      record_value would be quietly nonsensical
+    """
+    eligible = [f for f in cols
+                if pd.api.types.is_numeric_dtype(df[f]) and not pd.api.types.is_bool_dtype(df[f])]
+    dropped = [f for f in cols if f not in set(eligible)]
+    if dropped:
+        warnings.warn(
+            f"{context} skipped {sorted(dropped)}: peer quantiles and percentile ranks need an "
+            f"ordered numeric scale, which these dtypes don't provide. {hint}",
+            UserWarning,
+            stacklevel=3,
+        )
+    return eligible
+
+
+def _binary_proba_fn(model):
+    """
+    Return a callable mapping a feature DataFrame to P(class 1).
+
+    Dispatches on the model object rather than a caller-supplied algorithm name: a name can
+    disagree with the object it describes (and silently pick the wrong branch), while an
+    object cannot disagree with itself. Handles the sklearn wrappers for either library plus
+    raw xgboost and LightGBM boosters, which have no .predict_proba().
+    """
+    if hasattr(model, "predict_proba"):        # XGBClassifier / LGBMClassifier / sklearn
+        return lambda X: np.asarray(model.predict_proba(X))[:, 1]
+    try:
+        import xgboost as xgb
+    except ImportError:
+        pass
+    else:
+        if isinstance(model, xgb.Booster):
+            # enable_categorical is required for category dtypes and harmless without them.
+            return lambda X: np.asarray(model.predict(xgb.DMatrix(X, enable_categorical=True)))
+    try:
+        import lightgbm as lgb
+    except ImportError:
+        pass
+    else:
+        if isinstance(model, lgb.Booster):     # binary objective already returns P(class 1)
+            return lambda X: np.asarray(model.predict(X))
+    raise TypeError(
+        f"cannot score model of type {type(model).__module__}.{type(model).__name__}. Expected "
+        "a model exposing .predict_proba(), an xgboost.Booster, or a lightgbm.Booster."
+    )
+
+
 def value_vs_peer_status(value, peer_median, good_direction=None, tolerance=0.15,
                           no_activity_value=None, peer_percentile=None, ceiling_pct=0.95,
                           ceiling_label="near ceiling",
@@ -24,9 +121,14 @@ def value_vs_peer_status(value, peer_median, good_direction=None, tolerance=0.15
 
     value : value(s) to evaluate, scalar or array-like.
     peer_median : peer group median(s) to compare against; broadcasts against value.
-    good_direction : "decreasing" flips which side of the median counts as "above"
-        (e.g., for a metric where lower is better). Anything else (including None,
-        the default) is treated as increasing.
+    good_direction : one of "increasing", "decreasing", "both", "none" (scalar or
+        array-like, broadcast against value). "decreasing" flips which side of the median
+        counts as "above" (e.g., for a metric where lower is better). "both" and "none"
+        mean the feature has no single good direction, so the output is positional only:
+        no flip, and the ceiling_label upgrade below is suppressed since "near ceiling"
+        is a goodness judgment. None (the default) is treated as "none". Any other value
+        raises -- a blank/NaN in a feature dictionary must be normalized to "none" first
+        rather than silently defaulting to increasing.
     tolerance : relative distance from the peer median (as a fraction of the median)
         required to be classified above/below average rather than "average". E.g.
         the default 0.15 means a value must be >15% above (or below) its peer median
@@ -48,8 +150,14 @@ def value_vs_peer_status(value, peer_median, good_direction=None, tolerance=0.15
     value = pd.Series(value)
     # index=value.index (not .reindex()) so a bare scalar broadcasts correctly.
     peer_median = pd.Series(peer_median, index=value.index)
-    decreasing = pd.Series(good_direction, index=value.index).astype(str).str.lower().eq("decreasing") \
-        if good_direction is not None else pd.Series(False, index=value.index)
+    if good_direction is None:
+        norm = pd.Series("none", index=value.index)
+    else:
+        norm = pd.Series(good_direction, index=value.index).map(
+            lambda v: _norm_direction(v, "good_direction: "))
+    decreasing = norm.eq("decreasing")
+    # "increasing"/"decreasing" carry a good/bad judgment; "both"/"none" don't.
+    judged = norm.isin(("increasing", "decreasing"))
     eff_value = value.where(~decreasing, -value)
     eff_median = peer_median.where(~decreasing, -peer_median)
     denom = eff_median.abs()
@@ -62,11 +170,13 @@ def value_vs_peer_status(value, peer_median, good_direction=None, tolerance=0.15
     # "near ceiling": already above the peer median AND in the top ceiling_pct of the peer
     # group toward good_direction. Gating on labels[2] (above average) means a compressed
     # peer group whose top decile is still ~median is left "average", not falsely capped.
+    # Skipped where good_direction is "both"/"none": with no single good direction there is
+    # no strength to be tapped out in.
     # Applied before the null / no-activity masks below so those still take precedence.
     if peer_percentile is not None:
         pct = pd.Series(peer_percentile, index=value.index).astype(float)
         eff_pct = pct.where(~decreasing, 1 - pct)   # percentile toward the good direction
-        level = level.mask((eff_pct >= ceiling_pct) & (level == labels[2]), ceiling_label)
+        level = level.mask((eff_pct >= ceiling_pct) & (level == labels[2]) & judged, ceiling_label)
     level = level.mask(value.isna(), labels[3])
     if no_activity_value is not None:
         no_activity_value = pd.Series(no_activity_value, index=value.index)
@@ -92,7 +202,9 @@ def per_record_shap(
     the drivers.
 
     model : trained tree-based model (e.g., LightGBM, XGBoost). Its underlying booster
-        is used directly if the model exposes one (e.g. `model.booster_`).
+        is used directly if the model exposes one (e.g. `model.booster_`). A raw
+        `xgboost.Booster` (trained via `xgb.train`, or loaded back from a saved model file)
+        works as well as the sklearn wrapper -- see the categorical note below.
     df : model-ready feature matrix, indexed by unique_id.
     feature_dict : DataFrame, or path to a CSV, with 'field' and 'actionable' columns
         mapping each feature to whether/how it can be acted on.
@@ -104,6 +216,18 @@ def per_record_shap(
 
     Returns a long DataFrame, one row per (record, feature): unique_id, rank, feature,
     contribution, direction, feature_value, actionable.
+
+    Note on `direction`: "increases"/"decreases" describes the effect on the model's
+    predicted probability of class 1, not on the business outcome. Where class 1 is a bad
+    outcome (e.g. churn), "increases" means worse. Any narrative or scorecard layer reading
+    this column has to apply that polarity itself -- see `score_goal` in
+    per_record_counterfactuals for the equivalent handling there.
+
+    Note on category dtypes with a raw xgboost.Booster: shap builds its own DMatrix from df,
+    and only knows to pass enable_categorical=True when it can read that flag off an xgboost
+    *sklearn* wrapper. Given a raw Booster it has nowhere to read it from, so we build the
+    DMatrix here instead. Without this, a df with any `category` column raises "DataFrame.dtypes
+    for data must be int, float, bool or category".
     """
     import shap, warnings
     if isinstance(feature_dict, str):
@@ -111,9 +235,20 @@ def per_record_shap(
     feats = list(df.columns)
     ids = df.index
     booster = getattr(model, "booster_", model)
+    explain_input = df
+    if any(str(dt) == "category" for dt in df.dtypes):
+        try:
+            import xgboost as xgb
+        except ImportError:
+            pass                              # not an xgboost model; nothing to pre-convert
+        else:
+            # True only for a raw Booster: the sklearn wrapper carries the flag itself, and a
+            # LightGBM booster handles its own categoricals.
+            if isinstance(booster, xgb.Booster):
+                explain_input = xgb.DMatrix(df, enable_categorical=True)
     with warnings.catch_warnings():           # silence shap's informational list-output notice
         warnings.simplefilter("ignore")
-        sv = shap.TreeExplainer(booster, feature_perturbation="tree_path_dependent").shap_values(df)
+        sv = shap.TreeExplainer(booster, feature_perturbation="tree_path_dependent").shap_values(explain_input)
     if isinstance(sv, list):          # binary classifiers return [class0, class1]
         sv = sv[-1]
     sv = np.asarray(sv)
@@ -151,13 +286,13 @@ def per_record_counterfactuals(
     model,
     df,
     shap_df,
-    model_algo="lgb",
     unique_id="record_id",
     peer_group=None,
     candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9],
     direction=None,
+    score_goal="maximize",
     actionable_values=["Yes", "Partial"],
-    min_delta_p=0.005,
+    min_gain=0.005,
     impact_medium=0.01,
     impact_high=0.03,
     levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")},
@@ -167,48 +302,78 @@ def per_record_counterfactuals(
     "change X -> +Y", direction chosen empirically.
     For each actionable lever SHAP surfaced for a record, evaluate a set of candidate
     values (peer-group quantiles), re-score the model at each, and keep the single move
-    that maximizes the gain in predicted probability. The model decides whether that
-    means increasing or decreasing the feature, so non-monotonic and negatively related
-    features are handled correctly. No monotonicity assumption is made.
+    that maximizes `gain` -- the improvement in the model score, signed by score_goal
+    (see below). The model decides whether that means increasing or decreasing the
+    feature, so non-monotonic and negatively related features are handled correctly.
+    No monotonicity assumption is made.
 
-    model, df, model_algo, unique_id : as in per_record_shap (df indexed by unique_id).
+    model, df, unique_id : as in per_record_shap (df indexed by unique_id). The scoring call
+        is chosen from the model object -- .predict_proba() where available, otherwise a raw
+        xgboost.Booster or lightgbm.Booster is scored natively.
     shap_df : per_record_shap output; scopes which (record, feature) levers to test.
+        Only numeric levers are evaluated: candidate values are peer-group quantiles, which
+        don't exist for a categorical, so non-numeric features are skipped with a warning.
+        Marking them 'none' in `direction` is the explicit way to express the same thing.
     peer_group : Series/DataFrame indexed by unique_id; numeric columns auto-binned into
         n_bins quantile bands. None -> one global group. Candidate values are drawn
         from each feature's distribution within the record's peer group.
     candidate_quantiles : peer-group quantiles evaluated as candidate values.
-    direction : optional per-feature achievability constraint mapping feature ->
-        'increasing' | 'decreasing' | 'both' (dict or Series). Missing/None -> 'both' (unconstrained).
-    min_delta_p : drop levers whose best achievable gain is below this.
-    impact_medium, impact_high : delta_p thresholds bucketing each lever into
-        Low/Medium/High impact_bucket. delta_p shrinks mechanically near the tails of
+    direction : optional per-feature constraint mapping feature -> 'increasing' |
+        'decreasing' | 'both' | 'none' (dict or Series). 'increasing'/'decreasing' restrict
+        candidates to moves in that direction (an achievability constraint); 'both' allows
+        either; 'none' excludes the feature from lever evaluation entirely, for features
+        with no meaningful good direction (categoricals, identifiers, context-only numerics).
+        Features absent from the mapping, or direction=None, default to 'both'. A blank/NaN
+        raises -- normalize it to 'none' where the feature dictionary is read.
+    score_goal : 'maximize' if a higher predicted probability of class 1 is the good
+        outcome (e.g. class 1 = uptier), 'minimize' if it is the bad one (e.g. class 1 =
+        churn). Sets the sign of `gain`, which drives best-move selection, the min_gain
+        filter, impact_bucket, and the output ordering. Only the outcome's polarity --
+        `direction` above is a separate, feature-level concept and is unaffected.
+    min_gain : drop levers whose best achievable gain is below this. Note this is a
+        threshold on gain, not on raw delta_p: under score_goal="minimize" a good move has
+        a negative delta_p but a positive gain, so this stays positive for both polarities.
+        Negative values (or -inf) are allowed, and keep moves that make the outcome worse --
+        useful for inspecting the full candidate distribution while tuning thresholds.
+    impact_medium, impact_high : gain thresholds bucketing each lever into
+        Low/Medium/High impact_bucket. gain shrinks mechanically near the tails of
         the probability distribution, so a fixed pp threshold alone under-weights
         moves for low-scoring/mid-level records relative to those near a level edge.
         levels (below) corrects for that: any move that crosses a level boundary is
-        floored at "Medium" regardless of its raw delta_p, since crossing levels is
+        floored at "Medium" regardless of its raw gain, since crossing levels is
         typically the thing that actually changes which downstream action gets taken.
-        Tune impact_medium/high against the real delta_p distribution for your model;
+        Tune impact_medium/high against the real gain distribution for your model;
         levels should mirror whatever thresholds are live in your own scoring/leveling
         logic (if that logic considers factors beyond the score itself, levels are
         only meant to detect crossings for impact_bucket purposes, not to reproduce
-        it exactly).
-    levels : dict mapping label -> upper bound (on p_before/p_after) for that level,
-        ordered worst to best (e.g. {"poor fit": 0.03, "good fit": 0.10, "best fit":
-        float("inf")} means p <= 0.03 -> "poor fit", 0.03 < p <= 0.10 -> "good fit",
-        p > 0.10 -> "best fit"). The dict's key order doesn't matter -- levels are
-        sorted by their cutoff value -- but the highest-scoring level's cutoff must be
-        float("inf") since it has no upper bound. Used only to detect level crossings
-        for impact_bucket, not to reproduce your production leveling logic. Pass your
-        own dict (e.g. {"low": 0.03, "medium": 0.10, "high": float("inf")}) to match
-        your own pipeline.
+        it exactly). impact_bucket is only meaningful for gain > 0; under a negative
+        min_gain the retained harmful moves stay "Low" (the level-crossing floor does not
+        apply to them), so read gain's sign rather than the bucket alone.
+    levels : dict mapping label -> upper bound on P(class 1) for that level (e.g.
+        {"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")} means p <= 0.03 ->
+        "poor fit", 0.03 < p <= 0.10 -> "good fit", p > 0.10 -> "best fit"). The dict's key
+        order doesn't matter -- levels are sorted by their cutoff value, and labels follow
+        that order -- but the top level's cutoff must be float("inf") since it has no upper
+        bound. Cutoffs are always in P(class 1) space regardless of score_goal, and
+        crosses_level is a plain inequality, so name the labels for your own outcome: a
+        churn model would pass something like {"low risk": 0.03, "medium risk": 0.10,
+        "high risk": float("inf")}. Used only to detect level crossings for impact_bucket,
+        not to reproduce your production leveling logic.
     n_bins : quantile bins for numeric peer_group columns.
 
     Returns a long DataFrame: one row per (record, lever) with the best move found
     (current_value, intervention_value, intervention_quantile, p_before/p_after/delta_p,
-    impact_bucket, level_before, level_after, crosses_level).
+    gain, impact_bucket, level_before, level_after, crosses_level). delta_p is the raw
+    signed change in P(class 1); gain is that change signed so bigger is always better.
     """
     if impact_medium >= impact_high:
         raise ValueError(f"impact_medium ({impact_medium}) must be less than impact_high ({impact_high})")
+    _score_goal = str(score_goal).strip().lower()
+    if _score_goal not in ("maximize", "minimize"):
+        raise ValueError(f"score_goal must be 'maximize' or 'minimize', got {score_goal!r}")
+    # Sign that turns delta_p (always in P(class 1) space) into a gain where bigger is
+    # better, so every good/bad comparison below reads the same way for both polarities.
+    sign = 1.0 if _score_goal == "maximize" else -1.0
     ids = df.index
     # Peer-group key: numeric peer columns auto-binned into n_bins quantile bands.
     if peer_group is None:
@@ -222,29 +387,32 @@ def per_record_counterfactuals(
                     if pd.api.types.is_numeric_dtype(pk[c]) else pk[c].astype(str))
             key = band if key is None else key.str.cat(band, sep=" | ")
         grp = pd.Series(np.asarray(key), index=ids)
-    # Accept up/down/both or increasing/decreasing/both (from the dictionary
-    # good_direction column); anything else -> "both".
-    _dirmap = {"increasing": "up", "increase": "up", "up": "up",
-               "decreasing": "down", "decrease": "down", "down": "down",
-               "both": "both"}
-    direction = {k: _dirmap.get(str(v).lower(), "both")
+    # increasing/decreasing/both/none from the dictionary's good_direction column, mapped to
+    # the internal up/down/both/none. Unrecognized values raise rather than defaulting.
+    _internal = {"increasing": "up", "decreasing": "down", "both": "both", "none": "none"}
+    direction = {k: _internal[_norm_direction(v, f"direction[{k!r}]: ")]
                  for k, v in (dict(direction).items() if direction is not None else [])}
-    def proba(X):
-        if model_algo.lower() in ("xgb", "xgboost") and not hasattr(model, "predict_proba"):
-            import xgboost as xgb
-            return np.asarray(model.predict(xgb.DMatrix(X)))
-        return model.predict_proba(X)[:, 1]
+    proba = _binary_proba_fn(model)
     p0 = pd.Series(proba(df), index=ids)  # unclipped baseline
     levers = shap_df[shap_df["actionable"].isin(actionable_values)]
     records_by_feat = levers.groupby("feature")[unique_id].apply(set)
+    # Candidate values are peer-group quantiles, so only quantile-able levers can be tested.
+    # Checked up front rather than inside the loop so the warning lists them all at once.
+    # 'none' levers are filtered first, so marking them explicitly suppresses the warning.
+    eligible = set(_peer_quantile_eligible(
+        df,
+        [f for f in records_by_feat.index if f in df.columns and direction.get(f, "both") != "none"],
+        "per_record_counterfactuals",
+        "Set their good_direction to 'none' (or actionable to 'No') to make this explicit.",
+    ))
     Xw = df.copy()  # single reusable working matrix
     parts = []
     for f, recs in records_by_feat.items():
-        if f not in df.columns:
+        if f not in eligible:
             continue
+        allowed = direction.get(f, "both")
         cur = df[f]
         in_scope = pd.Series(ids.isin(recs), index=ids)
-        allowed = direction.get(f, "both")
         orig = df[f].values
         for q in candidate_quantiles:
             cand = df.groupby(grp)[f].transform(lambda s: s.quantile(q))
@@ -273,17 +441,18 @@ def per_record_counterfactuals(
     if not parts:
         return pd.DataFrame()
     out = pd.concat(parts, ignore_index=True)
+    out["gain"] = sign * out["delta_p"]
     # Keep the single best-scoring candidate per (record, feature).
-    out = (out.sort_values("delta_p", ascending=False)
+    out = (out.sort_values("gain", ascending=False)
               .drop_duplicates([unique_id, "feature"], keep="first"))
-    out = out[out["delta_p"] >= min_delta_p]
-    if impact_medium >= impact_high:
-        raise ValueError(f"impact_medium ({impact_medium}) must be less than impact_high ({impact_high})")
-    out["impact_bucket"] = pd.cut(out["delta_p"],
+    out = out[out["gain"] >= min_gain]
+    out["impact_bucket"] = pd.cut(out["gain"],
                                    bins=[-np.inf, impact_medium, impact_high, np.inf],
                                    labels=["Low", "Medium", "High"]).astype(str)
     # Level-crossing floor: a move that pushes the record into a better level is at
-    # least "Medium" impact even if its raw delta_p is small (see docstring).
+    # least "Medium" impact even if its raw gain is small (see docstring). Level cutoffs
+    # stay in P(class 1) space for both polarities -- crosses_level is an inequality, so
+    # only the caller's choice of labels is outcome-specific.
     _sorted_levels = sorted(levels.items(), key=lambda kv: kv[1])
     _edges = [-np.inf] + [cutoff for _, cutoff in _sorted_levels]
     _labels = [label for label, _ in _sorted_levels]
@@ -292,8 +461,12 @@ def per_record_counterfactuals(
     out["level_before"] = _level(out["p_before"])
     out["level_after"] = _level(out["p_after"])
     out["crosses_level"] = out["level_before"] != out["level_after"]
-    out.loc[out["crosses_level"] & (out["impact_bucket"] == "Low"), "impact_bucket"] = "Medium"
-    return out.sort_values([unique_id, "delta_p"], ascending=[True, False]).reset_index(drop=True)
+    # Gated on gain > 0: with a negative min_gain the output retains moves that make the
+    # outcome worse, and those cross level boundaries in the wrong direction. Promoting them
+    # would advertise the most harmful move found as a Medium-impact lever.
+    out.loc[out["crosses_level"] & (out["gain"] > 0) & (out["impact_bucket"] == "Low"),
+            "impact_bucket"] = "Medium"
+    return out.sort_values([unique_id, "gain"], ascending=[True, False]).reset_index(drop=True)
 
 
 def per_record_peer_percentiles(
@@ -318,6 +491,10 @@ def per_record_peer_percentiles(
         you want, including non-actionable descriptive fields.
         If None (default), computed for every actionable model feature in df.
 
+    Either way, only numeric non-bool columns are returned: percentile ranks and quantiles
+    need an ordered numeric scale. Categoricals, bools, and strings are skipped with a
+    warning naming them (see _peer_quantile_eligible for why each is excluded).
+
     Returns a long DataFrame: one row per (record, feature).
     """
     if isinstance(feature_dict, str):
@@ -327,6 +504,10 @@ def per_record_peer_percentiles(
     else:
         act_fields = set(feature_dict.loc[feature_dict["actionable"].isin(actionable_values), "field"])
         cols = [f for f in df.columns if f in act_fields]
+    cols = _peer_quantile_eligible(
+        df, cols, "per_record_peer_percentiles",
+        "Drop them from `features`, or mark them actionable='No' in the feature dictionary.",
+    )
     ids = df.index
     # Peer-group key: numeric peer columns auto-binned into n_bins quantile bands.
     if peer_group is None:

{gitlabds-2.2.2 → gitlabds-2.2.3}/gitlabds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.2.2
+Version: 2.2.3
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -827,10 +827,10 @@ Status label for a value vs. its peer median (+/- tolerance), not percentile ran
 #### Parameters:
 - _**value**_ : value(s) to evaluate, scalar or array-like
 - _**peer_median**_ : peer group median(s) to compare against
-- _**good_direction**_ : `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). Anything else is treated as increasing/default.
+- _**good_direction**_ : one of `"increasing"`, `"decreasing"`, `"both"`, `"none"` (scalar or array-like). `"decreasing"` flips which side of the median counts as "above" (e.g., for a metric where lower is better). `"both"` and `"none"` mean the feature has no single good direction, so the output is positional only: no flip, and the `ceiling_label` upgrade is suppressed. `None` (the default) is treated as `"none"`. Any other value raises — a blank/NaN in a feature dictionary must be normalized to `"none"` first rather than silently defaulting to increasing.
 - _**tolerance**_ : relative distance from the peer median (as a fraction of the median) required to be classified above/below average rather than "average". Default is 0.15 (a value must be >15% above/below its peer median to leave the "average" band)
 - _**no_activity_value**_ : value that should always map to `labels[3]` ("No activity") regardless of tolerance
-- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`
+- _**peer_percentile**_ : optional 0-1 percentile rank within the peer group. When provided, an "above average" reading that also sits in the top `ceiling_pct` toward `good_direction` is upgraded to `ceiling_label`. Only applies when `good_direction` is `"increasing"` or `"decreasing"`
 - _**ceiling_pct**_ : percentile threshold used with `peer_percentile` to detect a "tapped out" strength. Default is 0.95
 - _**ceiling_label**_ : label applied when the ceiling condition is met. Default is "near ceiling"
 - _**labels**_ : tuple of (below average, average, above average, no activity) labels
@@ -859,7 +859,7 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 `gitlabds.per_record_shap(model, df, feature_dict, unique_id="record_id", top_n=25, min_actionable=3, actionable_values=["Yes", "Partial"]):`
 
 #### Parameters:
-- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost)
+- _**model**_ : trained tree-based model (e.g., LightGBM, XGBoost). A raw `xgboost.Booster` (from `xgb.train`, or loaded back from a saved model file) works as well as the sklearn wrapper
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
 - _**feature_dict**_ : DataFrame or path to CSV with `field` and `actionable` columns
 - _**unique_id**_ : name to use for the record identifier column in the output. Default is "record_id"
@@ -870,6 +870,8 @@ Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tre
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `rank`, `feature`, `contribution`, `direction`, `feature_value`, `actionable`
 
+`direction` ("increases"/"decreases") describes the effect on the model's predicted probability of class 1, not on the business outcome. Where class 1 is a bad outcome (e.g. churn), "increases" means worse — any narrative or scorecard layer reading this column has to apply that polarity itself.
+
 #### Requirements
 This function requires the `shap` package (included in core dependencies).
 
@@ -889,27 +891,29 @@ shap_df = gitlabds.per_record_shap(
 <details><summary> Per-Record Counterfactuals </summary>
 
 #### Description
-"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
+"Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes `gain` — the improvement in the model score, signed by `score_goal` so that bigger is always better. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, score_goal="maximize", actionable_values=["Yes", "Partial"], min_gain=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
-- _**model**_ : trained model (as in `per_record_shap`)
+- _**model**_ : trained model (as in `per_record_shap`). How probabilities are scored is chosen from the model object itself — `.predict_proba()` where available, otherwise a raw `xgboost.Booster` or `lightgbm.Booster` is scored natively. An unsupported type raises a `TypeError` naming it
 - _**df**_ : model-ready feature matrix, indexed by `unique_id`
-- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test
-- _**model_algo**_ : `"lgb"` or `"xgb"`/`"xgboost"`; controls how probabilities are scored
+- _**shap_df**_ : output of `per_record_shap`; scopes which (record, feature) levers to test. Only numeric non-bool levers are evaluated — candidate values are peer-group quantiles, which need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning`. Marking them `'none'` in `direction` is the explicit way to express the same thing, and suppresses the warning
 - _**unique_id**_ : name of the record identifier column. Default is "record_id"
 - _**peer_group**_ : Series/DataFrame indexed by `unique_id`; numeric columns are auto-binned into `n_bins` quantile bands. `None` uses one global group
 - _**candidate_quantiles**_ : peer-group quantiles evaluated as candidate values
-- _**direction**_ : optional per-feature achievability constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` (dict or Series)
+- _**direction**_ : optional per-feature constraint mapping feature -> `'increasing'` | `'decreasing'` | `'both'` | `'none'` (dict or Series). `'increasing'`/`'decreasing'` restrict candidates to moves in that direction (an achievability constraint); `'both'` allows either; `'none'` excludes the feature from lever evaluation entirely, for features with no meaningful good direction (categoricals, identifiers, context-only numerics). Features absent from the mapping, or `direction=None`, default to `'both'`. A blank/NaN raises — normalize it to `'none'` where the feature dictionary is read
+- _**score_goal**_ : `"maximize"` if a higher predicted probability of class 1 is the good outcome (e.g. class 1 = uptier), `"minimize"` if it is the bad one (e.g. class 1 = churn). Sets the sign of `gain`, which drives best-move selection, the `min_gain` filter, `impact_bucket`, and the output ordering. This is the outcome's polarity only — `direction` above is a separate, feature-level concept and is unaffected. Default is `"maximize"`
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
-- _**min_delta_p**_ : drop levers whose best achievable gain is below this
-- _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**min_gain**_ : drop levers whose best achievable gain is below this. Note this is a threshold on `gain`, not on raw `delta_p`: under `score_goal="minimize"` a good move has a negative `delta_p` but a positive `gain`, so this stays positive for both polarities. Negative values (or `-inf`) are allowed, and keep moves that make the outcome worse — useful for inspecting the full candidate distribution while tuning thresholds
+- _**impact_medium, impact_high**_ : `gain` thresholds bucketing each lever into Low/Medium/High `impact_bucket`. Only meaningful for `gain > 0` — under a negative `min_gain` the retained harmful moves stay `"Low"` (the level-crossing floor doesn't apply to them), so read `gain`'s sign rather than the bucket alone
+- _**levels**_ : dict mapping label -> upper bound on P(class 1) for that level (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter — levels are sorted by cutoff and labels follow that order — but the top level's cutoff must be `float("inf")`. Cutoffs are always in P(class 1) space regardless of `score_goal`, and `crosses_level` is a plain inequality, so name the labels for your own outcome: a churn model would pass something like `{"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")}`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact)
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `gain`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
+
+`delta_p` is the raw signed change in P(class 1); `gain` is that change signed by `score_goal` so bigger is always better. For a `score_goal="minimize"` model, `delta_p` will be negative and `gain` positive.
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).
@@ -924,6 +928,17 @@ counterfactuals_df = gitlabds.per_record_counterfactuals(
     shap_df=shap_df,
     peer_group=peer_group_df,
 )
+
+# Churn model: class 1 = churn, so a lower score is the good outcome.
+counterfactuals_df = gitlabds.per_record_counterfactuals(
+    model=churn_model,
+    df=model_features,
+    shap_df=shap_df,
+    peer_group=peer_group_df,
+    score_goal="minimize",
+    direction=dict(zip(feature_dict["field"], feature_dict["good_direction"])),
+    levels={"low risk": 0.03, "medium risk": 0.10, "high risk": float("inf")},
+)
 ```
 
 </details>
@@ -944,6 +959,8 @@ Peer benchmarking. Each record's percentile for each feature within its peer gro
 - _**features**_ : optional explicit list of features to benchmark (used as-is, no actionable filter). If `None` (default), computed for every actionable feature in `df`
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
+Either way, only numeric non-bool columns are benchmarked — percentile ranks and quantiles need an ordered numeric scale. Categoricals, bools, and strings are skipped with a `UserWarning` naming them.
+
 #### Returns
 - Long DataFrame, one row per (record, feature): `unique_id`, `feature`, `record_value`, `peer_group`, `percentile`, `peer_p25`, `peer_p50`, `peer_p75`