nui-python-shared-utils 1.3.3__py3-none-any.whl → 1.4.1__py3-none-any.whl

nui_lambda_shared_utils/snowflake_client.py

@@ -0,0 +1,3 @@
+"""Backwards-compatibility shim. Use nui_shared_utils.snowflake_client instead."""
+
+from nui_shared_utils.snowflake_client import *  # noqa: F401,F403

{nui_python_shared_utils-1.3.3.dist-info → nui_python_shared_utils-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.3.3
+Version: 1.4.1
 Summary: Shared Python utilities for AWS Lambda, CLI tools, and agents with Slack, Elasticsearch, and monitoring integrations
 Home-page: https://github.com/nuimarkets/nui-python-shared-utils
 Author: NUI Markets
@@ -64,6 +64,10 @@ Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "powertools"
 Requires-Dist: coloredlogs>=15.0; extra == "powertools"
 Provides-Extra: jwt
 Requires-Dist: rsa>=4.9; extra == "jwt"
+Provides-Extra: snowflake
+Requires-Dist: snowflake-sql-api<0.2.0,>=0.1.1; extra == "snowflake"
+Provides-Extra: llm
+Requires-Dist: anthropic[bedrock]<1.0.0,>=0.45.0; extra == "llm"
 Provides-Extra: all
 Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
@@ -86,6 +90,8 @@ Requires-Dist: twine>=4.0.0; extra == "dev"
 Requires-Dist: build>=0.8.0; extra == "dev"
 Requires-Dist: rsa>=4.9; extra == "dev"
 Requires-Dist: cryptography>=41.0.0; extra == "dev"
+Requires-Dist: snowflake-sql-api<0.2.0,>=0.1.1; extra == "dev"
+Requires-Dist: anthropic[bedrock]<1.0.0,>=0.45.0; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -128,6 +134,7 @@ Production-ready shared Python utilities for AWS Lambda functions, CLI tools, an
 - **Database Connections** - Connection pooling, automatic retries, and transaction management
 - **CloudWatch Metrics** - Batched publishing with custom dimensions
 - **JWT Authentication** - RS256 token validation for API Gateway Lambdas (lightweight, no PyJWT needed)
+- **Anthropic (Claude) Helper** - Generic client plumbing for LLM calls: API-key or Bedrock IAM auth, forced tool-use, and text calls (prompts and schemas stay in your code)
 - **Error Handling** - Intelligent retry patterns with exponential backoff
 - **Timezone Utilities** - Timezone handling and formatting
 - **Configurable Defaults** - Environment-aware configuration system
@@ -158,12 +165,14 @@ Production-ready shared Python utilities for AWS Lambda functions, CLI tools, an
 pip install nui-python-shared-utils
 
 # With specific extras for optional dependencies
-pip install nui-python-shared-utils[all]          # All integrations
+pip install nui-python-shared-utils[all]          # Core optional integrations (excludes Snowflake and LLM)
 pip install nui-python-shared-utils[powertools]   # AWS Powertools only
 pip install nui-python-shared-utils[slack]        # Slack only
 pip install nui-python-shared-utils[elasticsearch] # Elasticsearch only
 pip install nui-python-shared-utils[database]     # Database only
 pip install nui-python-shared-utils[jwt]          # JWT authentication only
+pip install nui-python-shared-utils[snowflake]    # Snowflake SQL API client
+pip install nui-python-shared-utils[llm]          # Anthropic (Claude) client helper
 ```
 
 ### Basic Configuration
@@ -291,6 +300,35 @@ async with db.get_connection() as conn:
 
 **[→ See full database guide](docs/getting-started/quickstart.md#database-connections)**
 
+### Snowflake (SQL API)
+
+Pure-Python Snowflake client (no `snowflake-connector-python`), keypair auth via
+Secrets Manager, with NUI session defaults (`TIMEZONE=Pacific/Auckland`, role
+`NUI_LAMBDA`) that you can override via `timezone=` and `role=`, plus a redacting
+query-logging hook.
+
+```python
+from nui_shared_utils import create_snowflake_client
+
+# Loads account/user/private_key from Secrets Manager ("snowflake-credentials"
+# by default; override with SNOWFLAKE_CREDENTIALS_SECRET or secret_name=).
+# The NUI defaults are overridable, so the client stays generic for any account.
+client = create_snowflake_client(
+    warehouse="COMPUTE_WH",
+    database="ANALYTICS",
+    timezone="UTC",          # override the Pacific/Auckland default
+    role="MY_APP_ROLE",      # override the NUI_LAMBDA default
+)
+rows = client.query("SELECT id, name FROM orders WHERE status = ?", ["confirmed"])
+```
+
+Sync is the default; use `create_async_snowflake_client(...)` inside a Lambda
+or FastAPI app already on an event loop. Snowflake SQL API bindings use
+positional `?` placeholders, not connector-style `%s` placeholders. Requires
+the `[snowflake]` extra.
+
+**[→ See full Snowflake guide](docs/guides/snowflake-integration.md)**
+
 ### CloudWatch Metrics
 
 ```python
@@ -323,6 +361,41 @@ def lambda_handler(event, context):
 
 **[→ See JWT authentication guide](docs/guides/jwt-authentication.md)**
 
+### Anthropic (Claude) Helper
+
+Generic plumbing for Claude calls: build a client (API-key or Bedrock IAM), make
+a forced tool-use call or a text call, and get the parsed result back. Prompts,
+tool schemas, model ids, and result post-processing stay in your code.
+
+```python
+from nui_shared_utils import build_anthropic_client, call_tool
+
+# API-key auth: explicit key -> ANTHROPIC_API_KEY env -> Secrets Manager
+client = build_anthropic_client(secret_name="my/anthropic-key")
+# Or Bedrock IAM (no key): build_anthropic_client(mode="bedrock", region="us-east-1")
+
+tool = {
+    "name": "classify",
+    "description": "Classify the text.",
+    "input_schema": {
+        "type": "object",
+        "properties": {"label": {"type": "string"}, "score": {"type": "number"}},
+        "required": ["label", "score"],
+        "additionalProperties": False,
+    },
+}
+
+# Forced tool-use; returns the tool's input dict, or None on any model/parse failure.
+result = call_tool(client, tool=tool, prompt="Great product!", model="claude-haiku-4-5", max_tokens=256)
+if result is not None:
+    print(result["label"], result["score"])
+```
+
+Requires the `[llm]` extra. `call_tool` is best-effort (returns `None`, never
+raises); `call_text` returns `{text, input_tokens, output_tokens}`.
+
+**[→ See full LLM integration guide](docs/guides/llm-integration.md)**
+
 ### Error Handling
 
 ```python

{nui_python_shared_utils-1.3.3.dist-info → nui_python_shared_utils-1.4.1.dist-info}/RECORD

@@ -14,14 +14,15 @@ nui_lambda_shared_utils/powertools_helpers.py,sha256=xTnbiyE_5bl9saizsKYd1U4rQBP
 nui_lambda_shared_utils/secrets_helper.py,sha256=wuThNFPFnU0K8N7I0UGMsyk9oJmOSYTR08xJy2MC8-M,138
 nui_lambda_shared_utils/slack_client.py,sha256=_itnosOoODXq1dAX2dMReQi0gZBARjcGqwtRjh1MFPc,136
 nui_lambda_shared_utils/slack_formatter.py,sha256=gwCkhfVdOvg44WW6hBogvfmcHsZxSZ-mzXUq6ft1k84,139
+nui_lambda_shared_utils/snowflake_client.py,sha256=p-gI8vEF_QyFU0Zts8I5jwIPzrAuYopAKXsv76MNZio,151
 nui_lambda_shared_utils/timezone.py,sha256=eLXPmhgFazj76K1aWiO5CSZbuiSlbXEGY8X-MxDKbjw,132
 nui_lambda_shared_utils/utils.py,sha256=sWDeHr9Jm3A6yaIqgP9b6_lHoPJox8gD6G1-eiYAgq4,129
 nui_lambda_shared_utils/slack_setup/__init__.py,sha256=q78NzSznsSd3ri5OUohWxQt7r6q0zdrE3gF2hvpHnD8,140
 nui_lambda_shared_utils/slack_setup/channel_creator.py,sha256=xaeqzyEAqVqYj2EhN69UvcyZQ6LdFKYODPPCwxHInLA,172
 nui_lambda_shared_utils/slack_setup/channel_definitions.py,sha256=3TkdLzWvEMBMDy5jqOPMUGRgKQ3z9TN58D43V7O7LpE,180
 nui_lambda_shared_utils/slack_setup/setup_helpers.py,sha256=ex_RiUfiZqH9qGLQwmedezMbfp35uI-VQPevducfbBk,168
-nui_python_shared_utils-1.3.3.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
-nui_shared_utils/__init__.py,sha256=Myt_55yTIZO71iyz2wkM9wySd7xhOCCky4EBOs-aI0A,10964
+nui_python_shared_utils-1.4.1.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
+nui_shared_utils/__init__.py,sha256=WOpBwxBqJK_wq8l3s5TCCs4j__lMTbI7TjraTXfmH4c,11851
 nui_shared_utils/base_client.py,sha256=I1lKQGhrKyvujV2zps0TrtEdPDqMCwRQaIh6ceGONXQ,11016
 nui_shared_utils/cli.py,sha256=JJpSoQWKvAz4b8cO30yFNi5vY9jmqrCHzbFpvrVTkbU,8747
 nui_shared_utils/cloudwatch_metrics.py,sha256=p0J-s63UJDGK14TRGt0k8yoj7aWSSM55UKdgcuaT1dU,12098
@@ -32,19 +33,21 @@ nui_shared_utils/es_client.py,sha256=rLyexuL6_RXQpuMC4A2SeJDk30medx2qxOgWIG3A_7o
 nui_shared_utils/es_query_builder.py,sha256=UuheQf8b2UXaOiJlYCKYIfKfVERDZ3ag1P0OOOWm9do,12158
 nui_shared_utils/jwt_auth.py,sha256=2Ag1zZKxd2R8QBz3aQA4h8OtKHQvUVKrjUp6lXpJxJU,9143
 nui_shared_utils/lambda_helpers.py,sha256=psHVotpmOfnmyQCoOt4MSIEj7VwWcy6gZM3vYSZwjOk,3041
+nui_shared_utils/llm.py,sha256=adNUO8Qbeb3__GvpROxWSUERkpiazKiGJFE5xzU5eZ0,8351
 nui_shared_utils/log_processors.py,sha256=x5gz1LEkbmoMCZ3ZB6q-mbn26dSzwh1trz4wSkBGxqk,5538
 nui_shared_utils/powertools_helpers.py,sha256=qc-lYLfY-QX20gALfPOJcihrtJhiCU-fJW8rsPT7LJE,11037
-nui_shared_utils/secrets_helper.py,sha256=jtQZSbghNTyWYylGxFiHWeL28Q1JUpLTrnGIICU4R3k,6815
+nui_shared_utils/secrets_helper.py,sha256=_jQkMWzjayZ8vvyHG2yuuxur-SQYUUONfcsZ0MF8qOw,7025
 nui_shared_utils/slack_client.py,sha256=_qR7Q1GU7gvYhUxiaBxEohhoEYznqr8kz9enGfeDtn8,24759
 nui_shared_utils/slack_formatter.py,sha256=95g6XfAJst7RVhd0M0ahiF3gWWW5j96WYkCg5tLS6Zg,10894
+nui_shared_utils/snowflake_client.py,sha256=e3jH6_2mMqbtP1TE8-mUFFYrfGW9eqUPT5tlcgeCqx8,16181
 nui_shared_utils/timezone.py,sha256=TvtSZV7w3Vvz3NbMTcJSNbUf0ZxPwpFS-xfgye1h-4Q,3583
 nui_shared_utils/utils.py,sha256=gOpw80tZGC24QsyesR8EySRODY-TFXG8cXUvggPBsRI,8184
 nui_shared_utils/slack_setup/__init__.py,sha256=OElyS3xk4F_YKH5uUUTDpN0ah1dOO3e52muIPjAMPW8,320
 nui_shared_utils/slack_setup/channel_creator.py,sha256=0gyCBIS0EC96SVn1Z2dD4Fpzk0xNdHSWyiCxoUQIUe8,10667
 nui_shared_utils/slack_setup/channel_definitions.py,sha256=atfz5ZhpqefOeLh1gShbWd-TLzgjPmhv95bfuTdmZog,5676
 nui_shared_utils/slack_setup/setup_helpers.py,sha256=pzzXMs12GI9sdZttWeYzgLPgC0xqPz7ZLHM1GUPNNXc,7219
-nui_python_shared_utils-1.3.3.dist-info/METADATA,sha256=y_FgR8-pq8PWqEayZQfYAtOqzijcsdG2UOQDVxd4-7E,19387
-nui_python_shared_utils-1.3.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-nui_python_shared_utils-1.3.3.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
-nui_python_shared_utils-1.3.3.dist-info/top_level.txt,sha256=sNceq5okmEB54L-gm4a0OgGhnPlU62zYmlUoXKn-Fa8,41
-nui_python_shared_utils-1.3.3.dist-info/RECORD,,
+nui_python_shared_utils-1.4.1.dist-info/METADATA,sha256=jYHBmx1R9T3PEGS2aLOY0DvcuZFm7DuebJL4VaV3z_c,22632
+nui_python_shared_utils-1.4.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nui_python_shared_utils-1.4.1.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
+nui_python_shared_utils-1.4.1.dist-info/top_level.txt,sha256=sNceq5okmEB54L-gm4a0OgGhnPlU62zYmlUoXKn-Fa8,41
+nui_python_shared_utils-1.4.1.dist-info/RECORD,,

nui_shared_utils/__init__.py

@@ -104,6 +104,11 @@ _LAZY_EXPORTS = {
     # Optional: AWS Powertools
     "get_powertools_logger": ("powertools_helpers", "get_powertools_logger"),
     "powertools_handler": ("powertools_helpers", "powertools_handler"),
+    # Optional: Snowflake client adapter (snowflake-sql-api)
+    "create_snowflake_client": ("snowflake_client", "create_snowflake_client"),
+    "create_async_snowflake_client": ("snowflake_client", "create_async_snowflake_client"),
+    "get_snowflake_credentials": ("snowflake_client", "get_snowflake_credentials"),
+    "redacting_query_logger": ("snowflake_client", "redacting_query_logger"),
     # Optional: JWT validation (rsa)
     "validate_jwt": ("jwt_auth", "validate_jwt"),
     "require_auth": ("jwt_auth", "require_auth"),
@@ -111,6 +116,10 @@ _LAZY_EXPORTS = {
     "get_jwt_public_key": ("jwt_auth", "get_jwt_public_key"),
     "JWTValidationError": ("jwt_auth", "JWTValidationError"),
     "AuthenticationError": ("jwt_auth", "AuthenticationError"),
+    # Optional: Anthropic (Claude) LLM helper (anthropic[bedrock])
+    "build_anthropic_client": ("llm", "build_anthropic_client"),
+    "call_tool": ("llm", "call_tool"),
+    "call_text": ("llm", "call_text"),
 }
 
 # Submodules that are optional integrations; ImportError during lazy load
@@ -124,6 +133,8 @@ _OPTIONAL_SUBMODULES = {
     "db_client",
     "powertools_helpers",
     "jwt_auth",
+    "snowflake_client",
+    "llm",
     "slack_setup",
 }
 
@@ -248,6 +259,12 @@ if TYPE_CHECKING:
         build_user_activity_query,
     )
     from .db_client import DatabaseClient, PostgreSQLClient, get_pool_stats
+    from .snowflake_client import (
+        create_async_snowflake_client,
+        create_snowflake_client,
+        get_snowflake_credentials,
+        redacting_query_logger,
+    )
     from .powertools_helpers import get_powertools_logger, powertools_handler
     from .jwt_auth import (
         AuthenticationError,
@@ -257,6 +274,7 @@ if TYPE_CHECKING:
         require_auth,
         validate_jwt,
     )
+    from .llm import build_anthropic_client, call_text, call_tool
     from . import slack_setup
 
 

nui_shared_utils/llm.py

@@ -0,0 +1,209 @@
+"""Generic Anthropic (Claude) client helper for AWS Lambda functions and CLI tools.
+
+Plumbing only. Three repos independently hand-rolled the same Anthropic client +
+forced-tool-use call + ``tool_use``-block parse; this consolidates that into one
+tested surface. Prompts, tool schemas, model ids, and any domain post-processing
+of the result stay in the consuming repo.
+
+What lives here:
+
+- :func:`build_anthropic_client` - API-key auth (explicit -> ``ANTHROPIC_API_KEY``
+  env -> Secrets Manager) or Bedrock IAM auth, one function for both.
+- :func:`call_tool` - a forced tool-use call that returns the named tool's
+  ``input`` dict, or ``None`` on any model/parse failure (best-effort; never
+  raises, matching the dominant Lambda enrichment pattern).
+- :func:`call_text` - a plain text call returning ``{text, input_tokens,
+  output_tokens}``.
+
+The ``anthropic`` SDK is a module-level import (matching the package's other
+optional integrations), so the bare ``[llm]`` extra is required to use anything
+here. The cold-start guarantee is preserved by the package ``__init__`` PEP 562
+lazy loader: ``import nui_shared_utils`` never imports this module (and so never
+imports ``anthropic``) until a consumer first touches an ``llm`` attribute. See
+``tests/test_lazy_imports.py``.
+
+Install the extra::
+
+    pip install 'nui-python-shared-utils[llm]'
+
+``anthropic[bedrock]`` covers both auth modes (``anthropic.Anthropic`` for the
+API key, ``anthropic.AnthropicBedrock`` for IAM); the ``[bedrock]`` sub-extra is
+what makes ``AnthropicBedrock`` available.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, Optional
+
+import anthropic
+
+from .secrets_helper import get_api_key
+
+log = logging.getLogger(__name__)
+
+
+def build_anthropic_client(
+    mode: str = "api_key",
+    *,
+    api_key: Optional[str] = None,
+    secret_name: Optional[str] = None,
+    region: Optional[str] = None,
+    max_retries: int = 5,
+) -> Any:
+    """Build an Anthropic SDK client for the requested auth mode.
+
+    ``mode="api_key"`` (default) returns an :class:`anthropic.Anthropic`. The key
+    is resolved in order: the explicit ``api_key`` argument, then the
+    ``ANTHROPIC_API_KEY`` environment variable, then
+    :func:`nui_shared_utils.get_api_key` against ``secret_name`` (AWS Secrets
+    Manager, ``api_key`` field). A consumer whose key lives behind a CLI keyring
+    or a non-default secret field should resolve it and pass ``api_key=``.
+
+    ``mode="bedrock"`` returns an :class:`anthropic.AnthropicBedrock` (IAM auth,
+    no key). ``region`` sets ``aws_region``; it falls back to ``AWS_REGION`` /
+    ``AWS_DEFAULT_REGION`` and then to the SDK's own default region resolution.
+
+    Args:
+        mode: ``"api_key"`` or ``"bedrock"``.
+        api_key: Explicit Anthropic API key (api_key mode only). Skips env and
+            Secrets Manager when set.
+        secret_name: Secrets Manager secret name to read the key from when no
+            explicit key and no env var are present (api_key mode only).
+        region: AWS region for Bedrock (bedrock mode only).
+        max_retries: Passed through to the SDK client (default 5).
+
+    Raises:
+        ValueError: Unknown ``mode``, or api_key mode with no key resolvable
+            (no ``api_key``, no env var, and no ``secret_name``).
+    """
+    if mode == "bedrock":
+        aws_region = region or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+        return anthropic.AnthropicBedrock(aws_region=aws_region, max_retries=max_retries)
+
+    if mode == "api_key":
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not key:
+            if not secret_name:
+                raise ValueError(
+                    "build_anthropic_client(mode='api_key'): no api_key argument, "
+                    "no ANTHROPIC_API_KEY env var, and no secret_name to read from "
+                    "Secrets Manager"
+                )
+            key = get_api_key(secret_name, key_field="api_key")
+        return anthropic.Anthropic(api_key=key, max_retries=max_retries)
+
+    raise ValueError(f"build_anthropic_client: unknown mode {mode!r} (expected 'api_key' or 'bedrock')")
+
+
+def call_tool(
+    client: Any,
+    *,
+    tool: Dict[str, Any],
+    prompt: str,
+    model: str,
+    max_tokens: int,
+    system: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Make a forced tool-use call and return the named tool's ``input`` dict.
+
+    Best-effort by design: a transport error, a malformed tool definition, a
+    response with no matching ``tool_use`` block, or a non-object tool input
+    logs a warning and returns ``None`` so the caller can leave the item
+    unprocessed and retry on the next run. It never raises on a model or network
+    failure (the dominant Lambda enrichment pattern). Validation and any
+    coercion of the returned dict stay in the consumer.
+
+    Args:
+        client: An Anthropic client (from :func:`build_anthropic_client` or any
+            object exposing ``messages.create``).
+        tool: A single Anthropic tool definition. Must carry a ``name``.
+        prompt: The user-turn prompt text.
+        model: Model id (kept in the consumer; this helper imposes no default).
+        max_tokens: Response token cap.
+        system: Optional system prompt.
+
+    Returns:
+        The tool's ``input`` dict, or ``None`` on any failure.
+    """
+    if not isinstance(tool, dict):
+        log.warning("call_tool: tool is not a dict; cannot force tool use")
+        return None
+    tool_name = str(tool.get("name") or "").strip()
+    if not tool_name:
+        log.warning("call_tool: tool definition has no usable 'name'; cannot force tool use")
+        return None
+
+    kwargs: Dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [{"role": "user", "content": prompt}],
+        "tools": [tool],
+        "tool_choice": {"type": "tool", "name": tool_name},
+    }
+    if system is not None:
+        kwargs["system"] = system
+
+    try:
+        response = client.messages.create(**kwargs)
+    except Exception as exc:  # noqa: BLE001 - best-effort; never abort the caller's run
+        log.warning("call_tool: model call failed for tool '%s': %s", tool_name, exc)
+        return None
+
+    for block in getattr(response, "content", None) or []:
+        if getattr(block, "type", None) == "tool_use" and getattr(block, "name", "") == tool_name:
+            tool_input = block.input
+            if isinstance(tool_input, dict):
+                return tool_input
+            log.warning("call_tool: tool_use input for '%s' was not an object", tool_name)
+            return None
+
+    log.warning("call_tool: response contained no tool_use block for '%s'", tool_name)
+    return None
+
+
+def call_text(
+    client: Any,
+    *,
+    prompt: str,
+    model: str,
+    max_tokens: int,
+    system: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Make a plain text call and return the text plus token usage.
+
+    Returns ``{"text", "input_tokens", "output_tokens"}``. ``text`` is the
+    concatenation of all ``text`` content blocks (empty string if the response
+    carried none). Unlike :func:`call_tool` this is not best-effort: a transport
+    error propagates to the caller, who wanted the text or an exception.
+
+    Args:
+        client: An Anthropic client (from :func:`build_anthropic_client` or any
+            object exposing ``messages.create``).
+        prompt: The user-turn prompt text.
+        model: Model id (kept in the consumer; this helper imposes no default).
+        max_tokens: Response token cap.
+        system: Optional system prompt.
+
+    Returns:
+        ``{"text": str, "input_tokens": int | None, "output_tokens": int | None}``.
+    """
+    kwargs: Dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [{"role": "user", "content": prompt}],
+    }
+    if system is not None:
+        kwargs["system"] = system
+
+    response = client.messages.create(**kwargs)
+    text = "".join(
+        block.text for block in (getattr(response, "content", None) or []) if getattr(block, "type", None) == "text"
+    )
+    usage = getattr(response, "usage", None)
+    return {
+        "text": text,
+        "input_tokens": getattr(usage, "input_tokens", None),
+        "output_tokens": getattr(usage, "output_tokens", None),
+    }

nui_shared_utils/secrets_helper.py

@@ -38,7 +38,11 @@ def get_secret(secret_name: str) -> Dict:
 
     # Create a Secrets Manager client
     session = boto3.session.Session()
-    client = session.client(service_name="secretsmanager", region_name=session.region_name or "ap-southeast-2")
+    region = session.region_name or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+    if not region:
+        raise Exception("AWS region not configured for Secrets Manager lookup; set AWS_REGION or AWS_DEFAULT_REGION")
+
+    client = session.client(service_name="secretsmanager", region_name=region)
 
     try:
         response = client.get_secret_value(SecretId=secret_name)

nui_shared_utils/snowflake_client.py

@@ -0,0 +1,422 @@
+"""NUI adapter for the ``snowflake-sql-api`` pure-Python Snowflake client.
+
+This is the NUI-opinionated layer over the generic
+`snowflake-sql-api <https://github.com/hampsterx/snowflake-sql-api>`_ package.
+The generic package stays vendor-neutral (no account/role/timezone defaults);
+all NUI specifics live here:
+
+- **Keypair from Secrets Manager.** Credentials (account, user, PEM private key,
+  optional passphrase) are loaded from AWS Secrets Manager by default, with
+  environment-variable and explicit-argument overrides.
+- **NUI session defaults.** ``TIMEZONE='Pacific/Auckland'`` and role
+  ``NUI_LAMBDA`` are applied unless overridden. (``WEEK_START`` is *not* set: the
+  SQL API only accepts an allow-list of session parameters in a request and
+  rejects ``WEEK_START`` with HTTP 400. The API is stateless per statement, so
+  ``ALTER SESSION`` cannot substitute. Set it on the Snowflake user/role default
+  if a consumer needs Monday-first weeks.)
+- **Redacted query logging.** A logging hook records the statement text
+  (truncated) and the *number* of bind parameters, never the bind values, JWTs,
+  key material, or secret names.
+- **Sync by default.** :func:`create_snowflake_client` returns the synchronous
+  client; use :func:`create_async_snowflake_client` only for a Lambda already
+  running on an event loop.
+
+Install the extra to pull the client in::
+
+    pip install 'nui-python-shared-utils[snowflake]'
+
+Using any factory here without that extra raises a clear :class:`ImportError`
+rather than failing at package import time.
+"""
+
+import logging
+import os
+from typing import Any, Callable, Dict, Optional, Sequence, Union
+
+log = logging.getLogger(__name__)
+
+# Type alias for the on_query callback: receives SQL text and optional bind params.
+QueryHook = Callable[[str, Optional[Sequence[Any]]], None]
+
+# Optional dependency: the generic snowflake-sql-api client. Guarded so the
+# package imports without the [snowflake] extra; factories raise a clear error.
+try:
+    from snowflake_sql_api import AsyncSnowflakeClient, SnowflakeClient
+
+    SNOWFLAKE_SQL_API_AVAILABLE = True
+except ModuleNotFoundError as exc:  # pragma: no cover - flag is patched in tests
+    # Only the missing extra itself flips the availability flag. If the package
+    # is installed but a *dependency of it* is missing, re-raise so the user sees
+    # the real traceback instead of a misleading "not installed" message.
+    if exc.name and exc.name.split(".")[0] != "snowflake_sql_api":
+        raise
+    AsyncSnowflakeClient = None  # type: ignore[assignment,misc]
+    SnowflakeClient = None  # type: ignore[assignment,misc]
+    SNOWFLAKE_SQL_API_AVAILABLE = False
+
+__all__ = [
+    "DEFAULT_TIMEZONE",
+    "DEFAULT_ROLE",
+    "DEFAULT_SECRET_NAME",
+    "get_snowflake_credentials",
+    "create_snowflake_client",
+    "create_async_snowflake_client",
+    "redacting_query_logger",
+]
+
+#: NUI session defaults. Every one of these is overridable per call.
+DEFAULT_TIMEZONE = "Pacific/Auckland"
+DEFAULT_ROLE = "NUI_LAMBDA"
+
+#: Secrets Manager secret name used when none is supplied via argument or the
+#: ``SNOWFLAKE_CREDENTIALS_SECRET`` environment variable.
+DEFAULT_SECRET_NAME = "snowflake-credentials"
+
+#: Default ``User-Agent`` sent by NUI clients (overridable via ``user_agent``).
+_USER_AGENT = "nui-python-shared-utils-snowflake"
+
+# Secret/credential field aliases. The secret JSON may use any of these.
+_ACCOUNT_FIELDS = ("account", "snowflake_account")
+_USER_FIELDS = ("user", "username", "snowflake_user")
+_PRIVATE_KEY_FIELDS = ("private_key", "privateKey", "snowflake_private_key")
+_PASSPHRASE_FIELDS = (
+    "private_key_passphrase",
+    "passphrase",
+    "private_key_password",
+)
+
+
+def _require_snowflake_sql_api() -> None:
+    """Raise a clear, actionable error when the optional extra is missing."""
+    if not SNOWFLAKE_SQL_API_AVAILABLE:
+        raise ImportError(
+            "snowflake-sql-api is not installed. Install it with: pip install 'nui-python-shared-utils[snowflake]'"
+        )
+
+
+def _first(mapping: Dict[str, Any], keys: Sequence[str]) -> Optional[Any]:
+    """Return the first present, non-empty value among ``keys`` in ``mapping``."""
+    for key in keys:
+        value = mapping.get(key)
+        if value:
+            return value
+    return None
+
+
+def _as_key_bytes(value: Any) -> bytes:
+    """Coerce a PEM private key (``str`` or ``bytes``) to ``bytes``."""
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    raise ValueError("private_key must be PEM text (str) or bytes")
+
+
+def _resolve_secret_name(secret_name: Optional[str]) -> str:
+    """Resolve the secret name: explicit arg > env var > default."""
+    return secret_name or os.environ.get("SNOWFLAKE_CREDENTIALS_SECRET") or DEFAULT_SECRET_NAME
+
+
+def _env_private_key() -> Optional[bytes]:
+    """Read key bytes from ``SNOWFLAKE_PRIVATE_KEY`` (inline PEM) or ``SNOWFLAKE_PRIVATE_KEY_PATH`` (file)."""
+    key_pem = os.environ.get("SNOWFLAKE_PRIVATE_KEY")
+    if key_pem:
+        return _as_key_bytes(key_pem)
+    key_path = os.environ.get("SNOWFLAKE_PRIVATE_KEY_PATH")
+    if key_path:
+        with open(key_path, "rb") as handle:
+            return handle.read()
+    return None
+
+
+def get_snowflake_credentials(
+    secret_name: Optional[str] = None,
+    *,
+    account: Optional[str] = None,
+    user: Optional[str] = None,
+    private_key: Optional[Union[bytes, str]] = None,
+    private_key_passphrase: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Resolve Snowflake keypair credentials.
+
+    Each field is resolved independently with strict **explicit arg > env var >
+    Secrets Manager** precedence, so an explicit value is never shadowed by a
+    lower tier:
+
+    - ``account`` / ``user``: explicit arg, else ``SNOWFLAKE_ACCOUNT`` /
+      ``SNOWFLAKE_USER``, else the secret's ``account`` / ``user`` field.
+    - ``private_key``: explicit arg (bytes/PEM str), else ``SNOWFLAKE_PRIVATE_KEY``
+      (inline PEM) / ``SNOWFLAKE_PRIVATE_KEY_PATH`` (file), else the secret's
+      ``private_key`` field (PEM text).
+    - ``private_key_passphrase`` is paired with the key's source: an explicit
+      passphrase arg always wins, otherwise the passphrase comes from the **same
+      tier the key came from** (env key -> ``SNOWFLAKE_PRIVATE_KEY_PASSPHRASE``;
+      secret key -> the secret's passphrase field). An explicit key is therefore
+      never silently paired with a stale env/secret passphrase.
+
+    Secrets Manager is only contacted when ``account``, ``user`` or the key is
+    still unresolved after the explicit/env tiers.
+
+    Returns a dict with ``account``, ``user``, ``private_key`` (bytes) and
+    ``private_key_passphrase`` keys.
+    """
+    resolved_account = account or os.environ.get("SNOWFLAKE_ACCOUNT")
+    resolved_user = user or os.environ.get("SNOWFLAKE_USER")
+
+    # Resolve key + passphrase together so they always come from one source.
+    if private_key is not None:
+        resolved_key: Optional[bytes] = _as_key_bytes(private_key)
+        resolved_passphrase = private_key_passphrase  # explicit arg only
+    else:
+        env_key = _env_private_key()
+        if env_key is not None:
+            resolved_key = env_key
+            resolved_passphrase = (
+                private_key_passphrase
+                if private_key_passphrase is not None
+                else os.environ.get("SNOWFLAKE_PRIVATE_KEY_PASSPHRASE")
+            )
+        else:
+            resolved_key = None
+            resolved_passphrase = private_key_passphrase  # may be filled from secret
+
+    # Contact Secrets Manager only for what is still missing.
+    if not (resolved_account and resolved_user and resolved_key is not None):
+        from .secrets_helper import get_secret
+
+        resolved_name = _resolve_secret_name(secret_name)
+        secret = get_secret(resolved_name)
+
+        resolved_account = resolved_account or _first(secret, _ACCOUNT_FIELDS)
+        resolved_user = resolved_user or _first(secret, _USER_FIELDS)
+        if resolved_key is None:
+            secret_key = _first(secret, _PRIVATE_KEY_FIELDS)
+            resolved_key = _as_key_bytes(secret_key) if secret_key else None
+            if resolved_passphrase is None:
+                resolved_passphrase = _first(secret, _PASSPHRASE_FIELDS)
+
+        missing = [
+            name
+            for name, value in (
+                ("account", resolved_account),
+                ("user", resolved_user),
+                ("private_key", resolved_key),
+            )
+            if not value
+        ]
+        if missing:
+            # Name the secret but never its contents.
+            raise ValueError(f"Snowflake secret '{resolved_name}' is missing required field(s): " + ", ".join(missing))
+
+    if not resolved_key:
+        # An explicit empty key (``b""``) or an empty key file would otherwise
+        # slip past the missing-field check above (which only runs in the secret
+        # branch). Fail clearly here regardless of the key's source.
+        raise ValueError("a non-empty private_key is required")
+
+    return {
+        "account": resolved_account,
+        "user": resolved_user,
+        "private_key": resolved_key,
+        "private_key_passphrase": resolved_passphrase,
+    }
+
+
+def redacting_query_logger(
+    logger: Optional[logging.Logger] = None,
+    *,
+    level: int = logging.DEBUG,
+    max_sql_chars: int = 1000,
+) -> QueryHook:
+    """Build an ``on_query`` hook that logs statements without leaking values.
+
+    The returned callback logs the (truncated) SQL text and the *count* of bind
+    parameters. It never logs the bind values themselves, so user data, secrets,
+    and PII passed as parameters stay out of the logs.
+
+    Args:
+        logger: Destination logger. Defaults to this module's logger.
+        level: Log level for the query record (default ``DEBUG``).
+        max_sql_chars: Truncate the logged SQL beyond this many characters.
+    """
+    target = logger or log
+
+    def _hook(sql: str, params: Optional[Sequence[Any]]) -> None:
+        truncated = sql if len(sql) <= max_sql_chars else sql[:max_sql_chars] + "...(truncated)"
+        param_count = len(params) if params else 0
+        target.log(
+            level,
+            "snowflake query",
+            extra={"sql": truncated, "bind_param_count": param_count},
+        )
+
+    return _hook
+
+
+def _resolve_on_query(
+    on_query: Optional[QueryHook],
+    logger: Optional[logging.Logger],
+    log_queries: bool,
+    log_sql_max_chars: int,
+) -> Optional[QueryHook]:
+    """Pick the query hook: explicit override, redacting logger, or none."""
+    if on_query is not None:
+        return on_query
+    if log_queries:
+        return redacting_query_logger(logger, max_sql_chars=log_sql_max_chars)
+    return None
+
+
+def _client_kwargs(
+    creds: Dict[str, Any],
+    *,
+    role: Optional[str],
+    warehouse: Optional[str],
+    database: Optional[str],
+    schema: Optional[str],
+    timezone: Optional[str],
+    parameters: Optional[Dict[str, Any]],
+    on_query: Optional[QueryHook],
+    user_agent: Optional[str],
+    extra: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Shared keyword assembly for both sync and async client construction.
+
+    ``TIMEZONE`` rides the client's ``timezone`` argument; any caller-supplied
+    ``parameters`` pass straight through to the SQL API ``parameters`` map. Note
+    the SQL API only accepts an allow-list of session parameters there (TIMEZONE
+    and output-format params are fine; WEEK_START is rejected, see module docs).
+    """
+    # Start from passthrough kwargs, then let adapter-managed keys win, so an
+    # unexpected ``extra`` key can never silently override a managed one (the
+    # factories' named params already capture managed keys, so a caller cannot
+    # reach these via ``**client_kwargs`` today; this guards a future key add).
+    kwargs: Dict[str, Any] = dict(extra)
+    kwargs.update(
+        {
+            "account": creds["account"],
+            "user": creds["user"],
+            "private_key": creds["private_key"],
+            "private_key_passphrase": creds.get("private_key_passphrase"),
+            "role": role,
+            "warehouse": warehouse,
+            "database": database,
+            "schema": schema,
+            "timezone": timezone,
+            "parameters": dict(parameters) if parameters else None,
+            "on_query": on_query,
+            "user_agent": user_agent or _USER_AGENT,
+        }
+    )
+    return kwargs
+
+
+def create_snowflake_client(
+    *,
+    secret_name: Optional[str] = None,
+    account: Optional[str] = None,
+    user: Optional[str] = None,
+    private_key: Optional[Union[bytes, str]] = None,
+    private_key_passphrase: Optional[str] = None,
+    role: Optional[str] = DEFAULT_ROLE,
+    warehouse: Optional[str] = None,
+    database: Optional[str] = None,
+    schema: Optional[str] = None,
+    timezone: Optional[str] = DEFAULT_TIMEZONE,
+    parameters: Optional[Dict[str, Any]] = None,
+    logger: Optional[logging.Logger] = None,
+    log_queries: bool = True,
+    log_sql_max_chars: int = 1000,
+    on_query: Optional[QueryHook] = None,
+    user_agent: Optional[str] = None,
+    **client_kwargs: Any,
+) -> "SnowflakeClient":
+    """Construct a synchronous Snowflake client with NUI defaults.
+
+    This is the adapter's default entry point. Credentials are resolved via
+    :func:`get_snowflake_credentials`; NUI session defaults (timezone, role) are
+    applied unless overridden; a redacting query-logging hook is wired in unless
+    ``log_queries=False`` or a custom ``on_query`` is given.
+
+    Extra keyword arguments (``timeout``, ``statement_timeout``,
+    ``poll_interval``, ``retry_policy``, ``host`` ...) pass straight through to
+    :class:`snowflake_sql_api.SnowflakeClient`.
+
+    Returns:
+        A ready-to-use :class:`snowflake_sql_api.SnowflakeClient`.
+    """
+    _require_snowflake_sql_api()
+    creds = get_snowflake_credentials(
+        secret_name,
+        account=account,
+        user=user,
+        private_key=private_key,
+        private_key_passphrase=private_key_passphrase,
+    )
+    hook = _resolve_on_query(on_query, logger, log_queries, log_sql_max_chars)
+    kwargs = _client_kwargs(
+        creds,
+        role=role,
+        warehouse=warehouse,
+        database=database,
+        schema=schema,
+        timezone=timezone,
+        parameters=parameters,
+        on_query=hook,
+        user_agent=user_agent,
+        extra=client_kwargs,
+    )
+    return SnowflakeClient(**kwargs)
+
+
+def create_async_snowflake_client(
+    *,
+    secret_name: Optional[str] = None,
+    account: Optional[str] = None,
+    user: Optional[str] = None,
+    private_key: Optional[Union[bytes, str]] = None,
+    private_key_passphrase: Optional[str] = None,
+    role: Optional[str] = DEFAULT_ROLE,
+    warehouse: Optional[str] = None,
+    database: Optional[str] = None,
+    schema: Optional[str] = None,
+    timezone: Optional[str] = DEFAULT_TIMEZONE,
+    parameters: Optional[Dict[str, Any]] = None,
+    logger: Optional[logging.Logger] = None,
+    log_queries: bool = True,
+    log_sql_max_chars: int = 1000,
+    on_query: Optional[QueryHook] = None,
+    user_agent: Optional[str] = None,
+    **client_kwargs: Any,
+) -> "AsyncSnowflakeClient":
+    """Construct an asynchronous Snowflake client with NUI defaults.
+
+    Async parity with :func:`create_snowflake_client`. Use only inside a Lambda
+    already running on an event loop; the sync client is the NUI default
+    otherwise.
+
+    Returns:
+        A ready-to-use :class:`snowflake_sql_api.AsyncSnowflakeClient`.
+    """
+    _require_snowflake_sql_api()
+    creds = get_snowflake_credentials(
+        secret_name,
+        account=account,
+        user=user,
+        private_key=private_key,
+        private_key_passphrase=private_key_passphrase,
+    )
+    hook = _resolve_on_query(on_query, logger, log_queries, log_sql_max_chars)
+    kwargs = _client_kwargs(
+        creds,
+        role=role,
+        warehouse=warehouse,
+        database=database,
+        schema=schema,
+        timezone=timezone,
+        parameters=parameters,
+        on_query=hook,
+        user_agent=user_agent,
+        extra=client_kwargs,
+    )
+    return AsyncSnowflakeClient(**kwargs)