prodkit 0.2.1__tar.gz → 0.3.0__tar.gz

{prodkit-0.2.1 → prodkit-0.3.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-14
+
+### Added
+- **Prometheus metrics plugin** (`pip install prodkit[metrics]`): request
+  count, latency histogram, in-flight gauge. Exposed at `/metrics` (or a
+  custom path). Metrics use route templates as labels (bounded cardinality).
+  Dedicated `CollectorRegistry` per instance — no global-state collisions.
+- **Cache plugin** (`cache={...}`): a named cache service published in the
+  registry under `"cache"`. Memory (per-process LRU with TTL) and Redis
+  (shared across workers) backends. Values must be JSON-serializable.
+- **OpenTelemetry tracing plugin** (`pip install prodkit[otel]`): automatic
+  request spans with W3C `traceparent` propagation, configurable sampler
+  (`sample_rate`), and OTLP/console/none exporters. The `TracerProvider` is
+  published in the registry as `"tracer"`.
+- **Redis backend for rate limiting** (`rate_limit.backend="redis"`): shared
+  aligned fixed-window counters across all workers and hosts. Fails open on
+  Redis errors (availability > strict limiting). Readiness check via `/ready`.
+
+### Changed
+- CI installs `otel` and `metrics` extras for full test coverage.
+- `TracingMiddleware` now uses `context.attach()`/`detach()` for correct W3C
+  trace context propagation (previously passed unsupported `context` kwarg).
+- Dev dependencies now include `anyio` and `pytest-anyio` for async tests.
+
+
 ## [0.2.1] - 2026-07-23
 
 ### Changed

{prodkit-0.2.1 → prodkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: prodkit
-Version: 0.2.1
+Version: 0.3.0
 Summary: The production framework for FastAPI. One line. Production ready.
 Project-URL: Homepage, https://github.com/Pushkarpant/PRODKIT
 Project-URL: Documentation, https://github.com/Pushkarpant/PRODKIT#readme
@@ -10,7 +10,7 @@ Project-URL: Issues, https://github.com/Pushkarpant/PRODKIT/issues
 Author-email: Pushkar Pant <pantpushkar4@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: fastapi,health-check,logging,middleware,observability,production,security
+Keywords: fastapi,health-check,logging,metrics,middleware,observability,opentelemetry,production,security,tracing
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
@@ -28,21 +28,44 @@ Requires-Dist: fastapi>=0.110
 Requires-Dist: pydantic-settings>=2.1
 Requires-Dist: pydantic>=2.5
 Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: brotli-asgi>=1.4; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
+Requires-Dist: prometheus-client>=0.20; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: rich>=13; extra == 'all'
+Requires-Dist: typer>=0.12; extra == 'all'
 Provides-Extra: brotli
 Requires-Dist: brotli-asgi>=1.4; extra == 'brotli'
 Provides-Extra: cli
 Requires-Dist: rich>=13; extra == 'cli'
 Requires-Dist: typer>=0.12; extra == 'cli'
 Provides-Extra: dev
+Requires-Dist: anyio[trio]>=4.0; extra == 'dev'
+Requires-Dist: fakeredis[lua]>=2.21; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: import-linter>=2.0; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pytest-anyio>=0.0.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: rich>=13; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: tomli>=2.0; extra == 'dev'
 Requires-Dist: typer>=0.12; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
 Description-Content-Type: text/markdown
 
 # ProdKit
@@ -99,8 +122,16 @@ pip install "prodkit[cli]"    # + the `prodkit doctor` CLI (typer + rich)
 ```
 
 Requires Python 3.10+ and FastAPI 0.110+. The base install depends only on
-FastAPI and Pydantic — nothing else. Optional extras: `cli` (CLI),
-`brotli` (Brotli compression).
+FastAPI and Pydantic — nothing else. Optional extras:
+
+| Extra | Adds |
+|---|---|
+| `cli` | `prodkit doctor` CLI (typer + rich) |
+| `metrics` | Prometheus `/metrics` endpoint |
+| `otel` | OpenTelemetry tracing (OTLP export) |
+| `redis` | Shared Redis backends (rate-limit, cache) |
+| `brotli` | Brotli compression |
+| `all` | Everything above |
 
 ## Quick Start
 
@@ -151,7 +182,10 @@ Production(app, environment="development")
 | ❤️ **Health endpoints** | `/health`, `/live` (liveness) and `/ready` (readiness — aggregates checks from every plugin, 503 until all pass). Kubernetes-native. |
 | 🌐 **CORS** | Explicit origins only; the wildcard-with-credentials footgun is refused at boot. |
 | 📦 **Compression** | Gzip for responses over 500 bytes. |
-| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. In-memory backend (Redis in v0.3). |
+| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. Memory or Redis backend (shared across workers). |
+| 📊 **Prometheus metrics** | Request count, latency histogram, in-flight gauge at `/metrics`. Route-template labels (bounded cardinality). `pip install prodkit[metrics]` |
+| 🗄️ **Cache service** | Memory (LRU + TTL) or Redis backend, published in the registry. `await cache.get(key)` / `.set(key, value, ttl=60)`. |
+| 🔭 **OpenTelemetry tracing** | Automatic request spans with W3C `traceparent` propagation. OTLP, console, or none exporter. `pip install prodkit[otel]` |
 | 🩺 **`prodkit doctor`** | CLI production-readiness audit with a 0–100 score. `--strict` gates CI. |
 | 🔌 **Plugin system** | Every feature above is a plugin. Write your own with optional hooks incl. `doctor()`. |
 
@@ -301,13 +335,13 @@ plugins score too.
 
 ## Project Status
 
-**v0.2.1 — alpha.** Core kernel, eight built-in plugins (incl. rate-limiting),
-the `prodkit doctor` CLI with a production-readiness score, strict mypy, CI
-across Python 3.10–3.13.
+**v0.3.0 — alpha.** Core kernel, eleven built-in plugins (metrics, cache, tracing,
+rate-limiting with Redis), the `prodkit doctor` CLI, strict mypy, CI across
+Python 3.10–3.13.
 
-Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), Prometheus metrics +
-Redis backends (v0.3), Dockerfile/nginx/CI generators (v0.4), public plugin SDK
-(v0.5), auth helpers (v0.6), stable API (v1.0).
+Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), ✅ Prometheus metrics +
+Redis backends + OpenTelemetry tracing (v0.3), Dockerfile/nginx/CI generators
+(v0.4), public plugin SDK (v0.5), auth helpers (v0.6), stable API (v1.0).
 Full details in [docs/ARCHITECTURE.md](https://github.com/Pushkarpant/PRODKIT/blob/main/docs/ARCHITECTURE.md).
 
 ## Contributing

{prodkit-0.2.1 → prodkit-0.3.0}/README.md

@@ -52,8 +52,16 @@ pip install "prodkit[cli]"    # + the `prodkit doctor` CLI (typer + rich)
 ```
 
 Requires Python 3.10+ and FastAPI 0.110+. The base install depends only on
-FastAPI and Pydantic — nothing else. Optional extras: `cli` (CLI),
-`brotli` (Brotli compression).
+FastAPI and Pydantic — nothing else. Optional extras:
+
+| Extra | Adds |
+|---|---|
+| `cli` | `prodkit doctor` CLI (typer + rich) |
+| `metrics` | Prometheus `/metrics` endpoint |
+| `otel` | OpenTelemetry tracing (OTLP export) |
+| `redis` | Shared Redis backends (rate-limit, cache) |
+| `brotli` | Brotli compression |
+| `all` | Everything above |
 
 ## Quick Start
 
@@ -104,7 +112,10 @@ Production(app, environment="development")
 | ❤️ **Health endpoints** | `/health`, `/live` (liveness) and `/ready` (readiness — aggregates checks from every plugin, 503 until all pass). Kubernetes-native. |
 | 🌐 **CORS** | Explicit origins only; the wildcard-with-credentials footgun is refused at boot. |
 | 📦 **Compression** | Gzip for responses over 500 bytes. |
-| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. In-memory backend (Redis in v0.3). |
+| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. Memory or Redis backend (shared across workers). |
+| 📊 **Prometheus metrics** | Request count, latency histogram, in-flight gauge at `/metrics`. Route-template labels (bounded cardinality). `pip install prodkit[metrics]` |
+| 🗄️ **Cache service** | Memory (LRU + TTL) or Redis backend, published in the registry. `await cache.get(key)` / `.set(key, value, ttl=60)`. |
+| 🔭 **OpenTelemetry tracing** | Automatic request spans with W3C `traceparent` propagation. OTLP, console, or none exporter. `pip install prodkit[otel]` |
 | 🩺 **`prodkit doctor`** | CLI production-readiness audit with a 0–100 score. `--strict` gates CI. |
 | 🔌 **Plugin system** | Every feature above is a plugin. Write your own with optional hooks incl. `doctor()`. |
 
@@ -254,13 +265,13 @@ plugins score too.
 
 ## Project Status
 
-**v0.2.1 — alpha.** Core kernel, eight built-in plugins (incl. rate-limiting),
-the `prodkit doctor` CLI with a production-readiness score, strict mypy, CI
-across Python 3.10–3.13.
+**v0.3.0 — alpha.** Core kernel, eleven built-in plugins (metrics, cache, tracing,
+rate-limiting with Redis), the `prodkit doctor` CLI, strict mypy, CI across
+Python 3.10–3.13.
 
-Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), Prometheus metrics +
-Redis backends (v0.3), Dockerfile/nginx/CI generators (v0.4), public plugin SDK
-(v0.5), auth helpers (v0.6), stable API (v1.0).
+Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), ✅ Prometheus metrics +
+Redis backends + OpenTelemetry tracing (v0.3), Dockerfile/nginx/CI generators
+(v0.4), public plugin SDK (v0.5), auth helpers (v0.6), stable API (v1.0).
 Full details in [docs/ARCHITECTURE.md](https://github.com/Pushkarpant/PRODKIT/blob/main/docs/ARCHITECTURE.md).
 
 ## Contributing

{prodkit-0.2.1 → prodkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "prodkit"
-version = "0.2.1"
+version = "0.3.0"
 description = "The production framework for FastAPI. One line. Production ready."
 readme = "README.md"
 license = "MIT"
@@ -19,6 +19,9 @@ keywords = [
     "observability",
     "logging",
     "health-check",
+    "metrics",
+    "tracing",
+    "opentelemetry",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -44,9 +47,19 @@ dependencies = [
 [project.optional-dependencies]
 brotli = ["brotli-asgi>=1.4"]
 cli = ["typer>=0.12", "rich>=13"]
+metrics = ["prometheus-client>=0.20"]
+redis = ["redis>=5.0"]
+otel = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.20",
+]
+all = ["prodkit[metrics,redis,otel,brotli,cli]"]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
+    "anyio[trio]>=4.0",
+    "pytest-anyio>=0.0.0",
     "httpx>=0.27",
     "ruff>=0.6",
     "mypy>=1.11",
@@ -54,6 +67,10 @@ dev = [
     "tomli>=2.0",  # so mypy (python_version=3.10) can type-check the fallback import
     "typer>=0.12",  # CLI is type-checked and tested in CI
     "rich>=13",
+    "prometheus-client>=0.20",
+    "fakeredis[lua]>=2.21",
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
 ]
 
 [project.scripts]

{prodkit-0.2.1 → prodkit-0.3.0}/src/prodkit/__init__.py

@@ -9,15 +9,18 @@ Production(app)
 
 from prodkit.contracts.plugin import Audit, Check, Plugin
 from prodkit.core.config import (
+    CacheConfig,
     CompressionConfig,
     CORSConfig,
     ErrorsConfig,
     HealthConfig,
     LoggingConfig,
+    MetricsConfig,
     ProdKitConfig,
     RateLimitConfig,
     RequestIDConfig,
     SecurityConfig,
+    TracingConfig,
 )
 from prodkit.core.context import Context
 from prodkit.core.exceptions import (
@@ -34,17 +37,19 @@ from prodkit.plugins import builtin_plugins
 # root — the kernel itself never imports from prodkit.plugins.
 set_builtin_factory(builtin_plugins)
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 __all__ = [
     "Audit",
     "CORSConfig",
+    "CacheConfig",
     "Check",
     "CompressionConfig",
     "Context",
     "ErrorsConfig",
     "HealthConfig",
     "LoggingConfig",
+    "MetricsConfig",
     "Plugin",
     "PluginDependencyError",
     "PluginError",
@@ -56,5 +61,6 @@ __all__ = [
     "RequestIDConfig",
     "SecurityConfig",
     "ServiceNotFoundError",
+    "TracingConfig",
     "__version__",
 ]

prodkit-0.3.0/src/prodkit/contracts/__init__.py

@@ -0,0 +1,5 @@
+"""ProdKit plugin contract and supporting types."""
+
+from prodkit.contracts.plugin import Audit, AuditStatus, Check, Plugin
+
+__all__ = ["Audit", "AuditStatus", "Check", "Plugin"]

{prodkit-0.2.1 → prodkit-0.3.0}/src/prodkit/contracts/plugin.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, ClassVar, Literal
 
@@ -72,8 +73,12 @@ class Plugin:
     async def shutdown(self, ctx: Context) -> None:
         """Release resources gracefully."""
 
-    def checks(self, ctx: Context) -> list[Check]:
-        """Readiness checks, aggregated by the health plugin's /ready."""
+    def checks(self, ctx: Context) -> list[Check] | Awaitable[list[Check]]:
+        """Readiness checks, aggregated by the health plugin's /ready.
+
+        May be overridden as ``async def`` (e.g. to ping a backend); the
+        health plugin awaits awaitable results.
+        """
         return []
 
     def doctor(self, ctx: Context) -> list[Audit]:
@@ -89,6 +94,7 @@ class Plugin:
 PRIORITY_REQUEST_ID = 100
 PRIORITY_LOGGING = 200
 PRIORITY_ERRORS = 250
+PRIORITY_TRACING = 290
 PRIORITY_METRICS = 300
 PRIORITY_SECURITY = 400
 PRIORITY_CORS = 500

{prodkit-0.2.1 → prodkit-0.3.0}/src/prodkit/core/config.py

@@ -93,7 +93,37 @@ class RateLimitConfig(_Section):
     enabled: bool = False  # opt-in: an unexpected 429 is worse than no limit
     # "<count>/<second|minute|hour>", parsed and validated by the plugin.
     default: str = "100/minute"
-    by: Literal["ip"] = "ip"  # v0.2 keys on client IP; per-user/route land later
+    by: Literal["ip"] = "ip"  # keys on client IP; per-user/route land later
+    # "memory" is per-process; "redis" shares the limit across workers/hosts.
+    backend: Literal["memory", "redis"] = "memory"
+    redis_url: str = "redis://localhost:6379/0"
+    key_prefix: str = "prodkit:ratelimit:"
+
+
+class MetricsConfig(_Section):
+    enabled: bool = False  # opt-in: needs prodkit[metrics]
+    path: str = "/metrics"
+    buckets: list[float] | None = None  # None -> prometheus-client defaults
+    # Paths never measured (the metrics path itself is always excluded).
+    exclude_paths: list[str] = Field(default_factory=list)
+
+
+class CacheConfig(_Section):
+    enabled: bool = False  # opt-in: a service other code asks for, not middleware
+    backend: Literal["memory", "redis"] = "memory"
+    redis_url: str = "redis://localhost:6379/0"
+    default_ttl: int = 300  # seconds; 0 = no expiry
+    key_prefix: str = "prodkit:cache:"
+    max_entries: int = 1024  # memory backend LRU bound
+
+
+class TracingConfig(_Section):
+    enabled: bool = False  # opt-in: needs prodkit[otel]
+    service_name: str | None = None  # None -> the FastAPI app's title
+    exporter: Literal["otlp", "console", "none"] = "otlp"
+    # None defers to the standard OTEL_EXPORTER_OTLP_* environment variables.
+    endpoint: str | None = None
+    sample_rate: float = Field(default=1.0, ge=0.0, le=1.0)
 
 
 class ProdKitConfig(_Section):
@@ -109,6 +139,9 @@ class ProdKitConfig(_Section):
     cors: CORSConfig = Field(default_factory=CORSConfig)
     compression: CompressionConfig = Field(default_factory=CompressionConfig)
     rate_limit: RateLimitConfig = Field(default_factory=RateLimitConfig)
+    metrics: MetricsConfig = Field(default_factory=MetricsConfig)
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+    tracing: TracingConfig = Field(default_factory=TracingConfig)
 
 
 # Profile defaults: applied beneath toml/env/args. The one-liner must be

{prodkit-0.2.1 → prodkit-0.3.0}/src/prodkit/core/production.py

@@ -45,6 +45,9 @@ _TOGGLEABLE = (
     "cors",
     "compression",
     "rate_limit",
+    "metrics",
+    "cache",
+    "tracing",
 )
 
 

{prodkit-0.2.1 → prodkit-0.3.0}/src/prodkit/plugins/__init__.py

@@ -10,14 +10,17 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from prodkit.plugins.cache import CachePlugin
 from prodkit.plugins.compression import CompressionPlugin
 from prodkit.plugins.cors import CORSPlugin
 from prodkit.plugins.errors import ErrorsPlugin
 from prodkit.plugins.health import HealthPlugin
 from prodkit.plugins.logging import LoggingPlugin
+from prodkit.plugins.metrics import MetricsPlugin
 from prodkit.plugins.rate_limit import RateLimitPlugin
 from prodkit.plugins.request_id import RequestIDPlugin
 from prodkit.plugins.security import SecurityPlugin
+from prodkit.plugins.tracing import TracingPlugin
 
 if TYPE_CHECKING:
     from prodkit.contracts.plugin import Plugin
@@ -25,13 +28,16 @@ if TYPE_CHECKING:
 
 __all__ = [
     "CORSPlugin",
+    "CachePlugin",
     "CompressionPlugin",
     "ErrorsPlugin",
     "HealthPlugin",
     "LoggingPlugin",
+    "MetricsPlugin",
     "RateLimitPlugin",
     "RequestIDPlugin",
     "SecurityPlugin",
+    "TracingPlugin",
     "builtin_plugins",
 ]
 
@@ -55,4 +61,10 @@ def builtin_plugins(config: ProdKitConfig) -> list[Plugin]:
         plugins.append(RateLimitPlugin())
     if config.compression.enabled:
         plugins.append(CompressionPlugin())
+    if config.metrics.enabled:
+        plugins.append(MetricsPlugin())
+    if config.cache.enabled:
+        plugins.append(CachePlugin())
+    if config.tracing.enabled:
+        plugins.append(TracingPlugin())
     return plugins

prodkit-0.3.0/src/prodkit/plugins/_redis.py

@@ -0,0 +1,34 @@
+"""Shared Redis client construction for plugins with a Redis backend.
+
+The optional ``redis`` dependency is imported lazily here — plugin modules are
+imported unconditionally by ``prodkit.plugins``, so a missing extra must not
+break ``import prodkit``. It fails at plugin ``configure()`` time instead, with
+an actionable message. This function is also the single seam tests monkeypatch
+to inject a fake client (fakeredis).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from prodkit.core.exceptions import ProdKitConfigError
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+def create_client(url: str, *, section: str = "redis") -> Redis:
+    """Create an async Redis client, or fail with a named-section pip hint.
+
+    The client connects lazily (on first command), so calling this at boot is
+    cheap; reachability is verified by the owning plugin's ``startup()`` ping.
+    """
+    try:
+        from redis.asyncio import Redis
+    except ImportError:
+        raise ProdKitConfigError(
+            f"{section}: backend='redis' requires the redis package. "
+            "Install it with: pip install 'prodkit[redis]'"
+        ) from None
+    client: Any = Redis.from_url(url)
+    return client  # type: ignore[no-any-return]

prodkit-0.3.0/src/prodkit/plugins/cache/__init__.py

@@ -0,0 +1,150 @@
+"""Cache plugin: a named cache service other plugins and user code can share.
+
+The service is published in the registry under ``"cache"``::
+
+    cache = ctx.registry.get("cache")
+    await cache.set("user:42", {"name": "Ada"}, ttl=60)
+    user = await cache.get("user:42")
+
+Two backends: ``memory`` (per-process LRU with TTL, the default) and ``redis``
+(shared across workers/hosts). Values must be JSON-serializable so behavior is
+identical across backends.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol
+
+from prodkit.contracts.plugin import Audit, Check, Plugin
+from prodkit.core.context import Context
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+class CacheService(Protocol):
+    """The contract of the registry's ``"cache"`` service.
+
+    ``ttl=None`` means the configured default TTL; ``ttl=0`` means no expiry.
+    """
+
+    async def get(self, key: str) -> Any | None: ...
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None: ...
+
+    async def delete(self, key: str) -> None: ...
+
+
+class MemoryCache:
+    """Per-process LRU cache with monotonic-deadline TTLs (lazy expiry)."""
+
+    def __init__(self, default_ttl: int, max_entries: int) -> None:
+        self.default_ttl = default_ttl
+        self.max_entries = max_entries
+        # key -> (deadline_monotonic | None, value); insertion order = LRU order
+        self._data: OrderedDict[str, tuple[float | None, Any]] = OrderedDict()
+
+    def _deadline(self, ttl: int | None) -> float | None:
+        effective = self.default_ttl if ttl is None else ttl
+        return None if effective == 0 else time.monotonic() + effective
+
+    async def get(self, key: str) -> Any | None:
+        item = self._data.get(key)
+        if item is None:
+            return None
+        deadline, value = item
+        if deadline is not None and time.monotonic() >= deadline:
+            del self._data[key]
+            return None
+        self._data.move_to_end(key)
+        return value
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        self._data[key] = (self._deadline(ttl), value)
+        self._data.move_to_end(key)
+        while len(self._data) > self.max_entries:
+            self._data.popitem(last=False)  # evict least recently used
+
+    async def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+
+class RedisCache:
+    """Redis-backed cache; values JSON-encoded, keys prefixed."""
+
+    def __init__(self, url: str, default_ttl: int, prefix: str) -> None:
+        self.default_ttl = default_ttl
+        self.prefix = prefix
+        from prodkit.plugins._redis import create_client
+
+        self._client: Redis = create_client(url, section="cache")
+
+    async def get(self, key: str) -> Any | None:
+        raw = await self._client.get(self.prefix + key)
+        return None if raw is None else json.loads(raw)
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        effective = self.default_ttl if ttl is None else ttl
+        await self._client.set(
+            self.prefix + key,
+            json.dumps(value),
+            ex=effective if effective > 0 else None,
+        )
+
+    async def delete(self, key: str) -> None:
+        await self._client.delete(self.prefix + key)
+
+    async def ping(self) -> None:
+        await self._client.ping()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+class CachePlugin(Plugin):
+    name: ClassVar[str] = "cache"
+
+    def __init__(self) -> None:
+        self._cache: CacheService | None = None
+
+    def configure(self, ctx: Context) -> None:
+        cfg = ctx.config.cache
+        if cfg.backend == "redis":
+            # create_client raises a named ProdKitConfigError if the redis
+            # extra is missing; connection itself is verified in startup().
+            self._cache = RedisCache(cfg.redis_url, cfg.default_ttl, cfg.key_prefix)
+        else:
+            self._cache = MemoryCache(cfg.default_ttl, cfg.max_entries)
+        ctx.registry.provide("cache", self._cache)
+
+    async def startup(self, ctx: Context) -> None:
+        if isinstance(self._cache, RedisCache):
+            # Fail fast at boot if Redis is unreachable.
+            await self._cache.ping()
+
+    async def shutdown(self, ctx: Context) -> None:
+        if isinstance(self._cache, RedisCache):
+            await self._cache.aclose()
+
+    async def checks(self, ctx: Context) -> list[Check]:
+        if not isinstance(self._cache, RedisCache):
+            return []
+        try:
+            await self._cache.ping()
+        except Exception as exc:
+            return [Check(name="cache-redis", passed=False, detail=str(exc))]
+        return [Check(name="cache-redis", passed=True, detail="reachable")]
+
+    def doctor(self, ctx: Context) -> list[Audit]:
+        cfg = ctx.config.cache
+        return [
+            Audit(
+                name="Cache",
+                status="ok",
+                detail=f"{cfg.backend} backend, default_ttl={cfg.default_ttl}s",
+                weight=5,
+            )
+        ]