gitlabds 2.4.3__tar.gz → 2.4.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.4.3
+Version: 2.4.4
 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 verified and a mismatch raises `ValueError`. 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.4}/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 verified and a mismatch raises `ValueError`. 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.4}/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()

gitlabds-2.4.4/gitlabds/serving_features.py

@@ -0,0 +1,484 @@
+"""
+Feature serving functionality for Snowflake Feature Store integration.
+
+This module serves features from Snowflake Feature Store. Each call applies its parameters
+through session-scoped temporary views, so callers on different Snowpark sessions never see
+each other's parameters, and calls sharing one session are serialized in-process.
+
+Requires the optional Snowflake dependencies: pip install gitlabds[snowflake]
+"""
+
+import datetime
+import threading
+import time
+import uuid
+import warnings
+import weakref
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+from snowflake.snowpark import Session, DataFrame as SnowparkDataFrame
+from snowflake.ml.feature_store import FeatureStore
+
+
+_SESSION_LOCKS: "weakref.WeakKeyDictionary[Session, threading.Lock]" = weakref.WeakKeyDictionary()
+_SESSION_LOCKS_GUARD = threading.Lock()
+
+
+# Transient network/streaming errors that warrant a retry of the result fetch.
+# These are the errors that surface when the HTTP response from Snowflake is
+# interrupted mid-stream (e.g., flaky network, VPN blip, load-balancer reset).
+def _is_transient_fetch_error(exc: BaseException) -> bool:
+    """Return True if the exception looks like a transient streaming/network failure."""
+    # Match by class name to avoid hard imports of requests / urllib3 at module load.
+    transient_class_names = {
+        "ChunkedEncodingError",
+        "ProtocolError",
+        "ConnectionError",
+        "ConnectionResetError",
+        "ReadTimeoutError",
+        "ReadTimeout",
+        "IncompleteRead",
+    }
+    # Walk the exception chain — Snowpark often wraps the original error.
+    seen = set()
+    current = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        if type(current).__name__ in transient_class_names:
+            return True
+        msg = str(current).lower()
+        if "response ended prematurely" in msg:
+            return True
+        if "connection reset" in msg:
+            return True
+        if "connection aborted" in msg:
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def _session_lock(session: "Session") -> threading.Lock:
+    """Return the process-local lock that serializes serve_features calls on one session."""
+    with _SESSION_LOCKS_GUARD:
+        return _SESSION_LOCKS.setdefault(session, threading.Lock())
+
+
+def _to_date(value: Any) -> datetime.date:
+    """Normalize a date-like value (str, date, datetime, Timestamp) to a datetime.date."""
+    return pd.Timestamp(value).date()
+
+
+def _check_dynamic_view_feature_date(
+    session: "Session",
+    dynamic_view: str,
+    timestamp_col: str,
+    feature_date: str,
+) -> None:
+    """Raise if the session's dynamic view does not return the requested feature_date."""
+    rows = session.sql(f"SELECT {timestamp_col} FROM {dynamic_view} LIMIT 1").collect()
+    if not rows:
+        warnings.warn(
+            f"{dynamic_view} returned no rows; could not verify feature_date {feature_date}"
+        )
+        return
+    actual = rows[0][0]
+    if actual is None or _to_date(actual) != _to_date(feature_date):
+        raise ValueError(
+            f"{dynamic_view} returned {timestamp_col} {actual}, expected {feature_date}. "
+            f"The session's temporary view is not serving the requested parameters."
+        )
+
+
+def _check_retrieved_feature_date(
+    features_df: pd.DataFrame,
+    feature_date_col: str,
+    feature_date: str,
+) -> None:
+    """Raise if a retrieved feature-date column holds any date other than feature_date."""
+    values = features_df[feature_date_col].dropna()
+    if values.empty:
+        warnings.warn(
+            f"{feature_date_col} is null for every row, so all features from that view are "
+            f"null. A spine timestamp earlier than feature_date {feature_date} matches no "
+            f"feature rows in the point-in-time join."
+        )
+        return
+    expected = _to_date(feature_date)
+    mismatched = sorted({d for d in values.map(_to_date) if d != expected})
+    if mismatched:
+        raise ValueError(
+            f"{feature_date_col} returned {mismatched}, expected {feature_date}. "
+            f"The session's temporary view is not serving the requested parameters."
+        )
+
+
+def _warn_spine_before_feature_date(
+    features_df: pd.DataFrame,
+    spine_timestamp_col: str,
+    feature_date: str,
+) -> None:
+    """Warn when spine timestamps precede feature_date, which yields all-null features."""
+    matches = [c for c in features_df.columns if c.upper() == spine_timestamp_col.upper()]
+    if not matches or features_df.empty:
+        return
+    spine_ts = pd.to_datetime(features_df[matches[0]])
+    if getattr(spine_ts.dt, "tz", None) is not None:
+        spine_ts = spine_ts.dt.tz_localize(None)
+    n_early = int((spine_ts.dt.normalize() < pd.Timestamp(feature_date)).sum())
+    if n_early:
+        pct = n_early / len(features_df)
+        warnings.warn(
+            f"{n_early} spine rows ({pct:.2%}) have {spine_timestamp_col} earlier than "
+            f"feature_date {feature_date}. The point-in-time join returns null features "
+            f"for those rows."
+        )
+
+
+def clear_feature_serving_locks(session: "Session") -> int:
+    """
+    Clear rows from the legacy FEATURE_SERVING_LOCKS table.
+
+    Deprecated: serve_features no longer uses a Snowflake lock table, so there is nothing
+    to get stuck. This function will be removed in a future release, and the
+    FEATURE_SERVING_LOCKS table can be dropped.
+
+    Parameters
+    ----------
+    session : snowflake.snowpark.Session
+        Active Snowflake Session object.
+
+    Returns
+    -------
+    int
+        Number of lock rows cleared, or 0 if none exist or the table is gone.
+    """
+    warnings.warn(
+        "gitlabds.clear_feature_serving_locks is deprecated and will be removed in a future "
+        "release. serve_features no longer uses the FEATURE_SERVING_LOCKS table.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    lock_table = "FEATURE_SERVING_LOCKS"
+    lock_name = "FEATURE_SERVING"
+
+    try:
+        existing_locks = session.sql(f"""
+            SELECT session_id, acquired_at, expires_at,
+                   CASE WHEN expires_at > CURRENT_TIMESTAMP() THEN 'ACTIVE' ELSE 'EXPIRED' END as status
+            FROM {lock_table}
+            WHERE lock_name = '{lock_name}'
+            ORDER BY acquired_at DESC
+        """).collect()
+
+        if existing_locks:
+            print("🔍 Current feature serving locks:")
+            for lock in existing_locks:
+                print(f"  Session: {lock['SESSION_ID']}, "
+                      f"Acquired: {lock['ACQUIRED_AT']}, "
+                      f"Expires: {lock['EXPIRES_AT']}, "
+                      f"Status: {lock['STATUS']}")
+        else:
+            print("✅ No existing locks found")
+            return 0
+
+        session.sql(f"""
+            DELETE FROM {lock_table}
+            WHERE lock_name = '{lock_name}'
+        """).collect()
+
+        locks_cleared = len(existing_locks)
+        print(f"🧹 Cleared {locks_cleared} feature serving locks")
+        return locks_cleared
+
+    except Exception as e:
+        print(f"❌ Error clearing locks: {e}")
+        return 0
+
+
+def _udf_params(
+    fv_name: str,
+    feature_date: Optional[str],
+    lookback_window_value: Optional[Union[int, Dict[str, int]]],
+    lookback_window_unit: Optional[Union[str, Dict[str, str]]],
+) -> List[str]:
+    """Build the positional UDF arguments: SNAPSHOT_DATE, LOOKBACK_WINDOW_VALUE, LOOKBACK_WINDOW_UNIT."""
+    udf_params = []
+
+    if feature_date:
+        udf_params.append(f"'{feature_date}'::DATE")
+        print(f"  Using snapshot date: {feature_date}")
+    else:
+        print("  Using UDF default snapshot date")
+
+    if isinstance(lookback_window_value, dict) and fv_name in lookback_window_value:
+        udf_params.append(str(lookback_window_value[fv_name]))
+        print(f"  Using per-UDF lookback window value: {lookback_window_value[fv_name]}")
+    elif lookback_window_value is not None and not isinstance(lookback_window_value, dict):
+        udf_params.append(str(lookback_window_value))
+        print(f"  Using global lookback window value: {lookback_window_value}")
+    else:
+        print("  Using UDF default lookback window value")
+
+    if isinstance(lookback_window_unit, dict) and fv_name in lookback_window_unit:
+        udf_params.append(f"'{lookback_window_unit[fv_name]}'")
+        print(f"  Using per-UDF lookback window unit: {lookback_window_unit[fv_name]}")
+    elif lookback_window_unit is not None and not isinstance(lookback_window_unit, dict):
+        udf_params.append(f"'{lookback_window_unit}'")
+        print(f"  Using global lookback window unit: {lookback_window_unit}")
+    else:
+        print("  Using UDF default lookback window unit")
+
+    return udf_params
+
+
+def serve_features(
+    session: "Session",
+    feature_store: "FeatureStore",
+    feature_views_dict: Dict[str, str],
+    spine_df: Optional[Union[str, pd.DataFrame, "SnowparkDataFrame"]] = None,
+    feature_date: Optional[str] = None,
+    spine_timestamp_col: Optional[str] = None,
+    include_feature_view_timestamp_col: bool = False,
+    lookback_window_value: Optional[Union[int, Dict[str, int]]] = None,
+    lookback_window_unit: Optional[Union[str, Dict[str, str]]] = None,
+    lock_timeout_seconds: Optional[int] = None,
+    max_fetch_retries: int = 3,
+    fetch_retry_backoff_seconds: int = 30,
+) -> pd.DataFrame:
+    """
+    Serve features from Snowflake Feature Store with per-call UDF parameters.
+
+    Each feature view reads from a ``{FV}_DYNAMIC`` view. This function shadows that view
+    with a ``CREATE OR REPLACE TEMPORARY VIEW`` of the same name that calls ``{FV}_UDF``
+    with this call's parameters. Temporary views are scoped to the Snowpark session, so
+    callers on different sessions (including the same user in two notebooks) never see
+    each other's parameters, and the permanent ``_DYNAMIC`` view keeps its UDF defaults.
+    View and UDF names are qualified with the feature view's database and schema, so the
+    session's current schema does not matter.
+
+    The temporary views last until the session closes. A session that serves features 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.
+
+    Calls sharing one session object run one at a time: a process-local lock per session
+    is held for the whole call. Open one session per thread for real parallelism.
+
+    When ``feature_date`` is set, the served feature date is verified. With
+    ``spine_timestamp_col`` and ``include_feature_view_timestamp_col=True`` the returned
+    ``{FV}_{version}_{timestamp_col}`` column is checked; otherwise the session's temporary view is
+    queried before retrieval (``SELECT {timestamp_col} ... LIMIT 1``), which may run the
+    whole UDF.
+
+    Parameters
+    ----------
+    session : snowflake.snowpark.Session
+        Active Snowflake Session object. Must be the session ``feature_store`` was built
+        with (``feature_store._session``): retrieval reads through that session, so temp
+        views created on any other session are invisible to it.
+    feature_store : snowflake.ml.feature_store.FeatureStore
+        Initialized FeatureStore instance.
+    feature_views_dict : Dict[str, str]
+        Mapping of feature view names to versions (e.g., {"sales_activities": "1.0"}).
+    spine_df : Union[str, pd.DataFrame, snowflake.snowpark.DataFrame]
+        SQL query string, pandas DataFrame (converted to Snowpark), or Snowpark DataFrame.
+        Required by the Feature Store SDK; None raises ValueError.
+    feature_date : str, optional
+        Snapshot date for features (e.g., '2025-04-08'). If None, uses the UDF default and
+        the feature-date check is skipped.
+    spine_timestamp_col : str, optional
+        Name of the timestamp column in the spine for point-in-time lookup. If None,
+        point-in-time lookup is disabled. Spine timestamps earlier than ``feature_date``
+        match no feature rows and return null features; a warning is raised when that
+        happens.
+    include_feature_view_timestamp_col : bool, default=False
+        Include each feature view's timestamp column in the output. Only takes effect with
+        ``spine_timestamp_col``.
+    lookback_window_value : Union[int, Dict[str, int]], optional
+        Global integer (e.g., 6) or per-feature-view dict
+        (e.g., {"sales_activities_by_account": 3}).
+    lookback_window_unit : Union[str, Dict[str, str]], optional
+        Global string (e.g., 'months') or per-feature-view dict
+        (e.g., {"sales_activities_by_account": 'days'}).
+    lock_timeout_seconds : int, optional
+        Deprecated and ignored. The Snowflake lock table is no longer used.
+    max_fetch_retries : int, default=3
+        Maximum attempts for the result fetch (retrieve_feature_values +
+        to_arrow().to_pandas()) on transient network/streaming errors. 1 disables retries.
+    fetch_retry_backoff_seconds : int, default=30
+        Base sleep between fetch retries; grows linearly (attempt * backoff).
+
+    Returns
+    -------
+    pd.DataFrame
+        Combined features from all feature views, with lowercase column names.
+
+    Raises
+    ------
+    TypeError
+        When spine_df or feature_views_dict has the wrong type.
+    ValueError
+        When spine_df is None, feature_views_dict is empty, session is not the feature
+        store's session, or the served feature date does not match ``feature_date``.
+
+    Examples
+    --------
+    >>> df = serve_features(session, fs, {"sales_activities": "1.0"},
+    ...                     spine_df="SELECT account_id FROM accounts",
+    ...                     feature_date="2025-04-08")
+    """
+    if not isinstance(feature_views_dict, dict):
+        raise TypeError(f"feature_views_dict must be a dict, got {type(feature_views_dict)}")
+    if not feature_views_dict:
+        raise ValueError("feature_views_dict is empty")
+    if spine_df is None:
+        raise ValueError("spine_df is required - the Snowflake Feature Store SDK requires a spine DataFrame")
+    if not isinstance(spine_df, (str, pd.DataFrame, SnowparkDataFrame)):
+        raise TypeError(
+            f"spine_df must be a SQL query string, pandas DataFrame, or Snowpark DataFrame, "
+            f"got {type(spine_df)}"
+        )
+    if lock_timeout_seconds is not None:
+        warnings.warn(
+            "lock_timeout_seconds is deprecated and ignored: serve_features no longer uses a "
+            "Snowflake lock. It will be removed in a future release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    fs_session = getattr(feature_store, "_session", None)
+    if fs_session is None:
+        warnings.warn(
+            "Could not read feature_store._session to confirm it is the session passed to "
+            "serve_features. If they differ, retrieval cannot see this call's temporary "
+            "views and returns UDF-default features."
+        )
+    elif fs_session is not session:
+        raise ValueError(
+            "session must be the session feature_store was built with (feature_store._session). "
+            "Retrieval reads through the feature store's session, so temporary views created "
+            "on a different session are invisible to it and UDF-default features would be "
+            "returned. Pass session=feature_store._session."
+        )
+
+    call_id = f"call_{uuid.uuid4().hex[:8]}"
+    check_returned_column = (
+        bool(feature_date)
+        and spine_timestamp_col is not None
+        and include_feature_view_timestamp_col
+    )
+
+    lock = _session_lock(session)
+    if not lock.acquire(blocking=False):
+        print(f"⏳ [{call_id}] Waiting for another serve_features call on this session")
+        lock.acquire()
+
+    try:
+        feature_views_list = []
+        feature_date_cols = {}
+
+        for fv_name, version in feature_views_dict.items():
+            fv = feature_store.get_feature_view(fv_name, version)
+            feature_views_list.append(fv)
+
+            fv_schema = f"{fv.database}.{fv.schema}"
+            dynamic_view = f"{fv_schema}.{fv_name.upper()}_DYNAMIC"
+            udf_name = f"{fv_schema}.{fv_name.upper()}_UDF"
+            entity_id = fv.entities[0].join_keys[0]
+            timestamp_col = fv.timestamp_col
+
+            print(f"[{call_id}] {fv_name} v{version}:")
+            print(f"  Dynamic View: {dynamic_view} (temporary)")
+            print(f"  UDF: {udf_name}")
+            print(f"  Entity: {entity_id}")
+            print(f"  Timestamp: {timestamp_col}")
+
+            params_str = ", ".join(
+                _udf_params(fv_name, feature_date, lookback_window_value, lookback_window_unit)
+            )
+            update_view_sql = f"""
+                CREATE OR REPLACE TEMPORARY VIEW {dynamic_view} AS
+                SELECT * FROM TABLE({udf_name}({params_str}))
+                """
+            print(f"  {update_view_sql.strip()}")
+            session.sql(update_view_sql).collect()
+            print(f"  [{call_id}] Updated {dynamic_view}")
+
+            if not feature_date:
+                continue
+            if not timestamp_col:
+                warnings.warn(
+                    f"{fv_name} has no timestamp_col; could not verify feature_date {feature_date}"
+                )
+            elif check_returned_column:
+                feature_date_cols[f"{fv_name}_{version}_{timestamp_col}".upper()] = (
+                    dynamic_view,
+                    timestamp_col,
+                )
+            else:
+                _check_dynamic_view_feature_date(session, dynamic_view, timestamp_col, feature_date)
+                print(f"  [{call_id}] Verified {dynamic_view} serves {timestamp_col} {feature_date}")
+
+        if isinstance(spine_df, str):
+            snowpark_spine_df = session.sql(spine_df)
+            print(f"[{call_id}] Created spine from SQL query")
+        elif isinstance(spine_df, pd.DataFrame):
+            snowpark_spine_df = session.create_dataframe(spine_df)
+            print(f"[{call_id}] Created spine from pandas DataFrame")
+        else:
+            snowpark_spine_df = spine_df
+            print(f"[{call_id}] Using provided Snowpark DataFrame")
+
+        print(f"[{call_id}] Spine contains {snowpark_spine_df.count()} entities")
+
+        retrieve_kwargs = {
+            "spine_df": snowpark_spine_df,
+            "features": feature_views_list,
+            "include_feature_view_timestamp_col": include_feature_view_timestamp_col,
+        }
+        if spine_timestamp_col is not None:
+            retrieve_kwargs["spine_timestamp_col"] = spine_timestamp_col
+            print(f"[{call_id}] Using point-in-time lookup with timestamp column: {spine_timestamp_col}")
+        else:
+            print(f"[{call_id}] Point-in-time lookup disabled (no spine_timestamp_col)")
+
+        for fetch_attempt in range(1, max(1, max_fetch_retries) + 1):
+            try:
+                if fetch_attempt == 1:
+                    print(f"[{call_id}] Starting retrieve_feature_values (this may take a while)...")
+                else:
+                    print(f"[{call_id}] Retrying retrieve_feature_values "
+                          f"(attempt {fetch_attempt}/{max_fetch_retries}) after transient error...")
+
+                snowpark_features = feature_store.retrieve_feature_values(**retrieve_kwargs)
+                combined_features = snowpark_features.to_arrow().to_pandas()
+                break
+            except Exception as fetch_err:
+                if _is_transient_fetch_error(fetch_err) and fetch_attempt < max_fetch_retries:
+                    sleep_for = fetch_retry_backoff_seconds * fetch_attempt
+                    print(f"⚠️ [{call_id}] Transient fetch error "
+                          f"({type(fetch_err).__name__}: {fetch_err}). "
+                          f"Sleeping {sleep_for}s before retry "
+                          f"{fetch_attempt + 1}/{max_fetch_retries}...")
+                    time.sleep(sleep_for)
+                    continue
+                raise
+
+        returned_cols = {c.upper(): c for c in combined_features.columns}
+        for col, (dynamic_view, timestamp_col) in feature_date_cols.items():
+            if col in returned_cols:
+                _check_retrieved_feature_date(combined_features, returned_cols[col], feature_date)
+            else:
+                _check_dynamic_view_feature_date(session, dynamic_view, timestamp_col, feature_date)
+            print(f"[{call_id}] Verified {col} matches feature_date {feature_date}")
+
+        if spine_timestamp_col is not None and feature_date:
+            _warn_spine_before_feature_date(combined_features, spine_timestamp_col, feature_date)
+
+        combined_features.columns = map(str.lower, combined_features.columns)
+
+        print(f"✅ [{call_id}] Feature serving completed successfully")
+        return combined_features
+
+    finally:
+        lock.release()