agentic-exception-sdk 1.1.3__py3-none-any.whl

agentic_exception_sdk/budget/watchdog.py

@@ -0,0 +1,285 @@
+"""Budget watchdog — enforces agent resource budgets with concurrency-safe reservations.
+
+Budget consumption semantics (fixed):
+- consume_call(): once per resilient()/async_resilient() invocation.
+- failure_budget: incremented once per failed attempt, including retries.
+- Token/cost: check-and-reserve is one lock-protected atomic operation.
+  Calls that cannot reserve capacity fail before starting upstream work,
+  preventing N * delta overspend under contention.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+from agentic_exception_sdk.budget.models import AgentBudget
+from agentic_exception_sdk.taxonomy.errors import BudgetExhaustedError
+
+_log = logging.getLogger(__name__)
+
+__all__ = ["BudgetWatchdog"]
+
+
+class BudgetWatchdog:
+    """Tracks and enforces agent resource budgets with concurrency-safe atomic reservations.
+
+    Sync and async paths share a threading.RLock so mixed-concurrency callers
+    cannot race with each other.
+
+    All check-and-reserve operations are atomic within their respective lock so
+    that concurrent async_resilient() executions cannot overspend the budget
+    through races (N * delta overspend prevention).
+
+    Args:
+        budget: The AgentBudget configuration specifying ceiling values.
+    """
+
+    def __init__(self, budget: AgentBudget) -> None:
+        self._budget = budget
+        self._start_time: float = time.monotonic()
+        self._call_count: int = 0
+        self._failure_count: int = 0
+        self._input_tokens_used: int = 0
+        self._output_tokens_used: int = 0
+        self._cost_micros_used: int = 0
+        self._lock = threading.RLock()
+
+    def consume_call(self) -> None:
+        """Record one tool call invocation and check max_tool_calls ceiling.
+
+        This must be called once per resilient()/async_resilient() invocation.
+
+        Raises:
+            BudgetExhaustedError: If max_tool_calls ceiling is exceeded.
+            BudgetWarningError: Not currently raised here (implemented at soft-limit).
+        """
+        with self._lock:
+            self._call_count += 1
+            if (
+                self._budget.max_tool_calls is not None
+                and self._call_count > self._budget.max_tool_calls
+            ):
+                raise BudgetExhaustedError(
+                    f"tool call budget exhausted: {self._call_count} > "
+                    f"{self._budget.max_tool_calls} max_tool_calls"
+                )
+
+    def record_failure(self) -> None:
+        """Increment failure count once per failed attempt including retries.
+
+        Raises:
+            BudgetExhaustedError: If failure_budget ceiling is exceeded.
+        """
+        with self._lock:
+            self._failure_count += 1
+            if (
+                self._budget.failure_budget is not None
+                and self._failure_count >= self._budget.failure_budget
+            ):
+                raise BudgetExhaustedError(
+                    f"failure budget exhausted: {self._failure_count} failures >= "
+                    f"{self._budget.failure_budget} failure_budget"
+                )
+
+    def check_time(self) -> None:
+        """Check wall-clock time budget.
+
+        Raises:
+            BudgetExhaustedError: If max_seconds ceiling has been exceeded.
+        """
+        if self._budget.max_seconds is None:
+            return
+        elapsed = time.monotonic() - self._start_time
+        if elapsed > self._budget.max_seconds:
+            raise BudgetExhaustedError(
+                f"time budget exhausted: {elapsed:.2f}s > {self._budget.max_seconds}s max_seconds"
+            )
+
+    def check_before_sleep(self, sleep_seconds: float) -> None:
+        """Check whether the remaining time budget can accommodate a proposed sleep.
+
+        Called by the retry policy before each backoff sleep.
+
+        Args:
+            sleep_seconds: Proposed sleep duration in seconds.
+
+        Raises:
+            BudgetExhaustedError: If the remaining time budget cannot cover the sleep.
+        """
+        if self._budget.max_seconds is None:
+            return
+        elapsed = time.monotonic() - self._start_time
+        remaining = self._budget.max_seconds - elapsed
+        if sleep_seconds > remaining:
+            raise BudgetExhaustedError(
+                f"retry sleep ({sleep_seconds:.2f}s) would exceed remaining time budget "
+                f"({remaining:.2f}s)"
+            )
+
+    def reserve_tokens(
+        self,
+        *,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cost_micros_usd: int = 0,
+    ) -> None:
+        """Atomically check and reserve token/cost capacity before an LLM call.
+
+        Check-and-reserve is one lock-protected operation to prevent N * delta
+        overspend under concurrent async calls.
+
+        Args:
+            input_tokens: Input tokens to reserve.
+            output_tokens: Output tokens to reserve.
+            cost_micros_usd: Cost in integer micro-USD to reserve.
+
+        Raises:
+            BudgetExhaustedError: If any ceiling would be exceeded.
+        """
+        with self._lock:
+            self._check_token_ceilings(input_tokens, output_tokens, cost_micros_usd)
+            self._input_tokens_used += input_tokens
+            self._output_tokens_used += output_tokens
+            self._cost_micros_used += cost_micros_usd
+
+    def _check_token_ceilings(
+        self,
+        input_tokens: int,
+        output_tokens: int,
+        cost_micros_usd: int,
+    ) -> None:
+        """Check token/cost ceilings. Must be called while holding the lock."""
+        if (
+            self._budget.max_input_tokens is not None
+            and self._input_tokens_used + input_tokens > self._budget.max_input_tokens
+        ):
+            raise BudgetExhaustedError(
+                f"input token budget exhausted: "
+                f"{self._input_tokens_used + input_tokens} > {self._budget.max_input_tokens}"
+            )
+        if (
+            self._budget.max_output_tokens is not None
+            and self._output_tokens_used + output_tokens > self._budget.max_output_tokens
+        ):
+            raise BudgetExhaustedError(
+                f"output token budget exhausted: "
+                f"{self._output_tokens_used + output_tokens} > {self._budget.max_output_tokens}"
+            )
+        if (
+            self._budget.max_total_cost_micros_usd is not None
+            and self._cost_micros_used + cost_micros_usd > self._budget.max_total_cost_micros_usd
+        ):
+            raise BudgetExhaustedError(
+                f"cost budget exhausted: "
+                f"{self._cost_micros_used + cost_micros_usd} > "
+                f"{self._budget.max_total_cost_micros_usd} micro-USD"
+            )
+
+    async def async_reserve_tokens(
+        self,
+        *,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cost_micros_usd: int = 0,
+    ) -> None:
+        """Async-safe version of reserve_tokens using the shared thread lock.
+
+        Check-and-reserve is one asyncio.Lock-protected operation.
+
+        Args:
+            input_tokens: Input tokens to reserve.
+            output_tokens: Output tokens to reserve.
+            cost_micros_usd: Cost in integer micro-USD to reserve.
+
+        Raises:
+            BudgetExhaustedError: If any ceiling would be exceeded.
+        """
+        with self._lock:
+            self._check_token_ceilings(input_tokens, output_tokens, cost_micros_usd)
+            self._input_tokens_used += input_tokens
+            self._output_tokens_used += output_tokens
+            self._cost_micros_used += cost_micros_usd
+
+    def account_stream_delta(
+        self,
+        *,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cost_micros_usd: int = 0,
+    ) -> None:
+        """Update token/cost from a streaming LLM response delta.
+
+        Call this from the streaming consumer on each chunk. Raises
+        BudgetExhaustedError immediately if the incremental delta would exceed
+        the remaining reservation — aborting the stream early rather than waiting
+        for the full response.
+
+        Args:
+            input_tokens: Incremental input token delta.
+            output_tokens: Incremental output token delta.
+            cost_micros_usd: Incremental cost in integer micro-USD.
+
+        Raises:
+            BudgetExhaustedError: If any ceiling is exceeded mid-stream.
+        """
+        with self._lock:
+            self._check_token_ceilings(input_tokens, output_tokens, cost_micros_usd)
+            self._input_tokens_used += input_tokens
+            self._output_tokens_used += output_tokens
+            self._cost_micros_used += cost_micros_usd
+
+    def snapshot(self) -> dict[str, int | float | None]:
+        """Return a thread-safe snapshot of counters and ceilings.
+
+        Returns:
+            A plain dict of current usage counters, elapsed seconds, and budget
+            ceilings. Monetary values are integer micro-USD.
+        """
+        with self._lock:
+            elapsed = time.monotonic() - self._start_time
+            return {
+                "call_count": self._call_count,
+                "failure_count": self._failure_count,
+                "input_tokens_used": self._input_tokens_used,
+                "output_tokens_used": self._output_tokens_used,
+                "cost_micros_used": self._cost_micros_used,
+                "elapsed_seconds": elapsed,
+                "max_tool_calls": self._budget.max_tool_calls,
+                "failure_budget": self._budget.failure_budget,
+                "max_input_tokens": self._budget.max_input_tokens,
+                "max_output_tokens": self._budget.max_output_tokens,
+                "max_total_cost_micros_usd": self._budget.max_total_cost_micros_usd,
+                "max_seconds": self._budget.max_seconds,
+            }
+
+    @property
+    def call_count(self) -> int:
+        """Total tool call invocations recorded."""
+        with self._lock:
+            return self._call_count
+
+    @property
+    def failure_count(self) -> int:
+        """Total failed attempts recorded."""
+        with self._lock:
+            return self._failure_count
+
+    @property
+    def input_tokens_used(self) -> int:
+        """Total input tokens consumed."""
+        with self._lock:
+            return self._input_tokens_used
+
+    @property
+    def output_tokens_used(self) -> int:
+        """Total output tokens consumed."""
+        with self._lock:
+            return self._output_tokens_used
+
+    @property
+    def cost_micros_used(self) -> int:
+        """Total cost consumed in integer micro-USD."""
+        with self._lock:
+            return self._cost_micros_used

agentic_exception_sdk/budget/watchdog.pyi

@@ -0,0 +1,24 @@
+from agentic_exception_sdk.budget.models import AgentBudget
+
+__all__ = ['BudgetWatchdog']
+
+class BudgetWatchdog:
+    def __init__(self, budget: AgentBudget) -> None: ...
+    def consume_call(self) -> None: ...
+    def record_failure(self) -> None: ...
+    def check_time(self) -> None: ...
+    def check_before_sleep(self, sleep_seconds: float) -> None: ...
+    def reserve_tokens(self, *, input_tokens: int = 0, output_tokens: int = 0, cost_micros_usd: int = 0) -> None: ...
+    async def async_reserve_tokens(self, *, input_tokens: int = 0, output_tokens: int = 0, cost_micros_usd: int = 0) -> None: ...
+    def account_stream_delta(self, *, input_tokens: int = 0, output_tokens: int = 0, cost_micros_usd: int = 0) -> None: ...
+    def snapshot(self) -> dict[str, int | float | None]: ...
+    @property
+    def call_count(self) -> int: ...
+    @property
+    def failure_count(self) -> int: ...
+    @property
+    def input_tokens_used(self) -> int: ...
+    @property
+    def output_tokens_used(self) -> int: ...
+    @property
+    def cost_micros_used(self) -> int: ...

agentic_exception_sdk/bundle.py

@@ -0,0 +1,102 @@
+"""ResilienceBundle — injectable container for all SDK components.
+
+All fields default to safe NoOp implementations so a bundle with defaults is
+immediately usable without any configuration. Host projects replace individual
+components via constructor injection — never via global state or monkey-patching.
+
+Zero host imports: this module only imports from within the SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from agentic_exception_sdk.budget.models import AgentBudget
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+from agentic_exception_sdk.escalation.router import NoOpEscalationRouter
+from agentic_exception_sdk.observability.metrics import (
+    MetricsCollector,
+    NoOpMetricsCollector,
+)
+from agentic_exception_sdk.observability.sink import NoOpSink
+from agentic_exception_sdk.propagation.bus import InMemoryBus
+from agentic_exception_sdk.propagation.dlq import InMemoryDLQ
+from agentic_exception_sdk.resilience.circuit_breaker import (
+    NoOpCircuitBreaker,
+)
+from agentic_exception_sdk.resilience.retry import NoOpRetry
+from agentic_exception_sdk.taxonomy.classifier import ExceptionClassifier
+from agentic_exception_sdk.validation.gates import NoOpGate
+from agentic_exception_sdk.validation.guard_rails import NoOpGuardRails
+from agentic_exception_sdk.validation.trust_boundary import TrustBoundaryValidator
+
+if TYPE_CHECKING:
+    from opentelemetry.metrics import MeterProvider
+
+__all__ = ["ResilienceBundle"]
+
+
+@dataclass
+class ResilienceBundle:
+    """All SDK components in one injectable container.
+
+    Defaults every component to a safe no-op implementation. Host projects
+    replace individual fields to enable specific capabilities:
+
+        bundle = ResilienceBundle(
+            circuit_breaker=InMemoryCircuitBreaker(failure_threshold=3),
+            exception_sink=OTelExceptionAdapter(tracer_provider),
+        )
+
+    Attributes:
+        classifier: Maps exceptions to (class, source, level) tuples.
+        trust_boundary: Sanitizes all host-provided strings and snapshots.
+        guard_rails: Enforces tool call allowlist. NoOpGuardRails by default.
+        agent_budget: Tracks and enforces resource budgets. Unlimited by default.
+        retry_policy: Retry strategy. Single-attempt (no retry) by default.
+        circuit_breaker: Sync circuit breaker. NoOp (pass-through) by default.
+        output_validation_gate: Validates tool outputs. Pass-through by default.
+        exception_sink: Observability sink. Discards all envelopes by default.
+        metrics_collector: Metrics collector. NoOp by default.
+        meter_provider: Optional OTel MeterProvider for tool latency histograms.
+        propagation_bus: Propagation bus. Bounded in-memory (1000 envelopes) by default.
+        dlq: Dead-letter queue for HARD_KILL envelopes. InMemoryDLQ by default.
+        escalation_router: Routes envelopes to handlers. NoOp by default.
+        recovery_policy: Optional post-classification recovery policy. None by default.
+        async_circuit_breaker: Optional async circuit breaker. None by default,
+            meaning async_resilient() falls back to bundle.circuit_breaker.
+    """
+
+    classifier: ExceptionClassifier = field(default_factory=ExceptionClassifier)
+    trust_boundary: TrustBoundaryValidator = field(
+        default_factory=TrustBoundaryValidator
+    )
+    guard_rails: Any = field(default_factory=NoOpGuardRails)
+    agent_budget: BudgetWatchdog = field(
+        default_factory=lambda: BudgetWatchdog(AgentBudget())
+    )
+    retry_policy: Any = field(default_factory=NoOpRetry)
+    circuit_breaker: Any = field(default_factory=NoOpCircuitBreaker)
+    output_validation_gate: Any = field(default_factory=NoOpGate)
+    exception_sink: Any = field(default_factory=NoOpSink)
+    metrics_collector: MetricsCollector = field(default_factory=NoOpMetricsCollector)
+    meter_provider: MeterProvider | None = None
+    propagation_bus: Any = field(default_factory=InMemoryBus)
+    dlq: Any = field(default_factory=InMemoryDLQ)
+    escalation_router: Any = field(default_factory=NoOpEscalationRouter)
+    recovery_policy: Any | None = None
+    async_circuit_breaker: Any | None = None
+    _latency_histogram: Any | None = field(init=False, repr=False, default=None)
+
+    def __post_init__(self) -> None:
+        """Cache optional OTel instruments once at bundle construction."""
+        if self.meter_provider is None:
+            self._latency_histogram = None
+            return
+        meter = self.meter_provider.get_meter("agentic_exception_sdk")
+        self._latency_histogram = meter.create_histogram(
+            "agent_tool_call_duration_seconds",
+            unit="s",
+            description="Per-call tool duration by agent and tool name",
+        )

agentic_exception_sdk/bundle.pyi

@@ -0,0 +1,37 @@
+from _typeshed import Incomplete
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+from agentic_exception_sdk.escalation.router import NoOpEscalationRouter
+from agentic_exception_sdk.observability.metrics import MetricsCollector, NoOpMetricsCollector
+from agentic_exception_sdk.observability.sink import NoOpSink
+from agentic_exception_sdk.propagation.bus import InMemoryBus
+from agentic_exception_sdk.propagation.dlq import InMemoryDLQ
+from agentic_exception_sdk.resilience.circuit_breaker import NoOpCircuitBreaker
+from agentic_exception_sdk.resilience.retry import NoOpRetry
+from agentic_exception_sdk.taxonomy.classifier import ExceptionClassifier
+from agentic_exception_sdk.validation.gates import NoOpGate
+from agentic_exception_sdk.validation.guard_rails import NoOpGuardRails
+from agentic_exception_sdk.validation.trust_boundary import TrustBoundaryValidator
+from dataclasses import dataclass, field
+from opentelemetry.metrics import MeterProvider
+from typing import Any
+
+__all__ = ['ResilienceBundle']
+
+@dataclass
+class ResilienceBundle:
+    classifier: ExceptionClassifier = field(default_factory=ExceptionClassifier)
+    trust_boundary: TrustBoundaryValidator = field(default_factory=TrustBoundaryValidator)
+    guard_rails: Any = field(default_factory=NoOpGuardRails)
+    agent_budget: BudgetWatchdog = field(default_factory=Incomplete)
+    retry_policy: Any = field(default_factory=NoOpRetry)
+    circuit_breaker: Any = field(default_factory=NoOpCircuitBreaker)
+    output_validation_gate: Any = field(default_factory=NoOpGate)
+    exception_sink: Any = field(default_factory=NoOpSink)
+    metrics_collector: MetricsCollector = field(default_factory=NoOpMetricsCollector)
+    meter_provider: MeterProvider | None = ...
+    propagation_bus: Any = field(default_factory=InMemoryBus)
+    dlq: Any = field(default_factory=InMemoryDLQ)
+    escalation_router: Any = field(default_factory=NoOpEscalationRouter)
+    recovery_policy: Any | None = ...
+    async_circuit_breaker: Any | None = ...
+    def __post_init__(self) -> None: ...

agentic_exception_sdk/config/__init__.py

@@ -0,0 +1,10 @@
+"""Startup configuration validation helpers."""
+
+from __future__ import annotations
+
+from agentic_exception_sdk.config.validate import BundleValidationError, validate_bundle
+
+__all__ = [
+    "BundleValidationError",
+    "validate_bundle",
+]

agentic_exception_sdk/config/__init__.pyi

@@ -0,0 +1,3 @@
+from agentic_exception_sdk.config.validate import BundleValidationError as BundleValidationError, validate_bundle as validate_bundle
+
+__all__ = ['BundleValidationError', 'validate_bundle']

agentic_exception_sdk/config/validate.py

@@ -0,0 +1,74 @@
+"""Startup validation for ResilienceBundle configuration."""
+
+from __future__ import annotations
+
+from agentic_exception_sdk.bundle import ResilienceBundle
+
+__all__ = [
+    "BundleValidationError",
+    "validate_bundle",
+]
+
+
+class BundleValidationError(ValueError):
+    """Raised when validate_bundle finds one or more configuration failures."""
+
+    def __init__(self, failures: list[str]) -> None:
+        self.failures = list(failures)
+        self.report = "\n".join(self.failures)
+        super().__init__(self.report)
+
+
+def validate_bundle(bundle: ResilienceBundle) -> None:
+    """Validate a bundle at startup without mutating it.
+
+    Args:
+        bundle: The configured ResilienceBundle to inspect.
+
+    Raises:
+        BundleValidationError: If one or more configuration failures are found.
+    """
+    failures: list[str] = []
+    _check_redis_circuit_breaker(bundle, failures)
+    _check_guard_rails(bundle, failures)
+    _check_budget(bundle, failures)
+    if failures:
+        raise BundleValidationError(failures)
+
+
+def _check_redis_circuit_breaker(
+    bundle: ResilienceBundle,
+    failures: list[str],
+) -> None:
+    redis_url = getattr(bundle.circuit_breaker, "redis_url", None)
+    if redis_url is None:
+        return
+    if not isinstance(redis_url, str) or not redis_url.startswith("rediss://"):
+        failures.append("RedisCircuitBreaker: URL must use rediss:// (TLS required)")
+
+
+def _check_guard_rails(bundle: ResilienceBundle, failures: list[str]) -> None:
+    guard_rails = bundle.guard_rails
+    allowlist = getattr(guard_rails, "allowlist", None)
+    if allowlist is not None and len(allowlist) == 0:
+        failures.append("GuardRailPolicy: allowlist is empty - all tool calls will be blocked")
+        return
+
+    allowlisted_operations = getattr(guard_rails, "_allowlisted_operations", None)
+    canonical = getattr(allowlisted_operations, "canonical", None)
+    if canonical is not None and len(canonical) == 0:
+        failures.append("GuardRailPolicy: allowlist is empty - all tool calls will be blocked")
+
+
+def _check_budget(bundle: ResilienceBundle, failures: list[str]) -> None:
+    budget = getattr(bundle.agent_budget, "budget", None)
+    if budget is None:
+        budget = getattr(bundle.agent_budget, "_budget", None)
+    if budget is None:
+        return
+
+    max_cost = getattr(budget, "max_cost_micros", None)
+    if max_cost is None:
+        max_cost = getattr(budget, "max_total_cost_micros_usd", None)
+    if max_cost is not None and max_cost <= 0:
+        failures.append("AgentBudget: max_cost_micros must be positive")

agentic_exception_sdk/config/validate.pyi

@@ -0,0 +1,11 @@
+from _typeshed import Incomplete
+from agentic_exception_sdk.bundle import ResilienceBundle
+
+__all__ = ['BundleValidationError', 'validate_bundle']
+
+class BundleValidationError(ValueError):
+    failures: Incomplete
+    report: Incomplete
+    def __init__(self, failures: list[str]) -> None: ...
+
+def validate_bundle(bundle: ResilienceBundle) -> None: ...

agentic_exception_sdk/escalation/__init__.py

@@ -0,0 +1,22 @@
+"""Escalation: routing, handlers, and checkpoint store."""
+
+from __future__ import annotations
+
+from agentic_exception_sdk.escalation.checkpoint import CheckpointStore, InMemoryCheckpointStore
+from agentic_exception_sdk.escalation.handlers import NoOpHandler
+from agentic_exception_sdk.escalation.router import (
+    EscalationHandlerLike,
+    EscalationRouter,
+    NoOpEscalationRouter,
+    RecoveryDirective,
+)
+
+__all__ = [
+    "CheckpointStore",
+    "EscalationHandlerLike",
+    "EscalationRouter",
+    "InMemoryCheckpointStore",
+    "NoOpEscalationRouter",
+    "NoOpHandler",
+    "RecoveryDirective",
+]

agentic_exception_sdk/escalation/__init__.pyi

@@ -0,0 +1,5 @@
+from agentic_exception_sdk.escalation.checkpoint import CheckpointStore as CheckpointStore, InMemoryCheckpointStore as InMemoryCheckpointStore
+from agentic_exception_sdk.escalation.handlers import NoOpHandler as NoOpHandler
+from agentic_exception_sdk.escalation.router import EscalationHandlerLike as EscalationHandlerLike, EscalationRouter as EscalationRouter, NoOpEscalationRouter as NoOpEscalationRouter, RecoveryDirective as RecoveryDirective
+
+__all__ = ['CheckpointStore', 'EscalationHandlerLike', 'EscalationRouter', 'InMemoryCheckpointStore', 'NoOpEscalationRouter', 'NoOpHandler', 'RecoveryDirective']