gitlabds 2.1.7__tar.gz → 2.1.8__tar.gz

{gitlabds-2.1.7/gitlabds.egg-info → gitlabds-2.1.8}/PKG-INFO

@@ -1,22 +1,34 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.1.7
-Summary: Gitlab Data Science and Modeling Tools
-Home-page: https://gitlab.com/gitlab-data/gitlabds
-Author: Kevin Dietz
-Author-email: kdietz@gitlab.com
+Version: 2.1.8
+Summary: GitLab Data Science Tools
+Author-email: Kevin Dietz <kdietz@gitlab.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/gitlab-data/gitlabds
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pandas>=1.5.3
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: scikit-learn>=1.1.1
+Requires-Dist: imbalanced-learn>=0.9.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: shap>=0.50.0
+Requires-Dist: tqdm>=4.66.2
+Requires-Dist: xgboost>=1.6.1
+Provides-Extra: feature-store
+Requires-Dist: snowflake-snowpark-python; extra == "feature-store"
+Requires-Dist: snowflake-ml-python; extra == "feature-store"
+Dynamic: license-file
 
 [![PyPI version](https://badge.fury.io/py/gitlabds.svg)](https://badge.fury.io/py/gitlabds)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -35,7 +47,7 @@ pip install gitlabds
 
 ### Requirements
 
-- Python 3.10 or later
+- Python 3.11 or later
 - Core dependencies:
    - pandas>=1.5.3
    - numpy>=1.23.5
@@ -43,8 +55,27 @@ pip install gitlabds
    - scikit-learn>=1.1.1
    - imbalanced-learn>=0.9.1
    - seaborn>=0.13.2
-   - shap>=0.41.0
+   - shap>=0.50.0
    - tqdm>=4.66.2
+   - xgboost>=1.6.1
+
+### Optional Dependencies
+
+#### Snowflake Feature Store
+
+The `serve_features` and `clear_feature_serving_locks` functions require additional Snowflake dependencies.
+
+To use these functions, install with:
+
+```bash
+pip install gitlabds[feature-store]
+```
+
+This will install:
+- `snowflake-snowpark-python`
+- `snowflake-ml-python`
+
+If you try to use these functions without installing the optional dependencies, you'll get an error message with installation instructions.
 
 ## Main Features by Category
 
@@ -903,6 +934,115 @@ feature_drift = results['feature_drift']
 ```
 </details>
 
+### Deployment
+
+#### Feature Serving
+
+<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.
+
+`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):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+- **_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.
+- **_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.
+- **_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.
+
+#### Returns
+- DataFrame with combined features from all feature views
+
+#### Requirements
+This function requires Snowflake packages. Install with:
+```bash
+pip install snowflake-snowpark-python snowflake-ml-python
+```
+
+#### Examples:
+
+```python
+# Basic usage with SQL spine
+import gitlabds
+from snowflake.snowpark import Session
+from snowflake.ml.feature_store import FeatureStore
+
+session = Session.builder.configs(...).create()
+fs = FeatureStore(session, ...)
+
+spine_sql = "SELECT account_id FROM accounts WHERE active = TRUE"
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "marketing_activity": "2.1"},
+    spine_df=spine_sql,
+    feature_date=None
+)
+```
+
+```python
+# With per-feature-view parameters
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "product_stage": "2.1"},
+    spine_df=spine_df,
+    lookback_window_value={"sales_activities": 3, "product_stage": 6},
+    lookback_window_unit={"sales_activities": "days", "product_stage": "months"}
+)
+```
+
+```python
+# With point-in-time lookup
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0"},
+    spine_df=spine_df,
+    spine_timestamp_col="snapshot_date",
+    feature_date="2025-04-08"
+)
+```
+
+</details>
+
+<details><summary> Clear Feature Serving Locks </summary>
+
+#### Description
+Utility function to manually clear all feature serving locks. Use this if locks get stuck due to killed processes.
+
+`gitlabds.clear_feature_serving_locks(session):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+
+#### Returns
+- int: Number of locks cleared
+
+#### Examples:
+
+```python
+# Clear stuck locks
+import gitlabds
+from snowflake.snowpark import Session
+
+session = Session.builder.configs(...).create()
+locks_cleared = gitlabds.clear_feature_serving_locks(session)
+print(f"Cleared {locks_cleared} locks")
+```
+
+</details>
+
 ### SQL and Trend Analysis
 
 <details><summary> SQL Trend Query Generator </summary>

gitlabds-2.1.7/PKG-INFO → gitlabds-2.1.8/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.1
-Name: gitlabds
-Version: 2.1.7
-Summary: Gitlab Data Science and Modeling Tools
-Home-page: https://gitlab.com/gitlab-data/gitlabds
-Author: Kevin Dietz
-Author-email: kdietz@gitlab.com
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Scientific/Engineering :: Information Analysis
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Utilities
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 [![PyPI version](https://badge.fury.io/py/gitlabds.svg)](https://badge.fury.io/py/gitlabds)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -35,7 +15,7 @@ pip install gitlabds
 
 ### Requirements
 
-- Python 3.10 or later
+- Python 3.11 or later
 - Core dependencies:
    - pandas>=1.5.3
    - numpy>=1.23.5
@@ -43,8 +23,27 @@ pip install gitlabds
    - scikit-learn>=1.1.1
    - imbalanced-learn>=0.9.1
    - seaborn>=0.13.2
-   - shap>=0.41.0
+   - shap>=0.50.0
    - tqdm>=4.66.2
+   - xgboost>=1.6.1
+
+### Optional Dependencies
+
+#### Snowflake Feature Store
+
+The `serve_features` and `clear_feature_serving_locks` functions require additional Snowflake dependencies.
+
+To use these functions, install with:
+
+```bash
+pip install gitlabds[feature-store]
+```
+
+This will install:
+- `snowflake-snowpark-python`
+- `snowflake-ml-python`
+
+If you try to use these functions without installing the optional dependencies, you'll get an error message with installation instructions.
 
 ## Main Features by Category
 
@@ -903,6 +902,115 @@ feature_drift = results['feature_drift']
 ```
 </details>
 
+### Deployment
+
+#### Feature Serving
+
+<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.
+
+`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):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+- **_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.
+- **_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.
+- **_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.
+
+#### Returns
+- DataFrame with combined features from all feature views
+
+#### Requirements
+This function requires Snowflake packages. Install with:
+```bash
+pip install snowflake-snowpark-python snowflake-ml-python
+```
+
+#### Examples:
+
+```python
+# Basic usage with SQL spine
+import gitlabds
+from snowflake.snowpark import Session
+from snowflake.ml.feature_store import FeatureStore
+
+session = Session.builder.configs(...).create()
+fs = FeatureStore(session, ...)
+
+spine_sql = "SELECT account_id FROM accounts WHERE active = TRUE"
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "marketing_activity": "2.1"},
+    spine_df=spine_sql,
+    feature_date=None
+)
+```
+
+```python
+# With per-feature-view parameters
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "product_stage": "2.1"},
+    spine_df=spine_df,
+    lookback_window_value={"sales_activities": 3, "product_stage": 6},
+    lookback_window_unit={"sales_activities": "days", "product_stage": "months"}
+)
+```
+
+```python
+# With point-in-time lookup
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0"},
+    spine_df=spine_df,
+    spine_timestamp_col="snapshot_date",
+    feature_date="2025-04-08"
+)
+```
+
+</details>
+
+<details><summary> Clear Feature Serving Locks </summary>
+
+#### Description
+Utility function to manually clear all feature serving locks. Use this if locks get stuck due to killed processes.
+
+`gitlabds.clear_feature_serving_locks(session):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+
+#### Returns
+- int: Number of locks cleared
+
+#### Examples:
+
+```python
+# Clear stuck locks
+import gitlabds
+from snowflake.snowpark import Session
+
+session = Session.builder.configs(...).create()
+locks_cleared = gitlabds.clear_feature_serving_locks(session)
+print(f"Cleared {locks_cleared} locks")
+```
+
+</details>
+
 ### SQL and Trend Analysis
 
 <details><summary> SQL Trend Query Generator </summary>

{gitlabds-2.1.7 → gitlabds-2.1.8}/gitlabds/__init__.py

@@ -10,3 +10,18 @@ from .monitoring_metrics import calculate_monitoring_metrics, calculate_baseline
 from .outliers import mad_outliers, apply_outliers
 from .split_data import split_data
 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
+except ImportError as e:
+    # Snowflake packages not installed - create placeholder functions with helpful error messages
+    def _snowflake_not_installed(*args, **kwargs):
+        raise ImportError(
+            "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
+

gitlabds-2.1.8/gitlabds/serving_features.py

@@ -0,0 +1,386 @@
+"""
+Feature serving functionality for Snowflake Feature Store integration.
+
+This module provides utilities for serving features from Snowflake Feature Store
+in production environments, including distributed locking mechanisms and retry logic.
+
+Note: This module requires snowflake-snowpark-python and snowflake-ml-python packages.
+"""
+
+import time
+import uuid
+from typing import Dict, Optional, Union
+import pandas as pd
+
+# Optional imports with graceful fallback
+try:
+    from snowflake.snowpark import Session, DataFrame as SnowparkDataFrame
+    from snowflake.ml.feature_store import FeatureStore
+    SNOWFLAKE_AVAILABLE = True
+except ImportError:
+    SNOWFLAKE_AVAILABLE = False
+    SnowparkDataFrame = None
+    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 serving. "
+            "Install with: pip install snowflake-snowpark-python snowflake-ml-python"
+        )
+
+
+def clear_feature_serving_locks(session: 'Session') -> int:
+    """
+    Utility function to manually clear all feature serving locks.
+    
+    Use this if locks get stuck due to killed processes. This function checks
+    for existing locks, cleans up expired ones, and provides detailed status
+    information.
+    
+    Args:
+        session: Snowflake Session object      
+    Returns:
+        Number of locks cleared
+    """
+    _check_snowflake_available()
+    
+    # Constants - these are safe, not user-controlled
+    LOCK_TABLE = "FEATURE_SERVING_LOCKS"
+    LOCK_NAME = "FEATURE_SERVING"
+    
+    try:
+        # Check existing locks first
+        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
+        
+        # Clear all locks
+        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 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: int = 300
+) -> pd.DataFrame:
+    """
+    Serve features using simplified workflow with Snowflake-based locking and retry mechanism.
+    
+    This function orchestrates feature serving from Snowflake Feature Store with built-in
+    distributed locking to prevent concurrent executions and automatic retry logic for
+    robustness. It supports flexible spine DataFrame inputs and per-feature-view parameter
+    customization.
+    
+    Parameters
+    ----------
+    session : snowflake.snowpark.Session
+        Active Snowflake Session object
+    feature_store : snowflake.ml.feature_store.FeatureStore
+        Initialized FeatureStore instance
+    feature_views_dict : Dict[str, str]
+        Dictionary mapping feature view names to versions (e.g., {"sales_activities": "1.0"})
+    spine_df : Union[str, pd.DataFrame, snowflake.snowpark.DataFrame], optional
+        One of the following:
+        - SQL query string to generate the spine DataFrame
+        - pandas DataFrame (will be converted to Snowpark DataFrame)
+        - Snowpark DataFrame (used directly)
+        - None will raise an error (spine is required by Feature Store SDK)
+    feature_date : str, optional
+        Snapshot date for features (e.g., '2025-04-08'). If None, uses UDF default.
+    spine_timestamp_col : str, optional
+        Name of timestamp column in spine DataFrame for point-in-time lookup.
+        If None, point-in-time lookup is disabled.
+    include_feature_view_timestamp_col : bool, default=False
+        Whether to include timestamp column from feature views in output
+    lookback_window_value : Union[int, Dict[str, int]], optional
+        Either a global integer value (e.g., 6) or a dict with feature-view-specific values
+        (e.g., {"sales_activities_by_account": 3, "product_stage_by_namespace": 2})
+    lookback_window_unit : Union[str, Dict[str, str]], optional
+        Either a global string value (e.g., 'months') or a dict with feature-view-specific values
+        (e.g., {"sales_activities_by_account": 'days', "product_stage_by_namespace": 'weeks'})
+    lock_timeout_seconds : int, default=300
+        Timeout in seconds for acquiring the Snowflake lock
+        
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with combined features from all feature views, with column names
+        converted to lowercase
+    """
+    _check_snowflake_available()
+    
+    # Constants - these are safe, not user-controlled
+    LOCK_TABLE = "FEATURE_SERVING_LOCKS"
+    LOCK_NAME = "FEATURE_SERVING"
+    session_id = f"session_{uuid.uuid4().hex[:8]}"
+    
+    # Retry configuration
+    max_attempts = 10
+    retry_interval_seconds = 60
+    
+    for attempt in range(1, max_attempts + 1):
+        try:
+            # Try to acquire lock using lock table approach
+            if attempt == 1:
+                print(f"🔒 [{session_id}] Attempting to acquire Snowflake lock: {LOCK_NAME}")
+            else:
+                print(f"🔒 [{session_id}] Retry attempt {attempt}/{max_attempts} to acquire lock: {LOCK_NAME}")
+            
+            # Create lock table if it doesn't exist
+            session.sql(f"""
+                CREATE TABLE IF NOT EXISTS {LOCK_TABLE} (
+                    lock_name VARCHAR,
+                    session_id VARCHAR,
+                    acquired_at TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),
+                    expires_at TIMESTAMP_NTZ
+                )
+            """).collect()
+            
+            # Clean up expired locks first (this handles killed processes)
+            session.sql(f"""
+                DELETE FROM {LOCK_TABLE} 
+                WHERE expires_at < CURRENT_TIMESTAMP()
+            """).collect()
+            print(f"🧹 [{session_id}] Cleaned up expired locks")
+            
+            # Try to acquire lock - session_id is UUID-generated, safe from injection
+            session.sql(f"""
+                INSERT INTO {LOCK_TABLE} (lock_name, session_id, expires_at)
+                SELECT '{LOCK_NAME}', '{session_id}', DATEADD(second, {lock_timeout_seconds}, CURRENT_TIMESTAMP())
+                WHERE NOT EXISTS (
+                    SELECT 1 FROM {LOCK_TABLE} 
+                    WHERE lock_name = '{LOCK_NAME}'
+                    AND expires_at > CURRENT_TIMESTAMP()
+                )
+            """).collect()
+            
+            # Check if we got the lock - session_id is UUID-generated, safe from injection
+            lock_check = session.sql(f"""
+                SELECT COUNT(*) as lock_count 
+                FROM {LOCK_TABLE} 
+                WHERE lock_name = '{LOCK_NAME}' 
+                AND session_id = '{session_id}'
+                AND expires_at > CURRENT_TIMESTAMP()
+            """).collect()
+            
+            if lock_check[0]['LOCK_COUNT'] > 0:
+                # Successfully acquired lock
+                print(f"✅ [{session_id}] Acquired Snowflake lock: {LOCK_NAME}")
+                break
+            else:
+                # Lock is held by another session
+                existing_locks = session.sql(f"""
+                    SELECT session_id, acquired_at, expires_at,
+                           DATEDIFF(second, CURRENT_TIMESTAMP(), expires_at) as seconds_until_expiry
+                    FROM {LOCK_TABLE} 
+                    WHERE lock_name = '{LOCK_NAME}'
+                    AND expires_at > CURRENT_TIMESTAMP()
+                """).collect()
+                
+                if existing_locks:
+                    lock_info = existing_locks[0]
+                    if attempt < max_attempts:
+                        print(f"⏳ [{session_id}] Lock held by session {lock_info['SESSION_ID']} "
+                              f"(expires in {lock_info['SECONDS_UNTIL_EXPIRY']} seconds). "
+                              f"Retrying in {retry_interval_seconds} seconds... (attempt {attempt}/{max_attempts})")
+                        time.sleep(retry_interval_seconds)
+                        continue
+                    else:
+                        raise TimeoutError(f"Could not acquire lock after {max_attempts} attempts over {max_attempts * retry_interval_seconds // 60} minutes. "
+                                         f"Lock is held by session {lock_info['SESSION_ID']}, "
+                                         f"acquired at {lock_info['ACQUIRED_AT']}, expires in {lock_info['SECONDS_UNTIL_EXPIRY']} seconds. "
+                                         f"Please try again later.")
+                else:
+                    if attempt < max_attempts:
+                        print(f"⏳ [{session_id}] Could not acquire lock (unknown reason). "
+                              f"Retrying in {retry_interval_seconds} seconds... (attempt {attempt}/{max_attempts})")
+                        time.sleep(retry_interval_seconds)
+                        continue
+                    else:
+                        raise TimeoutError(f"Could not acquire lock after {max_attempts} attempts for unknown reason. Please try again later.")
+        
+        except TimeoutError:
+            # Re-raise TimeoutError to exit the retry loop
+            raise
+        except ValueError:
+            # Re-raise specific exceptions that shouldn't be retried
+            raise
+        except Exception as e:
+            if attempt < max_attempts:
+                print(f"❌ [{session_id}] Error during lock acquisition attempt {attempt}/{max_attempts}: {e}")
+                print(f"⏳ [{session_id}] Retrying in {retry_interval_seconds} seconds...")
+                time.sleep(retry_interval_seconds)
+                continue
+            else:
+                raise Exception(f"Failed to acquire lock after {max_attempts} attempts. Last error: {e}")
+    
+    # If we get here, we have the lock - proceed with feature serving
+    try:
+        feature_views_list = []
+
+        # Loop over all feature views to create the dynamic views
+        for fv_name, version in feature_views_dict.items():
+            fv = feature_store.get_feature_view(fv_name, version)
+            feature_views_list.append(fv)
+
+            # Derive dynamic view and UDF names from feature view name using naming convention
+            # Convention: feature_view_name -> feature_view_name_dynamic (view) and feature_view_name_udf (function)
+            dynamic_view = f"{fv_name.upper()}_DYNAMIC"
+            udf_name = f"{fv_name.upper()}_UDF"
+
+            # Extract metadata from FeatureView
+            entity_id = fv.entities[0].join_keys[0]  
+            timestamp_col = fv.timestamp_col
+
+            print(f"[{session_id}] {fv_name} v{version}:")
+            print(f"  Dynamic View: {dynamic_view}")
+            print(f"  UDF: {udf_name}")
+            print(f"  Entity: {entity_id}")
+            print(f"  Timestamp: {timestamp_col}")
+
+            # Build parameters in the new order: SNAPSHOT_DATE, LOOKBACK_WINDOW_VALUE, LOOKBACK_WINDOW_UNIT
+            udf_params = []
+            
+            # First parameter: SNAPSHOT_DATE (feature_date) - pass as DATE type, not string
+            if feature_date:
+                date_str = str(feature_date)
+                udf_params.append(f"'{date_str}'::DATE")
+                print(f"  Using snapshot date: {date_str}")
+            else:
+                print(f"  Using UDF default snapshot date")
+            
+            # Second parameter: LOOKBACK_WINDOW_VALUE
+            if lookback_window_value is not None:
+                if isinstance(lookback_window_value, dict):
+                    if fv_name in lookback_window_value:
+                        value_param = lookback_window_value[fv_name]
+                        udf_params.append(str(value_param))
+                        print(f"  Using per-UDF lookback window value: {value_param}")
+                    else:
+                        print(f"  Using UDF default lookback window value")
+                else:
+                    # Global value
+                    udf_params.append(str(lookback_window_value))
+                    print(f"  Using global lookback window value: {lookback_window_value}")
+            else:
+                print(f"  Using UDF default lookback window value")
+                
+            # Third parameter: LOOKBACK_WINDOW_UNIT
+            if lookback_window_unit is not None:
+                if isinstance(lookback_window_unit, dict):
+                    if fv_name in lookback_window_unit:
+                        unit_param = lookback_window_unit[fv_name]
+                        udf_params.append(f"'{unit_param}'")
+                        print(f"  Using per-UDF lookback window unit: {unit_param}")
+                    else:
+                        print(f"  Using UDF default lookback window unit")
+                else:
+                    # Global value
+                    udf_params.append(f"'{lookback_window_unit}'")
+                    print(f"  Using global lookback window unit: {lookback_window_unit}")
+            else:
+                print(f"  Using UDF default lookback window unit")
+
+            # Create the UDF call with parameters in the correct order
+            params_str = ', '.join(udf_params) if udf_params else ''
+            update_view_sql = f"""
+                CREATE OR REPLACE 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"  [{session_id}] Updated {dynamic_view}")
+        
+        # Handle spine_df - convert to Snowpark DataFrame as needed
+        if spine_df is None:
+            raise ValueError("spine_df is required - the Snowflake Feature Store SDK requires a spine DataFrame")
+        elif isinstance(spine_df, str):
+            # SQL query string
+            snowpark_spine_df = session.sql(spine_df)
+            print(f"[{session_id}] Created spine from SQL query")
+        elif isinstance(spine_df, pd.DataFrame):
+            # pandas DataFrame - convert to Snowpark
+            snowpark_spine_df = session.create_dataframe(spine_df)
+            print(f"[{session_id}] Created spine from pandas DataFrame")
+        elif SNOWFLAKE_AVAILABLE and isinstance(spine_df, SnowparkDataFrame):
+            # Already a Snowpark DataFrame
+            snowpark_spine_df = spine_df
+            print(f"[{session_id}] Using provided Snowpark DataFrame")
+        else:
+            raise TypeError(f"spine_df must be a SQL query string, pandas DataFrame, or Snowpark DataFrame. Got: {type(spine_df)}")
+        
+        print(f"[{session_id}] Spine contains {snowpark_spine_df.count()} entities")
+
+        # Build retrieve_feature_values arguments conditionally
+        retrieve_kwargs = {
+            "spine_df": snowpark_spine_df,
+            "features": feature_views_list,
+            "include_feature_view_timestamp_col": include_feature_view_timestamp_col
+        }
+        
+        # Only include spine_timestamp_col if provided
+        if spine_timestamp_col is not None:
+            retrieve_kwargs["spine_timestamp_col"] = spine_timestamp_col
+            print(f"[{session_id}] Using point-in-time lookup with timestamp column: {spine_timestamp_col}")
+        else:
+            print(f"[{session_id}] Point-in-time lookup disabled (no spine_timestamp_col)")
+
+        # Retrieve combined features
+        print(f"[{session_id}] Starting retrieve_feature_values (this may take a while)...")
+        combined_features = feature_store.retrieve_feature_values(**retrieve_kwargs)
+
+        combined_features = combined_features.to_pandas()
+        combined_features.columns = map(str.lower, combined_features.columns)
+
+        print(f"✅ [{session_id}] Feature serving completed successfully")
+        return combined_features
+        
+    finally:
+        # Always release the lock
+        try:
+            session.sql(f"""
+                DELETE FROM {LOCK_TABLE} 
+                WHERE lock_name = '{LOCK_NAME}' 
+                AND session_id = '{session_id}'
+            """).collect()
+            print(f"🔓 [{session_id}] Released Snowflake lock: {LOCK_NAME}")
+        except Exception as e:
+            print(f"⚠️ [{session_id}] Error releasing lock: {e}")

gitlabds-2.1.7/README.md → gitlabds-2.1.8/gitlabds.egg-info/PKG-INFO

@@ -1,3 +1,35 @@
+Metadata-Version: 2.4
+Name: gitlabds
+Version: 2.1.8
+Summary: GitLab Data Science Tools
+Author-email: Kevin Dietz <kdietz@gitlab.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/gitlab-data/gitlabds
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5.3
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: scikit-learn>=1.1.1
+Requires-Dist: imbalanced-learn>=0.9.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: shap>=0.50.0
+Requires-Dist: tqdm>=4.66.2
+Requires-Dist: xgboost>=1.6.1
+Provides-Extra: feature-store
+Requires-Dist: snowflake-snowpark-python; extra == "feature-store"
+Requires-Dist: snowflake-ml-python; extra == "feature-store"
+Dynamic: license-file
+
 [![PyPI version](https://badge.fury.io/py/gitlabds.svg)](https://badge.fury.io/py/gitlabds)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -15,7 +47,7 @@ pip install gitlabds
 
 ### Requirements
 
-- Python 3.10 or later
+- Python 3.11 or later
 - Core dependencies:
    - pandas>=1.5.3
    - numpy>=1.23.5
@@ -23,8 +55,27 @@ pip install gitlabds
    - scikit-learn>=1.1.1
    - imbalanced-learn>=0.9.1
    - seaborn>=0.13.2
-   - shap>=0.41.0
+   - shap>=0.50.0
    - tqdm>=4.66.2
+   - xgboost>=1.6.1
+
+### Optional Dependencies
+
+#### Snowflake Feature Store
+
+The `serve_features` and `clear_feature_serving_locks` functions require additional Snowflake dependencies.
+
+To use these functions, install with:
+
+```bash
+pip install gitlabds[feature-store]
+```
+
+This will install:
+- `snowflake-snowpark-python`
+- `snowflake-ml-python`
+
+If you try to use these functions without installing the optional dependencies, you'll get an error message with installation instructions.
 
 ## Main Features by Category
 
@@ -883,6 +934,115 @@ feature_drift = results['feature_drift']
 ```
 </details>
 
+### Deployment
+
+#### Feature Serving
+
+<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.
+
+`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):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+- **_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.
+- **_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.
+- **_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.
+
+#### Returns
+- DataFrame with combined features from all feature views
+
+#### Requirements
+This function requires Snowflake packages. Install with:
+```bash
+pip install snowflake-snowpark-python snowflake-ml-python
+```
+
+#### Examples:
+
+```python
+# Basic usage with SQL spine
+import gitlabds
+from snowflake.snowpark import Session
+from snowflake.ml.feature_store import FeatureStore
+
+session = Session.builder.configs(...).create()
+fs = FeatureStore(session, ...)
+
+spine_sql = "SELECT account_id FROM accounts WHERE active = TRUE"
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "marketing_activity": "2.1"},
+    spine_df=spine_sql,
+    feature_date=None
+)
+```
+
+```python
+# With per-feature-view parameters
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0", "product_stage": "2.1"},
+    spine_df=spine_df,
+    lookback_window_value={"sales_activities": 3, "product_stage": 6},
+    lookback_window_unit={"sales_activities": "days", "product_stage": "months"}
+)
+```
+
+```python
+# With point-in-time lookup
+features = gitlabds.serve_features(
+    session=session,
+    feature_store=fs,
+    feature_views_dict={"sales_activities": "1.0"},
+    spine_df=spine_df,
+    spine_timestamp_col="snapshot_date",
+    feature_date="2025-04-08"
+)
+```
+
+</details>
+
+<details><summary> Clear Feature Serving Locks </summary>
+
+#### Description
+Utility function to manually clear all feature serving locks. Use this if locks get stuck due to killed processes.
+
+`gitlabds.clear_feature_serving_locks(session):`
+
+#### Parameters:
+- **_session_** : Active Snowflake Session object
+
+#### Returns
+- int: Number of locks cleared
+
+#### Examples:
+
+```python
+# Clear stuck locks
+import gitlabds
+from snowflake.snowpark import Session
+
+session = Session.builder.configs(...).create()
+locks_cleared = gitlabds.clear_feature_serving_locks(session)
+print(f"Cleared {locks_cleared} locks")
+```
+
+</details>
+
 ### SQL and Trend Analysis
 
 <details><summary> SQL Trend Query Generator </summary>

{gitlabds-2.1.7 → gitlabds-2.1.8}/gitlabds.egg-info/SOURCES.txt

@@ -1,5 +1,6 @@
 LICENSE
 README.md
+pyproject.toml
 setup.py
 gitlabds/__init__.py
 gitlabds/baselines.py
@@ -14,11 +15,11 @@ gitlabds/missing_fill.py
 gitlabds/model_evaluator.py
 gitlabds/monitoring_metrics.py
 gitlabds/outliers.py
+gitlabds/serving_features.py
 gitlabds/split_data.py
 gitlabds/trends.py
 gitlabds.egg-info/PKG-INFO
 gitlabds.egg-info/SOURCES.txt
 gitlabds.egg-info/dependency_links.txt
 gitlabds.egg-info/requires.txt
-gitlabds.egg-info/top_level.txt
-tests/__init__.py
+gitlabds.egg-info/top_level.txt

{gitlabds-2.1.7 → gitlabds-2.1.8}/gitlabds.egg-info/requires.txt

@@ -4,5 +4,10 @@ scipy>=1.13.1
 scikit-learn>=1.1.1
 imbalanced-learn>=0.9.1
 seaborn>=0.13.2
-shap>=0.41.0
+shap>=0.50.0
 tqdm>=4.66.2
+xgboost>=1.6.1
+
+[feature-store]
+snowflake-snowpark-python
+snowflake-ml-python

{gitlabds-2.1.7 → gitlabds-2.1.8}/gitlabds.egg-info/top_level.txt

@@ -1,2 +1 @@
 gitlabds
-tests

gitlabds-2.1.8/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gitlabds"
+description = "GitLab Data Science Tools"
+dynamic = ["version"]
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "Kevin Dietz", email = "kdietz@gitlab.com"}
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pandas>=1.5.3",
+    "numpy>=1.23.5",
+    "scipy>=1.13.1",
+    "scikit-learn>=1.1.1",
+    "imbalanced-learn>=0.9.1",
+    "seaborn>=0.13.2",
+    "shap>=0.50.0",
+    "tqdm>=4.66.2",
+    "xgboost>=1.6.1",
+]
+
+[project.optional-dependencies]
+feature-store = [
+    "snowflake-snowpark-python",
+    "snowflake-ml-python",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/gitlab-data/gitlabds"
+
+[tool.setuptools]
+packages = ["gitlabds"]
+

gitlabds-2.1.8/setup.py

@@ -0,0 +1,11 @@
+import setuptools, os
+
+if os.environ.get('CI_COMMIT_TAG'):
+    version = os.environ['CI_COMMIT_TAG']
+elif os.environ.get('CI_JOB_ID'):
+    version = os.environ['CI_JOB_ID']
+else:
+    version = "0.0.0-dev"
+
+setuptools.setup(version=version)  
+

gitlabds-2.1.7/setup.py

@@ -1,41 +0,0 @@
-import setuptools, os
-from pathlib import Path
-
-if os.environ.get('CI_COMMIT_TAG'):
-    version = os.environ['CI_COMMIT_TAG']
-elif os.environ.get('CI_JOB_ID'):
-    version = os.environ['CI_JOB_ID']
-else:
-    version = "0.0.0-dev"
-
-requires = ["pandas>=1.5.3", "numpy>=1.23.5", "scipy>=1.13.1", "scikit-learn>=1.1.1", "imbalanced-learn>=0.9.1", "seaborn>=0.13.2", "shap>=0.41.0", "tqdm>=4.66.2"]
-
-# read the contents of README file
-this_directory = Path(__file__).parent
-long_description = (this_directory / "README.md").read_text()
-
-setuptools.setup(
-    name='gitlabds',
-    version=version,
-    description='Gitlab Data Science and Modeling Tools',
-    long_description = long_description,
-    long_description_content_type ='text/markdown',
-    author='Kevin Dietz',
-    author_email='kdietz@gitlab.com',
-    packages=setuptools.find_packages(),
-    url='https://gitlab.com/gitlab-data/gitlabds',
-    classifiers=[
-        'Development Status :: 5 - Production/Stable',
-        'Intended Audience :: Developers',
-        'Intended Audience :: Science/Research',
-        'License :: OSI Approved :: MIT License',
-        'Programming Language :: Python :: 3',
-        'Topic :: Scientific/Engineering :: Artificial Intelligence',
-        'Topic :: Scientific/Engineering :: Information Analysis',
-        'Topic :: Software Development :: Libraries',
-        'Topic :: Utilities',
-    ],
-    python_requires= '>=3.10',
-    install_requires=requires,
-)  
-