loom-kernel 0.9.0__tar.gz → 0.9.2__tar.gz

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/.github/workflows/docs.yml

@@ -19,10 +19,11 @@ on:
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
-# Prevent concurrent deploys; let an in-progress run finish.
+# PRs use a per-PR group so they never block or wait on the Pages deploy lock.
+# Push/dispatch use the shared 'pages' group to serialise concurrent deploys.
 concurrency:
-  group: pages
-  cancel-in-progress: false
+  group: ${{ github.event_name == 'pull_request' && format('docs-pr-{0}', github.event.pull_request.number) || 'pages' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   build:

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/CHANGELOG.md

@@ -1,98 +1,69 @@
-# 🚀 Release 0.9.0 ([#32](https://github.com/the-reacher-data/loom-py/pull/32)) ([`14072d1`](https://github.com/the-reacher-data/loom-py/commit/14072d1be9212116235f26d7a2590a4f0e622451))
+# 🚀 Release 0.9.2 ([#39](https://github.com/the-reacher-data/loom-py/pull/39)) ([`f1a482d`](https://github.com/the-reacher-data/loom-py/commit/f1a482d03f8b83f8e0c7725e7af6160466ac6126))
 
 
 ## ✨ Features
-### streaming
-- **streaming:** add Mongo CDC source
-- **streaming:** add MongoObjectId and MongoDBRef domain types<br>
-  > Replace opaque str/dict BSON normalization with structured domain types:
-  > MongoObjectId(id, created_at_ms) preserves ObjectId hex and creation
-  > timestamp extracted from the embedded 4-byte BSON timestamp field
-  > MongoDBRef(id, collection, database) models cross-collection references
-  > with explicit collection and optional database fields
-  > MongoCDCEvent.document_id widened to MongoObjectId | str | None to
-  > expose rich type when _id is an ObjectId
-  > _normalize_objectid and _normalize_dbref updated to produce the new types
-  > Guard clause added to _normalize_dbref for None identifier
-  > _message_key helper centralizes MongoObjectId → str key extraction
-  > MongoObjectId and MongoDBRef exported from loom.streaming public API
-  > Contract tests cover DBRef without database, integer id, None id error,
-  > and ObjectId without generation_time (created_at_ms=None)
-
-- **streaming:** add Backend.CLICKHOUSE with native clickhouse-connect sink<br>
-  > Add _ClickHouseTablePartition as a standalone SinkPartition backed by
-  > clickhouse-connect (HTTP/2, no SQLAlchemy). Uses a column-oriented buffer
-  > layout matching clickhouse-connect's column_oriented=True path, avoiding
-  > the internal pivot() transposition for maximum insert throughput.
-  > Resolves the _json_serializer crash that occurred when inserting list[str]
-  > fields via the SQLAlchemy backend against ClickHouseDialect_asynch. With the
-  > native client, Array(String) and all CH-native types work without workarounds.
-
-- **streaming:** add ExpandRoutes fan-out node and JsonStr semantic type<br>
-  > ExpandRoutes: expands one event once via PayloadExpander and routes each
-  > typed output list to its own independent Process (dict-based API, optional
-  > default route); wired in Bytewax via flat_map per route branch
-  > JsonStr: Annotated[str, _JsonMarker()] sentinel type for raw JSON fields;
-  > mapped to Text() in SQLAlchemy; passes through as str in ClickHouse/Delta
-  > ProcessNode union extended to include ExpandRoutes[Any]
+### config
+- **config:** add SecretsManagerResolver + shared resolver utilities
 
 
 
-## 🐛 Fixes
-### streaming
-- **streaming:** replace assert with explicit TypeError in _adapter.py<br>
-  > Bandit B101: assert statements are stripped when running with -O.
-  > Replaced both isinstance asserts with explicit TypeError raises to
-  > preserve the runtime invariant checks under all execution modes.
 
-- **streaming:** age-based buffer flush never fired in IntoTable sink partitions<br>
-  > Two bugs prevented buffer_max_age_s from triggering a flush:
-  > 1. write_batch([]) returned immediately on empty epochs, so quiet periods
-  > never checked the age threshold.
-  > 2. _last_append_at was updated right before _should_flush(), making the
-  > elapsed-time expression always ≈0ms.
-  > Replace _last_append_at with _buffer_started_at (set when the buffer
-  > transitions from empty, reset after each flush) in both
-  > _SQLAlchemyTablePartition and _DeltaTablePartition. Empty epoch calls
-  > now check for an age-based flush before returning.
 
-- **streaming:** wire ExpandRoutes runtime and ClickHouse HTTP URL resolution
 
-### compiler
-- **compiler:** add Backend.CLICKHOUSE dispatch in build_plan storage sink resolver
-- **compiler:** validate ExpandRoutes branches for terminal output detection
 
 
 
 
-## ♻️ Refactor
+
+# 🚀 Release 0.9.1 ([#36](https://github.com/the-reacher-data/loom-py/pull/36)) ([`5c420c9`](https://github.com/the-reacher-data/loom-py/commit/5c420c9dd4efe0f697affb8a921054bc6504358f))
+
+
+## ✨ Features
 ### streaming
-- **streaming:** improve Mongo CDC architecture compliance<br>
-  > Replace bare except Exception with specific OperationFailure catch
-  > Replace type(x).__name__ string dispatch with isinstance and lazy import
-  > Type watch_options as Mapping[str, object] to eliminate implicit Any
-  > Introduce _BSON_NORMALIZERS dispatch map in normalize_bson_value
-  > Define _ChangeStream and _DatabaseLike Protocols for PyMongo types
-  > Make FromMongoCDC generic with covariant MongoCDCPayloadT (PEP 696)
-  > Add needs_decode: ClassVar[bool] to compiled source types
-  > Replace isinstance type-switches with dispatch maps (_SOURCE_BUILDERS,
-  > _RUNTIME_SOURCE_BUILDERS) across compiler and bytewax runtime layers
-  > Declare typing_extensions>=4.12 as direct dependency
-  > Add contract tests for FromMongoCDC generic parametrization
-
-- **streaming:** simplify source dispatch and pymongo error handling<br>
-  > Replace _RUNTIME_SOURCE_BUILDERS dispatch map with direct isinstance check in build_runtime_source
-  > Replace lazy _operation_failure_type() with module-level try/except import for OperationFailure
-  > Use explicit isinstance in _source_topic_or_none instead of getattr duck-typing
-  > Remove redundant empty-collections branch in _open_change_stream
-  > Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+- **streaming:** add register_sink to StreamingRunner<br>
+  > Allows applications to declare sinks once via register_sink(cls) and
+  > let the runner resolve them from YAML config at startup, eliminating
+  > manual sink wiring in entrypoints.
+  > New public API:
+  > runner = StreamingRunner()
+  > runner.register_sink(ClickHouseErrorTableSink)
+  > runner.run(flow=build_flow(), config_path=streaming_config_path())
+  > Sink classes satisfy the RegisteredSink protocol (sink_type, config_type,
+  > build_binding). The runner matches YAML entries by type field, deserializes
+  > each section with config_type, and calls build_binding(cfg, ctx).
+  > Adds DuplicateErrorSinkError for conflicting ErrorKind assignments.
+  > Adds STREAMING_SINKS to ConfigKey.
+  > StreamingRunner.__init__ is now no-arg; factory methods unchanged.
+  > prepare_run(error_sinks=...) remains supported for tests and overrides.
 
 
+### config
+- **config:** add SSM dot-notation key navigation and resolve logging<br>
+  > _split_ssm_key splits /path/param.key into SSM path + JSON key list
+  > _navigate_json parses SSM value as JSON and traverses key path
+  > resolve() emits INFO log with expanded SSM path (never the value)
+  > ConfigResolver.resolve() widened to -> object (str <= object, LSP-safe)
+  > Guard against empty key with explicit ConfigError
 
 
-## ✅ Tests
-### streaming
-- **streaming:** add unit tests for ExpandRoutes fan-out node
+
+## 🐛 Fixes
+### tests
+- **tests:** guard received[0] index access in test_sink_registry
+
+
+
+
+
+
+
+## 🛠 Chores
+### release
+- **release:** sync pyproject.toml version to 0.9.0<br>
+  > The v0.9.0 tag was created by a hotfix but the version bump PR did not
+  > merge cleanly, leaving pyproject.toml stuck at 0.8.0 on master. This
+  > aligns the declared version with the existing tag so the next release
+  > computes 0.10.0 instead of colliding with v0.9.0.
 
 
 

loom_kernel-0.9.2/CHANGELOG_RELEASE.md

@@ -0,0 +1,15 @@
+# 🚀 Release 0.9.2 ([#39](https://github.com/the-reacher-data/loom-py/pull/39)) ([`f1a482d`](https://github.com/the-reacher-data/loom-py/commit/f1a482d03f8b83f8e0c7725e7af6160466ac6126))
+
+
+## ✨ Features
+### config
+- **config:** add SecretsManagerResolver + shared resolver utilities
+
+
+
+
+
+
+
+
+

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.9.0
+Version: 0.9.2
 Summary: Loom Python project
 License-File: LICENSE
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: aiocache<1.0,>=0.12
 Requires-Dist: msgspec<1.0,>=0.18
@@ -22,6 +23,10 @@ Requires-Dist: clickhouse-connect<1.0,>=0.7; extra == 'clickhouse'
 Provides-Extra: config
 Requires-Dist: fsspec>=2024.2.0; extra == 'config'
 Requires-Dist: omegaconf<3.0,>=2.3; extra == 'config'
+Provides-Extra: config-ssm
+Requires-Dist: boto3>=1.35; extra == 'config-ssm'
+Requires-Dist: fsspec>=2024.2.0; extra == 'config-ssm'
+Requires-Dist: omegaconf<3.0,>=2.3; extra == 'config-ssm'
 Provides-Extra: etl-otel
 Requires-Dist: opentelemetry-api<2.0,>=1.20; extra == 'etl-otel'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.20; extra == 'etl-otel'

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/pyproject.toml

@@ -1,9 +1,12 @@
 [project]
 name = "loom-kernel"
-version = "0.9.0"
+version = "0.9.2"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
+classifiers = [
+    "Typing :: Typed",
+]
 dependencies = [
     "msgspec>=0.18,<1.0",
     "structlog>=24.4,<26.0",
@@ -32,6 +35,11 @@ config = [
     "omegaconf>=2.3,<3.0",
     "fsspec>=2024.2.0",
 ]
+config-ssm = [
+    "omegaconf>=2.3,<3.0",
+    "fsspec>=2024.2.0",
+    "boto3>=1.35",
+]
 cache = [
     "aiocache>=0.12,<1.0",
     "omegaconf>=2.3,<3.0",
@@ -129,6 +137,7 @@ dev = [
     "findspark>=2.0.1",
     "confluent-kafka>=2.6,<3.0",
     "bytewax>=0.21",
+    "boto3>=1.35",
     "pymongo>=4.6,<5.0",
     "opentelemetry-api>=1.20,<2.0",
     "opentelemetry-sdk>=1.20,<2.0",
@@ -140,6 +149,9 @@ dev = [
 packages = [
     "src/loom",
 ]
+include = [
+    "src/loom/py.typed",
+]
 
 [tool.ruff]
 line-length = 100
@@ -235,7 +247,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.9.0"
+version = "0.9.2"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/src/loom/core/config/__init__.py

@@ -20,6 +20,8 @@ from loom.core.config.keys import ConfigKey
 from loom.core.config.loader import load_config, section
 from loom.core.config.observability import OtelConfig
 from loom.core.config.resolver import ConfigResolver
+from loom.core.config.secrets import SecretsManagerResolver
+from loom.core.config.ssm import SsmResolver
 
 __all__ = [
     "ConfigBinding",
@@ -29,6 +31,8 @@ __all__ = [
     "ConfigResolver",
     "Configurable",
     "OtelConfig",
+    "SecretsManagerResolver",
+    "SsmResolver",
     "StructBinder",
     "load_config",
     "section",

loom_kernel-0.9.2/src/loom/core/config/_resolver_utils.py

@@ -0,0 +1,116 @@
+"""Shared utilities for config resolvers (SSM, Secrets Manager, etc.)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+from loom.core.config.errors import ConfigError
+
+_ENV_VAR_PATTERN = re.compile(r"%([A-Z][A-Z0-9_]*)%")
+
+
+def _expand_env_vars(key: str) -> str:
+    """Expand ``%VAR_NAME%`` placeholders in *key* using environment variables.
+
+    Only uppercase identifiers matching ``[A-Z][A-Z0-9_]*`` are expanded.
+    The ``%VAR%`` syntax avoids conflicts with OmegaConf's ANTLR grammar,
+    which rejects bare ``{`` inside ``${resolver:...}`` interpolations.
+
+    Args:
+        key: Resolver path, possibly containing ``%VAR_NAME%`` tokens.
+
+    Returns:
+        Path with all tokens replaced by their environment variable values.
+
+    Raises:
+        ConfigError: When a referenced variable is absent from the environment.
+    """
+    if not _ENV_VAR_PATTERN.search(key):
+        return key
+
+    def _replace(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        value = os.environ.get(var_name)
+        if value is None:
+            raise ConfigError(
+                f"Env var {var_name!r} not found in environment "
+                f"(referenced in resolver path {key!r})"
+            )
+        return value
+
+    return _ENV_VAR_PATTERN.sub(_replace, key)
+
+
+def _split_resolver_key(key: str) -> tuple[str, list[str]]:
+    """Split a resolver key into the base path and JSON navigation keys.
+
+    The first dot after the last '/' separator marks the start of a JSON key
+    path. Both SSM and Secrets Manager use '/' as path separator, so a dot
+    is unambiguously a JSON navigation token.
+
+    Note: ARN-style SecretIds (``arn:aws:secretsmanager:...``) are not
+    supported for dot-notation — use short names instead.
+
+    **Limitation — env-var values with dots in the final path segment:**
+    If a ``%VAR%`` token expands to a value that contains a dot *and* that
+    token appears in the last path segment (after the final ``/``), the dot
+    will be interpreted as a JSON navigation separator, producing a confusing
+    ``ConfigError``. Example: ``/app/svc/%ENV%`` where ``ENV=db.prod`` becomes
+    ``/app/svc/db`` with JSON key ``["prod"]``.  Use env-var tokens only in
+    path segments that are guaranteed to be dot-free (environment names,
+    region codes, etc.).
+
+    Args:
+        key: Expanded resolver key, e.g. ``"/app/prod/db_config.host"``.
+
+    Returns:
+        A 2-tuple ``(base_path, json_keys)`` where *base_path* is the path
+        to fetch and *json_keys* is a list of dict keys to navigate
+        (empty list when no dot-notation is present).
+    """
+    if not key:
+        return key, []
+    last_slash = key.rfind("/")
+    after_last_slash = key[last_slash + 1 :] if last_slash != -1 else key
+    dot_pos = after_last_slash.find(".")
+    if dot_pos == -1:
+        return key, []
+    base_end = (last_slash + 1 + dot_pos) if last_slash != -1 else dot_pos
+    json_tail = key[base_end + 1 :]
+    return key[:base_end], [k for k in json_tail.split(".") if k]
+
+
+def _navigate_json(raw: str, keys: list[str], path: str) -> object:
+    """Parse *raw* as JSON and navigate to the value at *keys*.
+
+    Args:
+        raw: Raw string value from the resolver backend.
+        keys: Ordered list of dict keys to traverse.
+        path: Original path, used only in error messages.
+
+    Returns:
+        The value at the navigated position. May be any JSON-compatible type.
+
+    Raises:
+        ConfigError: When *raw* is not valid JSON, or a key is absent.
+    """
+    try:
+        data: object = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        # Suppress chain (from None) — JSONDecodeError.doc holds the raw secret
+        # and would be exposed via __cause__ in tracebacks / APM serialisation.
+        raise ConfigError(
+            f"Resolver path {path!r} value is not valid JSON "
+            f"(required for key navigation): {exc.msg} at position {exc.pos}"
+        ) from None
+    current: object = data
+    for k in keys:
+        if not isinstance(current, dict) or k not in current:
+            raise ConfigError(f"Key {k!r} not found at resolver path {path!r}")
+        current = current[k]
+    return current
+
+
+__all__ = ["_expand_env_vars", "_split_resolver_key", "_navigate_json"]

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/src/loom/core/config/keys.py

@@ -24,6 +24,7 @@ class ConfigKey(StrEnum):
     STORAGE = "storage"
     STREAMING = "streaming"
     STREAMING_RUNTIME = "streaming.runtime"
+    STREAMING_SINKS = "streaming.sinks"
     OBSERVABILITY = "observability"
     LOGGER = "logger"
     METRICS = "metrics"

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/src/loom/core/config/loader.py

@@ -212,7 +212,7 @@ def _register_resolvers(resolvers: Sequence[Any], omega_conf: Any) -> None:
     """
     for resolver in resolvers:
         with contextlib.suppress(Exception):
-            omega_conf.register_new_resolver(resolver.name, resolver.resolve)
+            omega_conf.register_new_resolver(resolver.name, resolver.resolve, use_cache=True)
 
 
 def load_config(

{loom_kernel-0.9.0 → loom_kernel-0.9.2}/src/loom/core/config/resolver.py

@@ -18,6 +18,15 @@ YAML placeholders::
 The resolver name becomes the placeholder prefix.  Values are resolved
 when OmegaConf materialises the config — i.e. at job startup, so secret
 rotation takes effect on the next run without redeployment.
+
+Built-in resolvers
+------------------
+:class:`~loom.core.config.ssm.SsmResolver` is the bundled implementation
+for AWS SSM Parameter Store.  Install ``loom[config-ssm]`` to use it::
+
+    from loom.core.config import load_config, SsmResolver
+
+    cfg = load_config("config/prod.yaml", resolvers=[SsmResolver()])
 """
 
 from __future__ import annotations
@@ -32,22 +41,19 @@ class ConfigResolver(Protocol):
     Implementors provide a *name* (used as the OmegaConf placeholder prefix)
     and a *resolve* callable that fetches the actual value at parse time.
 
-    Example::
-
-        class SsmResolver:
-            name = "ssm"
+    See :class:`~loom.core.config.ssm.SsmResolver` for the bundled AWS SSM
+    implementation.  Custom resolvers only need to satisfy this two-member
+    protocol::
 
-            def __init__(self, region: str) -> None:
-                self._region = region
+        class VaultResolver:
+            @property
+            def name(self) -> str:
+                return "vault"
 
-            def resolve(self, key: str) -> str:
-                import boto3
-                client = boto3.client("ssm", region_name=self._region)
-                return client.get_parameter(Name=key, WithDecryption=True)[
-                    "Parameter"
-                ]["Value"]
+            def resolve(self, key: str) -> object:
+                return vault_client.read_secret(key)
 
-        cfg = load_config("s3://bucket/prod.yaml", resolvers=[SsmResolver("eu-west-1")])
+        cfg = load_config("config/prod.yaml", resolvers=[VaultResolver()])
     """
 
     @property
@@ -62,7 +68,7 @@ class ConfigResolver(Protocol):
         """
         ...
 
-    def resolve(self, key: str) -> str:
+    def resolve(self, key: str) -> object:
         """Resolve *key* to its string value.
 
         Called by OmegaConf when materialising ``${<name>:key}``
@@ -74,7 +80,8 @@ class ConfigResolver(Protocol):
                 (e.g. ``"/prod/token"`` for ``${ssm:/prod/token}``).
 
         Returns:
-            Resolved string value.
+            Resolved value. Typically a string, but may be a structured type
+            when the resolver supports JSON navigation.
         """
         ...
 

loom_kernel-0.9.2/src/loom/core/config/secrets.py

@@ -0,0 +1,144 @@
+"""AWS Secrets Manager resolver for loom configuration.
+
+Resolves ``${secrets:/path/to/secret}`` placeholders in OmegaConf configs
+by fetching values from AWS Secrets Manager at parse time.
+
+Example::
+
+    from loom.core.config import load_config
+    from loom.core.config.secrets import SecretsManagerResolver
+
+    cfg = load_config("config/prod.yaml", resolvers=[SecretsManagerResolver("eu-west-1")])
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+try:
+    import boto3 as _boto3_module  # type: ignore[import-untyped]
+except ImportError:
+    _boto3_module = None
+
+from loom.core.config._resolver_utils import (
+    _expand_env_vars,
+    _navigate_json,
+    _split_resolver_key,
+)
+from loom.core.config.errors import ConfigError
+
+logger = logging.getLogger(__name__)
+
+
+def _fetch_secret(client: Any, name: str) -> str:
+    """Fetch a string secret value from AWS Secrets Manager.
+
+    Args:
+        client: Boto3 secretsmanager client.
+        name: Secret name or short ARN. ARN-style names are supported for
+            plain fetches but not for dot-notation JSON navigation.
+
+    Returns:
+        The secret value as a string.
+
+    Raises:
+        ConfigError: When the secret is binary, or on any API error.
+    """
+    try:
+        result = client.get_secret_value(SecretId=name)
+    except Exception as exc:
+        raise ConfigError(f"Failed to fetch Secrets Manager secret {name!r}: {exc}") from exc
+    if "SecretString" not in result:
+        raise ConfigError(
+            f"Secrets Manager secret {name!r} is binary — only string secrets are supported"
+        )
+    return str(result["SecretString"])
+
+
+class SecretsManagerResolver:
+    """Resolves AWS Secrets Manager paths for use with :func:`~loom.core.config.load_config`.
+
+    Fetches secret values from AWS Secrets Manager. The boto3 client is
+    created lazily on first use and reused across calls.
+
+    Env-var tokens in the form ``%VAR_NAME%`` (uppercase letters, digits,
+    and underscores only) are expanded from ``os.environ`` before the
+    request is made.
+
+    Args:
+        region: AWS region name. Passed directly to ``boto3.client``.
+            Defaults to ``None``, which lets boto3 use its own resolution
+            chain (env vars, instance metadata, etc.).
+
+    Example::
+
+        resolver = SecretsManagerResolver("eu-west-1")
+        value = resolver.resolve("/myapp/%ENV%/db_password")
+    """
+
+    def __init__(self, region: str | None = None) -> None:
+        self._region = region
+        self._client: Any = None
+
+    @property
+    def name(self) -> str:
+        """OmegaConf resolver prefix.
+
+        Returns:
+            The string ``"secrets"``.
+        """
+        return "secrets"
+
+    def _get_client(self) -> Any:
+        """Return the boto3 secretsmanager client, creating it on first call.
+
+        Returns:
+            A boto3 secretsmanager client instance.
+
+        Raises:
+            ConfigError: When boto3 is not installed.
+        """
+        if self._client is None:
+            if _boto3_module is None:
+                raise ConfigError(
+                    "boto3 is required for SecretsManagerResolver. "
+                    "Install it with: pip install loom[config-ssm]"
+                )
+            self._client = _boto3_module.client("secretsmanager", region_name=self._region)
+        return self._client
+
+    def resolve(self, key: str) -> object:
+        """Resolve an AWS Secrets Manager path to its stored value.
+
+        Expands ``%VAR_NAME%`` tokens in *key* from the environment, then
+        fetches the secret from AWS Secrets Manager.
+
+        Args:
+            key: Secret path, optionally containing ``%VAR_NAME%``
+                placeholders that are replaced with environment variable values.
+                Supports dot-notation for JSON key navigation: ``/path/secret.key``
+                fetches ``/path/secret`` and returns ``secret["key"]``.
+
+        Returns:
+            Resolved value. A plain string for secrets without dot-notation;
+            a structured value (string, int, dict, etc.) when dot-notation
+            navigates into a JSON secret.
+
+        Raises:
+            ConfigError: When *key* is empty, an env-var placeholder is
+                missing, boto3 is not installed, the secret is binary,
+                or the API call fails.
+        """
+        if not key:
+            raise ConfigError("Secrets Manager key must not be empty")
+        expanded = _expand_env_vars(key)
+        path, json_keys = _split_resolver_key(expanded)
+        logger.info("secrets_resolver: fetching %s", path)
+        raw = _fetch_secret(self._get_client(), path)
+        if not json_keys:
+            return raw
+        return _navigate_json(raw, json_keys, path)
+
+
+__all__ = ["SecretsManagerResolver"]