gitlabds 2.2.3__tar.gz → 2.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.2.3
+Version: 2.3.1
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -21,13 +21,17 @@ 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: matplotlib>=3.5.0
 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"
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: snowflake
+Requires-Dist: cryptography>=41.0.0; extra == "snowflake"
+Requires-Dist: snowflake-connector-python[pandas]>=3.0.0; extra == "snowflake"
+Requires-Dist: snowflake-snowpark-python>=1.37.0; extra == "snowflake"
+Requires-Dist: snowflake-ml-python>=1.11.0; extra == "snowflake"
 Dynamic: license-file
 
 [![PyPI version](https://badge.fury.io/py/gitlabds.svg)](https://badge.fury.io/py/gitlabds)
@@ -61,19 +65,23 @@ pip install gitlabds
 
 ### Optional Dependencies
 
-#### Snowflake Feature Store
+#### Snowflake
 
-The `serve_features`, `clear_feature_serving_locks`, and `get_feature_descriptions` functions require additional Snowflake dependencies.
+The Snowflake connectors (`snowflake_engine_factory`, `ds_query_dataframe`, `query_executor`, `snowflake_stage_load_copy_remove`, `feature_store_factory`) and the feature serving functions (`serve_features`, `clear_feature_serving_locks`, `get_feature_descriptions`) require additional dependencies.
 
 To use these functions, install with:
 
 ```bash
-pip install gitlabds[feature-store]
+pip install gitlabds[snowflake]
 ```
 
 This will install:
+- `snowflake-connector-python[pandas]`
 - `snowflake-snowpark-python`
 - `snowflake-ml-python`
+- `cryptography`
+
+These are optional rather than core because `snowflake-ml-python` constrains the numpy/scikit-learn/xgboost stack that the core package also depends on.
 
 If you try to use these functions without installing the optional dependencies, you'll get an error message with installation instructions.
 
@@ -1125,6 +1133,231 @@ feature_drift = results['feature_drift']
 
 ### Deployment
 
+#### Snowflake Connectors
+
+Thin wrappers over the native Snowflake SDKs that resolve GitLab's two credential paths — local (dbt profile + SSO) and GitLab CI (env vars + password or key pair) — and then hand off to the native objects. Migrated from `gitlabdata.orchestration_utils`; see the migration notes at the end of this section.
+
+All of these require `pip install gitlabds[snowflake]`.
+
+<details><summary> Snowflake Engine Factory </summary>
+
+#### Description
+Open a Snowflake connection, resolving credentials from your dbt profile locally or from GitLab CI environment variables in CI.
+
+`gitlabds.snowflake_engine_factory(args=None, role="DATA_SCIENCE_LOADER", run_target=None, profile_target="dev", schema="", auth_method="password", profiles_path=None, **connect_kwargs):`
+
+#### Parameters:
+- **_args_** : Environment mapping to read CI credentials from. Defaults to `os.environ`. Ignored on the local path.
+- **_role_** : CI credential set to use. Currently only supports `DATA_SCIENCE_LOADER`
+- **_run_target_** : `"local"` or `"ci"`. Inferred from the `GITLAB_CI` environment variable when not given.
+- **_profile_target_** : dbt profile output name. Only used on the local path.
+- **_schema_** : Schema to connect to. Falls back to the dbt profile's schema locally; when it resolves empty the connection is opened with no default schema.
+- **_auth_method_** : `"password"` or `"keypair"`. Only used on the CI path. Key pair secrets are not yet provisioned in CI.
+- **_profiles_path_** : Override the dbt `profiles.yml` location (defaults to `~/.dbt/profiles.yml`). Only used on the local path.
+- **_\*\*connect_kwargs_** : Passed through to `snowflake.connector.connect()`, e.g. `autocommit=False`, `client_session_keep_alive=True`.
+
+#### Returns
+- An open `snowflake.connector.SnowflakeConnection`. The caller owns its lifecycle.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+# Local: reads the "dev" target from ~/.dbt/profiles.yml and authenticates via SSO
+conn = gitlabds.snowflake_engine_factory()
+try:
+    df = gitlabds.ds_query_dataframe(conn, "select * from prod.data_science.my_table")
+finally:
+    conn.close()
+```
+```python
+# CI: credentials come from os.environ; run_target is inferred from GITLAB_CI
+conn = gitlabds.snowflake_engine_factory(role="DATA_SCIENCE_LOADER", schema="data_science")
+
+# Opt out of autocommit to group statements into one transaction
+conn = gitlabds.snowflake_engine_factory(autocommit=False)
+```
+</details>
+
+<details><summary> DS Query Dataframe </summary>
+
+#### Description
+Run a SELECT and return a pandas DataFrame, using Snowflake's Arrow-based fetch. Prefer this over `query_executor` for large reads such as pulling training data.
+
+`gitlabds.ds_query_dataframe(conn, query, optimize_memory=False, verbose=False):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_query_** : SELECT query to run
+- **_optimize_memory_** : Run the result through `reduce_memory_usage()` (dtype downcasting) before returning. Off by default because it is a lossy transform (e.g. float64 → float32).
+- **_verbose_** : Print the memory-optimization report and progress bar. Only applies when `optimize_memory=True`.
+
+#### Returns
+- A pandas DataFrame
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+df = gitlabds.ds_query_dataframe(conn, "select * from my_table")
+
+# Large pull: downcast dtypes on the way out
+df = gitlabds.ds_query_dataframe(conn, training_query, optimize_memory=True, verbose=True)
+```
+</details>
+
+<details><summary> Query Executor </summary>
+
+#### Description
+Execute a SQL statement and return its rows as a list of dicts keyed by column name, as Snowflake returns them. Use for DML/DDL/transaction-control statements, or reads where a DataFrame isn't needed.
+
+`gitlabds.query_executor(conn, query):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_query_** : SQL statement to run
+
+#### Returns
+- `List[Dict[str, Any]]` — rows as `{column: value}`. DML and DDL statements return Snowflake's own status row (e.g. `{"number of rows inserted": 12}`) rather than an empty list.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+rows = gitlabds.query_executor(conn, "select count(*) as n from my_table")
+print(rows[0]["N"])
+```
+```python
+# Connections autocommit by default, so group statements explicitly
+gitlabds.query_executor(conn, "begin;")
+gitlabds.query_executor(conn, "delete from my_table where run_date = '2026-01-01';")
+gitlabds.query_executor(conn, "commit;")
+```
+</details>
+
+<details><summary> Snowflake Stage Load Copy Remove </summary>
+
+#### Description
+Load a local file into a Snowflake table via an internal stage: remove any leftover staged file, PUT the file, COPY INTO the target table, then REMOVE the staged file.
+
+`gitlabds.snowflake_stage_load_copy_remove(file, stage, table_path, conn, type="json", on_error="abort_statement", file_format_options="", col_names=""):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_file_** : Path to the local file to upload
+- **_stage_** : Internal stage name **without** a leading `@` — the function adds it (e.g. `"my_stage"` or `"db.schema.my_stage"`)
+- **_table_path_** : Fully-qualified target table
+- **_type_** : File format type (e.g. `"json"`, `"csv"`)
+- **_on_error_** : `COPY INTO` `ON_ERROR` behavior
+- **_file_format_options_** : Extra `FILE_FORMAT` options appended after `TYPE`, e.g. `'FIELD_DELIMITER="," SKIP_HEADER=1'`
+- **_col_names_** : Explicit column list for `COPY INTO`, e.g. `"(first_name, last_name)"`. Defaults to `"(jsontext)"` for json, empty otherwise.
+
+#### Returns
+- `None`. Progress is emitted at INFO level through the `logging` module; call `logging.basicConfig()` in your entry point to see it.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+gitlabds.snowflake_stage_load_copy_remove(
+    file="scores.json", stage="my_stage", table_path="prod.data_science.scores", conn=conn
+)
+```
+```python
+# CSV with a header row and an explicit column list
+gitlabds.snowflake_stage_load_copy_remove(
+    file="scores.csv",
+    stage="my_stage",
+    table_path="prod.data_science.scores",
+    conn=conn,
+    type="csv",
+    file_format_options='FIELD_DELIMITER="," SKIP_HEADER=1',
+    col_names="(account_id, score)",
+)
+```
+</details>
+
+<details><summary> Feature Store Factory </summary>
+
+#### Description
+Create a Snowflake Feature Store connection (Snowpark Session + native `FeatureStore`), resolving credentials the same way as `snowflake_engine_factory`.
+
+`gitlabds.feature_store_factory(args=None, role="DATA_SCIENCE_LOADER", run_target=None, profile_target="feature_store", auth_method="password", creation_mode="CreationMode.FAIL_IF_NOT_EXIST", profiles_path=None):`
+
+#### Parameters:
+- **_args_** : Environment mapping to read CI credentials from. Defaults to `os.environ`. Ignored on the local path.
+- **_role_** : Snowflake role for CI credentials. The feature store's database and schema come from `SNOWFLAKE_FEATURE_STORE_DATABASE` / `SNOWFLAKE_FEATURE_STORE_SCHEMA` on the CI path, not from the role's usual database/schema.
+- **_run_target_** : `"local"` or `"ci"`. Inferred from the `GITLAB_CI` environment variable when not given.
+- **_profile_target_** : dbt profile output name. Only used on the local path.
+- **_auth_method_** : `"password"` or `"keypair"`. Only used on the CI path.
+- **_creation_mode_** : Either a `"CreationMode.X"` string or a `snowflake.ml.feature_store.CreationMode` member.
+- **_profiles_path_** : Override the dbt `profiles.yml` location. Only used on the local path.
+
+#### Returns
+- A `snowflake.ml.feature_store.FeatureStore`. The underlying Snowpark session is reachable as `fs._session` and is not closed by this function.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+fs = gitlabds.feature_store_factory()
+
+df = gitlabds.serve_features(
+    session=fs._session,
+    feature_store=fs,
+    feature_views_dict={"account_ci_usage": "1.0"},
+    spine_df="select account_id from prod.data_science.my_spine",
+)
+```
+</details>
+
+<details><summary> Migrating from gitlabdata.orchestration_utils </summary>
+
+These functions replace their `gitlabdata.orchestration_utils` equivalents, but the signatures intentionally differ — this is not a drop-in import swap. Changes that fail at runtime rather than at import:
+
+| Was | Now |
+|---|---|
+| `snowflake_engine_factory(...)` returns a SQLAlchemy `Engine` | returns a native `SnowflakeConnection` |
+| `data_science_engine_factory(...)` | folded into `snowflake_engine_factory(...)`, parameterized by `role` / `profile_target` |
+| `pd.read_sql(query, engine)` | `gitlabds.ds_query_dataframe(conn, query)` |
+| `df.to_sql(..., engine)` | `snowflake.connector.pandas_tools.write_pandas(conn, df, ...)` |
+| `engine.connect()` / `engine.dispose()` | `conn` is already open; `conn.close()` |
+| `query_executor(engine, query)` returns tuples — `row[0]` | returns dicts — `row["COLUMN_NAME"]` |
+| `query_executor(..., dispose_engine=..., connection=...)` | dropped; the caller owns the connection and passes it in |
+| `snowflake_stage_load_copy_remove(..., engine, type=...)` | unchanged, except `engine` is now a connection rather than a SQLAlchemy Engine |
+| `in_docker=True` | `profiles_path="/usr/local/snowflake_profile/profiles.yml"` |
+| `run_target="local"` default | `run_target=None`, inferred from `GITLAB_CI` |
+
+Also worth knowing:
+- `file_format_options` is now honored for `json` too; the original silently dropped it for that type.
+- `stage` must be passed **without** a leading `@` (the function adds it). The original behaved the same way but did not document or enforce it.
+- These functions log through `logging.getLogger(__name__)` and no longer call `logging.basicConfig()` for you.
+</details>
+
 #### Feature Serving
 
 <details><summary> Serve Features </summary>
@@ -1157,7 +1390,7 @@ Serve features from Snowflake Feature Store with built-in distributed locking an
 #### Requirements
 This function requires Snowflake packages. Install with:
 ```bash
-pip install snowflake-snowpark-python snowflake-ml-python
+pip install gitlabds[snowflake]
 ```
 
 #### Examples:
@@ -1252,7 +1485,7 @@ Look up each feature's source feature view and description from the feature stor
 #### Requirements
 This function requires Snowflake packages. Install with:
 ```bash
-pip install snowflake-snowpark-python snowflake-ml-python
+pip install gitlabds[snowflake]
 ```
 
 #### Examples:

gitlabds-2.2.3/PKG-INFO → gitlabds-2.3.1/README.md

@@ -1,35 +1,3 @@
-Metadata-Version: 2.4
-Name: gitlabds
-Version: 2.2.3
-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.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -61,19 +29,23 @@ pip install gitlabds
 
 ### Optional Dependencies
 
-#### Snowflake Feature Store
+#### Snowflake
 
-The `serve_features`, `clear_feature_serving_locks`, and `get_feature_descriptions` functions require additional Snowflake dependencies.
+The Snowflake connectors (`snowflake_engine_factory`, `ds_query_dataframe`, `query_executor`, `snowflake_stage_load_copy_remove`, `feature_store_factory`) and the feature serving functions (`serve_features`, `clear_feature_serving_locks`, `get_feature_descriptions`) require additional dependencies.
 
 To use these functions, install with:
 
 ```bash
-pip install gitlabds[feature-store]
+pip install gitlabds[snowflake]
 ```
 
 This will install:
+- `snowflake-connector-python[pandas]`
 - `snowflake-snowpark-python`
 - `snowflake-ml-python`
+- `cryptography`
+
+These are optional rather than core because `snowflake-ml-python` constrains the numpy/scikit-learn/xgboost stack that the core package also depends on.
 
 If you try to use these functions without installing the optional dependencies, you'll get an error message with installation instructions.
 
@@ -1125,6 +1097,231 @@ feature_drift = results['feature_drift']
 
 ### Deployment
 
+#### Snowflake Connectors
+
+Thin wrappers over the native Snowflake SDKs that resolve GitLab's two credential paths — local (dbt profile + SSO) and GitLab CI (env vars + password or key pair) — and then hand off to the native objects. Migrated from `gitlabdata.orchestration_utils`; see the migration notes at the end of this section.
+
+All of these require `pip install gitlabds[snowflake]`.
+
+<details><summary> Snowflake Engine Factory </summary>
+
+#### Description
+Open a Snowflake connection, resolving credentials from your dbt profile locally or from GitLab CI environment variables in CI.
+
+`gitlabds.snowflake_engine_factory(args=None, role="DATA_SCIENCE_LOADER", run_target=None, profile_target="dev", schema="", auth_method="password", profiles_path=None, **connect_kwargs):`
+
+#### Parameters:
+- **_args_** : Environment mapping to read CI credentials from. Defaults to `os.environ`. Ignored on the local path.
+- **_role_** : CI credential set to use. Currently only supports `DATA_SCIENCE_LOADER`
+- **_run_target_** : `"local"` or `"ci"`. Inferred from the `GITLAB_CI` environment variable when not given.
+- **_profile_target_** : dbt profile output name. Only used on the local path.
+- **_schema_** : Schema to connect to. Falls back to the dbt profile's schema locally; when it resolves empty the connection is opened with no default schema.
+- **_auth_method_** : `"password"` or `"keypair"`. Only used on the CI path. Key pair secrets are not yet provisioned in CI.
+- **_profiles_path_** : Override the dbt `profiles.yml` location (defaults to `~/.dbt/profiles.yml`). Only used on the local path.
+- **_\*\*connect_kwargs_** : Passed through to `snowflake.connector.connect()`, e.g. `autocommit=False`, `client_session_keep_alive=True`.
+
+#### Returns
+- An open `snowflake.connector.SnowflakeConnection`. The caller owns its lifecycle.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+# Local: reads the "dev" target from ~/.dbt/profiles.yml and authenticates via SSO
+conn = gitlabds.snowflake_engine_factory()
+try:
+    df = gitlabds.ds_query_dataframe(conn, "select * from prod.data_science.my_table")
+finally:
+    conn.close()
+```
+```python
+# CI: credentials come from os.environ; run_target is inferred from GITLAB_CI
+conn = gitlabds.snowflake_engine_factory(role="DATA_SCIENCE_LOADER", schema="data_science")
+
+# Opt out of autocommit to group statements into one transaction
+conn = gitlabds.snowflake_engine_factory(autocommit=False)
+```
+</details>
+
+<details><summary> DS Query Dataframe </summary>
+
+#### Description
+Run a SELECT and return a pandas DataFrame, using Snowflake's Arrow-based fetch. Prefer this over `query_executor` for large reads such as pulling training data.
+
+`gitlabds.ds_query_dataframe(conn, query, optimize_memory=False, verbose=False):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_query_** : SELECT query to run
+- **_optimize_memory_** : Run the result through `reduce_memory_usage()` (dtype downcasting) before returning. Off by default because it is a lossy transform (e.g. float64 → float32).
+- **_verbose_** : Print the memory-optimization report and progress bar. Only applies when `optimize_memory=True`.
+
+#### Returns
+- A pandas DataFrame
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+df = gitlabds.ds_query_dataframe(conn, "select * from my_table")
+
+# Large pull: downcast dtypes on the way out
+df = gitlabds.ds_query_dataframe(conn, training_query, optimize_memory=True, verbose=True)
+```
+</details>
+
+<details><summary> Query Executor </summary>
+
+#### Description
+Execute a SQL statement and return its rows as a list of dicts keyed by column name, as Snowflake returns them. Use for DML/DDL/transaction-control statements, or reads where a DataFrame isn't needed.
+
+`gitlabds.query_executor(conn, query):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_query_** : SQL statement to run
+
+#### Returns
+- `List[Dict[str, Any]]` — rows as `{column: value}`. DML and DDL statements return Snowflake's own status row (e.g. `{"number of rows inserted": 12}`) rather than an empty list.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+rows = gitlabds.query_executor(conn, "select count(*) as n from my_table")
+print(rows[0]["N"])
+```
+```python
+# Connections autocommit by default, so group statements explicitly
+gitlabds.query_executor(conn, "begin;")
+gitlabds.query_executor(conn, "delete from my_table where run_date = '2026-01-01';")
+gitlabds.query_executor(conn, "commit;")
+```
+</details>
+
+<details><summary> Snowflake Stage Load Copy Remove </summary>
+
+#### Description
+Load a local file into a Snowflake table via an internal stage: remove any leftover staged file, PUT the file, COPY INTO the target table, then REMOVE the staged file.
+
+`gitlabds.snowflake_stage_load_copy_remove(file, stage, table_path, conn, type="json", on_error="abort_statement", file_format_options="", col_names=""):`
+
+#### Parameters:
+- **_conn_** : An open connection, e.g. from `snowflake_engine_factory()`
+- **_file_** : Path to the local file to upload
+- **_stage_** : Internal stage name **without** a leading `@` — the function adds it (e.g. `"my_stage"` or `"db.schema.my_stage"`)
+- **_table_path_** : Fully-qualified target table
+- **_type_** : File format type (e.g. `"json"`, `"csv"`)
+- **_on_error_** : `COPY INTO` `ON_ERROR` behavior
+- **_file_format_options_** : Extra `FILE_FORMAT` options appended after `TYPE`, e.g. `'FIELD_DELIMITER="," SKIP_HEADER=1'`
+- **_col_names_** : Explicit column list for `COPY INTO`, e.g. `"(first_name, last_name)"`. Defaults to `"(jsontext)"` for json, empty otherwise.
+
+#### Returns
+- `None`. Progress is emitted at INFO level through the `logging` module; call `logging.basicConfig()` in your entry point to see it.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+gitlabds.snowflake_stage_load_copy_remove(
+    file="scores.json", stage="my_stage", table_path="prod.data_science.scores", conn=conn
+)
+```
+```python
+# CSV with a header row and an explicit column list
+gitlabds.snowflake_stage_load_copy_remove(
+    file="scores.csv",
+    stage="my_stage",
+    table_path="prod.data_science.scores",
+    conn=conn,
+    type="csv",
+    file_format_options='FIELD_DELIMITER="," SKIP_HEADER=1',
+    col_names="(account_id, score)",
+)
+```
+</details>
+
+<details><summary> Feature Store Factory </summary>
+
+#### Description
+Create a Snowflake Feature Store connection (Snowpark Session + native `FeatureStore`), resolving credentials the same way as `snowflake_engine_factory`.
+
+`gitlabds.feature_store_factory(args=None, role="DATA_SCIENCE_LOADER", run_target=None, profile_target="feature_store", auth_method="password", creation_mode="CreationMode.FAIL_IF_NOT_EXIST", profiles_path=None):`
+
+#### Parameters:
+- **_args_** : Environment mapping to read CI credentials from. Defaults to `os.environ`. Ignored on the local path.
+- **_role_** : Snowflake role for CI credentials. The feature store's database and schema come from `SNOWFLAKE_FEATURE_STORE_DATABASE` / `SNOWFLAKE_FEATURE_STORE_SCHEMA` on the CI path, not from the role's usual database/schema.
+- **_run_target_** : `"local"` or `"ci"`. Inferred from the `GITLAB_CI` environment variable when not given.
+- **_profile_target_** : dbt profile output name. Only used on the local path.
+- **_auth_method_** : `"password"` or `"keypair"`. Only used on the CI path.
+- **_creation_mode_** : Either a `"CreationMode.X"` string or a `snowflake.ml.feature_store.CreationMode` member.
+- **_profiles_path_** : Override the dbt `profiles.yml` location. Only used on the local path.
+
+#### Returns
+- A `snowflake.ml.feature_store.FeatureStore`. The underlying Snowpark session is reachable as `fs._session` and is not closed by this function.
+
+#### Requirements
+```bash
+pip install gitlabds[snowflake]
+```
+
+#### Examples:
+
+```python
+import gitlabds
+
+fs = gitlabds.feature_store_factory()
+
+df = gitlabds.serve_features(
+    session=fs._session,
+    feature_store=fs,
+    feature_views_dict={"account_ci_usage": "1.0"},
+    spine_df="select account_id from prod.data_science.my_spine",
+)
+```
+</details>
+
+<details><summary> Migrating from gitlabdata.orchestration_utils </summary>
+
+These functions replace their `gitlabdata.orchestration_utils` equivalents, but the signatures intentionally differ — this is not a drop-in import swap. Changes that fail at runtime rather than at import:
+
+| Was | Now |
+|---|---|
+| `snowflake_engine_factory(...)` returns a SQLAlchemy `Engine` | returns a native `SnowflakeConnection` |
+| `data_science_engine_factory(...)` | folded into `snowflake_engine_factory(...)`, parameterized by `role` / `profile_target` |
+| `pd.read_sql(query, engine)` | `gitlabds.ds_query_dataframe(conn, query)` |
+| `df.to_sql(..., engine)` | `snowflake.connector.pandas_tools.write_pandas(conn, df, ...)` |
+| `engine.connect()` / `engine.dispose()` | `conn` is already open; `conn.close()` |
+| `query_executor(engine, query)` returns tuples — `row[0]` | returns dicts — `row["COLUMN_NAME"]` |
+| `query_executor(..., dispose_engine=..., connection=...)` | dropped; the caller owns the connection and passes it in |
+| `snowflake_stage_load_copy_remove(..., engine, type=...)` | unchanged, except `engine` is now a connection rather than a SQLAlchemy Engine |
+| `in_docker=True` | `profiles_path="/usr/local/snowflake_profile/profiles.yml"` |
+| `run_target="local"` default | `run_target=None`, inferred from `GITLAB_CI` |
+
+Also worth knowing:
+- `file_format_options` is now honored for `json` too; the original silently dropped it for that type.
+- `stage` must be passed **without** a leading `@` (the function adds it). The original behaved the same way but did not document or enforce it.
+- These functions log through `logging.getLogger(__name__)` and no longer call `logging.basicConfig()` for you.
+</details>
+
 #### Feature Serving
 
 <details><summary> Serve Features </summary>
@@ -1157,7 +1354,7 @@ Serve features from Snowflake Feature Store with built-in distributed locking an
 #### Requirements
 This function requires Snowflake packages. Install with:
 ```bash
-pip install snowflake-snowpark-python snowflake-ml-python
+pip install gitlabds[snowflake]
 ```
 
 #### Examples:
@@ -1252,7 +1449,7 @@ Look up each feature's source feature view and description from the feature stor
 #### Requirements
 This function requires Snowflake packages. Install with:
 ```bash
-pip install snowflake-snowpark-python snowflake-ml-python
+pip install gitlabds[snowflake]
 ```
 
 #### Examples:

{gitlabds-2.2.3 → gitlabds-2.3.1}/gitlabds/__init__.py

@@ -12,19 +12,29 @@ 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
+
+# Snowflake connectors and feature serving. Optional so that a missing Snowflake
+# install doesn't make the whole package unimportable.
 try:
+    from .snowflake_connectors import (
+        snowflake_engine_factory,
+        ds_query_dataframe,
+        query_executor,
+        snowflake_stage_load_copy_remove,
+        feature_store_factory,
+    )
     from .serving_features import clear_feature_serving_locks, serve_features
     from .feature_descriptions import get_feature_descriptions
-except ImportError as e:
-    # Snowflake packages not installed - create placeholder functions with helpful error messages
+except ImportError:
+
     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"
+            "Snowflake functions require additional dependencies. "
+            "Install them with: pip install gitlabds[snowflake]"
         )
 
-    clear_feature_serving_locks = _snowflake_not_installed
-    serve_features = _snowflake_not_installed
+    snowflake_engine_factory = ds_query_dataframe = query_executor = _snowflake_not_installed
+    snowflake_stage_load_copy_remove = feature_store_factory = _snowflake_not_installed
+    clear_feature_serving_locks = serve_features = _snowflake_not_installed
     get_feature_descriptions = _snowflake_not_installed