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

agentic_exception_sdk/__init__.py

@@ -0,0 +1,308 @@
+"""Agentic Exception Management SDK.
+
+A protocol-first, zero-host-import SDK for structured exception handling,
+classification, retry, circuit breaking, propagation, and observability in
+agentic AI systems.
+
+Quick start:
+
+    from agentic_exception_sdk import (
+        NoOpResilienceBundle,
+        ResilienceBundle,
+        async_resilient,
+        resilient,
+    )
+
+    bundle = NoOpResilienceBundle()
+
+    @resilient(bundle, tool_name="search_flights", agent_id="travel-agent")
+    def search_flights(query: str) -> list[dict]:
+        ...
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version as _metadata_version
+
+__version__ = _metadata_version("agentic-exception-sdk")
+
+# Budget
+from agentic_exception_sdk.budget.models import AgentBudget, UnlimitedBudget
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+
+# Bundle and factory
+from agentic_exception_sdk.bundle import ResilienceBundle
+from agentic_exception_sdk.config.validate import BundleValidationError, validate_bundle
+
+# Escalation
+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,
+)
+
+# Multi-agent
+from agentic_exception_sdk.multi_agent.consensus import (
+    ConsensusGate,
+    ConsensusNotReachedError,
+)
+from agentic_exception_sdk.multi_agent.parallel import (
+    AgentOutcome,
+    FanOutOutcomeEnvelope,
+    call_parallel,
+)
+from agentic_exception_sdk.multi_agent.router import (
+    OrchestratorExceptionRouter,
+    WorkerHandler,
+    fan_out,
+)
+from agentic_exception_sdk.multi_agent.sla import AgentSLAPolicy
+from agentic_exception_sdk.noop import NoOpResilienceBundle
+from agentic_exception_sdk.observability.metrics import (
+    InMemoryMetricsCollector,
+    MetricsCollector,
+    NoOpMetricsCollector,
+    PrometheusMetricsCollector,
+)
+from agentic_exception_sdk.observability.otel import OTelExceptionAdapter
+
+# Observability
+from agentic_exception_sdk.observability.sink import ExceptionEventSink, NoOpSink
+from agentic_exception_sdk.observability.structured_log import StructuredLogEmitter
+from agentic_exception_sdk.persistence import (
+    AvailabilityMode,
+    Checkpoint,
+    NullProvider,
+    PersistedEnvelope,
+    PersistenceProvider,
+    ProviderCapabilities,
+    attestation,
+    get_active_provider,
+    set_active_provider,
+)
+
+# Propagation
+from agentic_exception_sdk.propagation.bus import (
+    AsyncExceptionPropagationBus,
+    AsyncInMemoryBus,
+    ExceptionPropagationBus,
+    InMemoryBus,
+    PropagationBufferFullError,
+)
+from agentic_exception_sdk.propagation.dlq import (
+    AsyncInMemoryDLQ,
+    DeadLetterQueue,
+    InMemoryDLQ,
+)
+from agentic_exception_sdk.propagation.protocol import (
+    envelope_canonical_bytes,
+    envelope_canonical_sha256,
+    envelope_debug_repr,
+    envelope_from_json,
+    envelope_leaf_hash,
+    envelope_to_json,
+)
+
+# Resilience components
+from agentic_exception_sdk.resilience.circuit_breaker import (
+    AsyncInMemoryCircuitBreaker,
+    CircuitState,
+    InMemoryCircuitBreaker,
+    NoOpAsyncCircuitBreaker,
+    NoOpCircuitBreaker,
+)
+from agentic_exception_sdk.resilience.compensating import (
+    CompensatingTransactionRegistry,
+)
+from agentic_exception_sdk.resilience.fallback import (
+    FallbackChain,
+    NoOpFallback,
+    OrderedFallbackChain,
+)
+from agentic_exception_sdk.resilience.retry import (
+    ExponentialBackoffRetry,
+    InMemoryRetryInFlightTracker,
+    NoOpRetry,
+    RetryContext,
+    RetryInFlightEntry,
+    RetryInFlightTracker,
+)
+
+# Primary resilience entry points
+from agentic_exception_sdk.resilience.wrap import (
+    MISSING,
+    ResilientCallConfig,
+    async_resilient,
+    extend_lineage,
+    force_flush_exception_telemetry,
+    resilient,
+)
+from agentic_exception_sdk.taxonomy.classifier import ExceptionClassifier
+
+# Core taxonomy — enums, errors, envelope, classifier
+from agentic_exception_sdk.taxonomy.enums import (
+    AgentExceptionClass,
+    EscalationLevel,
+    ExceptionSource,
+)
+from agentic_exception_sdk.taxonomy.envelope import (
+    AgentExceptionEnvelope,
+    SafeContextSnapshot,
+    SafeContextValue,
+)
+from agentic_exception_sdk.taxonomy.errors import (
+    AgentHardKillError,
+    BudgetExhaustedError,
+    BudgetWarningError,
+    CircuitBreakerStateUnavailableError,
+    CompensationPartialFailureError,
+    FallbackCapableError,
+    GuardRailViolationError,
+    PromptInjectionError,
+    SecurityViolationError,
+    SLAViolationError,
+    StateCorruptionError,
+    ToolKindMismatchError,
+    ValidationGateError,
+)
+
+# Validation
+from agentic_exception_sdk.validation.gates import (
+    NoOpGate,
+    OutputValidationGate,
+    PydanticValidationGate,
+)
+from agentic_exception_sdk.validation.guard_rails import (
+    AllowlistedOperations,
+    GuardRailPolicy,
+    NoOpGuardRails,
+)
+from agentic_exception_sdk.validation.rules_version import RULES_VERSION
+from agentic_exception_sdk.validation.trust_boundary import TrustBoundaryValidator
+
+__all__ = [
+    "__version__",
+    # Taxonomy
+    "AgentExceptionClass",
+    "AgentExceptionEnvelope",
+    "AgentHardKillError",
+    "BudgetExhaustedError",
+    "BudgetWarningError",
+    "CircuitBreakerStateUnavailableError",
+    "CompensationPartialFailureError",
+    "EscalationLevel",
+    "ExceptionClassifier",
+    "ExceptionSource",
+    "FallbackCapableError",
+    "GuardRailViolationError",
+    "PromptInjectionError",
+    "SafeContextSnapshot",
+    "SafeContextValue",
+    "SecurityViolationError",
+    "SLAViolationError",
+    "StateCorruptionError",
+    "ToolKindMismatchError",
+    "ValidationGateError",
+    # Bundle
+    "BundleValidationError",
+    "NoOpResilienceBundle",
+    "ResilienceBundle",
+    "validate_bundle",
+    # Resilience wrappers
+    "MISSING",
+    "ResilientCallConfig",
+    "async_resilient",
+    "extend_lineage",
+    "force_flush_exception_telemetry",
+    "resilient",
+    # Circuit breakers
+    "AsyncInMemoryCircuitBreaker",
+    "CircuitState",
+    "InMemoryCircuitBreaker",
+    "NoOpAsyncCircuitBreaker",
+    "NoOpCircuitBreaker",
+    # Retry
+    "ExponentialBackoffRetry",
+    "InMemoryRetryInFlightTracker",
+    "NoOpRetry",
+    "RetryContext",
+    "RetryInFlightEntry",
+    "RetryInFlightTracker",
+    # Fallback
+    "FallbackChain",
+    "NoOpFallback",
+    "OrderedFallbackChain",
+    # Compensating transactions
+    "CompensatingTransactionRegistry",
+    # Validation
+    "AllowlistedOperations",
+    "GuardRailPolicy",
+    "NoOpGate",
+    "NoOpGuardRails",
+    "OutputValidationGate",
+    "PydanticValidationGate",
+    "RULES_VERSION",
+    "TrustBoundaryValidator",
+    # Budget
+    "AgentBudget",
+    "BudgetWatchdog",
+    "UnlimitedBudget",
+    # Escalation
+    "CheckpointStore",
+    "EscalationHandlerLike",
+    "EscalationRouter",
+    "InMemoryCheckpointStore",
+    "NoOpEscalationRouter",
+    "NoOpHandler",
+    "RecoveryDirective",
+    # Persistence
+    "AvailabilityMode",
+    "Checkpoint",
+    "NullProvider",
+    "PersistedEnvelope",
+    "PersistenceProvider",
+    "ProviderCapabilities",
+    "attestation",
+    "get_active_provider",
+    "set_active_provider",
+    # Propagation
+    "AsyncExceptionPropagationBus",
+    "AsyncInMemoryBus",
+    "AsyncInMemoryDLQ",
+    "DeadLetterQueue",
+    "ExceptionPropagationBus",
+    "InMemoryBus",
+    "InMemoryDLQ",
+    "PropagationBufferFullError",
+    "envelope_canonical_bytes",
+    "envelope_canonical_sha256",
+    "envelope_debug_repr",
+    "envelope_from_json",
+    "envelope_leaf_hash",
+    "envelope_to_json",
+    # Observability
+    "ExceptionEventSink",
+    "InMemoryMetricsCollector",
+    "MetricsCollector",
+    "NoOpMetricsCollector",
+    "NoOpSink",
+    "OTelExceptionAdapter",
+    "PrometheusMetricsCollector",
+    "StructuredLogEmitter",
+    # Multi-agent
+    "AgentSLAPolicy",
+    "AgentOutcome",
+    "ConsensusGate",
+    "ConsensusNotReachedError",
+    "FanOutOutcomeEnvelope",
+    "OrchestratorExceptionRouter",
+    "WorkerHandler",
+    "call_parallel",
+    "fan_out",
+]

agentic_exception_sdk/__init__.pyi

@@ -0,0 +1,38 @@
+from _typeshed import Incomplete
+from agentic_exception_sdk.budget.models import AgentBudget as AgentBudget, UnlimitedBudget as UnlimitedBudget
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog as BudgetWatchdog
+from agentic_exception_sdk.bundle import ResilienceBundle as ResilienceBundle
+from agentic_exception_sdk.config.validate import BundleValidationError as BundleValidationError, validate_bundle as validate_bundle
+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
+from agentic_exception_sdk.multi_agent.consensus import ConsensusGate as ConsensusGate, ConsensusNotReachedError as ConsensusNotReachedError
+from agentic_exception_sdk.multi_agent.parallel import AgentOutcome as AgentOutcome, FanOutOutcomeEnvelope as FanOutOutcomeEnvelope, call_parallel as call_parallel
+from agentic_exception_sdk.multi_agent.router import OrchestratorExceptionRouter as OrchestratorExceptionRouter, WorkerHandler as WorkerHandler, fan_out as fan_out
+from agentic_exception_sdk.multi_agent.sla import AgentSLAPolicy as AgentSLAPolicy
+from agentic_exception_sdk.noop import NoOpResilienceBundle as NoOpResilienceBundle
+from agentic_exception_sdk.observability.metrics import InMemoryMetricsCollector as InMemoryMetricsCollector, MetricsCollector as MetricsCollector, NoOpMetricsCollector as NoOpMetricsCollector, PrometheusMetricsCollector as PrometheusMetricsCollector
+from agentic_exception_sdk.observability.otel import OTelExceptionAdapter as OTelExceptionAdapter
+from agentic_exception_sdk.observability.sink import ExceptionEventSink as ExceptionEventSink, NoOpSink as NoOpSink
+from agentic_exception_sdk.observability.structured_log import StructuredLogEmitter as StructuredLogEmitter
+from agentic_exception_sdk.persistence import AvailabilityMode as AvailabilityMode, Checkpoint as Checkpoint, NullProvider as NullProvider, PersistedEnvelope as PersistedEnvelope, PersistenceProvider as PersistenceProvider, ProviderCapabilities as ProviderCapabilities, attestation as attestation, get_active_provider as get_active_provider, set_active_provider as set_active_provider
+from agentic_exception_sdk.propagation.bus import AsyncExceptionPropagationBus as AsyncExceptionPropagationBus, AsyncInMemoryBus as AsyncInMemoryBus, ExceptionPropagationBus as ExceptionPropagationBus, InMemoryBus as InMemoryBus, PropagationBufferFullError as PropagationBufferFullError
+from agentic_exception_sdk.propagation.dlq import AsyncInMemoryDLQ as AsyncInMemoryDLQ, DeadLetterQueue as DeadLetterQueue, InMemoryDLQ as InMemoryDLQ
+from agentic_exception_sdk.propagation.protocol import envelope_canonical_bytes as envelope_canonical_bytes, envelope_canonical_sha256 as envelope_canonical_sha256, envelope_debug_repr as envelope_debug_repr, envelope_from_json as envelope_from_json, envelope_leaf_hash as envelope_leaf_hash, envelope_to_json as envelope_to_json
+from agentic_exception_sdk.resilience.circuit_breaker import AsyncInMemoryCircuitBreaker as AsyncInMemoryCircuitBreaker, CircuitState as CircuitState, InMemoryCircuitBreaker as InMemoryCircuitBreaker, NoOpAsyncCircuitBreaker as NoOpAsyncCircuitBreaker, NoOpCircuitBreaker as NoOpCircuitBreaker
+from agentic_exception_sdk.resilience.compensating import CompensatingTransactionRegistry as CompensatingTransactionRegistry
+from agentic_exception_sdk.resilience.fallback import FallbackChain as FallbackChain, NoOpFallback as NoOpFallback, OrderedFallbackChain as OrderedFallbackChain
+from agentic_exception_sdk.resilience.retry import ExponentialBackoffRetry as ExponentialBackoffRetry, InMemoryRetryInFlightTracker as InMemoryRetryInFlightTracker, NoOpRetry as NoOpRetry, RetryContext as RetryContext, RetryInFlightEntry as RetryInFlightEntry, RetryInFlightTracker as RetryInFlightTracker
+from agentic_exception_sdk.resilience.wrap import MISSING as MISSING, ResilientCallConfig as ResilientCallConfig, async_resilient as async_resilient, extend_lineage as extend_lineage, force_flush_exception_telemetry as force_flush_exception_telemetry, resilient as resilient
+from agentic_exception_sdk.taxonomy.classifier import ExceptionClassifier as ExceptionClassifier
+from agentic_exception_sdk.taxonomy.enums import AgentExceptionClass as AgentExceptionClass, EscalationLevel as EscalationLevel, ExceptionSource as ExceptionSource
+from agentic_exception_sdk.taxonomy.envelope import AgentExceptionEnvelope as AgentExceptionEnvelope, SafeContextSnapshot as SafeContextSnapshot, SafeContextValue as SafeContextValue
+from agentic_exception_sdk.taxonomy.errors import AgentHardKillError as AgentHardKillError, BudgetExhaustedError as BudgetExhaustedError, BudgetWarningError as BudgetWarningError, CircuitBreakerStateUnavailableError as CircuitBreakerStateUnavailableError, CompensationPartialFailureError as CompensationPartialFailureError, FallbackCapableError as FallbackCapableError, GuardRailViolationError as GuardRailViolationError, PromptInjectionError as PromptInjectionError, SLAViolationError as SLAViolationError, SecurityViolationError as SecurityViolationError, StateCorruptionError as StateCorruptionError, ToolKindMismatchError as ToolKindMismatchError, ValidationGateError as ValidationGateError
+from agentic_exception_sdk.validation.gates import NoOpGate as NoOpGate, OutputValidationGate as OutputValidationGate, PydanticValidationGate as PydanticValidationGate
+from agentic_exception_sdk.validation.guard_rails import AllowlistedOperations as AllowlistedOperations, GuardRailPolicy as GuardRailPolicy, NoOpGuardRails as NoOpGuardRails
+from agentic_exception_sdk.validation.rules_version import RULES_VERSION as RULES_VERSION
+from agentic_exception_sdk.validation.trust_boundary import TrustBoundaryValidator as TrustBoundaryValidator
+
+__all__ = ['__version__', 'AgentExceptionClass', 'AgentExceptionEnvelope', 'AgentHardKillError', 'BudgetExhaustedError', 'BudgetWarningError', 'CircuitBreakerStateUnavailableError', 'CompensationPartialFailureError', 'EscalationLevel', 'ExceptionClassifier', 'ExceptionSource', 'FallbackCapableError', 'GuardRailViolationError', 'PromptInjectionError', 'SafeContextSnapshot', 'SafeContextValue', 'SecurityViolationError', 'SLAViolationError', 'StateCorruptionError', 'ToolKindMismatchError', 'ValidationGateError', 'BundleValidationError', 'NoOpResilienceBundle', 'ResilienceBundle', 'validate_bundle', 'MISSING', 'ResilientCallConfig', 'async_resilient', 'extend_lineage', 'force_flush_exception_telemetry', 'resilient', 'AsyncInMemoryCircuitBreaker', 'CircuitState', 'InMemoryCircuitBreaker', 'NoOpAsyncCircuitBreaker', 'NoOpCircuitBreaker', 'ExponentialBackoffRetry', 'InMemoryRetryInFlightTracker', 'NoOpRetry', 'RetryContext', 'RetryInFlightEntry', 'RetryInFlightTracker', 'FallbackChain', 'NoOpFallback', 'OrderedFallbackChain', 'CompensatingTransactionRegistry', 'AllowlistedOperations', 'GuardRailPolicy', 'NoOpGate', 'NoOpGuardRails', 'OutputValidationGate', 'PydanticValidationGate', 'RULES_VERSION', 'TrustBoundaryValidator', 'AgentBudget', 'BudgetWatchdog', 'UnlimitedBudget', 'CheckpointStore', 'EscalationHandlerLike', 'EscalationRouter', 'InMemoryCheckpointStore', 'NoOpEscalationRouter', 'NoOpHandler', 'RecoveryDirective', 'AvailabilityMode', 'Checkpoint', 'NullProvider', 'PersistedEnvelope', 'PersistenceProvider', 'ProviderCapabilities', 'attestation', 'get_active_provider', 'set_active_provider', 'AsyncExceptionPropagationBus', 'AsyncInMemoryBus', 'AsyncInMemoryDLQ', 'DeadLetterQueue', 'ExceptionPropagationBus', 'InMemoryBus', 'InMemoryDLQ', 'PropagationBufferFullError', 'envelope_canonical_bytes', 'envelope_canonical_sha256', 'envelope_debug_repr', 'envelope_from_json', 'envelope_leaf_hash', 'envelope_to_json', 'ExceptionEventSink', 'InMemoryMetricsCollector', 'MetricsCollector', 'NoOpMetricsCollector', 'NoOpSink', 'OTelExceptionAdapter', 'PrometheusMetricsCollector', 'StructuredLogEmitter', 'AgentSLAPolicy', 'AgentOutcome', 'ConsensusGate', 'ConsensusNotReachedError', 'FanOutOutcomeEnvelope', 'OrchestratorExceptionRouter', 'WorkerHandler', 'call_parallel', 'fan_out']
+
+__version__: Incomplete

agentic_exception_sdk/budget/__init__.py

@@ -0,0 +1,14 @@
+"""Budget: agent resource models and watchdog enforcement."""
+
+from __future__ import annotations
+
+from agentic_exception_sdk.budget.models import AgentBudget, UnlimitedBudget
+from agentic_exception_sdk.budget.streaming import StreamingBudgetGuard
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+
+__all__ = [
+    "AgentBudget",
+    "BudgetWatchdog",
+    "StreamingBudgetGuard",
+    "UnlimitedBudget",
+]

agentic_exception_sdk/budget/__init__.pyi

@@ -0,0 +1,5 @@
+from agentic_exception_sdk.budget.models import AgentBudget as AgentBudget, UnlimitedBudget as UnlimitedBudget
+from agentic_exception_sdk.budget.streaming import StreamingBudgetGuard as StreamingBudgetGuard
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog as BudgetWatchdog
+
+__all__ = ['AgentBudget', 'BudgetWatchdog', 'StreamingBudgetGuard', 'UnlimitedBudget']

agentic_exception_sdk/budget/models.py

@@ -0,0 +1,48 @@
+"""Agent budget data models.
+
+Monetary ceilings use integer micro-USD (1 USD == 1_000_000 micro-USD).
+Binary floating point is never used for monetary values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["AgentBudget", "UnlimitedBudget"]
+
+
+@dataclass(frozen=True)
+class AgentBudget:
+    """Resource ceiling configuration for an agent run.
+
+    All fields are optional. When None, that ceiling is not enforced.
+    Non-LLM workloads can ignore token/cost fields entirely; LLM-facing
+    systems should set all relevant ceilings.
+
+    Monetary ceilings use integer micro-USD where $1.00 == 1_000_000.
+    Never use binary floating point for monetary ceilings.
+
+    Attributes:
+        max_seconds: Wall-clock time limit in seconds for the entire agent run.
+        max_tool_calls: Maximum total tool call invocations allowed.
+        failure_budget: Maximum number of failed tool call attempts before escalation.
+        max_input_tokens: Maximum input tokens consumed across all LLM calls.
+        max_output_tokens: Maximum output tokens generated across all LLM calls.
+        max_total_cost_micros_usd: Maximum total cost in integer micro-USD.
+    """
+
+    max_seconds: float | None = None
+    max_tool_calls: int | None = None
+    failure_budget: int | None = None
+    max_input_tokens: int | None = None
+    max_output_tokens: int | None = None
+    max_total_cost_micros_usd: int | None = None
+
+
+def UnlimitedBudget() -> AgentBudget:
+    """Return an AgentBudget with no enforced limits.
+
+    Returns:
+        An AgentBudget where all ceiling fields are None.
+    """
+    return AgentBudget()

agentic_exception_sdk/budget/models.pyi

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+__all__ = ['AgentBudget', 'UnlimitedBudget']
+
+@dataclass(frozen=True)
+class AgentBudget:
+    max_seconds: float | None = ...
+    max_tool_calls: int | None = ...
+    failure_budget: int | None = ...
+    max_input_tokens: int | None = ...
+    max_output_tokens: int | None = ...
+    max_total_cost_micros_usd: int | None = ...
+
+def UnlimitedBudget() -> AgentBudget: ...

agentic_exception_sdk/budget/streaming.py

@@ -0,0 +1,144 @@
+"""Streaming LLM budget enforcement.
+
+Provides a context manager and async generator wrapper that checks the
+BudgetWatchdog after each streamed chunk. When the budget ceiling is exceeded
+mid-stream, raises BudgetExhaustedError to abort generation.
+
+Usage (OpenAI-style streaming):
+    guard = StreamingBudgetGuard(watchdog, tool_name="llm-call", agent_id="agent-1")
+    with guard:
+        for chunk in openai_client.chat.completions.create(..., stream=True):
+            guard.record_chunk(token_delta=chunk.usage.completion_tokens or 1)
+            yield chunk.choices[0].delta.content
+
+Usage (async):
+    async with guard:
+        async for chunk in async_stream:
+            await guard.arecord_chunk(token_delta=...)
+            yield chunk
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterable, Callable, Generator, Iterable
+from typing import Literal, TypeVar
+
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+from agentic_exception_sdk.taxonomy.errors import BudgetExhaustedError
+
+__all__ = ["StreamingBudgetGuard"]
+
+T = TypeVar("T")
+
+
+class StreamingBudgetGuard:
+    """Abort streaming LLM output when a BudgetWatchdog ceiling is exceeded."""
+
+    def __init__(
+        self,
+        watchdog: BudgetWatchdog,
+        *,
+        tool_name: str,
+        agent_id: str,
+        correlation_id: str | None = None,
+    ) -> None:
+        self.watchdog = watchdog
+        self.tool_name = tool_name
+        self.agent_id = agent_id
+        self.correlation_id = correlation_id
+        self.total_tokens_streamed = 0
+        self.total_cost_streamed = 0.0
+
+    def __enter__(self) -> StreamingBudgetGuard:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: object | None,
+    ) -> Literal[False]:
+        return False
+
+    async def __aenter__(self) -> StreamingBudgetGuard:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: object | None,
+    ) -> Literal[False]:
+        return False
+
+    def record_chunk(self, token_delta: int = 1, cost_delta: float = 0.0) -> None:
+        """Record one streamed chunk and raise immediately on budget exhaustion."""
+        cost_micros_usd = _cost_to_micros(cost_delta)
+        self.watchdog.account_stream_delta(
+            output_tokens=token_delta,
+            cost_micros_usd=cost_micros_usd,
+        )
+        self.total_tokens_streamed += token_delta
+        self.total_cost_streamed += cost_delta
+
+    async def arecord_chunk(self, token_delta: int = 1, cost_delta: float = 0.0) -> None:
+        """Async record of one streamed chunk and raise on budget exhaustion."""
+        cost_micros_usd = _cost_to_micros(cost_delta)
+        await self.watchdog.async_reserve_tokens(
+            output_tokens=token_delta,
+            cost_micros_usd=cost_micros_usd,
+        )
+        self.total_tokens_streamed += token_delta
+        self.total_cost_streamed += cost_delta
+
+    @classmethod
+    def wrap_sync_stream(
+        cls,
+        stream: Iterable[T],
+        watchdog: BudgetWatchdog,
+        *,
+        tool_name: str,
+        agent_id: str,
+        token_extractor: Callable[[T], int] = lambda _: 1,
+        cost_extractor: Callable[[T], float] = lambda _: 0.0,
+    ) -> Generator[T, None, None]:
+        """Yield stream items while enforcing budget before each yield."""
+        guard = cls(watchdog, tool_name=tool_name, agent_id=agent_id)
+        with guard:
+            for chunk in stream:
+                try:
+                    guard.record_chunk(
+                        token_delta=token_extractor(chunk),
+                        cost_delta=cost_extractor(chunk),
+                    )
+                except BudgetExhaustedError:
+                    raise
+                yield chunk
+
+    @classmethod
+    async def awrap_async_stream(
+        cls,
+        stream: AsyncIterable[T],
+        watchdog: BudgetWatchdog,
+        *,
+        tool_name: str,
+        agent_id: str,
+        token_extractor: Callable[[T], int] = lambda _: 1,
+        cost_extractor: Callable[[T], float] = lambda _: 0.0,
+    ) -> AsyncGenerator[T, None]:
+        """Async-yield stream items while enforcing budget before each yield."""
+        guard = cls(watchdog, tool_name=tool_name, agent_id=agent_id)
+        async with guard:
+            async for chunk in stream:
+                try:
+                    await guard.arecord_chunk(
+                        token_delta=token_extractor(chunk),
+                        cost_delta=cost_extractor(chunk),
+                    )
+                except BudgetExhaustedError:
+                    raise
+                yield chunk
+
+
+def _cost_to_micros(cost_delta: float) -> int:
+    return round(cost_delta * 1_000_000)

agentic_exception_sdk/budget/streaming.pyi

@@ -0,0 +1,27 @@
+from _typeshed import Incomplete
+from agentic_exception_sdk.budget.watchdog import BudgetWatchdog
+from collections.abc import AsyncGenerator, AsyncIterable, Callable, Generator, Iterable
+from typing import Literal, TypeVar
+
+__all__ = ['StreamingBudgetGuard']
+
+T = TypeVar('T')
+
+class StreamingBudgetGuard:
+    watchdog: Incomplete
+    tool_name: Incomplete
+    agent_id: Incomplete
+    correlation_id: Incomplete
+    total_tokens_streamed: int
+    total_cost_streamed: float
+    def __init__(self, watchdog: BudgetWatchdog, *, tool_name: str, agent_id: str, correlation_id: str | None = None) -> None: ...
+    def __enter__(self) -> StreamingBudgetGuard: ...
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: object | None) -> Literal[False]: ...
+    async def __aenter__(self) -> StreamingBudgetGuard: ...
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: object | None) -> Literal[False]: ...
+    def record_chunk(self, token_delta: int = 1, cost_delta: float = 0.0) -> None: ...
+    async def arecord_chunk(self, token_delta: int = 1, cost_delta: float = 0.0) -> None: ...
+    @classmethod
+    def wrap_sync_stream(cls, stream: Iterable[T], watchdog: BudgetWatchdog, *, tool_name: str, agent_id: str, token_extractor: Callable[[T], int] = ..., cost_extractor: Callable[[T], float] = ...) -> Generator[T, None, None]: ...
+    @classmethod
+    async def awrap_async_stream(cls, stream: AsyncIterable[T], watchdog: BudgetWatchdog, *, tool_name: str, agent_id: str, token_extractor: Callable[[T], int] = ..., cost_extractor: Callable[[T], float] = ...) -> AsyncGenerator[T, None]: ...