gitlabds 2.1.10__tar.gz → 2.2.0__tar.gz

{gitlabds-2.1.10 → gitlabds-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.1.10
+Version: 2.2.0
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -63,7 +63,7 @@ pip install gitlabds
 
 #### Snowflake Feature Store
 
-The `serve_features` and `clear_feature_serving_locks` functions require additional Snowflake dependencies.
+The `serve_features`, `clear_feature_serving_locks`, and `get_feature_descriptions` functions require additional Snowflake dependencies.
 
 To use these functions, install with:
 
@@ -815,6 +815,151 @@ results = gitlabds.prescriptions(
 ```
 </details>
 
+### Record Benchmarking
+
+<details><summary> Value vs. Peer Status </summary>
+
+#### Description
+Status label for a value vs. its peer median (+/- tolerance), not percentile rank.
+
+`gitlabds.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", labels=("below average", "average", "above average", "No activity")):`
+
+#### 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.
+- _**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`
+- _**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
+
+#### Returns
+- Series of status labels, one per input value
+
+#### Examples:
+```python
+import gitlabds
+
+status = gitlabds.value_vs_peer_status(
+    value=df["monthly_spend"],
+    peer_median=df["peer_median_spend"],
+    peer_percentile=df["peer_percentile_spend"],
+)
+```
+
+</details>
+
+<details><summary> Per-Record SHAP </summary>
+
+#### Description
+Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tree_path_dependent TreeSHAP, which natively handles the model's categorical splits. Returns the top_n features by |contribution| per record, guaranteeing at least min_actionable actionable ones.
+
+`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)
+- _**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"
+- _**top_n**_ : number of features to return per record, ranked by |contribution|. Default is 25
+- _**min_actionable**_ : minimum number of actionable features guaranteed per record, even if outside the top_n. Default is 3
+- _**actionable_values**_ : values in `feature_dict["actionable"]` treated as actionable
+
+#### Returns
+- Long DataFrame, one row per (record, feature): `unique_id`, `rank`, `feature`, `contribution`, `direction`, `feature_value`, `actionable`
+
+#### Requirements
+This function requires the `shap` package (included in core dependencies).
+
+#### Examples:
+```python
+import gitlabds
+
+shap_df = gitlabds.per_record_shap(
+    model=trained_model,
+    df=model_features,
+    feature_dict="feature_dict.csv",
+)
+```
+
+</details>
+
+<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.
+
+`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, bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+
+#### Parameters:
+- _**model**_ : trained model (as in `per_record_shap`)
+- _**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
+- _**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)
+- _**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`
+- _**bands**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that band, 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 band's cutoff must be `float("inf")`. Used to detect whether a move crosses a band 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
+- _**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`, `band_before`, `band_after`, `crosses_band`
+
+#### Requirements
+For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).
+
+#### Examples:
+```python
+import gitlabds
+
+counterfactuals_df = gitlabds.per_record_counterfactuals(
+    model=trained_model,
+    df=model_features,
+    shap_df=shap_df,
+    peer_group=peer_group_df,
+)
+```
+
+</details>
+
+<details><summary> Per-Record Peer Percentiles </summary>
+
+#### Description
+Peer benchmarking. Each record's percentile for each feature within its peer group, plus the group's p25/p50/p75 for context. Pure pandas -- no model required.
+
+`gitlabds.per_record_peer_percentiles(df, feature_dict, peer_group=None, unique_id="record_id", actionable_values=["Yes", "Partial"], features=None, n_bins=5):`
+
+#### Parameters:
+- _**df**_ : model features DataFrame, indexed by `unique_id`
+- _**feature_dict**_ : DataFrame or path to CSV with `field` and `actionable` columns
+- _**peer_group**_ : Series/DataFrame indexed by `unique_id`; numeric columns are auto-binned into `n_bins` quantile bands. `None` uses one global group
+- _**unique_id**_ : name of the record identifier column. Default is "record_id"
+- _**actionable_values**_ : values in `feature_dict["actionable"]` treated as actionable
+- _**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
+
+#### Returns
+- Long DataFrame, one row per (record, feature): `unique_id`, `feature`, `record_value`, `peer_group`, `percentile`, `peer_p25`, `peer_p50`, `peer_p75`
+
+#### Examples:
+```python
+import gitlabds
+
+percentiles_df = gitlabds.per_record_peer_percentiles(
+    df=model_features,
+    feature_dict="feature_dict.csv",
+    peer_group=peer_group_df,
+)
+```
+
+</details>
+
 ### Model Monitoring
 
 <details><summary> Generate Baseline Features </summary>
@@ -1072,6 +1217,45 @@ print(f"Cleared {locks_cleared} locks")
 
 </details>
 
+<details><summary> Get Feature Descriptions </summary>
+
+#### Description
+Look up each feature's source feature view and description from the feature store's registered feature views (column comments set via `FeatureView.attach_feature_desc(...)`). Useful for documenting a model's fields or auditing everything registered in the store.
+
+`gitlabds.get_feature_descriptions(session, feature_store, features=None):`
+
+#### Parameters:
+- **_session_** : Active Snowpark session (e.g., `fs_engine._session`)
+- **_feature_store_** : Initialized FeatureStore instance (e.g., `fs_engine`); used to enumerate the registered feature views and locate their db/schema
+- **_features_** : Feature names to look up. If None, returns every feature in the store's registered feature views.
+
+#### Returns
+- DataFrame with columns: `feature`, `feature_view`, `data_type`, `description`. Features found in more than one feature view have their views/descriptions joined (`" | "` / `" || "`) so nothing is dropped. When `features` is provided, unmatched features (e.g., transformed or dummy-coded features) come back with blank `feature_view` / `data_type` / `description` for the user to populate manually, and the caller's order/list is preserved.
+
+#### Requirements
+This function requires Snowflake packages. Install with:
+```bash
+pip install snowflake-snowpark-python snowflake-ml-python
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+# Look up a specific list (e.g. the model fields from a config)
+desc = gitlabds.get_feature_descriptions(
+    session=fs_engine._session,
+    feature_store=fs_engine,
+    features=scoring_config["model"]["fields"],
+)
+
+# Or pull every feature registered in the store
+all_desc = gitlabds.get_feature_descriptions(session=fs_engine._session, feature_store=fs_engine)
+```
+
+</details>
+
 ### SQL and Trend Analysis
 
 <details><summary> SQL Trend Query Generator </summary>

{gitlabds-2.1.10 → gitlabds-2.2.0}/README.md

@@ -31,7 +31,7 @@ pip install gitlabds
 
 #### Snowflake Feature Store
 
-The `serve_features` and `clear_feature_serving_locks` functions require additional Snowflake dependencies.
+The `serve_features`, `clear_feature_serving_locks`, and `get_feature_descriptions` functions require additional Snowflake dependencies.
 
 To use these functions, install with:
 
@@ -783,6 +783,151 @@ results = gitlabds.prescriptions(
 ```
 </details>
 
+### Record Benchmarking
+
+<details><summary> Value vs. Peer Status </summary>
+
+#### Description
+Status label for a value vs. its peer median (+/- tolerance), not percentile rank.
+
+`gitlabds.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", labels=("below average", "average", "above average", "No activity")):`
+
+#### 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.
+- _**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`
+- _**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
+
+#### Returns
+- Series of status labels, one per input value
+
+#### Examples:
+```python
+import gitlabds
+
+status = gitlabds.value_vs_peer_status(
+    value=df["monthly_spend"],
+    peer_median=df["peer_median_spend"],
+    peer_percentile=df["peer_percentile_spend"],
+)
+```
+
+</details>
+
+<details><summary> Per-Record SHAP </summary>
+
+#### Description
+Per-record SHAP attribution (log-odds / margin space) for a tree model. Uses tree_path_dependent TreeSHAP, which natively handles the model's categorical splits. Returns the top_n features by |contribution| per record, guaranteeing at least min_actionable actionable ones.
+
+`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)
+- _**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"
+- _**top_n**_ : number of features to return per record, ranked by |contribution|. Default is 25
+- _**min_actionable**_ : minimum number of actionable features guaranteed per record, even if outside the top_n. Default is 3
+- _**actionable_values**_ : values in `feature_dict["actionable"]` treated as actionable
+
+#### Returns
+- Long DataFrame, one row per (record, feature): `unique_id`, `rank`, `feature`, `contribution`, `direction`, `feature_value`, `actionable`
+
+#### Requirements
+This function requires the `shap` package (included in core dependencies).
+
+#### Examples:
+```python
+import gitlabds
+
+shap_df = gitlabds.per_record_shap(
+    model=trained_model,
+    df=model_features,
+    feature_dict="feature_dict.csv",
+)
+```
+
+</details>
+
+<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.
+
+`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, bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+
+#### Parameters:
+- _**model**_ : trained model (as in `per_record_shap`)
+- _**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
+- _**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)
+- _**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`
+- _**bands**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that band, 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 band's cutoff must be `float("inf")`. Used to detect whether a move crosses a band 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
+- _**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`, `band_before`, `band_after`, `crosses_band`
+
+#### Requirements
+For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).
+
+#### Examples:
+```python
+import gitlabds
+
+counterfactuals_df = gitlabds.per_record_counterfactuals(
+    model=trained_model,
+    df=model_features,
+    shap_df=shap_df,
+    peer_group=peer_group_df,
+)
+```
+
+</details>
+
+<details><summary> Per-Record Peer Percentiles </summary>
+
+#### Description
+Peer benchmarking. Each record's percentile for each feature within its peer group, plus the group's p25/p50/p75 for context. Pure pandas -- no model required.
+
+`gitlabds.per_record_peer_percentiles(df, feature_dict, peer_group=None, unique_id="record_id", actionable_values=["Yes", "Partial"], features=None, n_bins=5):`
+
+#### Parameters:
+- _**df**_ : model features DataFrame, indexed by `unique_id`
+- _**feature_dict**_ : DataFrame or path to CSV with `field` and `actionable` columns
+- _**peer_group**_ : Series/DataFrame indexed by `unique_id`; numeric columns are auto-binned into `n_bins` quantile bands. `None` uses one global group
+- _**unique_id**_ : name of the record identifier column. Default is "record_id"
+- _**actionable_values**_ : values in `feature_dict["actionable"]` treated as actionable
+- _**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
+
+#### Returns
+- Long DataFrame, one row per (record, feature): `unique_id`, `feature`, `record_value`, `peer_group`, `percentile`, `peer_p25`, `peer_p50`, `peer_p75`
+
+#### Examples:
+```python
+import gitlabds
+
+percentiles_df = gitlabds.per_record_peer_percentiles(
+    df=model_features,
+    feature_dict="feature_dict.csv",
+    peer_group=peer_group_df,
+)
+```
+
+</details>
+
 ### Model Monitoring
 
 <details><summary> Generate Baseline Features </summary>
@@ -1040,6 +1185,45 @@ print(f"Cleared {locks_cleared} locks")
 
 </details>
 
+<details><summary> Get Feature Descriptions </summary>
+
+#### Description
+Look up each feature's source feature view and description from the feature store's registered feature views (column comments set via `FeatureView.attach_feature_desc(...)`). Useful for documenting a model's fields or auditing everything registered in the store.
+
+`gitlabds.get_feature_descriptions(session, feature_store, features=None):`
+
+#### Parameters:
+- **_session_** : Active Snowpark session (e.g., `fs_engine._session`)
+- **_feature_store_** : Initialized FeatureStore instance (e.g., `fs_engine`); used to enumerate the registered feature views and locate their db/schema
+- **_features_** : Feature names to look up. If None, returns every feature in the store's registered feature views.
+
+#### Returns
+- DataFrame with columns: `feature`, `feature_view`, `data_type`, `description`. Features found in more than one feature view have their views/descriptions joined (`" | "` / `" || "`) so nothing is dropped. When `features` is provided, unmatched features (e.g., transformed or dummy-coded features) come back with blank `feature_view` / `data_type` / `description` for the user to populate manually, and the caller's order/list is preserved.
+
+#### Requirements
+This function requires Snowflake packages. Install with:
+```bash
+pip install snowflake-snowpark-python snowflake-ml-python
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+# Look up a specific list (e.g. the model fields from a config)
+desc = gitlabds.get_feature_descriptions(
+    session=fs_engine._session,
+    feature_store=fs_engine,
+    features=scoring_config["model"]["fields"],
+)
+
+# Or pull every feature registered in the store
+all_desc = gitlabds.get_feature_descriptions(session=fs_engine._session, feature_store=fs_engine)
+```
+
+</details>
+
 ### SQL and Trend Analysis
 
 <details><summary> SQL Trend Query Generator </summary>

{gitlabds-2.1.10 → gitlabds-2.2.0}/gitlabds/__init__.py

@@ -3,6 +3,7 @@ from .config_generator import ConfigGenerator
 from .dummy import dummy_code, dummy_top, apply_dummy
 from .feature_reduction import drop_categorical, remove_low_variation, remove_outcome_proxies, correlation_reduction
 from .insights import marginal_effects, prescriptions
+from .record_benchmarking import value_vs_peer_status, per_record_shap, per_record_counterfactuals, per_record_peer_percentiles
 from .memory_optimization import reduce_memory_usage, sparse_encode_df, identify_categorical_candidates, compact_categorical, memory_profile_df, memory_optimization
 from .missing import missing_values, apply_missing_values
 from .model_evaluator import ModelEvaluator
@@ -14,6 +15,7 @@ from .trends import generate_sql_trend_query, trend_analysis
 # Optional imports for Snowflake feature serving
 try:
     from .serving_features import clear_feature_serving_locks, serve_features
+    from .feature_descriptions import get_feature_descriptions
 except ImportError as e:
     # Snowflake packages not installed - create placeholder functions with helpful error messages
     def _snowflake_not_installed(*args, **kwargs):
@@ -21,7 +23,8 @@ except ImportError as e:
             "Snowflake feature serving functions require additional dependencies. "
             "Install them with: pip install snowflake-snowpark-python snowflake-ml-python\n\n"
         )
-    
+
     clear_feature_serving_locks = _snowflake_not_installed
     serve_features = _snowflake_not_installed
+    get_feature_descriptions = _snowflake_not_installed
 

gitlabds-2.2.0/gitlabds/feature_descriptions.py

@@ -0,0 +1,106 @@
+"""
+Feature description lookup for Snowflake Feature Store integration.
+
+Given a list of feature names, return each feature's source feature view and its
+description (pulled from the registered feature views' column comments, which is
+where FeatureView.attach_feature_desc(...) stores them). Follows the same call
+pattern as gitlabds.serve_features: pass the feature-store session and object.
+
+Note: This module requires snowflake-snowpark-python and snowflake-ml-python packages.
+"""
+
+from typing import Iterable, Optional
+import pandas as pd
+
+# Optional imports with graceful fallback
+try:
+    from snowflake.snowpark import Session
+    from snowflake.ml.feature_store import FeatureStore
+    SNOWFLAKE_AVAILABLE = True
+except ImportError:
+    SNOWFLAKE_AVAILABLE = False
+    Session = None
+    FeatureStore = None
+
+
+def _check_snowflake_available():
+    """Check if Snowflake packages are available."""
+    if not SNOWFLAKE_AVAILABLE:
+        raise ImportError(
+            "Snowflake packages are required for feature descriptions. "
+            "Install with: pip install snowflake-snowpark-python snowflake-ml-python"
+        )
+
+
+def get_feature_descriptions(
+    session: 'Session',
+    feature_store: 'FeatureStore',
+    features: Optional[Iterable[str]] = None,
+) -> pd.DataFrame:
+    """
+    Look up each feature's source feature view and description from the feature
+    store's registered feature views (column comments set via
+    FeatureView.attach_feature_desc(...)).
+
+    Parameters
+    ----------
+    session : snowflake.snowpark.Session
+        Active Snowpark session (e.g., fs_engine._session).
+    feature_store : snowflake.ml.feature_store.FeatureStore
+        Initialized FeatureStore instance (e.g., fs_engine); used to enumerate the
+        registered feature views and to locate their db/schema.
+    features : Iterable[str], optional
+        Feature names to look up. If None, returns every feature in the store's
+        registered feature views.
+
+    Returns
+    -------
+    pd.DataFrame
+        Columns: [feature, feature_view, data_type, description]. Features found
+        in more than one feature view have their views/descriptions joined
+        (" | " / " || ") so nothing is dropped. When `features` is provided,
+        unmatched features (e.g., transformed or dummy-coded features) come back
+        with blank feature_view / data_type / description for the user to
+        populate manually, and order/list is preserved.
+    """
+    _check_snowflake_available()
+
+    # Registered feature views -> exact published table names (e.g. ACCOUNT_CI_USAGE$1.0).
+    fvs = feature_store.list_feature_views().select("NAME", "VERSION").to_pandas()
+    tables = [f"{n}${v}" for n, v in zip(fvs["NAME"], fvs["VERSION"])]
+
+    # Database/schema come from the live feature-store session, not hard-coded.
+    # Pulled directly rather than parsed out of get_fully_qualified_current_schema(),
+    # which would require quote-aware splitting to handle identifiers containing ".".
+    database = session.get_current_database().strip('"')
+    schema = session.get_current_schema().strip('"')
+
+    def sql_list(values):
+        return ",".join("'" + str(v).replace("'", "''") + "'" for v in values)
+
+    meta = session.sql(
+        "SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COMMENT "
+        f"FROM {database}.INFORMATION_SCHEMA.COLUMNS "
+        f"WHERE TABLE_SCHEMA = '{schema}' AND TABLE_NAME IN ({sql_list(tables)})"
+    ).to_pandas()
+    meta.columns = [c.upper() for c in meta.columns]
+
+    meta["feature_view"] = meta["TABLE_NAME"].str.split("$").str[0]
+    meta["feature"] = meta["COLUMN_NAME"].str.lower()
+
+    catalog = meta.groupby("feature", as_index=False).agg(
+        feature_view=("feature_view", lambda s: " | ".join(sorted(set(s)))),
+        data_type=("DATA_TYPE", lambda s: " | ".join(sorted(set(s.dropna().astype(str))))),
+        description=("COMMENT", lambda s: " || ".join(dict.fromkeys(x for x in s if x))),
+    )
+
+    if features is None:
+        return catalog.sort_values("feature").reset_index(drop=True)
+
+    # Preserve the caller's feature list/order; blanks where unmatched.
+    requested = pd.DataFrame({"feature": list(features)})
+    requested["_key"] = requested["feature"].str.lower()
+    out = requested.merge(
+        catalog.rename(columns={"feature": "_key"}), on="_key", how="left"
+    ).drop(columns="_key")
+    return out[["feature", "feature_view", "data_type", "description"]].fillna("")