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

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

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main, master, develop ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test Python ${{ matrix.python-version }}
@@ -74,6 +77,42 @@ jobs:
         name: codecov-umbrella
         fail_ci_if_error: false
 
+  es-compat:
+    name: Elasticsearch client ${{ matrix.elasticsearch-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every major the [elasticsearch] extra allows. The ES tests drive the
+        # real client with a stubbed transport, so a call shape that a major
+        # stops accepting fails here. 8.x is pinned at three points because the
+        # client handles `body=` differently across the major: 8.0-8.11 route it
+        # through the parameter-rewriting fallback, 8.12+ take it as a declared
+        # parameter, and a bare `8.*` only ever resolves to the latter.
+        elasticsearch-version: ['7.17.*', '8.0.*', '8.11.*', '8.*', '9.*']
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-mock
+        pip install -e .
+        pip install "elasticsearch==${{ matrix.elasticsearch-version }}"
+        python -c "import elasticsearch; print('elasticsearch', elasticsearch.__version__)"
+
+    - name: Test Elasticsearch client
+      run: |
+        pytest tests/test_es_client.py tests/test_es_client_compat.py tests/test_es_query_builder.py -v
+
   build:
     name: Build Package
     runs-on: ubuntu-latest
@@ -109,5 +148,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.1}/.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.1}/AGENTS.md

@@ -40,7 +40,7 @@ This is `nui-python-shared-utils`, a Python package providing production-ready u
 - **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
+- **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities (stdlib `zoneinfo`)
 
 ### Optional Dependencies
 
@@ -52,6 +52,7 @@ The package uses optional extras to minimize Lambda bundle size:
 - `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)
+- `timezone` - `tzdata`, for minimal images with no system IANA database (Alpine, distroless)
 - `all` - All integrations
 - `dev` - Development and testing tools
 

{nui_python_shared_utils-1.6.0 → nui_python_shared_utils-2.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.6.0
+Version: 2.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
@@ -49,11 +49,11 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: boto3>=1.20.0
-Requires-Dist: pytz>=2021.3
 Requires-Dist: click>=8.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: tzdata>=2023.3; platform_system == "Windows"
 Provides-Extra: elasticsearch
-Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "elasticsearch"
+Requires-Dist: elasticsearch<10.0.0,>=7.17.0; extra == "elasticsearch"
 Provides-Extra: database
 Requires-Dist: pymysql>=1.0.0; extra == "database"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
@@ -64,12 +64,14 @@ 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: timezone
+Requires-Dist: tzdata>=2023.3; extra == "timezone"
 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: elasticsearch<10.0.0,>=7.17.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: slack-sdk>=3.19.0; extra == "all"
@@ -85,11 +87,11 @@ Requires-Dist: black>=22.0.0; extra == "dev"
 Requires-Dist: mypy>=0.990; extra == "dev"
 Requires-Dist: boto3-stubs[essential]>=1.20.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
-Requires-Dist: types-pytz>=2021.3.0; extra == "dev"
 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: tzdata>=2023.3; 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
@@ -526,7 +528,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.1}/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.1}/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.1/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.1/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.1/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.1/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.