ahi-aws 0.4.0__tar.gz

ahi_aws-0.4.0/.gitignore

@@ -0,0 +1,25 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.dist/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDEs/OS
+.DS_Store
+.vscode/*.code-snippets
+
+# Docs build
+site/

ahi_aws-0.4.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.4.0](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-aws-v0.3.0...ahi-aws-v0.4.0) (2026-11-10)
+
+
+### Features
+
+* **LHI-1728:** add ahi-aws auth helpers for SSO and attached roles ([7e2c7fe](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/7e2c7fed2ce86bbd95f0b0036120c9c5bf1cf050))
+
+## [0.3.0](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-aws-v0.2.1...ahi-aws-v0.3.0) (2026-10-21)
+
+
+### Features
+
+* **ahi-aws:** add S3 storage helpers ([0a71bf6](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/0a71bf6e17bc43f13844ff2a47c5baad23924c33))
+
+## [0.2.1](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-aws-v0.2.0...ahi-aws-v0.2.1) (2026-06-28)
+
+
+### Bug Fixes
+
+* **ahi-aws:** allow ahi-core 0.2 ([505ea28](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/505ea28d5bb3e154487d32af1e742fdf79299c83))
+
+## [0.2.0](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-aws-v0.1.0...ahi-aws-v0.2.0) (2026-06-27)
+
+
+### Features
+
+* scaffold uv workspace with core, sql, aws packages ([8c42f2f](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/8c42f2f371284180bf0569785837640e39deb80b))

ahi_aws-0.4.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: ahi-aws
+Version: 0.4.0
+Summary: Thin, typed boto3 helpers for AHI: AWS auth (SSO and attached-role sessions), Redshift Data API and Athena query execution, and S3 file storage.
+Project-URL: Homepage, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Project-URL: Documentation, https://adaptivehealthintelligence.github.io/ahi-python-packages/
+Project-URL: Repository, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Author: Adaptive Health Intelligence
+License: MIT
+Keywords: ahi,athena,auth,aws,boto3,redshift,s3,sso,sts
+Requires-Python: >=3.11
+Requires-Dist: ahi-core<0.3,>=0.2
+Requires-Dist: boto3>=1.34
+Provides-Extra: types
+Requires-Dist: boto3-stubs[athena,redshift-data,s3,sts]>=1.34; extra == 'types'
+Description-Content-Type: text/markdown
+
+# ahi-aws
+
+Thin, typed `boto3` helpers for AHI. Today: AWS **auth** (one session, checked
+once, with clear errors), running SQL on **Redshift** (Data API) and **Athena**,
+with async query handling, and moving files and folders to and from **S3**.
+
+```python
+from ahi.aws.auth import aws_session, check_identity
+
+session = aws_session()  # AWS_PROFILE / default profile / attached role
+identity = check_identity(session)  # raises an AuthError saying what to run
+print(identity.arn, identity.method)  # e.g. "sso", "iam-role", "container-role"
+```
+
+```python
+from ahi.aws.redshift import RedshiftDataClient
+from ahi.aws.athena import AthenaClient
+
+rs = RedshiftDataClient(workgroup_name="analytics", database="dev")
+rows = rs.run_query(
+    "select count(*) from events where day = :day",
+    parameters={"day": "2026-06-26"},
+)
+print(rows.scalar())
+
+ath = AthenaClient(workgroup="primary", database="analytics")
+for row in ath.run_query("select name from users where id = ?", parameters=[42]):
+    print(row["name"])
+```
+
+```python
+from ahi.aws.auth import aws_session
+from ahi.aws.s3 import S3Storage
+
+session = aws_session()
+storage = S3Storage("s3://my-bucket/some/prefix", client=session.client("s3"))
+
+uploaded = storage.upload_dir("runs/run-01", prefix="run-01")  # list[S3Object]
+storage.download_dir("run-01", "local/run-01")
+```
+
+## Design notes
+
+- **Never logs in for you.** No browser, no AWS CLI. Run `aws sso login`
+  beforehand (local SSO), or run where an AWS role is attached (EC2 instance
+  role, ECS task role); missing or expired credentials raise `AuthError`
+  with the command to run. No default region: set `AWS_REGION` or the
+  profile's `region`.
+- **Parameterized queries by default.** Pass values via `parameters` (named
+  `:name` for Redshift, positional `?` for Athena) — never format them in.
+- **One synchronous call.** `run_query` submits, polls with backoff (see
+  `ahi.core.poll_until`), and pages the full result set, returning a
+  `QueryResult` you can iterate, `len()`, or call `.scalar()` on.
+- **Typed results from Redshift; strings from Athena** (Athena returns all values
+  as strings — we preserve that rather than guessing).
+- **Failures raise** `QueryFailedError`; timeouts raise `PollTimeoutError`.
+- **S3 transfers return `S3Object` records** (bucket, key, local path, size);
+  failures raise `UploadFailedError` / `DownloadFailedError`.
+
+Install the optional `types` extra (`ahi-aws[types]`) for `boto3-stubs` during
+development.
+
+Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).

ahi_aws-0.4.0/README.md

@@ -0,0 +1,63 @@
+# ahi-aws
+
+Thin, typed `boto3` helpers for AHI. Today: AWS **auth** (one session, checked
+once, with clear errors), running SQL on **Redshift** (Data API) and **Athena**,
+with async query handling, and moving files and folders to and from **S3**.
+
+```python
+from ahi.aws.auth import aws_session, check_identity
+
+session = aws_session()  # AWS_PROFILE / default profile / attached role
+identity = check_identity(session)  # raises an AuthError saying what to run
+print(identity.arn, identity.method)  # e.g. "sso", "iam-role", "container-role"
+```
+
+```python
+from ahi.aws.redshift import RedshiftDataClient
+from ahi.aws.athena import AthenaClient
+
+rs = RedshiftDataClient(workgroup_name="analytics", database="dev")
+rows = rs.run_query(
+    "select count(*) from events where day = :day",
+    parameters={"day": "2026-06-26"},
+)
+print(rows.scalar())
+
+ath = AthenaClient(workgroup="primary", database="analytics")
+for row in ath.run_query("select name from users where id = ?", parameters=[42]):
+    print(row["name"])
+```
+
+```python
+from ahi.aws.auth import aws_session
+from ahi.aws.s3 import S3Storage
+
+session = aws_session()
+storage = S3Storage("s3://my-bucket/some/prefix", client=session.client("s3"))
+
+uploaded = storage.upload_dir("runs/run-01", prefix="run-01")  # list[S3Object]
+storage.download_dir("run-01", "local/run-01")
+```
+
+## Design notes
+
+- **Never logs in for you.** No browser, no AWS CLI. Run `aws sso login`
+  beforehand (local SSO), or run where an AWS role is attached (EC2 instance
+  role, ECS task role); missing or expired credentials raise `AuthError`
+  with the command to run. No default region: set `AWS_REGION` or the
+  profile's `region`.
+- **Parameterized queries by default.** Pass values via `parameters` (named
+  `:name` for Redshift, positional `?` for Athena) — never format them in.
+- **One synchronous call.** `run_query` submits, polls with backoff (see
+  `ahi.core.poll_until`), and pages the full result set, returning a
+  `QueryResult` you can iterate, `len()`, or call `.scalar()` on.
+- **Typed results from Redshift; strings from Athena** (Athena returns all values
+  as strings — we preserve that rather than guessing).
+- **Failures raise** `QueryFailedError`; timeouts raise `PollTimeoutError`.
+- **S3 transfers return `S3Object` records** (bucket, key, local path, size);
+  failures raise `UploadFailedError` / `DownloadFailedError`.
+
+Install the optional `types` extra (`ahi-aws[types]`) for `boto3-stubs` during
+development.
+
+Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).

ahi_aws-0.4.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "ahi-aws"
+version = "0.4.0"
+description = "Thin, typed boto3 helpers for AHI: AWS auth (SSO and attached-role sessions), Redshift Data API and Athena query execution, and S3 file storage."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Adaptive Health Intelligence" }]
+keywords = ["ahi", "aws", "boto3", "auth", "sso", "sts", "redshift", "athena", "s3"]
+dependencies = [
+  # Independent versioning: depend on a compatible RANGE of ahi-core, not a pin.
+  "ahi-core>=0.2,<0.3",
+  "boto3>=1.34",
+]
+
+[project.optional-dependencies]
+# Opt-in type stubs for editor/CI type-checking of the boto3 surface we use.
+types = [
+  "boto3-stubs[athena,redshift-data,s3,sts]>=1.34",
+]
+
+[project.urls]
+Homepage = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+Documentation = "https://adaptivehealthintelligence.github.io/ahi-python-packages/"
+Repository = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ahi"]

ahi_aws-0.4.0/src/ahi/aws/__init__.py

@@ -0,0 +1,44 @@
+"""Thin, typed boto3 helpers for AHI."""
+
+from ahi.aws.athena import AthenaClient
+from ahi.aws.auth import AwsIdentity, aws_session, check_identity
+from ahi.aws.errors import (
+    AuthError,
+    AwsUnreachableError,
+    CredentialsNotFoundError,
+    CredentialsRejectedError,
+    DownloadFailedError,
+    ProfileNotFoundError,
+    QueryError,
+    QueryFailedError,
+    RegionNotConfiguredError,
+    S3Error,
+    SsoLoginRequiredError,
+    UploadFailedError,
+)
+from ahi.aws.redshift import RedshiftDataClient
+from ahi.aws.results import QueryResult
+from ahi.aws.s3 import S3Object, S3Storage
+
+__all__ = [
+    "AthenaClient",
+    "AuthError",
+    "AwsIdentity",
+    "AwsUnreachableError",
+    "CredentialsNotFoundError",
+    "CredentialsRejectedError",
+    "DownloadFailedError",
+    "ProfileNotFoundError",
+    "QueryError",
+    "QueryFailedError",
+    "QueryResult",
+    "RedshiftDataClient",
+    "RegionNotConfiguredError",
+    "S3Error",
+    "S3Object",
+    "S3Storage",
+    "SsoLoginRequiredError",
+    "UploadFailedError",
+    "aws_session",
+    "check_identity",
+]

ahi_aws-0.4.0/src/ahi/aws/athena.py

@@ -0,0 +1,167 @@
+"""Thin wrapper over Athena for running SQL.
+
+Like Redshift's Data API, Athena is asynchronous: start an execution, poll its
+state, then page the results. ``AthenaClient.run_query`` collapses that into one
+synchronous call returning a :class:`~ahi.aws.results.QueryResult`.
+
+    from ahi.aws.athena import AthenaClient
+
+    client = AthenaClient(workgroup="primary", database="analytics")
+    result = client.run_query(
+        "select name from users where id = ?",
+        parameters=[42],
+    )
+    for row in result:
+        print(row["name"])
+
+Athena returns every value as a string (or NULL); this wrapper preserves that
+rather than guessing types.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ahi.aws.errors import QueryFailedError
+from ahi.aws.results import QueryResult
+from ahi.core import get_logger, poll_until
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Sequence
+
+_log = get_logger("aws.athena")
+
+# Terminal states reported by get_query_execution.
+_TERMINAL_STATES = frozenset({"SUCCEEDED", "FAILED", "CANCELLED"})
+
+
+class AthenaClient:
+    """Run queries against Athena.
+
+    Args:
+        workgroup: Athena workgroup. Result location and encryption are usually
+            configured on the workgroup, so ``output_location`` is optional.
+        database: Default Glue/Athena database (overridable per call).
+        catalog: Default data catalog (for example ``"AwsDataCatalog"``).
+        output_location: ``s3://`` prefix for results. Only needed when the
+            workgroup does not enforce one.
+        region_name: AWS region; defaults to the ambient boto3 configuration.
+        client: A pre-built ``athena`` boto3 client (injection point for tests).
+    """
+
+    def __init__(
+        self,
+        *,
+        workgroup: str = "primary",
+        database: str | None = None,
+        catalog: str | None = None,
+        output_location: str | None = None,
+        region_name: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        if client is None:
+            import boto3
+
+            client = boto3.client("athena", region_name=region_name)
+        self._client = client
+        self._workgroup = workgroup
+        self._database = database
+        self._catalog = catalog
+        self._output_location = output_location
+
+    def run_query(
+        self,
+        sql: str,
+        *,
+        parameters: Sequence[Any] | None = None,
+        database: str | None = None,
+        timeout: float = 300.0,
+        poll_interval: float = 1.0,
+    ) -> QueryResult:
+        """Execute ``sql`` and return its result.
+
+        Args:
+            sql: The SQL to run. Use positional ``?`` placeholders with
+                ``parameters`` rather than formatting values into the string.
+            parameters: Positional bind parameters, in order of ``?`` appearance.
+            database: Override the default database for this query.
+            timeout: Maximum seconds to wait for completion.
+            poll_interval: Initial delay between status polls.
+
+        Raises:
+            QueryFailedError: If the execution ends in ``FAILED``/``CANCELLED``.
+            PollTimeoutError: If it does not finish within ``timeout``.
+        """
+        query_id = self._start(sql, parameters, database)
+        _log.debug("started athena execution %s", query_id)
+
+        execution = poll_until(
+            lambda: self._client.get_query_execution(QueryExecutionId=query_id),
+            lambda e: e["QueryExecution"]["Status"]["State"] in _TERMINAL_STATES,
+            timeout=timeout,
+            interval=poll_interval,
+        )
+
+        status = execution["QueryExecution"]["Status"]
+        state = status["State"]
+        if state != "SUCCEEDED":
+            raise QueryFailedError(query_id, state, status.get("StateChangeReason"))
+        return self._collect(query_id)
+
+    def _start(
+        self,
+        sql: str,
+        parameters: Sequence[Any] | None,
+        database: str | None,
+    ) -> str:
+        args: dict[str, Any] = {"QueryString": sql, "WorkGroup": self._workgroup}
+
+        context: dict[str, str] = {}
+        db = database or self._database
+        if db is not None:
+            context["Database"] = db
+        if self._catalog is not None:
+            context["Catalog"] = self._catalog
+        if context:
+            args["QueryExecutionContext"] = context
+
+        if self._output_location is not None:
+            args["ResultConfiguration"] = {"OutputLocation": self._output_location}
+        if parameters:
+            args["ExecutionParameters"] = [str(value) for value in parameters]
+
+        return self._client.start_query_execution(**args)["QueryExecutionId"]
+
+    def _collect(self, query_id: str) -> QueryResult:
+        columns: list[str] = []
+        rows: list[dict[str, Any]] = []
+        next_token: str | None = None
+        first_page = True
+
+        while True:
+            kwargs: dict[str, Any] = {"QueryExecutionId": query_id}
+            if next_token:
+                kwargs["NextToken"] = next_token
+            page = self._client.get_query_results(**kwargs)
+            result_set = page.get("ResultSet", {})
+
+            if not columns:
+                column_info = result_set.get("ResultSetMetadata", {}).get("ColumnInfo", [])
+                columns = [col["Label"] for col in column_info]
+
+            page_rows = result_set.get("Rows", [])
+            # Athena repeats the column labels as the first data row of the first
+            # page for SELECT statements; skip it so it isn't returned as data.
+            if first_page and page_rows:
+                page_rows = page_rows[1:]
+            first_page = False
+
+            for row in page_rows:
+                values = [cell.get("VarCharValue") for cell in row.get("Data", [])]
+                rows.append(dict(zip(columns, values, strict=False)))
+
+            next_token = page.get("NextToken")
+            if not next_token:
+                break
+
+        return QueryResult(columns=columns, rows=rows, query_id=query_id)

ahi_aws-0.4.0/src/ahi/aws/auth.py

@@ -0,0 +1,227 @@
+"""AWS credentials for AHI apps
+
+This module provides :func:`aws_session`, which builds a boto3 session using
+boto3's standard credential resolution, :func:`check_identity`, which checks it
+with a single ``sts:GetCallerIdentity`` call, and :class:`AwsIdentity`, which
+records who the credentials belong to and how they were found, great for provenance.
+
+Caters to common ways of running AHI apps:
+
+- **Local SSO** (a person at their machine): their own SSO login, done
+  beforehand with ``aws sso login``, picked up from ``AWS_PROFILE`` or the
+  default profile.
+- **Attached role** (EC2 instance, ECS/Fargate task, scheduled jobs): the role
+  attached to the resource, found by boto3 with no profile and no login.
+
+Hand ``session.client(...)`` to the other helpers:
+
+    from ahi.aws.athena import AthenaClient
+    from ahi.aws.auth import aws_session, check_identity
+
+    session = aws_session()
+    identity = check_identity(session)
+    log.info("AWS: %s via %s", identity.arn, identity.method)
+
+    athena = AthenaClient(workgroup="primary", client=session.client("athena"))
+
+This module does not log in for you: no browser, no AWS CLI. When credentials are
+missing or expired it raises an :class:`~ahi.aws.errors.AuthError` subclass
+saying what to run (for example ``aws sso login``).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import boto3
+from botocore.exceptions import (
+    BotoCoreError,
+    ClientError,
+    HTTPClientError,
+    NoCredentialsError,
+    NoRegionError,
+    PartialCredentialsError,
+    ProfileNotFound,
+    SSOTokenLoadError,
+    TokenRetrievalError,
+    UnauthorizedSSOTokenError,
+)
+from botocore.exceptions import ConnectionError as BotoConnectionError
+
+from ahi.aws.errors import (
+    AuthError,
+    AwsUnreachableError,
+    CredentialsNotFoundError,
+    CredentialsRejectedError,
+    ProfileNotFoundError,
+    RegionNotConfiguredError,
+    SsoLoginRequiredError,
+)
+from ahi.core import get_logger
+
+_log = get_logger("aws.auth")
+
+
+@dataclass(frozen=True)
+class AwsIdentity:
+    """The identity behind a set of AWS credentials
+
+    Returned by :func:`check_identity`. Log it, or record it with a run's provenance.
+
+    Attributes:
+        account: The AWS account id.
+        arn: The caller's ARN (an assumed-role ARN for SSO and attached roles).
+        user_id: The caller's unique id.
+        region: The region the identity check ran in.
+        profile: The named profile in effect, or ``None`` for the default
+            profile or when no profile is in use.
+        method: How botocore found the credentials, from
+            ``session.get_credentials().method``: for example ``"sso"`` for an
+            SSO login, ``"iam-role"`` for an EC2 instance role, or
+            ``"container-role"`` for an ECS/Fargate task role. ``None`` if it
+            could not tell.
+    """
+
+    account: str
+    arn: str
+    user_id: str
+    region: str | None
+    profile: str | None
+    method: str | None
+
+
+def aws_session(*, profile: str | None = None, region: str | None = None) -> boto3.Session:
+    """Return a boto3 session using the standard credential resolution.
+
+    Credentials lookup order is the same as boto3's, but;
+    later sources are not checked:
+
+    1. Environment variables: ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``
+    2. The profile in use: ``AWS_PROFILE``, else ``[default]`` in ``~/.aws``.
+    3. The attached role: ECS/Fargate task role, else EC2 instance role.
+
+    Passing ``profile`` skips this list and uses only that profile and authenticate via SSO.
+
+    Region lookup order;
+    1. ``region`` argument to this function.
+    2. Environment variables: ``AWS_REGION``, ``AWS_DEFAULT_REGION``.
+    3. The profile's ``region`` setting.
+
+    Makes no network calls; use :func:`check_identity` to verify the session.
+
+    Args:
+        profile: AWS SSO profile name to use. This uses SSO method over other credential
+            sources (environment keys, ``AWS_PROFILE``, attached roles).
+            If you pass one, it must exist on the machine running the code, or this raises
+            ``ProfileNotFoundError``. On machines that use an attached role
+            (EC2, ECS), pass ``None``.
+        region: Region override.
+
+    Returns:
+        The session, ready for ``session.client(...)``.
+
+    Raises:
+        ProfileNotFoundError: If the profile is not configured.
+        RegionNotConfiguredError: If no region resolves.
+    """
+    region_name = region or os.environ.get("AWS_REGION") or None
+    try:
+        session = boto3.Session(profile_name=profile, region_name=region_name)
+        resolved_region = session.region_name
+    except ProfileNotFound as exc:
+        raise _to_auth_error(exc, profile=profile, method=None, region=None) from exc
+
+    profile_in_use = _profile_in_use(session)
+    if not resolved_region:
+        raise RegionNotConfiguredError(profile=profile_in_use)
+    _log.debug("AWS session: profile=%s region=%s", profile_in_use or "<default>", resolved_region)
+    return session
+
+
+def check_identity(session: boto3.Session, *, client: Any | None = None) -> AwsIdentity:
+    """Return the identity behind the session's credentials, checked via an STS call.
+
+    Call this once at the start of a run so missing or expired credentials
+    fail early with a message that says what to do.
+
+    Args:
+        session: The session to check, usually from :func:`aws_session`.
+        client: A pre-built ``sts`` boto3 client (injection point for tests).
+            Defaults to ``session.client("sts")``.
+
+    Returns:
+        The caller's identity and how its credentials were found.
+
+    Raises:
+        SsoLoginRequiredError: If the SSO login is missing or expired.
+        CredentialsNotFoundError: If no credentials are found.
+        CredentialsRejectedError: If AWS rejects the credentials.
+        AwsUnreachableError: If AWS STS cannot be reached.
+        AuthError: For any other credential failure (the base of all the above).
+    """
+    profile = _profile_in_use(session)
+    method: str | None = None
+    region: str | None = session.region_name
+    try:
+        credentials = session.get_credentials()
+        method = credentials.method if credentials is not None else None
+        sts = client if client is not None else session.client("sts")
+        region = sts.meta.region_name
+        response = sts.get_caller_identity()
+    except (BotoCoreError, ClientError) as exc:
+        raise _to_auth_error(exc, profile=profile, method=method, region=region) from exc
+
+    identity = AwsIdentity(
+        account=response["Account"],
+        arn=response["Arn"],
+        user_id=response["UserId"],
+        region=region,
+        profile=profile,
+        method=method,
+    )
+    _log.debug("AWS identity: %s via %s", identity.arn, identity.method)
+    return identity
+
+
+def _profile_in_use(session: boto3.Session) -> str | None:
+    """Return the profile in use, or ``None`` when it's the default profile."""
+    name = session.profile_name
+    return None if name == "default" else name
+
+
+def _to_auth_error(
+    exc: BotoCoreError | ClientError,
+    *,
+    profile: str | None,
+    method: str | None,
+    region: str | None,
+) -> AuthError:
+    """Return the AHI auth error that matches a botocore failure.
+
+    Maps each botocore credential, region and network error to its ``AuthError``
+    subclass, adding context botocore doesn't have (the profile in effect, how
+    the credentials were found, the region) so the message can say what to do
+    next. Anything not recognised becomes a plain ``AuthError``.
+    """
+    reason = str(exc)
+    if isinstance(exc, ProfileNotFound):
+        return ProfileNotFoundError(profile=profile or exc.kwargs.get("profile"), reason=reason)
+    if isinstance(exc, SSOTokenLoadError | UnauthorizedSSOTokenError | TokenRetrievalError):
+        return SsoLoginRequiredError(profile=profile, reason=reason)
+    if isinstance(exc, NoCredentialsError | PartialCredentialsError):
+        return CredentialsNotFoundError(profile=profile, reason=reason)
+    if isinstance(exc, NoRegionError):
+        return RegionNotConfiguredError(profile=profile, reason=reason)
+    if isinstance(exc, BotoConnectionError | HTTPClientError):
+        return AwsUnreachableError(reason=reason, region=region, profile=profile)
+    if isinstance(exc, ClientError):
+        error = exc.response.get("Error", {})
+        return CredentialsRejectedError(
+            error.get("Code", "Unknown"),
+            reason=reason,  # botocore's full message, which names the operation too
+            method=method,
+            profile=profile,
+        )
+    return AuthError(profile=profile, reason=reason)