tai42-kit 0.1.0__py3-none-any.whl

tai42_kit/__init__.py

@@ -0,0 +1,20 @@
+"""tai42-kit — generic leaf helpers, LLM factories, pooled clients, and settings
+for the TAI ecosystem.
+
+Utilities (data/runtime/langchain helpers), LLM provider + checkpoint/store
+factories, pooled clients + MCP transports, and co-located pydantic-settings.
+The only tai-* dependency is ``tai42-contract`` (the leaf rule): kit implements its
+``BaseClient`` Protocol and consumes its manifest types; it imports no other
+tai-* package.
+
+Deliberately light: nothing is re-exported here, so ``import tai42_kit`` pulls no
+vendor dependency (no langchain, no drivers). Import the subpackage you need —
+each one (``tai42_kit.llm``, ``tai42_kit.clients``, ...) is the opt-in boundary for
+its dependencies.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("tai42-kit")
+
+__all__ = ["__version__"]

tai42_kit/clients/__init__.py

@@ -0,0 +1,27 @@
+"""Pooled clients + the generic client facade.
+
+Each client subclasses ``PooledClient`` (per-loop pooling, satisfies the contract
+``BaseClient`` Protocol) and is reached by class through ``client_ctx``. The
+driver each impl needs is declared by an extra (``tai42-kit[curl]`` /
+``[postgres]``); import a driver submodule only when its driver is installed.
+"""
+
+from tai42_contract.errors import ClientDisconnectedError
+
+from tai42_kit.clients.base import PooledClient, shutdown_all_clients
+from tai42_kit.clients.facade import client_ctx
+from tai42_kit.clients.settings import (
+    ClientSettings,
+    PostgresConnectionSettings,
+    RedisConnectionSettings,
+)
+
+__all__ = [
+    "ClientDisconnectedError",
+    "ClientSettings",
+    "PooledClient",
+    "PostgresConnectionSettings",
+    "RedisConnectionSettings",
+    "client_ctx",
+    "shutdown_all_clients",
+]

tai42_kit/clients/base.py

@@ -0,0 +1,203 @@
+import asyncio
+import json
+import logging
+import threading
+from asyncio import AbstractEventLoop
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import cast
+from weakref import WeakKeyDictionary
+
+from tai42_contract.errors import ClientDisconnectedError
+
+logger = logging.getLogger(__name__)
+
+# Clients are cached per event loop (async pools are bound to the loop that
+# created them) and per PooledClient subclass + connection key. Keyed off the
+# loop in a WeakKeyDictionary so a loop's caches drop when the loop is collected —
+# no attribute is stashed on the loop object.
+_loop_clients: "WeakKeyDictionary[AbstractEventLoop, dict[type, dict[str, object]]]" = WeakKeyDictionary()
+_loop_locks: "WeakKeyDictionary[AbstractEventLoop, dict[tuple[type, str], asyncio.Lock]]" = WeakKeyDictionary()
+
+# The two maps above are module-global and reached from many threads: a template
+# render runs in a worker thread (asyncio.to_thread) whose {% include %} bridge
+# spins its own loop (asyncio.run), so concurrent renders touch these maps at the
+# same time. WeakKeyDictionary is not thread-safe, so every EXPLICIT access to the
+# OUTER maps is serialized under this lock. The lock is held only around dict
+# bookkeeping, never across an await (client creation/closing happens outside it).
+# The weak-ref cleanup of a collected loop's entry still fires off-lock on an
+# arbitrary thread, but that removal is a single C-level op (atomic under the
+# GIL). Inner per-loop dicts stay owned by their single loop.
+_registry_lock = threading.Lock()
+
+# RuntimeError messages asyncio emits when a loop-bound resource is used after
+# its event loop closed or from a different loop. Driver stacks that surface a
+# dead session as a plain RuntimeError (curl_cffi, anyio) produce one of these;
+# any other RuntimeError comes from caller code and must propagate untouched.
+_LOOP_BOUND_ERROR_MARKERS = (
+    "Event loop is closed",
+    "attached to a different loop",
+    "bound to a different event loop",
+)
+
+
+def is_loop_bound_runtime_error(exc: BaseException) -> bool:
+    """Whether ``exc`` is a RuntimeError signalling a closed/mismatched event loop."""
+    return isinstance(exc, RuntimeError) and any(marker in str(exc) for marker in _LOOP_BOUND_ERROR_MARKERS)
+
+
+def reject_unknown_connection_kwargs(client_label: str, kwargs: dict[str, object], allowed: frozenset[str]) -> None:
+    """Reject connection kwargs a client does not understand, raising ``ValueError``.
+
+    A pooled client keys its per-loop pool on the full kwargs dict, so an
+    unrecognized kwarg (typically a typo) would otherwise split the pool key and
+    silently create a second, mis-configured client rather than the caller's
+    intended one. The shared validation convention across the concrete impls:
+    fail loudly, naming the offending keys and the allowed set.
+    """
+    unknown = sorted(set(kwargs) - allowed)
+    if unknown:
+        raise ValueError(f"{client_label} received unknown connection kwarg(s) {unknown}; allowed: {sorted(allowed)}")
+
+
+class PooledClient[T]:
+    @staticmethod
+    def _key(**kwargs) -> str:
+        return json.dumps(kwargs, sort_keys=True)
+
+    def _clients_for_loop(self, loop: AbstractEventLoop) -> dict[str, T]:
+        with _registry_lock:
+            per_loop = _loop_clients.get(loop)
+            if per_loop is None:
+                per_loop = {}
+                _loop_clients[loop] = per_loop
+            # The registry is heterogeneous across subclasses (values typed
+            # ``object``); a single class's entries are all ``T``.
+            return cast("dict[str, T]", per_loop.setdefault(self.__class__, {}))
+
+    def _create_lock(self, loop: AbstractEventLoop, key: str) -> asyncio.Lock:
+        with _registry_lock:
+            per_loop = _loop_locks.get(loop)
+            if per_loop is None:
+                per_loop = {}
+                _loop_locks[loop] = per_loop
+            lock = per_loop.get((self.__class__, key))
+            if lock is None:
+                lock = asyncio.Lock()
+                per_loop[(self.__class__, key)] = lock
+            return lock
+
+    @asynccontextmanager
+    async def current(self, **kwargs) -> AsyncIterator[T]:
+        loop = asyncio.get_running_loop()
+        clients_for_loop = self._clients_for_loop(loop)
+        key = self._key(**kwargs)
+        # Double-checked creation under a per-(class, key) lock: without it two
+        # concurrent first-use callers both create a client and one is orphaned
+        # (never closed). The synchronous get/setdefault above never awaits, so
+        # the cache and lock lookups are themselves race-free on the single loop.
+        if key not in clients_for_loop:
+            async with self._create_lock(loop, key):
+                # Re-fetch the live inner dict now that the lock is held.
+                # ``shutdown_all_clients()`` may have popped this loop's pool out
+                # of ``_loop_clients`` — detaching and clearing the dict captured
+                # before the lock — between that capture and acquiring the lock.
+                # Both the re-check and the write below must see the LIVE dict: a
+                # second waiter re-checking the stale-cleared dict would find
+                # ``key`` absent, create a duplicate, and overwrite the first
+                # waiter's client in the re-registered dict — orphaning it (never
+                # closed). The re-fetch and re-check are synchronous, so on the
+                # single loop nothing interleaves between them.
+                clients_for_loop = self._clients_for_loop(loop)
+                if key not in clients_for_loop:
+                    created = await self._create(**kwargs)
+                    # ``_create`` awaited above, so a shutdown may have detached
+                    # the pool again. Re-fetch once more so the write lands in the
+                    # live (re-registered if it was swept) dict rather than a
+                    # stale one, where a future shutdown/close can reach it. The
+                    # re-fetch and write are synchronous — nothing interleaves.
+                    clients_for_loop = self._clients_for_loop(loop)
+                    clients_for_loop[key] = created
+
+        client = clients_for_loop[key]
+        try:
+            yield client
+        except BaseException as e:
+            # Only errors the predicate classifies as a disconnection evict the
+            # client; everything else (including cancellation) re-raises
+            # untouched.
+            if not self._is_disconnection_error(e):
+                raise
+            clients_for_loop.pop(key, None)
+            try:
+                await self._close(client)
+            except Exception:
+                logger.debug("Failed to close disconnected client %s", type(client).__name__, exc_info=True)
+            raise ClientDisconnectedError(
+                f"{type(client).__name__} disconnected and was removed from the cache. "
+                f"Retry the operation to create a new client. (Original error: {e})"
+            ) from e
+
+    async def close(self, **kwargs) -> None:
+        loop = asyncio.get_running_loop()
+        clients_for_loop = self._clients_for_loop(loop)
+
+        key = self._key(**kwargs)
+        client = clients_for_loop.pop(key, None)
+        if client is not None:
+            await self._close(client)
+
+    async def _create(self, **kwargs) -> T:
+        raise NotImplementedError
+
+    async def _close(self, client: T) -> None:
+        raise NotImplementedError
+
+    def _disconnection_exceptions(self) -> tuple[type[BaseException], ...]:
+        # Cancellation is deliberately excluded: a cancelled ``current()`` body
+        # must re-raise ``CancelledError`` so the await point unwinds, never be
+        # converted into ``ClientDisconnectedError``. Concrete clients override
+        # this with their driver's real disconnection set.
+        return (ConnectionError,)
+
+    def _is_disconnection_error(self, exc: BaseException) -> bool:
+        # Predicate ``current()`` consults to decide whether an error from the
+        # body means the pooled client is dead (evict + close + wrap in
+        # ``ClientDisconnectedError``) or is an ordinary caller error
+        # (propagate untouched). Defaults to an isinstance check against
+        # ``_disconnection_exceptions()``; clients whose drivers signal
+        # disconnection through a broad exception type (e.g. a plain
+        # ``RuntimeError``) override this to also match by message.
+        return isinstance(exc, self._disconnection_exceptions())
+
+
+async def shutdown_all_clients() -> None:
+    """Close every live client pool for the running event loop.
+
+    Sweeps the per-loop class-keyed cache and closes each pooled client. Closes
+    are best-effort — failures are collected and raised together, never silently
+    dropped.
+    """
+    # Always called from within a running loop (it is async); get_running_loop
+    # raises loudly if that invariant is ever broken.
+    loop = asyncio.get_running_loop()
+    # Detach this loop's pool atomically, then close its clients without holding
+    # the registry lock across the awaits.
+    with _registry_lock:
+        per_loop = _loop_clients.pop(loop, None)
+    if not per_loop:
+        return
+
+    errors = []
+    for cls, clients in list(per_loop.items()):
+        closer = cls()
+        for client in list(clients.values()):
+            try:
+                await closer._close(client)
+            except Exception as e:
+                logger.exception("Error closing client %s", type(client).__name__)
+                errors.append(e)
+        clients.clear()
+
+    if errors:
+        raise ExceptionGroup("Errors while shutting down clients", errors)

tai42_kit/clients/facade.py

@@ -0,0 +1,44 @@
+"""The generic client facade — one way to get any pooled client.
+
+``client_ctx(SomeClient, settings)`` returns an async context manager yielding a
+connected client, pooled and reused per event-loop + connection params (the
+pooling lives in ``PooledClient``). A client is a plain ``PooledClient`` subclass,
+and callers reach it by class — no container, no wiring.
+
+- ``settings`` (a ``ClientSettings``) supplies connection kwargs via
+  ``client_kwargs()``; or pass raw ``**kwargs`` for clients with none.
+- ``fresh=True`` yields a one-shot client built outside the pool and closed on
+  exit (for a blocking op that must not hold a shared-pool connection).
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Any
+
+from tai42_kit.clients.base import PooledClient
+from tai42_kit.clients.settings import ClientSettings
+
+
+def client_ctx[T](
+    client_cls: type[PooledClient[T]],
+    settings: ClientSettings | None = None,
+    *,
+    fresh: bool = False,
+    **kwargs: Any,
+) -> AbstractAsyncContextManager[T]:
+    if settings is not None and kwargs:
+        raise ValueError("client_ctx: pass either `settings` or **kwargs, not both")
+    kw = settings.client_kwargs() if settings is not None else kwargs
+    if fresh:
+        return _fresh_client(client_cls, kw)
+    return client_cls().current(**kw)
+
+
+@asynccontextmanager
+async def _fresh_client[T](client_cls: type[PooledClient[T]], kw: dict) -> AsyncIterator[T]:
+    inst = client_cls()
+    client = await inst._create(**kw)
+    try:
+        yield client
+    finally:
+        await inst._close(client)

tai42_kit/clients/impl/__init__.py

@@ -0,0 +1,3 @@
+"""Concrete pooled clients. Each imports its driver at module top, so import the
+submodule only with the matching extra installed (``tai42-kit[redis]`` / ``[curl]``
+/ ``[postgres]``)."""

tai42_kit/clients/impl/curl.py

@@ -0,0 +1,41 @@
+import anyio
+from curl_cffi import requests
+from curl_cffi.requests.exceptions import SessionClosed
+
+from tai42_kit.clients.base import PooledClient, is_loop_bound_runtime_error, reject_unknown_connection_kwargs
+
+_ALLOWED_KWARGS = frozenset({"session_params"})
+
+
+class CurlClient(PooledClient[requests.AsyncSession]):
+    """Manages reusable curl_cffi sessions.
+
+    Every primitive in ``session_params`` maps onto the ``AsyncSession``, giving
+    full control over the network layer.
+    """
+
+    async def _create(self, **kwargs) -> requests.AsyncSession:
+        reject_unknown_connection_kwargs("Curl client", kwargs, _ALLOWED_KWARGS)
+        # Copy before mutating — never alter the caller's dict.
+        session_params = {k: v for k, v in kwargs.get("session_params", {}).items() if k != "session_key"}
+        return requests.AsyncSession(**session_params)
+
+    async def _close(self, client: requests.AsyncSession):
+        if client:
+            await client.close()
+
+    def _disconnection_exceptions(self) -> tuple[type[Exception], ...]:
+        return (
+            # The async resource is dead (socket / loop closed)
+            anyio.ClosedResourceError,
+            anyio.BrokenResourceError,
+            # The curl_cffi session object is explicitly closed / invalid
+            SessionClosed,
+        )
+
+    def _is_disconnection_error(self, exc: BaseException) -> bool:
+        # curl_cffi/anyio surface a dead loop-bound session as a plain
+        # RuntimeError ("Event loop is closed" / "... attached to a different
+        # loop"); match those by message so an unrelated RuntimeError raised by
+        # caller code never tears down the pool.
+        return super()._is_disconnection_error(exc) or is_loop_bound_runtime_error(exc)

tai42_kit/clients/impl/http.py

@@ -0,0 +1,26 @@
+import httpx
+
+from tai42_kit.clients.base import PooledClient, reject_unknown_connection_kwargs
+
+
+class HttpxClient(PooledClient[httpx.AsyncClient]):
+    """Pooled ``httpx.AsyncClient`` for app-owned outbound HTTP.
+
+    Connection params arrive as kwargs (``timeout``, ``max_connections``,
+    ``max_keepalive_connections``, ``keepalive_expiry``); unspecified ones keep
+    httpx's defaults. ``trust_env=False`` ignores ambient proxy env vars.
+    """
+
+    _LIMIT_KEYS = ("max_connections", "max_keepalive_connections", "keepalive_expiry")
+    _ALLOWED_KWARGS = frozenset({"timeout", *_LIMIT_KEYS})
+
+    async def _create(self, **kwargs) -> httpx.AsyncClient:
+        reject_unknown_connection_kwargs("Httpx client", kwargs, self._ALLOWED_KWARGS)
+        limits = httpx.Limits(**{k: kwargs[k] for k in self._LIMIT_KEYS if k in kwargs})
+        client_kwargs = {"trust_env": False, "limits": limits}
+        if "timeout" in kwargs:
+            client_kwargs["timeout"] = httpx.Timeout(kwargs["timeout"])
+        return httpx.AsyncClient(**client_kwargs)
+
+    async def _close(self, client: httpx.AsyncClient):
+        await client.aclose()

tai42_kit/clients/impl/mcp.py

@@ -0,0 +1,60 @@
+import asyncio
+from typing import Literal
+
+import anyio
+from fastmcp import Client
+from tai42_contract.manifest import TaiMCPConfig
+
+from tai42_kit.clients.base import PooledClient, is_loop_bound_runtime_error, reject_unknown_connection_kwargs
+from tai42_kit.clients.settings import mcp_client_settings
+from tai42_kit.transport import get_mcp_transport
+
+# Connection kwargs a FastMCP client accepts. Anything else is rejected so it
+# can't silently split the pool key.
+_ALLOWED_KWARGS = frozenset({"config", "uds_protocol"})
+
+
+class FastMCPClient(PooledClient[Client]):
+    async def _create(self, **kwargs) -> Client:
+        if "config" not in kwargs:
+            raise KeyError("FastMCP client requires a `config` kwarg")
+
+        config = kwargs["config"]
+        if not config or not isinstance(config, dict):
+            raise TypeError("FastMCP client `config` must be a non-empty dict")
+        reject_unknown_connection_kwargs("FastMCP client", kwargs, _ALLOWED_KWARGS)
+
+        # The MCP wire protocol over a UDS socket; the caller (which owns the
+        # runtime/CLI) supplies it. Ignored for non-UDS servers.
+        uds_protocol: Literal["http", "sse"] = kwargs.get("uds_protocol", "http")
+        transport = get_mcp_transport(TaiMCPConfig(**config), uds_protocol=uds_protocol)
+        # No ambient-header forwarding: fastmcp transports default
+        # ``forward_incoming_headers=False``, so this server's own inbound headers
+        # (incl. auth) are never leaked to the downstream MCP — only the headers
+        # declared in ``config`` are sent. The conformance tests lock this so a
+        # future fastmcp default-change fails loudly instead of leaking silently.
+        #
+        # Bound the connect/init: this runs inside the pooled per-key creation
+        # lock, so an unbounded connect-stall would queue every same-config caller
+        # forever. wait_for cancels the inner enter on expiry, letting fastmcp
+        # unwind its partial transport state; nothing is registered in the pool.
+        timeout = mcp_client_settings().connect_timeout_seconds
+        try:
+            return await asyncio.wait_for(Client(transport).__aenter__(), timeout=timeout)
+        except TimeoutError as exc:
+            raise TimeoutError(
+                f"MCP client connect/init did not complete within {timeout}s (MCP_CLIENT_CONNECT_TIMEOUT_SECONDS)"
+            ) from exc
+
+    async def _close(self, client: Client):
+        await client.__aexit__(None, None, None)
+
+    def _disconnection_exceptions(self) -> tuple[type[Exception], ...]:
+        return anyio.ClosedResourceError, anyio.BrokenResourceError
+
+    def _is_disconnection_error(self, exc: BaseException) -> bool:
+        # anyio/asyncio surface a dead loop-bound transport as a plain
+        # RuntimeError ("Event loop is closed" / "... attached to a different
+        # loop"); match those by message so an unrelated RuntimeError raised by
+        # caller code never tears down the pool.
+        return super()._is_disconnection_error(exc) or is_loop_bound_runtime_error(exc)

tai42_kit/clients/impl/postgres.py

@@ -0,0 +1,58 @@
+from psycopg import AsyncConnection
+from psycopg.rows import TupleRow
+from psycopg.types.json import Json
+from psycopg_pool import AsyncConnectionPool
+
+from tai42_kit.clients.base import PooledClient, reject_unknown_connection_kwargs
+
+# ``Json`` is re-exported so callers wrap jsonb params through the pooled
+# client's own module rather than importing psycopg directly — every pg
+# primitive the app touches is reached through the kit client layer.
+__all__ = ["Json", "PostgresClient"]
+
+# The pool's default connection type. Naming it lets the pooled-client generic
+# resolve concretely (the AsyncConnectionPool default hides ACT behind a cast).
+_Pool = AsyncConnectionPool[AsyncConnection[TupleRow]]
+
+# Connection kwargs a Postgres client accepts — the identity produced by
+# ``PostgresConnectionSettings.client_kwargs``. Anything else is rejected so it
+# can't silently split the pool key.
+_ALLOWED_KWARGS = frozenset({"dsn", "min_size", "max_size"})
+
+
+class PostgresClient(PooledClient[_Pool]):
+    """Pooled ``psycopg_pool.AsyncConnectionPool``, one pool per (DSN, size) per
+    loop. Compose ``PostgresConnectionSettings`` for the connection kwargs."""
+
+    async def _create(self, **kwargs) -> _Pool:
+        if "dsn" not in kwargs:
+            raise KeyError("Postgres client requires a 'dsn' kwarg")
+        dsn = kwargs["dsn"]
+        if not dsn or not isinstance(dsn, str):
+            raise ValueError("Postgres client 'dsn' must be a non-empty string")
+        reject_unknown_connection_kwargs("Postgres client", kwargs, _ALLOWED_KWARGS)
+
+        pool = AsyncConnectionPool(
+            conninfo=dsn,
+            min_size=kwargs.get("min_size", 2),
+            max_size=kwargs.get("max_size", 10),
+            open=False,
+            connection_class=AsyncConnection,
+            # Validate each connection on checkout: a connection the server has
+            # since closed (idle drop, restart, a severed-then-restored link) is
+            # discarded and replaced instead of handed to the caller, who would
+            # otherwise get an OperationalError on the first query. This is what
+            # lets a pooled caller ride out a transient Postgres outage without a
+            # restart.
+            check=AsyncConnectionPool.check_connection,
+        )
+        await pool.open()
+        return pool
+
+    async def _close(self, client: _Pool):
+        await client.close()
+
+    def _disconnection_exceptions(self) -> tuple[type[Exception], ...]:
+        import psycopg
+
+        return (psycopg.OperationalError,)

tai42_kit/clients/impl/redis.py

@@ -0,0 +1,120 @@
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Mapping
+from typing import Any, cast
+
+from redis import Redis as SyncRedis
+from redis.asyncio import Redis as AsyncRedis
+
+from tai42_kit.clients.base import PooledClient, reject_unknown_connection_kwargs
+
+# Connection kwargs a Redis client accepts — the JSON-serializable identity
+# produced by ``RedisConnectionSettings.client_kwargs``. Anything else is a typo
+# or a stray value and is rejected so it can't silently split the pool key.
+_ALLOWED_KWARGS = frozenset(
+    {
+        "url",
+        "max_connections",
+        "decode_responses",
+        "socket_timeout",
+        "socket_connect_timeout",
+        "retry_on_timeout",
+        "retry_attempts",
+    }
+)
+
+
+def _validate_kwargs(kwargs: dict[str, Any]) -> None:
+    _validate_url(kwargs)
+    reject_unknown_connection_kwargs("Redis client", kwargs, _ALLOWED_KWARGS)
+
+
+def _validate_url(kwargs: dict[str, Any]) -> None:
+    if "url" not in kwargs:
+        raise KeyError("Redis client requires a 'url' kwarg")
+    url = kwargs["url"]
+    if not url:
+        raise ValueError("Redis client 'url' cannot be empty")
+    if not isinstance(url, str):
+        raise TypeError("Redis client 'url' must be a string (e.g., 'redis://localhost:6379/0')")
+
+
+class RedisClient(PooledClient[AsyncRedis]):
+    async def _create(self, **kwargs) -> AsyncRedis:
+        _validate_kwargs(kwargs)
+        return await AsyncRedis.from_url(**_with_retry(kwargs)).initialize()
+
+    async def _close(self, client: AsyncRedis):
+        await client.aclose()
+
+    def _disconnection_exceptions(self) -> tuple[type[Exception], ...]:
+        from redis.exceptions import ConnectionError as RedisConnectionError
+        from redis.exceptions import TimeoutError as RedisTimeoutError
+
+        return RedisConnectionError, RedisTimeoutError
+
+
+class SyncRedisClient(PooledClient[SyncRedis]):
+    async def _create(self, **kwargs) -> SyncRedis:
+        _validate_kwargs(kwargs)
+        return SyncRedis.from_url(**_with_retry(kwargs, sync=True))
+
+    async def _close(self, client: SyncRedis):
+        # Sync close can do network I/O to release pool connections — keep it
+        # off the event loop.
+        await asyncio.to_thread(client.close)
+
+    def _disconnection_exceptions(self) -> tuple[type[Exception], ...]:
+        from redis.exceptions import ConnectionError as RedisConnectionError
+        from redis.exceptions import TimeoutError as RedisTimeoutError
+
+        return RedisConnectionError, RedisTimeoutError
+
+
+def _with_retry(kwargs: dict[str, Any], *, sync: bool = False) -> dict[str, Any]:
+    """Turn the serializable ``retry_attempts`` int into a redis ``Retry`` object.
+
+    ``retry_attempts`` is part of the pool key (a stable int) but is not a valid
+    ``Redis.from_url`` argument, so it is consumed here and, when positive,
+    materialized into an exponential-backoff ``Retry`` on connection/timeout
+    errors — built per client because a ``Retry`` instance is not serializable.
+    The sync and async clients import ``Retry`` from their own subpackage.
+    """
+    retry_attempts = kwargs.pop("retry_attempts", 0)
+    if retry_attempts > 0:
+        if sync:
+            from redis.retry import Retry
+        else:
+            from redis.asyncio.retry import Retry
+        from redis.backoff import ExponentialBackoff
+        from redis.exceptions import ConnectionError as RedisConnectionError
+        from redis.exceptions import TimeoutError as RedisTimeoutError
+
+        kwargs["retry"] = Retry(ExponentialBackoff(), retry_attempts)
+        kwargs["retry_on_error"] = [RedisConnectionError, RedisTimeoutError]
+    return kwargs
+
+
+# Typed seams over redis-py 7.x async client stubs.
+#
+# redis-py 7.x annotates command methods with the shared sync/async signature
+# (``Awaitable[T] | T``), so ``await client.hgetall(...)`` fails type checking
+# even though the async client always returns an awaitable at runtime. These
+# helpers pin the async half of the hash commands, confining the required casts
+# to one place; they add no runtime behavior beyond a plain function call.
+
+
+def hgetall(client: AsyncRedis, key: str) -> Awaitable[dict[str, str]]:
+    """``client.hgetall(key)`` pinned to the async client's true awaitable return
+    (decoded-responses shape: a field/value string map, ``{}`` for a missing key)."""
+    return cast("Awaitable[dict[str, str]]", client.hgetall(key))
+
+
+def hset_mapping(client: AsyncRedis, key: str, mapping: Mapping[str, str]) -> Awaitable[int]:
+    """``client.hset(key, mapping=mapping)`` pinned to the async client's true
+    awaitable return (the count of newly added fields)."""
+    return cast("Awaitable[int]", client.hset(key, mapping=dict(mapping)))
+
+
+def scan_iter(client: AsyncRedis, match: str) -> AsyncIterator[Any]:
+    """``client.scan_iter(match=match)`` pinned to the async client's iterator."""
+    return cast("AsyncIterator[Any]", client.scan_iter(match=match))