omkit 0.0.2__py3-none-any.whl

omkit/platform/__init__.py

@@ -0,0 +1,18 @@
+"""omkit.platform — re-exports platform primitives.
+
+Settings + sync notification + lazy model lifecycle helpers. Additive
+grouping; flat imports still work.
+"""
+
+from omkit.config import BaseServiceSettings
+from omkit.model_lifecycle import ModelLifecycle, ModelRegistry
+from omkit.settings import SettingsManager
+from omkit.sync_notifier import SyncNotifier
+
+__all__ = [
+    "BaseServiceSettings",
+    "ModelLifecycle",
+    "ModelRegistry",
+    "SettingsManager",
+    "SyncNotifier",
+]

omkit/providers/__init__.py

@@ -0,0 +1,11 @@
+"""packages/omur-sdk/omkit/providers/__init__.py — Package init for providers.
+
+exports: none
+rules:   none
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+from .base import ProviderBase, ProviderDocument, ProviderMetric
+from .registry import ProviderRegistry
+
+__all__ = ["ProviderBase", "ProviderDocument", "ProviderMetric", "ProviderRegistry"]

omkit/providers/base.py

@@ -0,0 +1,76 @@
+"""packages/omur-sdk/omkit/providers/base.py — ProviderBase ABC and shared data contracts for all Omur providers.
+
+exports: class ProviderDocument | class ProviderMetric | class ProviderBase
+rules:   All provider classes must inherit from ProviderBase and implement the run() method, with ProviderMetric values must be coercible to float.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ProviderDocument(BaseModel):
+    """Document emitted by an indexer provider."""
+    source: str
+    source_id: str
+    title: str
+    content: str
+    doc_type: str | None = None
+    doc_date: str | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProviderMetric(BaseModel):
+    """Time-series metric emitted by a collector or sensor provider."""
+    source: str
+    metric: str
+    value: float
+    unit: str
+    ts: int           # nanoseconds UTC epoch
+    tenant_id: str
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def coerce_value(cls, v: Any) -> float:
+        """
+        Rules:   Input value must be convertible to float, otherwise float() will raise ValueError. Future developers should ensure proper error handling for non-numeric inputs.
+        """
+        return float(v)
+
+
+class ProviderBase(ABC):
+    """
+    Base class for all Omur data providers.
+
+    Subclasses must declare class-level `kind` and `name` and implement `run()`.
+    `run()` is called once per active tenant instance and must handle
+    asyncio.CancelledError for clean shutdown.
+    """
+
+    kind: str   # 'collector' | 'indexer' | 'sensor'
+    name: str   # e.g. 'fitbit', 'gdrive', 'weather_station'
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not getattr(cls, "__abstractmethods__", None):
+            for attr in ("kind", "name"):
+                if not isinstance(cls.__dict__.get(attr), str):
+                    raise TypeError(f"{cls.__name__} must define class attribute '{attr}' as a str")
+
+    def __init__(self, tenant_id: str, config: dict[str, Any]) -> None:
+        self.tenant_id = tenant_id
+        self.config = config
+
+    @abstractmethod
+    async def run(self) -> None:
+        """Main loop. Must handle asyncio.CancelledError for clean shutdown.
+
+        Rules:   Must handle asyncio.CancelledError for clean shutdown. Future developers MUST know that this function is the main execution loop and any cleanup logic should be implemented in response to cancellation.
+        """
+        ...

omkit/providers/registry.py

@@ -0,0 +1,263 @@
+"""packages/omur-sdk/omkit/providers/registry.py — loads providers from DB, manages asyncio tasks, hot-reloads via Valkey.
+
+exports: DEFAULT_PROVIDERS_POLL_INTERVAL | class ProviderRegistry
+rules:   The module must maintain thread safety across all asyncio task management and ensure consistent state synchronization between PostgreSQL and Valkey for tenant-provider configurations.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import structlog
+
+from .base import ProviderBase
+
+log = structlog.get_logger()
+
+
+def _backend_from_env() -> str:
+    v = os.getenv("PROVIDERS_BACKEND", "postgres")
+    if v not in {"postgres", "redis"}:
+        # Invalid values fall back to postgres to avoid blocking startup on a typo.
+        log.warning("registry.invalid_backend_env", value=v)
+        return "postgres"
+    return v
+
+
+DEFAULT_PROVIDERS_POLL_INTERVAL = 10.0
+
+
+class ProviderRegistry:
+    """
+    Manages one asyncio Task per active (tenant_id, provider_name) pair.
+
+    Lifecycle:
+    - start(): load all enabled providers from DB, start tasks, subscribe to Valkey
+    - stop(): cancel all tasks cleanly
+    - _reload_tenant(tenant_id): cancel stale tasks, re-query DB, start new tasks
+
+    Valkey channel: omur:providers:updated:{tenant_id}
+    On reconnect after Valkey disconnect: re-read full providers table to reconcile
+    any events missed during the outage (reconnect-with-exponential-backoff).
+    """
+
+    def __init__(
+        self,
+        kind: str,
+        provider_classes: dict[str, type[ProviderBase]],
+        postgres_dsn: str,
+        valkey_url: str,
+        *,
+        poll_interval: float = DEFAULT_PROVIDERS_POLL_INTERVAL,
+        backend: str | None = None,
+    ) -> None:
+        self.kind = kind
+        self.provider_classes = provider_classes
+        self._postgres_dsn = postgres_dsn
+        self._valkey_url = valkey_url
+        self._tasks: dict[str, asyncio.Task] = {}  # key: "{tenant_id}:{name}"
+        self._valkey_task: asyncio.Task | None = None
+        self._poll_task: asyncio.Task | None = None
+        self._table_missing: bool = False
+        self._poll_interval = poll_interval
+        self._backend = backend or _backend_from_env()
+        self._stop = asyncio.Event()
+
+    # ── Public API ────────────────────────────────────────────────
+
+    async def start(self) -> None:
+        """
+        Rules:   Registry must handle database unavailability gracefully by falling back to empty provider list and logging warning. The backend type (redis vs poll) determines which subscription mechanism is used, with redis using _subscribe_valkey() and poll using _poll_loop().
+        """
+        try:
+            rows = await self._fetch_providers()
+        except Exception as exc:
+            log.warning("registry.db_unavailable", kind=self.kind, error=str(exc))
+            rows = []
+        for row in rows:
+            self._start_task(row["tenant_id"], row["name"], row["config"])
+        if self._backend == "redis":
+            self._valkey_task = asyncio.create_task(self._subscribe_valkey())
+        else:
+            self._poll_task = asyncio.create_task(self._poll_loop())
+        log.info(
+            "registry.started", kind=self.kind, tasks=len(self._tasks),
+            backend=self._backend,
+        )
+
+    async def stop(self) -> None:
+        """
+        Rules:   Stop method must properly cancel all active tasks and ensure clean shutdown of both redis subscription and polling tasks, with proper exception handling during task cancellation.
+        """
+        self._stop.set()
+        if self._valkey_task:
+            self._valkey_task.cancel()
+            await asyncio.gather(self._valkey_task, return_exceptions=True)
+        if self._poll_task:
+            self._poll_task.cancel()
+            await asyncio.gather(self._poll_task, return_exceptions=True)
+        await self._cancel_tasks(list(self._tasks.keys()))
+        log.info("registry.stopped", kind=self.kind)
+
+    async def _poll_loop(self) -> None:
+        """Reconcile running-vs-desired tasks every poll_interval by re-reading
+        the providers table. Replaces the valkey pub/sub path when backend is
+        set to postgres (default)."""
+        while not self._stop.is_set():
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=self._poll_interval)
+            except asyncio.TimeoutError:
+                pass
+            if self._stop.is_set():
+                return
+            try:
+                await self._reconcile_all()
+            except Exception as exc:
+                log.warning("registry.poll_failed", kind=self.kind, error=str(exc))
+
+    async def _reload_tenant(self, tenant_id: str) -> None:
+        if not tenant_id or len(tenant_id) < 36:
+            log.warning("registry.invalid_tenant_id", tenant_id=tenant_id, hint="skipping reload")
+            return
+        # Cancel all tasks for this tenant
+        tenant_keys = [k for k in self._tasks if k.startswith(f"{tenant_id}:")]
+        await self._cancel_tasks(tenant_keys)
+
+        # Re-query and restart
+        rows = await self._fetch_providers(tenant_id=tenant_id)
+        for row in rows:
+            self._start_task(row["tenant_id"], row["name"], row["config"])
+        log.info("registry.tenant_reloaded", tenant_id=tenant_id, new_tasks=len(rows))
+
+    # ── Internal ─────────────────────────────────────────────────
+
+    def _start_task(self, tenant_id: str, name: str, config: dict[str, Any]) -> None:
+        cls = self.provider_classes.get(name)
+        if cls is None:
+            log.warning("registry.unknown_provider", name=name, tenant_id=tenant_id)
+            return
+        key = f"{tenant_id}:{name}"
+        assert key not in self._tasks, f"Task {key!r} already running — cancel before starting"
+        instance = cls(tenant_id=tenant_id, config=config)
+        task = asyncio.create_task(instance.run(), name=key)
+        task.add_done_callback(lambda t, k=key: self._on_task_done(k, t))
+        self._tasks[key] = task
+        log.info("registry.task_started", key=key)
+
+    def _on_task_done(self, key: str, task: asyncio.Task) -> None:
+        """Remove crashed tasks from _tasks so reconcile can restart them."""
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            log.error("registry.task_crashed", key=key, error=str(exc))
+            self._tasks.pop(key, None)
+
+    async def _cancel_tasks(self, keys: list[str]) -> None:
+        tasks = []
+        for key in keys:
+            task = self._tasks.pop(key, None)
+            if task and not task.done():
+                task.cancel()
+                tasks.append(task)
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _fetch_providers(self, tenant_id: str | None = None) -> list[dict[str, Any]]:
+        """Query DB for enabled providers of this registry's kind.
+
+        Returns [] and logs a warning if the providers table doesn't exist yet
+        (pre-migration state). The warning is rate-limited to avoid log spam.
+        """
+        import asyncpg
+        # Connect directly to postgres (bypass PgBouncer) to avoid RLS issues
+        # with SET ROLE omur_app when app.tenant_id isn't set.
+        dsn = self._postgres_dsn.replace("postgresql+asyncpg://", "postgresql://")
+        dsn = dsn.replace("pgbouncer:6432", "postgres:5432")
+        conn = await asyncpg.connect(dsn)
+        try:
+            if tenant_id:
+                rows = await conn.fetch(
+                    "SELECT tenant_id::text, name, config FROM providers "
+                    "WHERE kind = $1 AND enabled = TRUE AND tenant_id = $2::uuid",
+                    self.kind, tenant_id,
+                )
+            else:
+                rows = await conn.fetch(
+                    "SELECT tenant_id::text, name, config FROM providers "
+                    "WHERE kind = $1 AND enabled = TRUE",
+                    self.kind,
+                )
+            if self._table_missing:
+                log.info("registry.table_available", kind=self.kind)
+                self._table_missing = False
+            return [{"tenant_id": r["tenant_id"], "name": r["name"], "config": r["config"]} for r in rows]
+            # asyncpg auto-deserializes JSONB to dict — no json.loads() needed
+        except asyncpg.UndefinedTableError:
+            if not self._table_missing:
+                log.warning("registry.table_missing", kind=self.kind,
+                            hint="run the migrate container to create the providers table")
+                self._table_missing = True
+            return []
+        finally:
+            await conn.close()
+
+    async def _subscribe_valkey(self) -> None:
+        """
+        Subscribe to omur:providers:updated:* and reload tenants on events.
+        Implements reconnect-with-exponential-backoff.
+        On reconnect, performs a full provider reconciliation to catch missed events.
+        """
+        import redis.asyncio as redis
+
+        backoff = 1.0
+        while True:
+            client = None
+            pubsub = None
+            try:
+                client = redis.from_url(self._valkey_url)
+                pubsub = client.pubsub()
+                await pubsub.psubscribe("omur:providers:updated:*")
+                log.info("registry.valkey_subscribed", kind=self.kind)
+                backoff = 1.0
+
+                # On (re)connect: full reconciliation to catch missed events
+                await self._reconcile_all()
+
+                async for message in pubsub.listen():
+                    if message["type"] != "pmessage":
+                        continue
+                    channel: str = message["channel"].decode()
+                    tenant_id = channel.split(":")[-1]
+                    await self._reload_tenant(tenant_id)
+
+            except asyncio.CancelledError:
+                return
+            except Exception as exc:
+                log.warning("registry.valkey_disconnected", error=str(exc), retry_in=backoff)
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 60.0)
+            finally:
+                if pubsub is not None:
+                    await pubsub.aclose()
+                if client is not None:
+                    await client.aclose()
+
+    async def _reconcile_all(self) -> None:
+        """Re-read all enabled providers from DB and sync running tasks."""
+        rows = await self._fetch_providers()
+        desired = {f"{r['tenant_id']}:{r['name']}": r for r in rows}
+        current = set(self._tasks.keys())
+        desired_keys = set(desired.keys())
+
+        # Cancel tasks no longer in DB
+        await self._cancel_tasks(list(current - desired_keys))
+
+        # Start new tasks not yet running
+        for key in desired_keys - current:
+            row = desired[key]
+            self._start_task(row["tenant_id"], row["name"], row["config"])

omkit/quota.py

@@ -0,0 +1,186 @@
+"""packages/omur-sdk/omkit/quota.py — Per-tenant quota helpers (plan 1.7).
+
+Mirrors ``packages/omur-go-sdk/quota/quota.go`` so marrow (Python) and
+spine (Go) enforce identical defaults. Absence of a ``tenant_quotas`` row
+means "use defaults below". Limits are integers; bytes are BIGINT.
+
+exports: DEFAULT_DOCS | DEFAULT_STORAGE_BYTES | DEFAULT_QUERIES_PER_MONTH | class Resource | class Limits | class Usage | class Decision | load(session) | get_usage(session) | check_upload(lim, usage, incoming_bytes) | check_query(lim, usage)
+rules:   The module must maintain backward compatibility with existing quota enforcement logic and cannot modify the public API of `load`, `get_usage`, `check_upload`, or `check_query` functions.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+DEFAULT_DOCS = 100
+DEFAULT_STORAGE_BYTES = 500 * 1024 * 1024  # 500 MiB
+DEFAULT_QUERIES_PER_MONTH = 1000
+
+
+class Resource(str, enum.Enum):
+    DOCS = "docs"
+    STORAGE_BYTES = "storage_bytes"
+    QUERIES_PER_MONTH = "queries_per_month"
+
+
+@dataclass(frozen=True)
+class Limits:
+    docs: int
+    storage_bytes: int
+    queries_per_month: int
+
+
+@dataclass(frozen=True)
+class Usage:
+    docs: int
+    storage_bytes: int
+    queries_this_month: int
+
+
+@dataclass(frozen=True)
+class Decision:
+    allowed: bool
+    resource: Resource | None = None
+    limit: int = 0
+    used: int = 0
+    retry_after: int = 0  # seconds; 0 means "no retry will help"
+
+
+async def load(session: AsyncSession) -> Limits:
+    """Read the caller's effective limits under the session's RLS role.
+
+    The caller is expected to have already invoked ``tenant.set_rls(session)``.
+    Falls back to defaults when no row exists for the tenant.
+
+    Rules:   The function assumes that `tenant.set_rls(session)` has already been called, and explicitly filters by `app.tenant_id` to prevent cross-tenant data leakage since `tenant_quotas` has no RLS policy.
+    """
+    # ``tenant_quotas`` intentionally has no RLS policy (operators need
+    # cross-tenant visibility for capacity planning), so we filter by
+    # the caller's app.tenant_id GUC explicitly. Without this WHERE the
+    # helper would return an arbitrary row belonging to another tenant.
+    row = (
+        await session.execute(
+            text(
+                "SELECT docs_limit, storage_bytes_limit, queries_per_month_limit "
+                "FROM tenant_quotas "
+                "WHERE tenant_id = current_setting('app.tenant_id', true)::uuid "
+                "LIMIT 1"
+            )
+        )
+    ).first()
+    if row is None:
+        return Limits(
+            docs=DEFAULT_DOCS,
+            storage_bytes=DEFAULT_STORAGE_BYTES,
+            queries_per_month=DEFAULT_QUERIES_PER_MONTH,
+        )
+    return Limits(
+        docs=int(row[0]),
+        storage_bytes=int(row[1]),
+        queries_per_month=int(row[2]),
+    )
+
+
+async def get_usage(session: AsyncSession) -> Usage:
+    """Read docs / storage_bytes / queries-this-month for the request tenant.
+
+    Caller must have already set RLS on the session.
+
+    Services that don't hold SELECT on ``usage_log`` (e.g. marrow, which
+    only enforces upload-side quotas) get ``queries_this_month=0`` from
+    this helper — the upload-path checks never read that field, and the
+    spine middleware that does enforce query quota will roll back and
+    surface the real permission error instead.
+
+    Rules:   The function requires the caller to have already set RLS on the session, and services without SELECT permission on `usage_log` will get `queries_this_month=0`, which may mask real permission errors in query enforcement.
+    """
+    doc_row = (
+        await session.execute(
+            text(
+                "SELECT COUNT(*)::int, COALESCE(SUM(size_bytes), 0)::bigint "
+                "FROM document_files"
+            )
+        )
+    ).one()
+    queries = 0
+    nested = await session.begin_nested()
+    try:
+        queries = (
+            await session.execute(
+                text(
+                    "SELECT COUNT(*)::int FROM usage_log "
+                    "WHERE created_at >= date_trunc('month', now())"
+                )
+            )
+        ).scalar() or 0
+        await nested.commit()
+    except Exception:
+        # Permission denied / table missing: upload-side callers don't
+        # need queries_this_month. Rolling back the savepoint keeps the
+        # outer transaction usable so callers can still read `docs`.
+        await nested.rollback()
+    return Usage(
+        docs=int(doc_row[0]),
+        storage_bytes=int(doc_row[1]),
+        queries_this_month=int(queries),
+    )
+
+
+def check_upload(lim: Limits, usage: Usage, incoming_bytes: int) -> Decision:
+    """
+    Rules:   The function does not validate that `incoming_bytes` is non-negative, which could lead to incorrect quota calculations if negative values are passed.
+    """
+    if usage.docs + 1 > lim.docs:
+        return Decision(
+            allowed=False,
+            resource=Resource.DOCS,
+            limit=lim.docs,
+            used=usage.docs,
+            retry_after=0,
+        )
+    if usage.storage_bytes + incoming_bytes > lim.storage_bytes:
+        return Decision(
+            allowed=False,
+            resource=Resource.STORAGE_BYTES,
+            limit=lim.storage_bytes,
+            used=usage.storage_bytes,
+            retry_after=0,
+        )
+    return Decision(allowed=True)
+
+
+def check_query(lim: Limits, usage: Usage) -> Decision:
+    """
+    Rules:   The function relies on `_seconds_until_next_month()` to calculate retry_after, which may not be accurate if the system clock is skewed or if the function is called outside of normal monthly boundaries.
+    """
+    if usage.queries_this_month + 1 > lim.queries_per_month:
+        return Decision(
+            allowed=False,
+            resource=Resource.QUERIES_PER_MONTH,
+            limit=lim.queries_per_month,
+            used=usage.queries_this_month,
+            retry_after=_seconds_until_next_month(),
+        )
+    return Decision(allowed=True)
+
+
+def _cap_at_32_days(s: int) -> int:
+    if s < 0:
+        return 60
+    if s > 32 * 24 * 3600:
+        return 32 * 24 * 3600
+    return s
+
+
+def _seconds_until_next_month() -> int:
+    now = datetime.now(timezone.utc)
+    y, m = (now.year + 1, 1) if now.month == 12 else (now.year, now.month + 1)
+    nxt = datetime(y, m, 1, 0, 0, 0, tzinfo=timezone.utc)
+    return _cap_at_32_days(int((nxt - now).total_seconds()))

omkit/resilience.py

@@ -0,0 +1,122 @@
+"""packages/omur-sdk/omkit/resilience.py — HTTP resilience primitives: circuit breaker + retry with exponential backoff.
+
+exports: T | class CircuitOpen | class CircuitBreaker | resilient(breaker)
+rules:   The circuit breaker must maintain thread safety across all state transitions and failure tracking operations. The breaker's state must be consistent between concurrent calls and failures, with proper synchronization to prevent race conditions during state changes. All external dependencies like httpx exceptions must be handled with specific type checking to ensure transient error detection works correctly.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+from __future__ import annotations
+
+import functools
+import time
+from enum import Enum
+from typing import Awaitable, Callable, TypeVar
+
+import httpx
+from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+
+T = TypeVar("T")
+
+
+class _State(Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitOpen(Exception):
+    """Raised when a call is rejected because the circuit is open."""
+
+
+class CircuitBreaker:
+    """Async circuit breaker for single-process services.
+
+    States: CLOSED (normal) → OPEN (fail-fast) → HALF_OPEN (probe) → CLOSED
+    Thread-safe within a single asyncio event loop (no cross-thread use).
+    """
+
+    def __init__(self, fail_max: int = 5, reset_timeout: int = 60, name: str = "") -> None:
+        self.fail_max = fail_max
+        self.reset_timeout = reset_timeout
+        self.name = name
+        self._failures = 0
+        self._state = _State.CLOSED
+        self._opened_at: float = 0.0
+        self._open_observed: bool = False  # True after first "open" state is returned
+
+    @property
+    def state(self) -> str:
+        """
+        Rules:   When the circuit breaker is in OPEN state, it transitions to HALF_OPEN only after the reset_timeout has elapsed since it was opened. The _open_observed flag is used to track whether the breaker has been observed in OPEN state during the current reset period.
+        """
+        if self._state == _State.OPEN:
+            if self._open_observed and time.monotonic() - self._opened_at >= self.reset_timeout:
+                self._state = _State.HALF_OPEN
+            else:
+                self._open_observed = True
+        return self._state.value
+
+    def record_success(self) -> None:
+        """
+        Rules:   Calling this function resets the failure count and transitions the circuit breaker to CLOSED state, regardless of the current state. The _open_observed flag is reset to False to ensure proper behavior in subsequent state transitions.
+        """
+        self._failures = 0
+        self._state = _State.CLOSED
+        self._open_observed = False
+
+    def record_failure(self) -> None:
+        """
+        Rules:   Each call increments the failure count. When the failure count reaches the configured fail_max threshold, the circuit breaker transitions to OPEN state and records the current timestamp. The _open_observed flag is reset to False to ensure proper behavior in subsequent state transitions.
+        """
+        self._failures += 1
+        if self._failures >= self.fail_max:
+            self._state = _State.OPEN
+            self._opened_at = time.monotonic()
+            self._open_observed = False
+
+    async def call(self, coro: Awaitable[T]) -> T:
+        """
+        Rules:   The circuit breaker must be in the 'closed' state to allow calls; otherwise, it raises a CircuitOpen exception. The state transition logic depends on reset_timeout and fail_max thresholds.
+        """
+        if self.state == "open":
+            raise CircuitOpen(
+                f"Circuit '{self.name}' is open — retry after {self.reset_timeout}s"
+            )
+        try:
+            result = await coro
+            self.record_success()
+            return result
+        except Exception:
+            self.record_failure()
+            raise
+
+
+def _is_transient(exc: BaseException) -> bool:
+    """True for errors that warrant a retry."""
+    if isinstance(exc, (httpx.ConnectError, httpx.TimeoutException)):
+        return True
+    if isinstance(exc, httpx.HTTPStatusError) and exc.response is not None:
+        return exc.response.status_code in (502, 503, 504)
+    return False
+
+
+def resilient(breaker: CircuitBreaker) -> Callable:
+    """Decorator: retry 3× with exponential backoff, guarded by a circuit breaker.
+
+    Rules:   The decorator applies a retry mechanism with exponential backoff and uses the provided circuit breaker to guard the function call. It assumes the circuit breaker is properly initialized with valid fail_max and reset_timeout values.
+    """
+
+    def decorator(fn: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+        @retry(
+            stop=stop_after_attempt(3),
+            wait=wait_exponential(multiplier=1, min=1, max=8),
+            retry=retry_if_exception(_is_transient),
+            reraise=True,
+        )
+        @functools.wraps(fn)
+        async def wrapped(*args, **kwargs):
+            return await breaker.call(fn(*args, **kwargs))
+
+        return wrapped
+
+    return decorator