nui-python-shared-utils 1.6.0__tar.gz → 2.0__tar.gz

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/.github/workflows/ci.yml

@@ -109,5 +109,4 @@ jobs:
       run: |
         pip install dist/*.whl
         python -c "import nui_shared_utils; print('✅ Package imports successfully')"
-        python -c "from nui_shared_utils import Config, get_secret; print('✅ Core imports work')"
-        python -W ignore::DeprecationWarning -c "import nui_lambda_shared_utils; print('✅ Backwards-compat shim works')"
+        python -c "from nui_shared_utils import Config, get_secret; print('✅ Core imports work')"

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/.github/workflows/publish.yml

@@ -107,32 +107,4 @@ jobs:
       with:
         verbose: true
         print-hash: true
-        skip-existing: true  # No-op instead of failing if the version is already on PyPI (safe re-runs)
-
-  publish-test:
-    name: Publish to TestPyPI
-    runs-on: ubuntu-latest
-    needs: [test, build]
-    # Publish to TestPyPI on manual (non-tag) dispatch only; tag pushes go to PyPI above
-    if: github.event_name == 'workflow_dispatch' && !startsWith(github.ref, 'refs/tags/')
-    environment:
-      name: testpypi
-      url: https://test.pypi.org/project/nui-python-shared-utils/
-    
-    permissions:
-      id-token: write
-      contents: read
-    
-    steps:
-    - name: Download artifacts
-      uses: actions/download-artifact@v7
-      with:
-        name: dist
-        path: dist/
-    
-    - name: Publish to TestPyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        repository-url: https://test.pypi.org/legacy/
-        verbose: true
-        print-hash: true
+        skip-existing: true  # No-op instead of failing if the version is already on PyPI (safe re-runs)

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/MANIFEST.in

@@ -1,12 +1,10 @@
 # Include the license and readme
 include LICENSE
 include README.md
-include CHANGELOG.md
 
 # Include package data
 recursive-include nui_shared_utils *.py
 recursive-include nui_shared_utils/slack_setup *.yaml
-recursive-include nui_lambda_shared_utils *.py
 
 # Exclude development and build files
 exclude .gitignore

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.6.0
+Version: 2.0
 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
@@ -526,7 +526,6 @@ slack-channel-setup --config channels.yaml
 - **GitHub Repository**: https://github.com/nuimarkets/nui-python-shared-utils
 - **Issue Tracker**: https://github.com/nuimarkets/nui-python-shared-utils/issues
 - **PyPI Package**: https://pypi.org/project/nui-python-shared-utils/
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ### 💬 Support
 

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/README.md

@@ -427,7 +427,6 @@ slack-channel-setup --config channels.yaml
 - **GitHub Repository**: https://github.com/nuimarkets/nui-python-shared-utils
 - **Issue Tracker**: https://github.com/nuimarkets/nui-python-shared-utils/issues
 - **PyPI Package**: https://pypi.org/project/nui-python-shared-utils/
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ### 💬 Support
 

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/docs/README.md

@@ -1,6 +1,6 @@
 # Documentation
 
-Welcome to the comprehensive documentation for `nui-python-shared-utils` (formerly `nui-lambda-shared-utils`).
+Welcome to the comprehensive documentation for `nui-python-shared-utils`.
 
 **Last Updated**: 2026-02-13
 

nui_python_shared_utils-2.0/docs/decisions/ADR-002-keep-shared-utilities-generic.md

@@ -0,0 +1,94 @@
+# ADR-002: Keep shared utilities generic
+
+**Status**: Proposed
+**Date**: 2026-07-13
+
+## Context
+
+This package ships to PyPI as `nui-python-shared-utils` and is imported by many independent Lambda
+functions and CLI tools. `README.md` targets two audiences on purpose: the origin team, whose
+defaults match, and external teams, who share none of its schema, currency, or service taxonomy. A
+shared library that bakes one consumer's domain into its public surface forces every other consumer
+to either carry dead weight or fork.
+
+The pressure to bake it in is recurring and structural, not a one-time slip. It is always faster to
+hardcode a caller's known table names, service list, or home currency into a "convenience" method
+than to thread those through as parameters, and each such shortcut looks locally harmless. So the
+constraint has to be a standing rule that every new method is measured against, not a cleanup done
+once.
+
+The line that survives that pressure is **infrastructure vs. business**. The domain-neutral half
+(Slack messaging, Elasticsearch query building, database connection and query execution, CloudWatch
+metrics, JWT validation, secrets, timezone) is what belongs in the shared core. The business half
+(what a row means, which services exist, what currency a number is in, which status values are
+terminal) is the consumer's, and it changes per deployment.
+
+## Decision
+
+Public APIs expose configurable infrastructure utilities and leave business-specific queries, names,
+currencies, and mappings to the consumer.
+
+- **Database access is generic.** `query()` / `execute()` take SQL and parameters. No method assumes
+  a table schema, column names, or a soft-delete/status convention.
+- **Values that vary by geography or deployment are required parameters or explicit configuration**,
+  never defaulted to one org's convention. Currency, service name, timezone, and environment label
+  are supplied by the caller.
+- **No org-specific mapping constants** (service-to-emoji tables, status vocabularies) live in the
+  shipped surface. A caller that wants one passes it in.
+
+The rule is enforced continuously by `AGENTS.md`: the "Keeping the Package Generic" DO/DON'T list,
+the three-question "When Adding New Features" gate ("Is this specific to NUI, or useful for any
+Lambda project? / Could this be made configurable rather than hardcoded? / Can someone use this
+without NUI-specific knowledge?"), the Pull Request Checklist item **"No hardcoded
+organization-specific values (service names, currencies, business logic)"**, and the "Code Review
+Focus Areas" ("Generic utility patterns vs vendor-specific code"). Commit `ce48031` applied the rule
+(removed `get_entity_stats` / `get_record_stats`, the `SERVICE_EMOJI` map, the `currency="NZD"`
+default, and value-key currency inference); that is evidence the rule bites, not the decision itself.
+
+## Alternatives considered
+
+- **Ship domain convenience helpers in the core** (org-specific stats queries, a service-emoji map,
+  an assumed row schema). Ergonomic for the one consumer whose schema matches. Rejected: every other
+  consumer imports code that queries tables it does not have, and a schema change in one consumer
+  becomes a shared-library release. `get_entity_stats`/`get_record_stats` embedded `entities`/`users`
+  tables, an `entity_id` foreign key, a `deleted_at` soft-delete column, and hardcoded
+  `'confirmed'`/`'cancelled'` status literals: none of that is a shared library's business.
+- **Keep configurable defaults but seed them with the origin org's values** (e.g. `currency="NZD"`).
+  Rejected: a default silently encodes one geography. A caller in another currency gets numerically
+  wrong output with no error to catch it. A required parameter forces the choice at the call site.
+- **A kwargs escape hatch** (`get_record_stats(status_col=..., value_col=..., created_col=...)`).
+  Rejected: the mapping kwargs prove the method is not generic, it is one schema with holes punched in
+  it. A raw `query()` taking the caller's own SQL is both simpler and actually neutral.
+- **Split the business helpers into a separate consumer-specific package.** Viable, and the correct
+  home if such a helper is ever genuinely shared across consumers. Not built now: the removed helpers
+  were thin logic wrapping a SQL string, so it is cheaper for each consumer to own its query than to
+  version a shared domain layer for it.
+
+## Consequences
+
+- Consumers write their own domain queries and pass their own currency / service / schema values.
+  More boilerplate per consumer, in exchange for zero cross-consumer coupling.
+- The package is adoptable by a team with no knowledge of the origin platform, which is the third
+  gate question made real.
+- Reviewers get a bright-line test (does this name a table, currency, service, or status a specific
+  org uses?) instead of a per-PR judgment call.
+- Convenience is pushed to the consuming edges; the core stays small, which also serves the
+  optional-extras bundle-size goal.
+- One deliberate exception is on record: ADR-006 ships overridable `Pacific/Auckland` / `NUI_LAMBDA`
+  Snowflake session defaults, governed as a bounded exception in that ADR. The bright-line test still
+  holds everywhere else; a new baked geography/org default needs the same explicit, ADR-level
+  justification, or it is out.
+
+## Load-bearing premises (supersede triggers)
+
+- **This package stays a general-purpose shared library with multiple independent consumers**
+  (including external PyPI users). If it collapsed to a single internal consumer, folded into one
+  application as an internal module, the generic constraint reopens: a library with one caller has no
+  one to stay neutral for, and inlining that caller's schema becomes reasonable.
+- **The infrastructure/business split stays clean.** Connection, query execution, formatting, and
+  metrics stay domain-neutral; row meaning, service list, currency, and status vocabulary stay the
+  consumer's. If a domain concept emerged that every consumer implemented identically, a shared
+  domain layer (likely a separate package, not a bulge in the generic core) would be reconsidered.
+- **Requiring the caller to supply currency / service / schema stays cheap enough that no default is
+  worth the geography lock-in.** If a default ever became strictly necessary, it would come from
+  explicit configuration, not from a baked geography or currency constant.

nui_python_shared_utils-2.0/docs/decisions/ADR-003-lazy-load-integrations.md

@@ -0,0 +1,110 @@
+# ADR-003: Lazy-load integrations to keep package import cheap
+
+**Status**: Proposed
+**Date**: 2026-07-13
+
+## Context
+
+This package is a shared utility layer for a fleet of AWS Lambda functions and CLI tools. Both
+workloads are startup-latency sensitive: a Lambda pays the package's import cost on every cold start,
+and a CLI pays it on every invocation. The package spans many integrations (Slack, Elasticsearch,
+database drivers, CloudWatch/boto3, RS256 JWT via `rsa`, AWS Lambda Powertools, Snowflake, and an
+Anthropic LLM helper), and most of those pull heavy third-party dependencies.
+
+The public surface is a flat namespace: consumers write `import nui_shared_utils as nui` and reach
+`nui.SlackClient`, `nui.get_secret`, `nui.bind_request`, etc. A naive way to offer that flat surface
+is to import every submodule at the top of the package `__init__`, which means `import
+nui_shared_utils` transitively imports boto3, the Slack SDK, elasticsearch, and everything else,
+whether or not the caller touches them.
+
+Two properties of the stack make that cost avoidable:
+
+- **The integrations are independent.** A Lambda that only validates a JWT never needs boto3; one
+  that only publishes metrics never needs the Slack SDK. Import cost is dominated by dependencies the
+  caller does not use.
+- **The dependencies are already optional at install time.** The package exposes per-integration
+  extras (`elasticsearch`, `database`, `slack`, `jwt`, `snowflake`, `llm`, plus `all`) so a consumer
+  installs only the heavy deps it needs. Eager top-level imports would either break (an uninstalled
+  extra raises `ImportError` at package import) or force every consumer onto the full dependency set.
+
+## Decision
+
+The package's public API resolves lazily through a PEP 562 module-level `__getattr__`
+(`nui_shared_utils/__init__.py`). `import nui_shared_utils` executes almost no integration code; a
+heavy dependency loads only when the export that needs it is first accessed.
+
+- **An export map, not eager imports.** `_LAZY_EXPORTS` maps each public name to its
+  `(submodule, attr)` pair. On first access to a missing attribute, `__getattr__` imports that one
+  submodule, pulls the attribute, and caches it into the module `globals()` so subsequent access
+  skips the loader entirely (PEP 562 `__getattr__` fires only for names not already in the module
+  dict).
+- **Optional integrations degrade to `None`.** Submodules whose heavy dep is an optional extra are
+  listed in `_OPTIONAL_SUBMODULES`; an `ImportError` during lazy resolution yields `None` instead of
+  propagating, so a capability check like `if nui.SlackClient is not None` still works when the extra
+  is not installed. Non-optional submodules still raise.
+- **The flat surface is preserved.** `__all__` and `__dir__` enumerate the full export set, so star
+  imports and interactive/tab completion behave as if everything were eagerly imported. A
+  `TYPE_CHECKING`-guarded block holds the real `from .submodule import ...` statements for static type
+  checkers and IDEs; that block is never executed at runtime.
+- **Core boto3 use defers too.** Modules that back always-present exports (`secrets_helper`, `utils`,
+  `cloudwatch_metrics`) construct their boto3 clients on first call rather than at import, so even the
+  non-extra AWS path does not tax a cold start that never reaches it.
+
+Commit `c301214` (PR #24) records the effect: `import nui_shared_utils` drops from ~700ms to ~10ms
+locally. `tests/test_lazy_imports.py` locks it in, asserting in fresh subprocesses that a bare
+package import loads neither boto3/botocore, nor `anthropic`, nor the `logging` subpackage, and that
+representative integrations stay lazy until first touched (`jwt_auth` and `powertools_helpers` pull no
+heavy dep on access, the legacy shim reaches an attribute without loading `db_client`/`es_client`, and
+`secrets_helper` builds its boto3 client only on first call). The `__getattr__` mechanism makes every
+export lazy; the suite pins this representative subset rather than asserting it for each integration.
+
+## Alternatives considered
+
+- **Eager import of every integration submodule (and its heavy deps) at package import.** The
+  simplest flat-API implementation, and the standing rejected option-class. Rejected because it makes
+  every consumer pay every dependency's import cost regardless of use (the ~700ms cold-start tax), and
+  because it forces the full dependency set to be installed or `import nui_shared_utils` breaks,
+  defeating the optional-extras model.
+- **Drop the flat re-exports; require explicit submodule imports** (`from nui_shared_utils.slack_client
+  import SlackClient`). Achieves laziness but breaks the established `nui.X` API and star imports for
+  every caller. PEP 562 delivers the same laziness while keeping the flat surface.
+- **`try/except ImportError` guards at module top.** A common optional-dependency idiom, but it still
+  imports every *installed* dependency eagerly, so an environment with the `all` extra pays the full
+  import cost on startup. It solves availability, not cold start.
+- **Split each integration into its own distribution.** Per-integration install granularity already
+  comes from extras; N packages multiply versioning and release overhead without improving import
+  cost beyond what lazy loading already gives.
+
+## Consequences
+
+- `import nui_shared_utils` is cheap (~10ms); heavy deps load on first use of the export that needs
+  them. Cold-start and CLI-startup cost scale with what a caller uses, not with what the package
+  ships.
+- The flat public API and star imports are unchanged, so no consumer edit is required to gain the
+  saving. The legacy import shim (`nui_lambda_shared_utils`) forwards through the same PEP 562 path,
+  so callers on the old name benefit too.
+- New integrations must follow the pattern: add the export to `_LAZY_EXPORTS`, add the submodule to
+  `_OPTIONAL_SUBMODULES` if its dep is an optional extra, mirror it in the `TYPE_CHECKING` block for
+  IDE/type-checker visibility, and add a laziness assertion to `tests/test_lazy_imports.py`. A missing
+  `_LAZY_EXPORTS` entry breaks runtime access; a missing `TYPE_CHECKING` entry only costs static
+  completion.
+- Two lists (`_LAZY_EXPORTS` and the `TYPE_CHECKING` imports) describe the same surface and must stay
+  in sync by hand. `__all__` and `__dir__` derive from `_LAZY_EXPORTS`, so the runtime export set stays
+  self-consistent (`test_dir_includes_lazy_exports` guards a sample of it); nothing cross-checks the
+  `TYPE_CHECKING` block against `_LAZY_EXPORTS`, so a gap there costs only static completion, as above.
+- Import errors surface on first use rather than at package import. For optional integrations that is
+  intentional (`None` sentinel); for a genuinely missing required dependency the failure moves from
+  import time to first access, which the lazy tests and normal exercise cover.
+
+## Load-bearing premises (supersede triggers)
+
+- Package-import latency and Lambda bundle/cold-start cost remain a real, recurring cost paid per new
+  integration. If all consumers moved to always-on, long-running services where cold start is
+  irrelevant, the eager-import simplicity could be reconsidered.
+- The optional-extras model stays: a given integration's heavy dependency is installed only when its
+  extra is requested. If every dependency became a hard requirement of the package, eager import would
+  no longer risk breaking on a missing dep (though the startup-cost argument would still stand on its
+  own).
+- PEP 562 module-level `__getattr__` stays available on the supported interpreters. If the package
+  had to run where it is unavailable, the mechanism would need replacing (explicit submodule imports)
+  and this decision would reopen.

nui_python_shared_utils-2.0/docs/decisions/ADR-004-credential-resolution-precedence.md

@@ -0,0 +1,98 @@
+# ADR-004: Credential resolution precedence
+
+**Status**: Proposed
+**Date**: 2026-07-13
+
+## Context
+
+This package ships service clients (Slack, Elasticsearch, database, Snowflake) that run in two
+very different places. The primary runtime is short-lived functions with an IAM role and no
+secrets in the environment, where a named secret in a managed secret store (AWS Secrets Manager)
+is the idiomatic credential source: rotatable, IAM-scoped, absent from the process listing. The
+secondary runtime is local development, CLI tools, and the unit-test suite, where AWS may be
+unreachable, no role is attached, and the caller already holds the credentials or has them in the
+environment.
+
+A client that reaches for Secrets Manager unconditionally imposes that store on both runtimes. It
+forces every construction to have AWS reachable plus IAM permission plus a network round-trip,
+even when the caller passed the credentials in directly, and it couples what should be a pure
+object construction to AWS mocking in tests. Callers legitimately supply credentials three ways:
+an explicit dict at construction, per-client environment variables, or (the default) a named
+secret. The store cannot be the only path without breaking local dev, CLI, and test isolation.
+
+The function-based helper historically undercut this. `get_elasticsearch_credentials`
+(`secrets_helper.py`) called Secrets Manager first even when `ES_PASSWORD` was set, so CLI and
+local-dev paths paid an avoidable AWS call. Commit `0d3f8e8` (PR #23) added the env-var check
+ahead of the store lookup, aligning the helper with the precedence the clients already enforced.
+
+## Decision
+
+Credentials resolve in a fixed order, first match wins, owned by `BaseClient._resolve_credentials`
+in `base_client.py`:
+
+1. **Explicit `credentials` dict** passed to the constructor. Returned as-is; nothing else is
+   consulted. The caller owns these values and the package does not merge or second-guess them.
+2. **Per-client environment variables**, via each client's `_resolve_credentials_from_env` override
+   (Elasticsearch reads `ES_PASSWORD`/`ES_PASS` in `es_client.py`; database requires
+   `DB_HOST` + `DB_PASSWORD` in `db_client.py`; Slack requires `SLACK_BOT_TOKEN` in
+   `slack_client.py`). When the required vars are present, the resolved dict is returned without
+   touching AWS.
+3. **AWS Secrets Manager** as the default fallback, via `_fetch_credentials_from_sm` and
+   `get_secret`, reading the named secret resolved from constructor arg, env var, or config.
+
+A later tier fires only when every earlier tier is absent. An AWS call happens only when neither
+an explicit dict nor env vars resolve, so local-dev, CLI, and test paths that supply explicit or
+environment credentials make **zero** Secrets Manager calls. The direct function helper mirrors
+the tail of this ladder for callers that bypass the client classes:
+`get_elasticsearch_credentials` checks env vars, then the store.
+
+## Alternatives considered
+
+- **Always call Secrets Manager (first, or unconditionally).** Simplest single code path, and the
+  right default for the Lambda runtime taken alone. Rejected: it forces AWS reachability, IAM
+  permission, and a network round-trip onto every construction in every runtime, including local
+  dev, CLI, and unit tests that have no reason to touch AWS. Explicit and env credentials degrade
+  to dead options or a bolted-on override, and the test suite has to mock AWS to build an object.
+  This is the live rejected option: precedence exists specifically so the store is a fallback, not
+  a precondition.
+- **Environment variables only (strict 12-factor).** Clean for containers, but the primary runtime's
+  idiomatic store is Secrets Manager (rotation, IAM scoping, secrets kept out of the env). Dropping
+  the store would push plaintext secrets into every function's environment.
+- **Explicit injection everywhere (no env, no store).** Maximally testable, but forces every
+  entrypoint to hand-write secret retrieval, defeating the point of a shared client that just works
+  under an attached role.
+- **Per-client ad-hoc ordering.** Each client invents its own precedence. Rejected: callers cannot
+  reason uniformly about where credentials come from, and the orders drift. One ladder lives in the
+  base class; clients override only the env-detection and default-secret hooks.
+
+## Consequences
+
+- One predictable resolution order across every client. A new client implements
+  `_resolve_credentials_from_env` and `_get_default_secret_name` and inherits the full ladder.
+- Unit tests construct clients from an explicit dict with no AWS mock needed to do so; the explicit-
+  and env-credential tests assert the store is not called (`get_secret_value.assert_not_called()` in
+  `tests/test_secrets_helper.py`). Fallback-path tests still patch `get_secret` where they exercise the
+  store tier.
+- Local dev and CLI run against real services using environment variables with no AWS credentials
+  present.
+- Secrets Manager stays the zero-config default in the Lambda runtime: moving from local env creds
+  to the store needs no code change, only unsetting the env vars.
+- Explicit-over-remote is a deliberate trust choice. A caller passing a `credentials` dict is
+  trusted to own those values in-process; the package neither validates them against the store nor
+  falls back when they are wrong.
+
+## Load-bearing premises (supersede triggers)
+
+- Explicit dict and environment variables stay first-class, supported paths for local dev, CLI, and
+  tests. If every runtime became Secrets-Manager-only (no consumer ever supplies explicit or env
+  credentials), tiers 1 and 2 are dead weight and the precedence collapses to "always store".
+- The caller owns any credentials it passes explicitly or sets in the environment. The
+  explicit/env-beats-remote posture holds only while supplying credentials is an intentional act by
+  a trusted in-process caller, not attacker-controlled input. If untrusted input could populate the
+  `credentials` dict or the environment, the ordering needs re-evaluation.
+- Secrets Manager remains the right default store for the primary runtime. A move to a different
+  managed store changes tier 3's implementation but not the ladder's shape.
+- Env-var **presence** is the trigger, not correctness. A required var being set means "use env"
+  (`ES_PASSWORD`; `DB_HOST` + `DB_PASSWORD`; `SLACK_BOT_TOKEN`); a set-but-wrong value fails loudly
+  rather than silently falling through to the store. If callers expected fallback-on-bad-env, the
+  trigger semantics reopen.

nui_python_shared_utils-2.0/docs/decisions/ADR-005-explicit-secrets-manager-region.md

@@ -0,0 +1,88 @@
+# ADR-005: Explicit Secrets Manager region resolution
+
+**Status**: Proposed
+**Date**: 2026-07-13
+
+## Context
+
+`get_secret` in `secrets_helper.py` is the single door through which every consumer of this package
+reaches AWS Secrets Manager. It is a shared credential entry point for a fleet of Lambda functions
+and CLI tools that run across multiple AWS accounts and multiple regions.
+
+A boto3 Secrets Manager client cannot be built without a region, and where that region comes from
+decides whether a lookup hits the right account's secret store. The region is available in different
+places depending on the runtime: a Lambda execution environment exports `AWS_REGION`; a CLI or a
+differently-wired process gets it from the boto3 session (a configured profile / config file) or
+`AWS_DEFAULT_REGION`; and in some runtimes it is simply absent.
+
+Getting the region wrong is **not** a loud failure by default. A client built against the wrong
+region reads a different account/region's secret namespace and typically returns
+`ResourceNotFoundException`, which reads to the caller as "this secret does not exist" rather than
+"you are pointed at the wrong region." A region *default* baked into the helper is the worst version
+of this: it masks a missing config as one specific (usually wrong) region, and does so silently for
+every consumer that never set a region. Commit `342b24b` (PR #26) is the point of record for
+removing such a default from this helper.
+
+## Decision
+
+`get_secret` derives its region from an **explicit resolution chain, first match wins**, and never
+supplies a region of its own:
+
+1. **boto3 session region**, from `boto3.session.Session().region_name` (a configured profile or
+   `AWS_DEFAULT_REGION`, which the Lambda runtime also sets). boto3 does not natively resolve
+   `AWS_REGION`, so step 2 adds it explicitly for runtimes that set only that variable.
+2. **`AWS_REGION`** environment variable.
+3. **`AWS_DEFAULT_REGION`** environment variable.
+
+When none of these resolve, the call **fails loudly before any client is constructed**, raising with
+an explicit message that names the fix
+(`"AWS region not configured for Secrets Manager lookup; set AWS_REGION or AWS_DEFAULT_REGION"`). No
+client is ever built against a guessed region.
+
+The helper carries **no hardcoded region**. A missing region is a configuration error surfaced to
+the caller, not a value the package invents. This behaviour is pinned by two tests in
+`tests/test_secrets_helper.py`: `test_get_secret_uses_aws_region_when_session_region_missing`
+(the env-var fallback path builds the client with the configured region) and
+`test_get_secret_requires_region_when_session_and_env_missing` (no session region and empty env
+raises the clear error and asserts no client is created).
+
+## Alternatives considered
+
+- **A hidden hardcoded region default** (e.g. silently defaulting to `ap-southeast-2` inside the
+  helper). This is the cheapest thing to reach for whenever a new AWS call needs a region, so it
+  stays a live temptation. Rejected: it binds a store-neutral, geography-neutral package to one
+  region, and any consumer running elsewhere silently reads the wrong region's secret namespace and
+  gets a `ResourceNotFoundException` that reads as "secret missing," not "wrong region." Removed in
+  commit `342b24b` (PR #26).
+- **Best-effort silent fallthrough**: skip the region entirely and let boto3 pick whatever it can,
+  or return empty on a miss. Rejected: fail-loud on missing config beats silent best-effort. A
+  lookup that cannot name its own region should stop with a clear error, not guess and read from an
+  unknown place.
+- **Require region as an explicit function argument.** Rejected: consumers already carry region in
+  the standard boto3/session and environment locations, and Lambda sets `AWS_REGION` for free.
+  Threading a region parameter through every call site duplicates what the session/env already
+  answer.
+
+## Consequences
+
+- A consumer in **any** AWS account/region works as long as region is configured the standard way
+  (Lambda ambient, boto3 profile, or `AWS_REGION` / `AWS_DEFAULT_REGION`). The package assumes no
+  home region.
+- Misconfiguration **fails fast with a message that names the fix**, instead of a downstream
+  `ResourceNotFoundException` that misattributes the cause to a missing secret and costs an operator
+  a debugging session.
+- Every future AWS client added to this package inherits the same rule: **no hidden region default;
+  resolve explicitly or fail loud.** This is ADR-002's keep-generic principle applied to region: a
+  hidden geo default is exactly the vendor/geography assumption the package forbids (see ADR-002, and
+  the "Keeping the Package Generic" design principle in `AGENTS.md`).
+
+## Load-bearing premises (supersede triggers)
+
+- The package must run in **arbitrary AWS accounts/regions with no assumed home region**. If it were
+  ever deliberately scoped to a single fixed region (a single-account, single-region product), a
+  region default could be reconsidered.
+- **Fail-loud on missing config is preferred over silent best-effort.** If that preference inverted
+  under some "degrade quietly" runtime contract, the explicit raise would reopen.
+- **Region is reachable from the boto3 session or the environment at call time.** If a supported
+  runtime cannot expose region through either path, an explicit-argument region parameter would
+  reopen.

nui_python_shared_utils-2.0/docs/decisions/ADR-006-snowflake-sql-api-client.md

@@ -0,0 +1,105 @@
+# ADR-006: Snowflake access via the pure-Python SQL API client
+
+**Status**: Proposed
+**Date**: 2026-07-13
+
+## Context
+
+This package is a shared utility layer for AWS Lambda functions, CLIs, and async API
+services. Bundle size and pure-Python portability are first-order constraints: every
+integration ships as an optional extra so a consumer pulls only the dependency it uses,
+and the package avoids native/C-extension builds so one wheel runs unchanged across
+Lambda runtimes, layers, and local tooling with no compile step.
+
+Snowflake access comes in two dependency shapes. The official
+`snowflake-connector-python` is a large connector with native (C-extension) components:
+Arrow result decoding, pyarrow/cython wheels, a binary footprint that dominates a Lambda
+bundle and pins the build to a specific platform/Python ABI. The Snowflake **SQL REST
+API** needs none of that. It is authenticated HTTP (keypair-minted JWT bearer tokens,
+positional `?` bindings, JSON result sets), fully expressible in pure Python.
+
+The consumers here (analytics reads and simple SQL execution from Lambdas and a FastAPI
+service) need the query surface the SQL API already covers, not the connector's native
+result-streaming or stateful-session features.
+
+## Decision
+
+Snowflake access is provided by wrapping the pure-Python `snowflake-sql-api` package
+(the Snowflake SQL REST API) with a thin NUI adapter, exposed through the optional
+`snowflake` extra (`snowflake-sql-api>=0.1.1,<0.2.0`). The generic package stays
+vendor-neutral; all NUI opinion lives in the adapter
+(`nui_shared_utils/snowflake_client.py`):
+
+- **Sync and async client factories.** `create_snowflake_client` (the default) and
+  `create_async_snowflake_client` (for a Lambda or FastAPI app already on an event loop)
+  return ready `SnowflakeClient` / `AsyncSnowflakeClient` instances. Both run through one
+  shared keyword-assembly path, so sync and async stay at feature parity.
+- **Keypair authentication.** Credentials (account, user, PEM private key, optional
+  passphrase) resolve per field with strict `explicit-arg > SNOWFLAKE_* env > AWS Secrets
+  Manager` precedence; the underlying SQL API client mints short-lived JWT bearer tokens
+  from the keypair. Secrets Manager is contacted only for fields still unresolved after
+  the explicit/env tiers. This per-field resolution is a deliberate divergence from
+  ADR-004's whole-dict ladder (where an explicit `credentials` dict is used as-is and nothing
+  else is consulted): a keypair's fields legitimately come from different sources (account and
+  user from env, private key from Secrets Manager), so each resolves independently. A field left
+  unset at every tier surfaces as a missing-credential error at client construction, not a silent
+  partial.
+- **Redacted query logging.** A default `redacting_query_logger` hook records the
+  (truncated) statement text and the *count* of bind parameters, never the bind values,
+  JWTs, key material, or secret names. Callers can pass a custom `on_query` hook (for
+  metrics, for example) or disable logging.
+- **Overridable session defaults.** `TIMEZONE='Pacific/Auckland'` and role `NUI_LAMBDA`
+  apply unless overridden. These are baked geography/org defaults, the class ADR-002 (and the
+  `AGENTS.md` DON'T list) caution against, and are kept here as a deliberate, bounded exception:
+  both are documented and overridable per call, so a consumer in another region or account
+  supplies its own at the factory call rather than inheriting a value that silently encodes
+  one geography.
+
+Import is guarded: using a factory without the extra raises a clear `ImportError` rather
+than failing at package import. Introduced in commit `d0af0b6` (PR #25).
+
+## Alternatives considered
+
+- **Bundle `snowflake-connector-python`.** The official, fullest-featured client: native
+  Arrow result streaming, richer session/cursor semantics, `%s` and named bindings.
+  Rejected as the dependency here because its native wheels and binary footprint fight
+  both package constraints at once, bundle size (it dominates a Lambda artifact) and
+  pure-Python portability (the C-extension build pins platform/ABI and needs a compile
+  step). Its extra surface is not what these consumers need.
+- **Vendor the SQL API calls directly** (hand-rolled HTTP client plus JWT minting inside
+  this package). Rejected: the generic `snowflake-sql-api` package already owns that
+  surface plus an offline test transport (`FakeSnowflake`); duplicating it here couples
+  the shared utils to Snowflake's REST contract for no gain.
+- **Ship no Snowflake helper and let each consumer wire its own.** Rejected: credential
+  resolution, redaction, and session defaults are exactly the cross-consumer patterns a
+  shared layer exists to standardize; re-implementing them per service re-introduces
+  drift and redaction gaps.
+
+## Consequences
+
+- The Snowflake path stays pure-Python and small: the `snowflake` extra adds an HTTP
+  client, not a native connector, so it fits Lambda bundles and runs unchanged across
+  runtimes.
+- The adapter's reach is bounded by the SQL REST API surface. A concrete limit already
+  lives with this: the SQL API accepts only an allow-list of session parameters per
+  request and rejects `WEEK_START` with HTTP 400, and being stateless per statement it
+  offers no `ALTER SESSION` escape hatch, so Monday-first weeks must be set on the
+  Snowflake user/role default instead. Capabilities outside the REST surface (native
+  result streaming, stateful session mutation) are unavailable by construction.
+- One credential/redaction/session-default contract across sync and async consumers;
+  bind values and key material stay out of logs by default.
+
+## Load-bearing premises (supersede triggers)
+
+- **The SQL REST API covers the query surface these consumers need.** If a required
+  capability were SQL-API-unavailable (native result streaming, a stateful session
+  feature the REST contract cannot express), the native connector reopens as the
+  dependency for that need.
+- **Pure-Python / small-bundle portability outweighs the native connector's extra
+  features.** If this package stopped targeting size-constrained, compile-free runtimes,
+  the bundle-size/portability tradeoff that rejects `snowflake-connector-python` no
+  longer holds and that choice returns to the table.
+- **The generic `snowflake-sql-api` package remains the SQL API surface.** The adapter is
+  a thin layer over it; if that package stopped tracking the REST contract or dropped its
+  offline test transport, vendoring the calls (or adopting another SQL-API client)
+  returns as an option.

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/docs/decisions/README.md

@@ -24,3 +24,8 @@ Keep each ADR under two pages. Longer than that means it is a plan, not an ADR.
 | # | Decision | Status | Date |
 |---|----------|--------|------|
 | [001](ADR-001-structured-logging-field-vocabulary.md) | Structured logging field vocabulary (dotted registry + helpers + consistency test) | Proposed | 2026-07-11 |
+| [002](ADR-002-keep-shared-utilities-generic.md) | Keep shared utilities generic: configurable infrastructure, business queries/names/currencies to the consumer | Proposed | 2026-07-13 |
+| [003](ADR-003-lazy-load-integrations.md) | Lazy-load integrations via PEP 562 so package import stays cheap; heavy deps load on first use | Proposed | 2026-07-13 |
+| [004](ADR-004-credential-resolution-precedence.md) | Credential resolution precedence: explicit dict, then env vars, then Secrets Manager | Proposed | 2026-07-13 |
+| [005](ADR-005-explicit-secrets-manager-region.md) | Resolve the Secrets Manager region explicitly (session, then env); no hidden default, fail loud | Proposed | 2026-07-13 |
+| [006](ADR-006-snowflake-sql-api-client.md) | Snowflake access via the pure-Python SQL API client, not the native connector | Proposed | 2026-07-13 |

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.0}/docs/getting-started/installation.md

@@ -183,7 +183,7 @@ zip -r nui-utils-layer.zip python/
 
 # Upload to AWS Lambda Layers (via AWS CLI)
 aws lambda publish-layer-version \
-  --layer-name nui-lambda-shared-utils \
+  --layer-name nui-python-shared-utils \
   --description "NUI Lambda Shared Utilities" \
   --zip-file fileb://nui-utils-layer.zip \
   --compatible-runtimes python3.9 python3.10 python3.11