techai-webutils 0.1.0__tar.gz

techai_webutils-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.3
+Name: techai-webutils
+Version: 0.1.0
+Summary: techai-webutils
+Author: Tech AI at Georgia Institute of Technology
+License: MIT
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiobotocore>=3.5.0
+Requires-Dist: aiosmtplib>=3.0.0
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: grpcio>=1.80.0
+Requires-Dist: grpcio-health-checking>=1.80.0
+Requires-Dist: grpcio-reflection>=1.80.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: opentelemetry-api>=1.41.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.41.0
+Requires-Dist: opentelemetry-sdk>=1.41.0
+Requires-Dist: prometheus-client>=0.25.0
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: qdrant-client>=1.12.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: redis>=7.4.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: uvicorn>=0.48.0
+Requires-Dist: protovalidate>=2.0.0,<3
+Requires-Dist: langdetect>=1.0.9 ; extra == 'langdetect'
+Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6 ; extra == 'parsing'
+Requires-Dist: pymupdf>=1.28.0 ; extra == 'parsing'
+Requires-Dist: asyncpg>=0.30.0 ; extra == 'postgres'
+Requires-Dist: ray==2.56.1 ; extra == 'ray'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/gt-tech-ai/knowledge-engine
+Project-URL: Documentation, https://github.com/gt-tech-ai/knowledge-engine
+Project-URL: Repository, https://github.com/gt-tech-ai/knowledge-engine
+Provides-Extra: langdetect
+Provides-Extra: parsing
+Provides-Extra: postgres
+Provides-Extra: ray
+Description-Content-Type: text/markdown
+

techai_webutils-0.1.0/pyproject.toml

@@ -0,0 +1,164 @@
+[project]
+name = "techai-webutils"
+version = "0.1.0"
+description = "techai-webutils"
+requires-python = ">= 3.12"
+dependencies = [
+    "aiobotocore>=3.5.0",
+    "aiosmtplib>=3.0.0",
+    "fastapi>=0.136.0",
+    "grpcio>=1.80.0",
+    "grpcio-health-checking>=1.80.0",
+    "grpcio-reflection>=1.80.0",
+    "httpx>=0.28.1",
+    "opentelemetry-api>=1.41.0",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.41.0",
+    "opentelemetry-sdk>=1.41.0",
+    "prometheus-client>=0.25.0",
+    "pydantic>=2.13.3",
+    "pydantic-settings>=2.14.1",
+    "qdrant-client>=1.12.0",
+    "pyyaml>=6.0.3",
+    "redis>=7.4.0",
+    "structlog>=25.5.0",
+    "tenacity>=9.1.4",
+    "uvicorn>=0.48.0",
+    "protovalidate>=2.0.0,<3",
+]
+classifiers = [
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.readme]
+text = ""
+content-type = "text/markdown"
+
+[[project.authors]]
+name = "Tech AI at Georgia Institute of Technology"
+
+[project.optional-dependencies]
+ray = ["ray==2.56.1"]
+postgres = ["asyncpg>=0.30.0"]
+parsing = [
+    "markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6",
+    "pymupdf>=1.28.0",
+]
+langdetect = ["langdetect>=1.0.9"]
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/gt-tech-ai/knowledge-engine"
+Documentation = "https://github.com/gt-tech-ai/knowledge-engine"
+Repository = "https://github.com/gt-tech-ai/knowledge-engine"
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "autogitsemver>=0.9.13",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=7.1.0",
+    "ray==2.56.1",
+    "ruff>=0.15.13",
+    "basedpyright>=1.31",
+    "asyncpg>=0.30.0",
+    "markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6",
+    "pymupdf>=1.28.0",
+    "langdetect>=1.0.9",
+    "testcontainers[postgres,redis]>=4.14.2",
+    "ty>=0.0.38",
+]
+
+[tool.pytest.ini_options]
+addopts = "--verbose -vv --capture=no --strict-markers --cov=techai_webutils --cov-report html --cov-report term --cov-report xml:coverage.xml --cov-fail-under=90.0"
+markers = [
+    "integration: real-dependency tests via testcontainers (Docker required); deselected in the unit run",
+    "slow: slow tests, deselected with --fast",
+]
+
+[tool.coverage.run]
+relative_files = true
+data_file = "coverage_unit.dat"
+
+[tool.coverage.report]
+omit = [
+    "*/clients/transport/grpc/server.py",
+    "*/clients/rpc/grpc/interceptors/tracing.py",
+    "*/clients/rpc/grpc/interceptors/tracing_server.py",
+    "*/clients/messaging/sqs/sqs_publisher.py",
+    "*/clients/messaging/sqs/sqs_subscriber.py",
+    "*/foundation/resilience/sqs_dlq.py",
+    "*/clients/storage/s3/s3_client.py",
+    "*/clients/llm/bedrock/*.py",
+    "*/clients/retrieval/bedrock/*.py",
+    "*/clients/kb_ingestion/bedrock/*.py",
+    "*/clients/email/ses/provider.py",
+    "*/clients/email/smtp/provider.py",
+    "*/clients/cache/redis/cache.py",
+    "*/foundation/tracer/tracer.py",
+    "*/foundation/observability.py",
+    "*/execution/executor/real_ray_runtime.py",
+]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+exclude = ["tests/**"]
+select = ["ALL"]
+ignore = [
+    "ANN002",
+    "ANN003",
+    "BLE001",
+    "COM812",
+    "CPY001",
+    "D105",
+    "D107",
+    "D202",
+    "D203",
+    "D213",
+    "E501",
+    "FIX002",
+    "I001",
+    "N802",
+    "N999",
+    "RSE102",
+    "S101",
+    "TC006",
+    "TD002",
+    "TD003",
+    "TRY002",
+    "TRY300",
+    "UP032",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/techai_webutils/clients/llm/bedrock/*.py" = ["N803"]
+"src/techai_webutils/clients/retrieval/bedrock/*.py" = ["N803"]
+"src/techai_webutils/clients/kb_ingestion/bedrock/*.py" = ["N803"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.pylint]
+max-args = 10
+max-branches = 20
+max-returns = 20
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+include = ["src/techai_webutils"]
+exclude = ["tests"]
+
+[tool.uv.build-backend]
+module-name = "techai_webutils"

techai_webutils-0.1.0/pyproject.toml.orig

@@ -0,0 +1,235 @@
+[project]
+name = "techai-webutils"
+version = "0.1.0"
+#          ^^^^^
+# Wheel names will be generated according to this value. Do not manually modify this value; instead
+# update it according to committed changes by running this command from the root of the repository:
+#
+#   uv run python -m AutoGitSemVer.scripts.UpdatePythonVersion ./pyproject.toml ./src
+
+description = "techai-webutils"
+readme = { text = "", content-type = "text/markdown" }
+authors = [
+    { name = "Tech AI at Georgia Institute of Technology" }
+]
+requires-python = ">= 3.12"
+dependencies = [
+    "aiobotocore>=3.5.0",
+    # aiosmtplib: async SMTP send for the SMTP email backend (clients/email/smtp); lazy-imported by
+    # email_from_config only on the SMTP path. Peer of aiobotocore (the SES backend's transport).
+    "aiosmtplib>=3.0.0",
+    "fastapi>=0.136.0",
+    "grpcio>=1.80.0",
+    "grpcio-health-checking>=1.80.0",
+    "grpcio-reflection>=1.80.0",
+    "httpx>=0.28.1",
+    "opentelemetry-api>=1.41.0",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.41.0",
+    "opentelemetry-sdk>=1.41.0",
+    "prometheus-client>=0.25.0",
+    "pydantic>=2.13.3",
+    "pydantic-settings>=2.14.1",
+    "qdrant-client>=1.12.0",
+    "pyyaml>=6.0.3",
+    "redis>=7.4.0",
+    "structlog>=25.5.0",
+    "tenacity>=9.1.4",
+    "uvicorn>=0.48.0",
+    "protovalidate>=2.0.0,<3",
+]
+classifiers = [
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+# Distributed execution backend (RayExecutor + RealRayRuntime). Optional and heavy:
+# only the S3 bulk-ingestion job installs `techai-webutils[ray]`. The default
+# asyncio path (AsyncioExecutor) never pulls Ray — the RayRuntime protocol and
+# RayExecutor carry no `ray` import; only RealRayRuntime does, imported lazily by
+# `executor_from_config` when `ingestion.executor.kind: ray`.
+#
+# ⚠ Ray requires the driver and the cluster to run the SAME version. Pinned EXACTLY to match the
+# `ray-head` Compose image (rayproject/ray:2.56.1-py312), the KubeRay cluster, AND the Ray
+# testcontainer in the integration tests — `ray://` rejects a version mismatch. Bump this pin, the
+# dev-group `ray` pin below, and the compose/KubeRay image together when upgrading Ray.
+ray = ["ray==2.56.1"]
+
+# Cross-pod single-writer lock backend (PostgresAdvisoryLock). Optional: only the
+# ingestion worker installs `techai-webutils[postgres]`. The default in-memory lock never pulls
+# asyncpg — the `postgres` backend impl is imported lazily by `lock_from_config` when
+# `ingestion.lock.kind: postgres`.
+postgres = ["asyncpg>=0.30.0"]
+
+# Document-parsing backend (the `isolated` parser: MarkItDown + pymupdf). Optional and heavy: only a
+# parse-running deployable (the ingestion worker) installs `techai-webutils[parsing]`. The
+# `clients/parsing` factory + interface never import these — the `isolated` backend imports them
+# lazily inside its parse methods / the forkserver, so the default import graph never pulls them.
+parsing = ["markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6", "pymupdf>=1.28.0"]
+
+# Language-detection backend (the `langdetect` MetadataExtractor). Optional: only a
+# metadata-extracting deployable installs `techai-webutils[langdetect]`. The `clients/metadata`
+# factory never imports it — the `langdetect` backend subpackage is imported lazily by
+# `metadata_extractor_from_config`, so the default import graph never pulls it.
+langdetect = ["langdetect>=1.0.9"]
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/gt-tech-ai/knowledge-engine"
+Documentation = "https://github.com/gt-tech-ai/knowledge-engine"
+Repository = "https://github.com/gt-tech-ai/knowledge-engine"
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "autogitsemver>=0.9.13",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=7.1.0",
+    # Installed in dev/CI so basedpyright can resolve RealRayRuntime's `import ray` and the real-Ray
+    # integration tests (@pytest.mark.integration) can run against a Ray testcontainer; production
+    # consumers pull it via the `ray` extra, not this group. Pinned EXACTLY to the same version as the
+    # `ray` extra + the ray-head image so the ray:// driver matches the cluster (see the extra above).
+    "ray==2.56.1",
+    "ruff>=0.15.13",
+    "basedpyright>=1.31",
+    # asyncpg in dev so basedpyright resolves `import asyncpg` in the postgres lock backend and the
+    # real-Postgres integration test can run; production consumers pull it via the `postgres` extra.
+    "asyncpg>=0.30.0",
+    # markitdown + pymupdf in dev so basedpyright resolves the `isolated` parser backend's lazy
+    # imports and its parity tests (real conversion + real subprocess isolation) run; production
+    # consumers pull them via the `parsing` extra.
+    "markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6",
+    "pymupdf>=1.28.0",
+    # langdetect in dev so basedpyright resolves the `langdetect` metadata backend and its parity
+    # tests run; production consumers pull it via the `langdetect` extra.
+    "langdetect>=1.0.9",
+    "testcontainers[postgres,redis]>=4.14.2",
+    "ty>=0.0.38",
+]
+
+[tool.pytest.ini_options]
+# tests/ is put on sys.path by pytest's default prepend import mode (there is no
+# tests/__init__.py). Test doubles are built inline with unittest.mock in each
+# test (spec-bound to the real core interfaces), so no shared test-double package
+# and no pythonpath directive are needed.
+# Phase 3: hand-written unit coverage is gated at >=90%. The earlier "91.6% vs
+# 83.4%" pytest-vs-`python -m pytest` discrepancy did NOT reproduce (both paths
+# measure identically) — it was a stale-`.coverage` artifact. The real driver of
+# the sub-90 reading was the denominator: integration-only external wrappers (gRPC
+# server factory + OTel tracing interceptors, SQS/S3/Redis clients, OTel tracer/
+# observability). Those are carved out below (covered by the Phase-4 integration
+# suite, the Python equivalent of Go's unit-only carve-outs); the genuinely
+# unit-testable interceptor logic was tested instead of excluded.
+addopts = "--verbose -vv --capture=no --strict-markers --cov=techai_webutils --cov-report html --cov-report term --cov-report xml:coverage.xml --cov-fail-under=90.0"
+# Registered markers (enforced by --strict-markers, so a typo'd/unregistered marker
+# now errors instead of silently passing). `integration` tests need a Docker daemon
+# (testcontainers) and are deselected from the default unit run via `-m "not integration"`.
+markers = [
+    "integration: real-dependency tests via testcontainers (Docker required); deselected in the unit run",
+    "slow: slow tests, deselected with --fast",
+]
+
+[tool.coverage.run]
+# relative_files + a distinct (non-hidden, so GitHub upload-artifact keeps it)
+# data file let the combined coverage GATE merge this unit dataset with the
+# integration dataset across separate CI jobs (see the `python-coverage-gate` job
+# + .coveragerc.combined). `search test unit --python` writes coverage_unit.dat;
+# the integration run writes coverage_integration.dat; the gate combines them.
+relative_files = true
+data_file = "coverage_unit.dat"
+
+[tool.coverage.report]
+# Excluded from the UNIT denominator (>=90% gate is over hand-written, unit-testable
+# logic). Each entry is either test infrastructure or a thin external-dependency
+# wrapper whose uncovered lines are the real network/SDK calls — exercised by the
+# Phase-4 integration suite, not unit tests. Mirrors Go's unit-only carve-out set.
+#
+# This omit is at REPORT time (not [run]) so the unit run still MEASURES the
+# wrappers — their partial unit coverage then lands in .coverage.unit and merges
+# into the combined gate (.coveragerc.combined), which counts the wrappers.
+omit = [
+    "*/clients/transport/grpc/server.py",                        # gRPC server factory (binds/serves) — integration
+    "*/clients/rpc/grpc/interceptors/tracing.py",          # OTel client span wiring — integration/runtime
+    "*/clients/rpc/grpc/interceptors/tracing_server.py",   # OTel server span wiring — integration/runtime
+    "*/clients/messaging/sqs/sqs_publisher.py",        # boto3 SQS send — integration (ElasticMQ)
+    "*/clients/messaging/sqs/sqs_subscriber.py",       # boto3 SQS receive loop — integration (ElasticMQ)
+    "*/foundation/resilience/sqs_dlq.py",              # boto3 SQS DLQ send — integration (ElasticMQ)
+    "*/clients/storage/s3/s3_client.py",               # boto3 S3 client — integration (MinIO)
+    "*/clients/llm/bedrock/*.py",                      # aiobotocore bedrock-runtime wrapper — integration/runtime
+    "*/clients/retrieval/bedrock/*.py",                # aiobotocore bedrock-agent-runtime wrapper — integration/runtime
+    "*/clients/kb_ingestion/bedrock/*.py",                       # aiobotocore bedrock-agent KB ingestion — integration/runtime
+    "*/clients/email/ses/provider.py",                 # aiobotocore SESv2 send — E2E only (staging/prod SES)
+    "*/clients/email/smtp/provider.py",                # aiosmtplib SMTP send — E2E only (dev Mailpit)
+    "*/clients/cache/redis/cache.py",              # aioredis wrapper — integration (Redis)
+    "*/foundation/tracer/tracer.py",                   # OTel tracer SDK init — integration/runtime
+    "*/foundation/observability.py",                   # OTel observability bootstrap — integration/runtime
+    "*/execution/executor/real_ray_runtime.py",        # ray.init + @ray.remote wrapper — integration (real Ray)
+]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+exclude = ["tests/**"]
+
+select = ["ALL"]
+
+ignore = [
+    "ANN002", # Missing type annotation for `*args`
+    "ANN003", # Missing type annotation for `**kwargs`
+    "BLE001", # Do not catch blind exception: `Exception`
+    "COM812", # Trailing comma missing
+    "CPY001", # flake8-copyright: repo does not use file copyright headers
+    "D105", # Missing docstring in magic method
+    "D107", # Missing docstring in `__init__` method
+    "D202", # No blank lines allowed after function docstring
+    "D203", # 1 blank line before class docstring (conflicts with D211; ruff keeps D211)
+    "D213", # Multi-line summary on second line (conflicts with D212; ruff keeps D212)
+    "E501", # Line too long
+    "FIX002", # Line contains TODO, consider resolving the issue
+    "I001", # Import block is un-sorted or un-formatted
+    "N802", # Function name `xxx` should be lowercase
+    "N999", # Invalid module name
+    "RSE102", # Unnecessary parentheses on raise exception
+    "S101", # Use of assert detected
+    "TC006", # Add quotes to type expression in `typing.cast()`
+    "TD002", # Missing author in TODO
+    "TD003", # Missing issue link for this TODO
+    "TRY002", # Create your own exception
+    "TRY300", # Consider moving this statement to an `else` block
+    "UP032", # Use f-string instead of `format` call
+]
+
+[tool.ruff.lint.per-file-ignores]
+# The bedrock clients mirror the AWS bedrock-runtime / bedrock-agent-runtime / bedrock-agent APIs, whose
+# keyword params are camelCase (knowledgeBaseId, modelId, retrievalQuery, dataSourceId, …) — N803 does
+# not apply to a wire mirror.
+"src/techai_webutils/clients/llm/bedrock/*.py" = ["N803"]
+"src/techai_webutils/clients/retrieval/bedrock/*.py" = ["N803"]
+"src/techai_webutils/clients/kb_ingestion/bedrock/*.py" = ["N803"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.pylint]
+max-args = 10
+max-branches = 20
+max-returns = 20
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+include = ["src/techai_webutils"]
+exclude = ["tests"]
+
+[tool.uv.build-backend]
+module-name = "techai_webutils"

techai_webutils-0.1.0/src/techai_webutils/__init__.py

@@ -0,0 +1,5 @@
+"""TechAI web utilities shared library."""
+
+from importlib.metadata import version
+
+__version__ = version("techai_webutils")

techai_webutils-0.1.0/src/techai_webutils/clients/__init__.py

@@ -0,0 +1,8 @@
+"""Clients layer - external system integration abstractions.
+
+This layer contains gRPC client/server factories, decorators, messaging (SQS),
+storage (S3), cache decorators, and integration code for external systems.
+
+Clients implements the third layer in the nine-layer architecture model:
+core -> foundation -> clients -> repos -> services -> pipelines -> workflows -> controllers
+"""

techai_webutils-0.1.0/src/techai_webutils/clients/cache/__init__.py

@@ -0,0 +1,35 @@
+"""Cache client tier — config-selected backends (redis/local/null) + decorators.
+
+Mirrors Go's ``clients/cache``: ``builder.py`` selects a backend by ``CacheKind`` and returns the
+core ``Cache`` interface; each backend lives in its own subpackage (``redis``/``local``/``null``);
+``decorators.py`` wraps a cache with logging + metrics. Relocated from ``foundation/cache`` (D2) so the
+concrete backends sit at the clients tier (L2, external-system integration), matching Go.
+"""
+
+from techai_webutils.clients.cache.builder import (
+    CacheConfig,
+    CacheKind,
+    default_config,
+    new_cache_from_config,
+)
+from techai_webutils.clients.cache.decorators import CacheBuilder
+from techai_webutils.clients.cache.envelope import CacheEnvelope, decode, encode
+from techai_webutils.clients.cache.local import LocalCache
+from techai_webutils.clients.cache.null import NullCache
+from techai_webutils.clients.cache.redis import RedisCache
+from techai_webutils.clients.cache.types import FailureMode
+
+__all__ = [
+    "CacheBuilder",
+    "CacheConfig",
+    "CacheEnvelope",
+    "CacheKind",
+    "FailureMode",
+    "LocalCache",
+    "NullCache",
+    "RedisCache",
+    "decode",
+    "default_config",
+    "encode",
+    "new_cache_from_config",
+]

techai_webutils-0.1.0/src/techai_webutils/clients/cache/builder.py

@@ -0,0 +1,87 @@
+"""Cache builder with kind enum, config dataclass, and factory function.
+
+Creates cache instances based on configuration. Supports REDIS, LOCAL, and NULL
+cache kinds. The factory function routes to the correct implementation based on
+the CacheKind in the config.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, TYPE_CHECKING
+
+from techai_webutils.clients.cache.local import LocalCache
+from techai_webutils.clients.cache.null import NullCache
+from techai_webutils.clients.cache.redis import RedisCache
+from techai_webutils.clients.cache.types import FailureMode
+
+if TYPE_CHECKING:
+    from techai_webutils.core.interfaces.cache import Cache
+
+
+class CacheKind(StrEnum):
+    """Available cache implementations."""
+
+    REDIS = "redis"
+    """The Redis-backed cache (shared, cross-pod; stage/prod)."""
+    LOCAL = "local"
+    """The in-process TTL cache (single-pod; dev/test)."""
+    NULL = "null"
+    """The no-op cache that never stores or returns a value (caching disabled)."""
+
+
+@dataclass
+class CacheConfig:
+    """Configuration for cache creation.
+
+    Attributes:
+        kind: Which cache implementation to use.
+        default_ttl: Default TTL in seconds.
+        redis_client: An async Redis client instance (required when kind is REDIS).
+        failure_mode: Redis failure mode (only used when kind is REDIS).
+
+    """
+
+    kind: CacheKind = CacheKind.LOCAL
+    """Selects the cache implementation (defaults to the in-process LOCAL cache)."""
+    default_ttl: int = 300
+    """Default time-to-live for cached entries, in seconds."""
+    redis_client: Any = None
+    """An async Redis client instance (required when ``kind`` is REDIS)."""
+    failure_mode: FailureMode = FailureMode.BYPASS
+    """How a Redis failure is handled (only used when ``kind`` is REDIS)."""
+
+
+def default_config() -> CacheConfig:
+    """Return a default cache config (LOCAL with 300s TTL)."""
+    return CacheConfig(kind=CacheKind.LOCAL, default_ttl=300)
+
+
+def new_cache_from_config(config: CacheConfig) -> Cache:
+    """Create a cache instance from config.
+
+    Args:
+        config: Cache configuration specifying kind and parameters.
+
+    Returns:
+        A Cache implementation matching the requested kind.
+
+    Raises:
+        ValueError: If the kind is unknown or required parameters are missing.
+
+    """
+    if config.kind == CacheKind.LOCAL:
+        return LocalCache(default_ttl=config.default_ttl)
+
+    if config.kind == CacheKind.NULL:
+        return NullCache()
+
+    if config.kind == CacheKind.REDIS:
+        if config.redis_client is None:
+            msg = "redis_client is required when kind is REDIS"
+            raise ValueError(msg)
+        return RedisCache(client=config.redis_client, failure_mode=config.failure_mode)
+
+    msg = f"unknown cache kind: {config.kind}"
+    raise ValueError(msg)