gitlabds 2.4.3__tar.gz → 2.4.5__tar.gz

{gitlabds-2.4.3 → gitlabds-2.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.4.3
+Version: 2.4.5
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -790,7 +790,13 @@ display(effects_df)
 ```
 </details>
 
-<details><summary> Prescriptions </summary>
+<details><summary> Prescriptions (deprecated) </summary>
+
+> **Deprecated:** `prescriptions` raises a `DeprecationWarning` and will be removed in a future
+> release. Use `per_record_shap` and `per_record_counterfactuals` instead. Note that
+> `per_record_shap` requires a tree-based model (e.g. LightGBM, XGBoost), so they are not a
+> drop-in replacement for linear/logistic models. They also choose each move's direction from
+> the model and size moves from peer-group quantiles rather than a fixed step.
 
 #### Description
 Return "actionable" prescriptions and explanatory insights for each scored record. Insights first list actionable prescriptions follow by explainatory insights. This approach is recommended or linear/logistic methodologies only. Caution should be used if using a black box approach, as manpulating more than one prescription at a time could change a record's model score in unintended ways.  
@@ -1391,24 +1397,30 @@ Also worth knowing:
 <details><summary> Serve Features </summary>
 
 #### Description
-Serve features from Snowflake Feature Store with built-in distributed locking and retry logic. This function orchestrates feature retrieval from multiple feature views with support for point-in-time lookups and flexible parameter customization.
+Serve features from Snowflake Feature Store with per-call UDF parameters and retry logic. Each call shadows the shared `{FV}_DYNAMIC` view with a `CREATE OR REPLACE TEMPORARY VIEW` of the same name, so the parameters apply only to your Snowpark session: callers on other sessions (including your own other notebooks) never see them, and the permanent view keeps its UDF defaults.
+
+- **Schema:** view and UDF names are qualified with the feature view's database and schema, so a `USE SCHEMA` in your session doesn't change what is served.
+- **Redeploying in the same session:** the temporary views last until the session closes, so a session that serves and then redeploys the permanent `_DYNAMIC` view keeps reading its temporary view until the next `serve_features` call. Use a fresh session to read the redeployed defaults.
+- **Concurrency:** calls sharing one session object run one at a time. Open one session per thread for real parallelism.
+- **Feature-date check:** when `feature_date` is set, the served date is checked and a mismatch raises a warning, not an error: some feature views use a timestamp other than the snapshot date (e.g. a refresh week), so a mismatch isn't always wrong. With `spine_timestamp_col` and `include_feature_view_timestamp_col=True` the returned `{FV}_{version}_FEATURE_DATE` column is checked; otherwise the session's temporary view is queried before retrieval, which may run the whole UDF.
+- **Spine timestamps earlier than `feature_date`** match no feature rows in the point-in-time join and return all-null features. A warning is raised when this happens.
 
-`gitlabds.serve_features(session, feature_store, feature_views_dict, spine_df=None, feature_date=None, spine_timestamp_col=None, include_feature_view_timestamp_col=False, lookback_window_value=None, lookback_window_unit=None, lock_timeout_seconds=300, max_fetch_retries=3, fetch_retry_backoff_seconds=30):`
+`gitlabds.serve_features(session, feature_store, feature_views_dict, spine_df=None, feature_date=None, spine_timestamp_col=None, include_feature_view_timestamp_col=False, lookback_window_value=None, lookback_window_unit=None, lock_timeout_seconds=None, max_fetch_retries=3, fetch_retry_backoff_seconds=30):`
 
 #### Parameters:
-- **_session_** : Active Snowflake Session object
+- **_session_** : Active Snowflake Session object. Must be the session the FeatureStore was built with (`feature_store._session`); a different session raises `ValueError`, because retrieval could not see this call's temporary views.
 - **_feature_store_** : Initialized FeatureStore instance
 - **_feature_views_dict_** : Dictionary mapping feature view names to versions (e.g., {"sales_activities": "1.0"})
 - **_spine_df_** : One of the following:
   - SQL query string to generate the spine DataFrame
   - pandas DataFrame (will be converted to Snowpark DataFrame)
   - Snowpark DataFrame (used directly)
-- **_feature_date_** : Date for feature retrieval (e.g., '2025-04-08'). If None, uses UDF default.
+- **_feature_date_** : Date for feature retrieval (e.g., '2025-04-08'). If None, uses UDF default and skips the feature-date check.
 - **_spine_timestamp_col_** : Name of timestamp column in spine DataFrame for point-in-time lookup. Used for when multiple feature_dates may be present in the feature view. If only one feature_date is present, can set value to None for faster execution.
-- **_include_feature_view_timestamp_col_** : Whether to include timestamp column from feature views in output. Default is False.
+- **_include_feature_view_timestamp_col_** : Whether to include timestamp column from feature views in output. Only takes effect with `spine_timestamp_col`. Default is False.
 - **_lookback_window_value_** : Either a global integer value (e.g., 6) or a dict with feature-view-specific values
 - **_lookback_window_unit_** : Either a global string value (e.g., 'months') or a dict with feature-view-specific values
-- **_lock_timeout_seconds_** : Timeout in seconds for acquiring the Snowflake lock. Default is 300.
+- **_lock_timeout_seconds_** : Deprecated and ignored; the Snowflake lock table is no longer used. Passing it raises a `DeprecationWarning`.
 - **_max_fetch_retries_** : Maximum number of attempts for the result-fetch step (`retrieve_feature_values` + `to_arrow().to_pandas()`) when a transient network/streaming error occurs (e.g., `ChunkedEncodingError`, "Response ended prematurely"). Set to 1 to disable retries. Default is 3.
 - **_fetch_retry_backoff_seconds_** : Base sleep duration between fetch retries. Sleep grows linearly with attempt number (`attempt * backoff`). With defaults (3 retries, 30s base), sleeps are 30s before attempt 2 and 60s before attempt 3. Default is 30.
 
@@ -1468,10 +1480,10 @@ features = gitlabds.serve_features(
 
 </details>
 
-<details><summary> Clear Feature Serving Locks </summary>
+<details><summary> Clear Feature Serving Locks (deprecated) </summary>
 
 #### Description
-Utility function to manually clear all feature serving locks. Use this if locks get stuck due to killed processes.
+**Deprecated.** `serve_features` no longer uses the `FEATURE_SERVING_LOCKS` table, so there is nothing to get stuck. This clears any leftover rows from that table, raises a `DeprecationWarning`, and will be removed in a future release. The table can be dropped.
 
 `gitlabds.clear_feature_serving_locks(session):`
 

{gitlabds-2.4.3 → gitlabds-2.4.5}/README.md

@@ -754,7 +754,13 @@ display(effects_df)
 ```
 </details>
 
-<details><summary> Prescriptions </summary>
+<details><summary> Prescriptions (deprecated) </summary>
+
+> **Deprecated:** `prescriptions` raises a `DeprecationWarning` and will be removed in a future
+> release. Use `per_record_shap` and `per_record_counterfactuals` instead. Note that
+> `per_record_shap` requires a tree-based model (e.g. LightGBM, XGBoost), so they are not a
+> drop-in replacement for linear/logistic models. They also choose each move's direction from
+> the model and size moves from peer-group quantiles rather than a fixed step.
 
 #### Description
 Return "actionable" prescriptions and explanatory insights for each scored record. Insights first list actionable prescriptions follow by explainatory insights. This approach is recommended or linear/logistic methodologies only. Caution should be used if using a black box approach, as manpulating more than one prescription at a time could change a record's model score in unintended ways.  
@@ -1355,24 +1361,30 @@ Also worth knowing:
 <details><summary> Serve Features </summary>
 
 #### Description
-Serve features from Snowflake Feature Store with built-in distributed locking and retry logic. This function orchestrates feature retrieval from multiple feature views with support for point-in-time lookups and flexible parameter customization.
+Serve features from Snowflake Feature Store with per-call UDF parameters and retry logic. Each call shadows the shared `{FV}_DYNAMIC` view with a `CREATE OR REPLACE TEMPORARY VIEW` of the same name, so the parameters apply only to your Snowpark session: callers on other sessions (including your own other notebooks) never see them, and the permanent view keeps its UDF defaults.
+
+- **Schema:** view and UDF names are qualified with the feature view's database and schema, so a `USE SCHEMA` in your session doesn't change what is served.
+- **Redeploying in the same session:** the temporary views last until the session closes, so a session that serves and then redeploys the permanent `_DYNAMIC` view keeps reading its temporary view until the next `serve_features` call. Use a fresh session to read the redeployed defaults.
+- **Concurrency:** calls sharing one session object run one at a time. Open one session per thread for real parallelism.
+- **Feature-date check:** when `feature_date` is set, the served date is checked and a mismatch raises a warning, not an error: some feature views use a timestamp other than the snapshot date (e.g. a refresh week), so a mismatch isn't always wrong. With `spine_timestamp_col` and `include_feature_view_timestamp_col=True` the returned `{FV}_{version}_FEATURE_DATE` column is checked; otherwise the session's temporary view is queried before retrieval, which may run the whole UDF.
+- **Spine timestamps earlier than `feature_date`** match no feature rows in the point-in-time join and return all-null features. A warning is raised when this happens.
 
-`gitlabds.serve_features(session, feature_store, feature_views_dict, spine_df=None, feature_date=None, spine_timestamp_col=None, include_feature_view_timestamp_col=False, lookback_window_value=None, lookback_window_unit=None, lock_timeout_seconds=300, max_fetch_retries=3, fetch_retry_backoff_seconds=30):`
+`gitlabds.serve_features(session, feature_store, feature_views_dict, spine_df=None, feature_date=None, spine_timestamp_col=None, include_feature_view_timestamp_col=False, lookback_window_value=None, lookback_window_unit=None, lock_timeout_seconds=None, max_fetch_retries=3, fetch_retry_backoff_seconds=30):`
 
 #### Parameters:
-- **_session_** : Active Snowflake Session object
+- **_session_** : Active Snowflake Session object. Must be the session the FeatureStore was built with (`feature_store._session`); a different session raises `ValueError`, because retrieval could not see this call's temporary views.
 - **_feature_store_** : Initialized FeatureStore instance
 - **_feature_views_dict_** : Dictionary mapping feature view names to versions (e.g., {"sales_activities": "1.0"})
 - **_spine_df_** : One of the following:
   - SQL query string to generate the spine DataFrame
   - pandas DataFrame (will be converted to Snowpark DataFrame)
   - Snowpark DataFrame (used directly)
-- **_feature_date_** : Date for feature retrieval (e.g., '2025-04-08'). If None, uses UDF default.
+- **_feature_date_** : Date for feature retrieval (e.g., '2025-04-08'). If None, uses UDF default and skips the feature-date check.
 - **_spine_timestamp_col_** : Name of timestamp column in spine DataFrame for point-in-time lookup. Used for when multiple feature_dates may be present in the feature view. If only one feature_date is present, can set value to None for faster execution.
-- **_include_feature_view_timestamp_col_** : Whether to include timestamp column from feature views in output. Default is False.
+- **_include_feature_view_timestamp_col_** : Whether to include timestamp column from feature views in output. Only takes effect with `spine_timestamp_col`. Default is False.
 - **_lookback_window_value_** : Either a global integer value (e.g., 6) or a dict with feature-view-specific values
 - **_lookback_window_unit_** : Either a global string value (e.g., 'months') or a dict with feature-view-specific values
-- **_lock_timeout_seconds_** : Timeout in seconds for acquiring the Snowflake lock. Default is 300.
+- **_lock_timeout_seconds_** : Deprecated and ignored; the Snowflake lock table is no longer used. Passing it raises a `DeprecationWarning`.
 - **_max_fetch_retries_** : Maximum number of attempts for the result-fetch step (`retrieve_feature_values` + `to_arrow().to_pandas()`) when a transient network/streaming error occurs (e.g., `ChunkedEncodingError`, "Response ended prematurely"). Set to 1 to disable retries. Default is 3.
 - **_fetch_retry_backoff_seconds_** : Base sleep duration between fetch retries. Sleep grows linearly with attempt number (`attempt * backoff`). With defaults (3 retries, 30s base), sleeps are 30s before attempt 2 and 60s before attempt 3. Default is 30.
 
@@ -1432,10 +1444,10 @@ features = gitlabds.serve_features(
 
 </details>
 
-<details><summary> Clear Feature Serving Locks </summary>
+<details><summary> Clear Feature Serving Locks (deprecated) </summary>
 
 #### Description
-Utility function to manually clear all feature serving locks. Use this if locks get stuck due to killed processes.
+**Deprecated.** `serve_features` no longer uses the `FEATURE_SERVING_LOCKS` table, so there is nothing to get stuck. This clears any leftover rows from that table, raises a `DeprecationWarning`, and will be removed in a future release. The table can be dropped.
 
 `gitlabds.clear_feature_serving_locks(session):`
 

{gitlabds-2.4.3 → gitlabds-2.4.5}/gitlabds/insights.py

@@ -1,3 +1,5 @@
+import warnings
+
 import pandas as pd
 import numpy as np
 
@@ -283,8 +285,18 @@ def prescriptions(model, input_df:pd.DataFrame, scored_df:pd.DataFrame, actionab
     explanation_fields : List of explainable (non-actionable insights) fields to return insights for. Defaults to 'all' for all fields.
 
 
-    Returns a Dataframe of prescriptive actions. One row per record input."""
-    
+    Returns a Dataframe of prescriptive actions. One row per record input.
+
+    Deprecated: use per_record_shap and per_record_counterfactuals instead. prescriptions will
+    be removed in a future release."""
+
+    warnings.warn(
+        "gitlabds.prescriptions is deprecated and will be removed in a future release. "
+        "Use gitlabds.per_record_shap and gitlabds.per_record_counterfactuals instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
     bf = pd.DataFrame(input_df.columns.tolist(), columns=['feature'])
     
     change_score = pd.DataFrame()