nui-python-shared-utils 1.3.2__tar.gz → 1.4.1__tar.gz

nui_python_shared_utils-1.3.2/CLAUDE.md → nui_python_shared_utils-1.4.1/AGENTS.md

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Canonical agent guidance for this repository. Read by Claude Code (via `CLAUDE.md` import), Codex CLI, and humans. If you only have time to read one doc, read this one.
 
 ## Quick Links
 
@@ -38,6 +38,7 @@ This is `nui-python-shared-utils`, a Python package providing production-ready u
 - **Database** (`db_client.py`) - Connection pooling with retry logic
 - **Metrics** (`cloudwatch_metrics.py`) - Batched CloudWatch publishing with decorators
 - **JWT Authentication** (`jwt_auth.py`) - RS256 token validation for API Gateway Lambdas (uses `rsa` package)
+- **LLM Helper** (`llm.py`) - Generic Anthropic (Claude) client plumbing: API-key/Bedrock auth, forced tool-use call, text call (uses `anthropic`)
 - **Error Handling** (`error_handler.py`) - Retry patterns with exponential backoff
 - **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities
 
@@ -49,6 +50,8 @@ The package uses optional extras to minimize Lambda bundle size:
 - `database` - MySQL/PostgreSQL drivers
 - `slack` - Slack SDK
 - `jwt` - RS256 JWT validation (`rsa` package)
+- `snowflake` - Pure-Python Snowflake SQL API client (`snowflake-sql-api`)
+- `llm` - Anthropic (Claude) client helper (`anthropic[bedrock]`, both API-key and Bedrock IAM auth)
 - `all` - All integrations
 - `dev` - Development and testing tools
 
@@ -362,7 +365,7 @@ The package is designed to work well in Lambda layers for sharing across multipl
 
 This project follows a clear documentation structure:
 
-- **[CLAUDE.md](CLAUDE.md)** (this file) - Development workflows, commands, testing strategies
+- **[AGENTS.md](AGENTS.md)** (this file) - Development workflows, commands, testing strategies (`CLAUDE.md` imports it)
 - **[README.md](README.md)** - User-facing PyPI package description with quick start examples
 - **[docs/](docs/README.md)** - Comprehensive usage guides and references
   - `getting-started/` - Installation, configuration, quick start patterns
@@ -371,7 +374,7 @@ This project follows a clear documentation structure:
   - `templates/` - Configuration file templates (Slack setup YAML)
   - `archive/` - Historical documentation and migration notes
 
-**For Claude Code users**: The docs/ directory contains detailed usage patterns,
+**For coding agents**: The docs/ directory contains detailed usage patterns,
 configuration examples, and integration guides that complement these development instructions.
 
 **For new package users**: Start with [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)

nui_python_shared_utils-1.4.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{nui_python_shared_utils-1.3.2 → nui_python_shared_utils-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.3.2
+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.2 → nui_python_shared_utils-1.4.1}/README.md

@@ -35,6 +35,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
@@ -65,12 +66,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
@@ -198,6 +201,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
@@ -230,6 +262,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.2 → nui_python_shared_utils-1.4.1}/docs/README.md

@@ -20,7 +20,9 @@ Component-specific guides for major features:
 - **[Lambda Context Helpers](guides/lambda-utilities.md)** - Environment info extraction for logging and metrics
 - **[Slack Integration](guides/slack-integration.md)** - Messaging, formatting, and file uploads
 - **[Elasticsearch Integration](guides/elasticsearch-integration.md)** - Search, bulk indexing, health checks
+- **[Snowflake Integration](guides/snowflake-integration.md)** - SQL API client, Secrets Manager credentials, sync/async usage
 - **[JWT Authentication](guides/jwt-authentication.md)** - RS256 token validation for API Gateway Lambdas
+- **[Anthropic (Claude) Integration](guides/llm-integration.md)** - Client helper for API-key/Bedrock auth, forced tool-use, and text calls
 - **[Log Processing](guides/log-processing.md)** - Kinesis log extraction and ES index naming
 - Database Connections (planned)
 - Error Handling Patterns (planned)
@@ -124,7 +126,9 @@ When contributing to documentation:
 - Lambda context helpers guide (guides/lambda-utilities.md)
 - Slack integration guide (guides/slack-integration.md)
 - Elasticsearch integration guide (guides/elasticsearch-integration.md)
+- Snowflake integration guide (guides/snowflake-integration.md)
 - JWT authentication guide (guides/jwt-authentication.md)
+- Anthropic (Claude) integration guide (guides/llm-integration.md)
 - Shared types reference (guides/shared-types.md)
 - CLI tools guide (guides/cli-tools.md)
 - Testing guide (development/testing.md)

nui_python_shared_utils-1.4.1/docs/guides/llm-integration.md

@@ -0,0 +1,200 @@
+# Anthropic (Claude) Integration
+
+The LLM helper (`nui_shared_utils.llm`) is generic plumbing for calling
+Anthropic's Claude models from Lambda functions and CLI tools. It builds a
+client, makes a forced tool-use call or a plain text call, and hands back the
+parsed result.
+
+It is deliberately thin. Prompts, tool schemas, model ids, and any
+domain-specific processing of the result stay in your code. The helper owns auth,
+the call shape, and result extraction, the parts that were being copy-pasted
+across repos.
+
+Install the optional extra:
+
+```bash
+pip install "nui-python-shared-utils[llm]"
+```
+
+`anthropic[bedrock]` covers both auth modes (API key and Bedrock IAM). The
+`[bedrock]` sub-extra is what makes `anthropic.AnthropicBedrock` importable.
+
+## What this helper is (and is not)
+
+| In scope (lives here)                         | Out of scope (stays in your repo)              |
+| --------------------------------------------- | ---------------------------------------------- |
+| Build a client (API key or Bedrock IAM)       | Model id selection                             |
+| Forced tool-use call + `tool_use` extraction  | Tool schemas (`input_schema`)                  |
+| Text call + token-usage extraction            | Prompts and system prompts                     |
+| Best-effort `None` on tool-call failure       | Validation / coercion of the returned dict     |
+
+If you find yourself wanting to add a default model, a prompt, or a tool schema
+to this module, it belongs in the consumer instead.
+
+## Building a Client
+
+`build_anthropic_client(mode="api_key" | "bedrock", *, api_key=None, secret_name=None, region=None, max_retries=5)`
+
+### API-key auth (default)
+
+Returns an `anthropic.Anthropic`. The key resolves in order:
+
+1. explicit `api_key` argument
+2. `ANTHROPIC_API_KEY` environment variable
+3. AWS Secrets Manager via `secret_name` (read from the `api_key` field)
+
+```python
+from nui_shared_utils import build_anthropic_client
+
+# Lambda: key in Secrets Manager
+client = build_anthropic_client(secret_name="my-service/anthropic-key")
+
+# Local dev: key in the environment
+client = build_anthropic_client()  # reads ANTHROPIC_API_KEY
+
+# Explicit (e.g. a key resolved from a CLI keyring or a non-default secret field)
+client = build_anthropic_client(api_key=my_resolved_key)
+```
+
+If your secret stores the key under a field other than `api_key`, resolve it
+yourself and pass `api_key=`:
+
+```python
+from nui_shared_utils import get_api_key, build_anthropic_client
+
+key = get_api_key("my-service/creds", key_field="anthropic_api_key")
+client = build_anthropic_client(api_key=key)
+```
+
+### Bedrock IAM auth
+
+Returns an `anthropic.AnthropicBedrock`. No key, the Lambda's IAM role provides
+access. `region` sets `aws_region`; it falls back to `AWS_REGION` /
+`AWS_DEFAULT_REGION` and then to the SDK's own default region resolution.
+
+```python
+client = build_anthropic_client(mode="bedrock", region="us-east-1")
+```
+
+## Forced Tool-Use: `call_tool`
+
+`call_tool(client, *, tool, prompt, model, max_tokens, system=None) -> dict | None`
+
+Forces the model to answer through the named tool (`tool_choice` of type `tool`)
+and returns that tool's `tool_use.input` dict. The helper only forces the call
+and returns the input; it does no validation or coercion itself. Setting
+`"strict": True` on your tool's `input_schema` asks the API to constrain the tool
+input to that schema, but you still own validating and coercing the returned dict
+(value ranges, enum membership, types) in your code.
+
+```python
+from nui_shared_utils import build_anthropic_client, call_tool
+
+client = build_anthropic_client(secret_name="my-service/anthropic-key")
+
+# The tool schema is yours; the helper just forces and extracts it.
+classify_tool = {
+    "name": "classify_item",
+    "description": "Classify a support message.",
+    "strict": True,
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "category": {"type": "string", "enum": ["bug", "question", "feature"]},
+            "urgency": {"type": "number", "description": "0.0 low to 1.0 urgent"},
+        },
+        "required": ["category", "urgency"],
+        "additionalProperties": False,
+    },
+}
+
+result = call_tool(
+    client,
+    tool=classify_tool,
+    prompt="The export button does nothing and I have a deadline.",
+    model="claude-haiku-4-5",   # your choice; the helper imposes no default
+    max_tokens=256,
+    system="You triage inbound support messages.",  # optional
+)
+
+if result is None:
+    # Model error, no tool block, or a malformed result. Leave the item
+    # unprocessed and let the next run retry it.
+    ...
+else:
+    category = result["category"]   # validate/coerce in your code
+    urgency = result["urgency"]
+```
+
+### Best-effort contract
+
+`call_tool` is best-effort and **never raises** on a model or network failure. It
+logs a warning and returns `None` when:
+
+- `client.messages.create` raises any exception (transport, timeout, rate-limit, etc.),
+- the response has no `tool_use` block for the named tool,
+- the tool's `input` is not an object,
+- the tool definition is not a dict or has no `name`.
+
+This matches the dominant Lambda pattern: a single item failing to enrich must
+not abort the batch. If a caller genuinely needs the exception (rather than a
+`None`-check), that is a deliberate future addition, not the default.
+
+## Text Calls: `call_text`
+
+`call_text(client, *, prompt, model, max_tokens, system=None) -> dict`
+
+Returns `{"text", "input_tokens", "output_tokens"}`. `text` is the concatenation
+of all text content blocks (empty string if the response carried none). Unlike
+`call_tool`, this is **not** best-effort: a transport error propagates, because
+the caller wanted the text or an exception.
+
+```python
+from nui_shared_utils import build_anthropic_client, call_text
+
+client = build_anthropic_client(mode="bedrock", region="us-east-1")
+
+out = call_text(
+    client,
+    prompt="Summarize this PDF extract in two sentences:\n\n" + extract,
+    model="claude-haiku-4-5",
+    max_tokens=512,
+)
+print(out["text"])
+print(out["input_tokens"], out["output_tokens"])  # for cost/usage tracking
+```
+
+## Cold Start and the Optional Extra
+
+`anthropic` is imported at the top of `nui_shared_utils.llm`, so any use of the
+helper requires the `[llm]` extra. Importing the package itself stays cheap:
+`import nui_shared_utils` does not import this module (and therefore does not
+import `anthropic`) until you first touch an `llm` attribute. This is the same
+PEP 562 lazy-loading behaviour the rest of the package uses to keep Lambda
+cold-start fast (enforced by `tests/test_lazy_imports.py`).
+
+Without the extra installed, the top-level lazy exports resolve to `None`
+(matching the other optional integrations), so a missing dependency surfaces as a
+clear `None` rather than a package import failure:
+
+```python
+import nui_shared_utils as nui
+
+if nui.build_anthropic_client is None:
+    raise RuntimeError("install nui-python-shared-utils[llm] to use the LLM helper")
+```
+
+A direct `from nui_shared_utils.llm import build_anthropic_client` raises
+`ImportError` when the extra is missing.
+
+## Credential Resolution Summary
+
+Consistent with the other shared clients (Slack, Elasticsearch, Snowflake):
+
+1. explicit argument (`api_key=`)
+2. environment variable (`ANTHROPIC_API_KEY`)
+3. AWS Secrets Manager (`secret_name`, `api_key` field)
+
+Bedrock mode uses IAM instead of any of the above. A consumer needing a CLI
+keyring or GPG-backed key resolves it on its own and passes `api_key=`, the
+helper does not pull in a CLI credential loader.

nui_python_shared_utils-1.4.1/docs/guides/snowflake-integration.md

@@ -0,0 +1,159 @@
+# Snowflake Integration
+
+The Snowflake adapter wraps `snowflake-sql-api`, a pure-Python SQL API client.
+Use it when a Lambda, CLI, or async API needs Snowflake reads or simple SQL
+execution without bundling `snowflake-connector-python`.
+
+Install the optional extra:
+
+```bash
+pip install "nui-python-shared-utils[snowflake]"
+```
+
+## Credential Resolution
+
+Credentials resolve in the same order as the other shared clients:
+
+1. explicit arguments
+2. `SNOWFLAKE_*` environment variables
+3. AWS Secrets Manager
+
+Supported direct environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `SNOWFLAKE_ACCOUNT` | Snowflake account locator, for example `xy12345.ap-southeast-2` |
+| `SNOWFLAKE_USER` | Service user |
+| `SNOWFLAKE_PRIVATE_KEY` | Inline PEM private key |
+| `SNOWFLAKE_PRIVATE_KEY_PATH` | Local PEM/DER private key path |
+| `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE` | Optional private key passphrase |
+| `SNOWFLAKE_CREDENTIALS_SECRET` | Secret name override |
+
+Secrets Manager values use this JSON shape:
+
+```json
+{
+  "account": "xy12345.ap-southeast-2",
+  "user": "SERVICE_USER",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
+  "private_key_passphrase": "optional"
+}
+```
+
+Existing `snowflake-agent-credentials` secrets and service-specific secrets such
+as a future `NUI_ANALYTICS_SVC` secret fit this shape. Pass `secret_name=` when a
+service should not use the default or environment-selected secret.
+
+## Sync Usage
+
+```python
+from nui_shared_utils import create_snowflake_client
+
+with create_snowflake_client(
+    secret_name="snowflake-agent-credentials",
+    role="NUI_LAMBDA",
+    warehouse="AGENT_WH",
+    database="NUI_MARKETS",
+    schema="ANALYTICS",
+) as client:
+    rows = client.query(
+        "SELECT source_id, title FROM source_items WHERE source_id = ? LIMIT 10",
+        ["edairynews"],
+    )
+```
+
+The adapter applies NUI defaults for `role="NUI_LAMBDA"` and
+`timezone="Pacific/Auckland"`. Override role, warehouse, database, schema, and
+timezone explicitly for service accounts that need narrower production access.
+
+## Async Usage
+
+Use the async factory in FastAPI routes or other runtimes that already own an
+event loop:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from nui_shared_utils import create_async_snowflake_client
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.snowflake = create_async_snowflake_client(
+        secret_name="nui-analytics-snowflake",
+        role="NUI_ANALYTICS_API",
+        warehouse="ANALYTICS_WH",
+        database="NUI_MARKETS",
+        schema="ANALYTICS_API",
+        statement_timeout=30,
+    )
+    try:
+        yield
+    finally:
+        await app.state.snowflake.aclose()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+For Lambda handlers that use an async framework, create the client during
+startup and close it during shutdown. For normal synchronous Lambda handlers,
+prefer `create_snowflake_client`.
+
+## Query Parameters
+
+Snowflake SQL API bindings are positional `?` bindings:
+
+```python
+rows = client.query("SELECT id FROM trades WHERE solution_id = ?", [solution_id])
+```
+
+Do not use connector-style `%s` placeholders or named `:name` bindings with this
+adapter.
+
+## Logging And Metrics Hooks
+
+By default the adapter installs a redacting query logger. It logs SQL text and
+bind parameter count, never bind values:
+
+```python
+client = create_snowflake_client(log_sql_max_chars=500)
+```
+
+For service metrics, pass a custom `on_query` hook:
+
+```python
+def record_query(sql, params):
+    metrics.put_metric("SnowflakeQuery", 1, "Count")
+
+client = create_snowflake_client(on_query=record_query)
+```
+
+Keep hooks generic. Domain-specific table names, market-intelligence state
+transitions, and analytics endpoint logic belong in the consuming service.
+
+## Offline Tests
+
+Use `snowflake_sql_api.testing.FakeSnowflake` to test service code without a
+network or real Snowflake account:
+
+```python
+import httpx
+from snowflake_sql_api.testing import FakeSnowflake
+from nui_shared_utils import create_async_snowflake_client
+
+async def test_query(rsa_private_key_pem):
+    fake = FakeSnowflake()
+    fake.register("SELECT 1 AS value", [{"value": 1}])
+
+    async with httpx.AsyncClient(transport=fake.transport) as http_client:
+        client = create_async_snowflake_client(
+            account="xy12345.ap-southeast-2",
+            user="TEST_USER",
+            private_key=rsa_private_key_pem,
+            http_client=http_client,
+            log_queries=False,
+        )
+        assert await client.query_scalar("SELECT 1 AS value") == 1
+```
+
+Add live smoke tests for behavior that FakeSnowflake cannot prove, such as
+`MERGE` row counts, `PARSE_JSON(?)`, and timestamp/session timezone semantics.