guardloop 0.2.0__py3-none-any.whl

guardloop/__init__.py

@@ -0,0 +1,48 @@
+"""GuardLoop public API."""
+
+from guardloop.circuit_breaker import (
+    CircuitBreakerConfig,
+    CircuitBreakerPolicy,
+    CircuitBreakerSnapshot,
+    CircuitBreakerState,
+)
+from guardloop.context import RunContext
+from guardloop.exceptions import (
+    BudgetExceeded,
+    CircuitBreakerOpen,
+    GuardLoopError,
+    ModelPricingMissing,
+    TimeLimitExceeded,
+    TokenLimitExceeded,
+    TokenLimitMissing,
+    ToolCallLimitExceeded,
+)
+from guardloop.models import BudgetConfig, RunResult, TelemetryConfig
+from guardloop.pricing import ModelPricing
+from guardloop.runtime import GuardLoop
+
+AgentRuntime = GuardLoop
+AgentRuntimeError = GuardLoopError
+
+__all__ = [
+    "AgentRuntime",
+    "AgentRuntimeError",
+    "BudgetConfig",
+    "BudgetExceeded",
+    "CircuitBreakerConfig",
+    "CircuitBreakerOpen",
+    "CircuitBreakerPolicy",
+    "CircuitBreakerSnapshot",
+    "CircuitBreakerState",
+    "GuardLoop",
+    "GuardLoopError",
+    "ModelPricing",
+    "ModelPricingMissing",
+    "RunContext",
+    "RunResult",
+    "TelemetryConfig",
+    "TimeLimitExceeded",
+    "TokenLimitExceeded",
+    "TokenLimitMissing",
+    "ToolCallLimitExceeded",
+]

guardloop/budget.py

@@ -0,0 +1,180 @@
+"""Resource accounting and hard pre-flight budget checks."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from decimal import Decimal
+
+from guardloop.exceptions import (
+    BudgetExceeded,
+    TimeLimitExceeded,
+    TokenLimitExceeded,
+    TokenLimitMissing,
+    ToolCallLimitExceeded,
+)
+from guardloop.models import BudgetConfig
+from guardloop.pricing import ModelPricing, PricingCatalog
+
+
+@dataclass(frozen=True, slots=True)
+class LLMPreflight:
+    provider: str
+    model: str
+    estimated_input_tokens: int
+    reserved_output_tokens: int
+    estimated_cost_usd: Decimal
+    pricing: ModelPricing
+
+
+class BudgetController:
+    """Single source of truth for one runtime execution's resource usage."""
+
+    def __init__(self, config: BudgetConfig, pricing_catalog: PricingCatalog) -> None:
+        self.config = config
+        self.pricing_catalog = pricing_catalog
+        self._started_at = time.monotonic()
+        self._cost_usd = Decimal("0")
+        self._estimated_cost_usd = Decimal("0")
+        self._input_tokens = 0
+        self._output_tokens = 0
+        self._tool_calls = 0
+
+    @property
+    def cost_usd(self) -> Decimal:
+        return self._cost_usd
+
+    @property
+    def estimated_cost_usd(self) -> Decimal:
+        return self._estimated_cost_usd
+
+    @property
+    def input_tokens(self) -> int:
+        return self._input_tokens
+
+    @property
+    def output_tokens(self) -> int:
+        return self._output_tokens
+
+    @property
+    def tokens_used(self) -> int:
+        return self._input_tokens + self._output_tokens
+
+    @property
+    def tool_calls(self) -> int:
+        return self._tool_calls
+
+    @property
+    def duration_seconds(self) -> float:
+        return time.monotonic() - self._started_at
+
+    def check_time(self) -> None:
+        if (
+            self.config.time_limit_seconds is not None
+            and self.duration_seconds > self.config.time_limit_seconds
+        ):
+            raise TimeLimitExceeded(
+                f"Run exceeded time limit of {self.config.time_limit_seconds:.3f}s.",
+                details={
+                    "limit_seconds": self.config.time_limit_seconds,
+                    "duration_seconds": self.duration_seconds,
+                },
+            )
+
+    def check_llm_call(
+        self,
+        *,
+        provider: str,
+        model: str,
+        estimated_input_tokens: int,
+        reserved_output_tokens: int | None,
+    ) -> LLMPreflight:
+        self.check_time()
+        if reserved_output_tokens is None or reserved_output_tokens <= 0:
+            raise TokenLimitMissing(
+                "LLM calls must include a positive max output token limit so the runtime can "
+                "reserve worst-case spend before the request."
+            )
+
+        pricing = self.pricing_catalog.get(provider, model)
+        projected_tokens = self.tokens_used + estimated_input_tokens + reserved_output_tokens
+        if self.config.token_limit is not None and projected_tokens > self.config.token_limit:
+            raise TokenLimitExceeded(
+                "LLM call would exceed token_limit before the request is sent.",
+                details={
+                    "limit": self.config.token_limit,
+                    "current_tokens": self.tokens_used,
+                    "estimated_input_tokens": estimated_input_tokens,
+                    "reserved_output_tokens": reserved_output_tokens,
+                    "projected_tokens": projected_tokens,
+                },
+            )
+
+        projected_call_cost = pricing.estimate_cost(
+            input_tokens=estimated_input_tokens,
+            output_tokens=reserved_output_tokens,
+        )
+        projected_cost = self.cost_usd + projected_call_cost
+        cost_limit = self.config.cost_limit
+        if cost_limit is not None and projected_cost > cost_limit:
+            raise BudgetExceeded(
+                "LLM call would exceed cost_limit_usd before the request is sent.",
+                limit=cost_limit,
+                current=self.cost_usd,
+                projected=projected_cost,
+            )
+
+        self._estimated_cost_usd += projected_call_cost
+        return LLMPreflight(
+            provider=provider,
+            model=model,
+            estimated_input_tokens=estimated_input_tokens,
+            reserved_output_tokens=reserved_output_tokens,
+            estimated_cost_usd=projected_call_cost,
+            pricing=pricing,
+        )
+
+    def record_llm_call(
+        self,
+        *,
+        provider: str,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+    ) -> Decimal:
+        self.check_time()
+        pricing = self.pricing_catalog.get(provider, model)
+        actual_cost = pricing.estimate_cost(input_tokens=input_tokens, output_tokens=output_tokens)
+        self._input_tokens += input_tokens
+        self._output_tokens += output_tokens
+        self._cost_usd += actual_cost
+
+        if self.config.token_limit is not None and self.tokens_used > self.config.token_limit:
+            raise TokenLimitExceeded(
+                "Actual provider usage exceeded token_limit after the request completed.",
+                details={"limit": self.config.token_limit, "tokens_used": self.tokens_used},
+            )
+        cost_limit = self.config.cost_limit
+        if cost_limit is not None and self.cost_usd > cost_limit:
+            raise BudgetExceeded(
+                "Actual provider usage exceeded cost_limit_usd after the request completed.",
+                limit=cost_limit,
+                current=self.cost_usd,
+                projected=self.cost_usd,
+            )
+        return actual_cost
+
+    def record_tool_call_started(self, tool_name: str) -> None:
+        self.check_time()
+        projected = self._tool_calls + 1
+        if self.config.tool_call_limit is not None and projected > self.config.tool_call_limit:
+            raise ToolCallLimitExceeded(
+                "Tool call would exceed tool_call_limit before the tool is invoked.",
+                details={
+                    "tool": tool_name,
+                    "limit": self.config.tool_call_limit,
+                    "current_tool_calls": self._tool_calls,
+                    "projected_tool_calls": projected,
+                },
+            )
+        self._tool_calls = projected

guardloop/circuit_breaker.py

@@ -0,0 +1,243 @@
+"""Per-tool circuit breaker state machines."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from guardloop.exceptions import CircuitBreakerOpen
+
+
+class CircuitBreakerState(StrEnum):
+    """Public circuit breaker states."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreakerPolicy(BaseModel):
+    """Failure policy for one tool circuit breaker."""
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = True
+    failure_threshold: int = 3
+    recovery_timeout_seconds: float = 30.0
+    half_open_success_threshold: int = 1
+
+    @field_validator("failure_threshold", "half_open_success_threshold")
+    @classmethod
+    def _validate_positive_int(cls, value: int) -> int:
+        if value < 1:
+            raise ValueError("circuit breaker thresholds must be at least 1")
+        return value
+
+    @field_validator("recovery_timeout_seconds")
+    @classmethod
+    def _validate_recovery_timeout(cls, value: float) -> float:
+        if value <= 0:
+            raise ValueError("recovery_timeout_seconds must be greater than zero")
+        return value
+
+
+class CircuitBreakerConfig(BaseModel):
+    """Circuit breaker configuration for runtime tools."""
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = True
+    default: CircuitBreakerPolicy = Field(default_factory=CircuitBreakerPolicy)
+    tool_overrides: dict[str, CircuitBreakerPolicy] = Field(default_factory=dict)
+
+
+class CircuitBreakerSnapshot(BaseModel):
+    """Point-in-time circuit breaker state for inspection and metadata."""
+
+    model_config = ConfigDict(frozen=True)
+
+    tool_name: str
+    state: CircuitBreakerState
+    failure_count: int = 0
+    consecutive_successes: int = 0
+    opened_at: float | None = None
+    remaining_open_seconds: float = 0.0
+
+
+@dataclass
+class CircuitBreakerDecision:
+    """Internal decision returned after a breaker state check or update."""
+
+    snapshot: CircuitBreakerSnapshot
+    events: tuple[str, ...] = ()
+
+
+@dataclass
+class _CircuitBreakerRecord:
+    policy: CircuitBreakerPolicy
+    state: CircuitBreakerState = CircuitBreakerState.CLOSED
+    failure_count: int = 0
+    consecutive_successes: int = 0
+    opened_at: float | None = None
+
+
+Clock = Callable[[], float]
+
+EVENT_OPENED = "guardloop.circuit_breaker.opened"
+EVENT_REOPENED = "guardloop.circuit_breaker.reopened"
+EVENT_HALF_OPENED = "guardloop.circuit_breaker.half_opened"
+EVENT_CLOSED = "guardloop.circuit_breaker.closed"
+
+
+class CircuitBreakerRegistry:
+    """Thread-safe in-memory registry of per-tool circuit breakers."""
+
+    def __init__(
+        self,
+        config: CircuitBreakerConfig | None = None,
+        *,
+        clock: Clock | None = None,
+    ) -> None:
+        self._config = config or CircuitBreakerConfig()
+        self._clock = clock or time.monotonic
+        self._lock = threading.Lock()
+        self._breakers: dict[str, _CircuitBreakerRecord] = {}
+
+    def before_call(self, tool_name: str) -> CircuitBreakerDecision | None:
+        policy = self._policy_for(tool_name)
+        if policy is None:
+            return None
+
+        with self._lock:
+            now = self._clock()
+            breaker = self._breaker_for(tool_name, policy)
+            if breaker.state != CircuitBreakerState.OPEN:
+                return CircuitBreakerDecision(snapshot=self._snapshot(tool_name, breaker, now))
+
+            remaining = self._remaining_open_seconds(breaker, now)
+            if remaining > 0:
+                snapshot = self._snapshot(tool_name, breaker, now)
+                raise CircuitBreakerOpen(
+                    tool_name=tool_name,
+                    state=snapshot.state.value,
+                    failure_count=snapshot.failure_count,
+                    remaining_open_seconds=snapshot.remaining_open_seconds,
+                )
+
+            breaker.state = CircuitBreakerState.HALF_OPEN
+            breaker.consecutive_successes = 0
+            return CircuitBreakerDecision(
+                snapshot=self._snapshot(tool_name, breaker, now),
+                events=(EVENT_HALF_OPENED,),
+            )
+
+    def record_success(self, tool_name: str) -> CircuitBreakerDecision | None:
+        policy = self._policy_for(tool_name)
+        if policy is None:
+            return None
+
+        with self._lock:
+            now = self._clock()
+            breaker = self._breaker_for(tool_name, policy)
+            events: tuple[str, ...] = ()
+
+            if breaker.state == CircuitBreakerState.HALF_OPEN:
+                breaker.consecutive_successes += 1
+                if breaker.consecutive_successes >= breaker.policy.half_open_success_threshold:
+                    breaker.state = CircuitBreakerState.CLOSED
+                    breaker.failure_count = 0
+                    breaker.consecutive_successes = 0
+                    breaker.opened_at = None
+                    events = (EVENT_CLOSED,)
+            elif breaker.state == CircuitBreakerState.CLOSED:
+                breaker.failure_count = 0
+                breaker.consecutive_successes = 0
+
+            return CircuitBreakerDecision(
+                snapshot=self._snapshot(tool_name, breaker, now), events=events
+            )
+
+    def record_failure(self, tool_name: str) -> CircuitBreakerDecision | None:
+        policy = self._policy_for(tool_name)
+        if policy is None:
+            return None
+
+        with self._lock:
+            now = self._clock()
+            breaker = self._breaker_for(tool_name, policy)
+            events: tuple[str, ...] = ()
+
+            if breaker.state == CircuitBreakerState.HALF_OPEN:
+                breaker.state = CircuitBreakerState.OPEN
+                breaker.failure_count = max(1, breaker.failure_count)
+                breaker.consecutive_successes = 0
+                breaker.opened_at = now
+                events = (EVENT_REOPENED,)
+            else:
+                breaker.failure_count += 1
+                breaker.consecutive_successes = 0
+                if (
+                    breaker.state == CircuitBreakerState.CLOSED
+                    and breaker.failure_count >= breaker.policy.failure_threshold
+                ):
+                    breaker.state = CircuitBreakerState.OPEN
+                    breaker.opened_at = now
+                    events = (EVENT_OPENED,)
+
+            return CircuitBreakerDecision(
+                snapshot=self._snapshot(tool_name, breaker, now), events=events
+            )
+
+    def snapshots(self) -> dict[str, CircuitBreakerSnapshot]:
+        with self._lock:
+            now = self._clock()
+            return {
+                tool_name: self._snapshot(tool_name, breaker, now)
+                for tool_name, breaker in sorted(self._breakers.items())
+            }
+
+    def reset(self, tool_name: str | None = None) -> None:
+        with self._lock:
+            if tool_name is None:
+                self._breakers.clear()
+                return
+            self._breakers.pop(tool_name, None)
+
+    def _policy_for(self, tool_name: str) -> CircuitBreakerPolicy | None:
+        if not self._config.enabled:
+            return None
+
+        policy = self._config.tool_overrides.get(tool_name, self._config.default)
+        if not policy.enabled:
+            return None
+        return policy
+
+    def _breaker_for(self, tool_name: str, policy: CircuitBreakerPolicy) -> _CircuitBreakerRecord:
+        breaker = self._breakers.get(tool_name)
+        if breaker is None:
+            breaker = _CircuitBreakerRecord(policy=policy)
+            self._breakers[tool_name] = breaker
+        return breaker
+
+    def _remaining_open_seconds(self, breaker: _CircuitBreakerRecord, now: float) -> float:
+        if breaker.state != CircuitBreakerState.OPEN or breaker.opened_at is None:
+            return 0.0
+        opened_until = breaker.opened_at + breaker.policy.recovery_timeout_seconds
+        return max(0.0, opened_until - now)
+
+    def _snapshot(
+        self, tool_name: str, breaker: _CircuitBreakerRecord, now: float
+    ) -> CircuitBreakerSnapshot:
+        return CircuitBreakerSnapshot(
+            tool_name=tool_name,
+            state=breaker.state,
+            failure_count=breaker.failure_count,
+            consecutive_successes=breaker.consecutive_successes,
+            opened_at=breaker.opened_at,
+            remaining_open_seconds=self._remaining_open_seconds(breaker, now),
+        )

guardloop/context.py

@@ -0,0 +1,68 @@
+"""RunContext passed to user agents."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from guardloop.budget import BudgetController
+from guardloop.circuit_breaker import CircuitBreakerRegistry
+from guardloop.providers.anthropic import WrappedAnthropicClient
+from guardloop.providers.openai import WrappedOpenAIClient
+from guardloop.telemetry.tracer import Telemetry
+from guardloop.tools import ToolRunner
+
+
+class RunContext:
+    """Runtime services available to an agent during one execution."""
+
+    def __init__(
+        self,
+        *,
+        budget: BudgetController,
+        telemetry: Telemetry,
+        circuit_breakers: CircuitBreakerRegistry,
+        openai_client: Any | None = None,
+        anthropic_client: Any | None = None,
+    ) -> None:
+        self.budget = budget
+        self.telemetry = telemetry
+        self._raw_openai_client = openai_client
+        self._raw_anthropic_client = anthropic_client
+        self._openai: WrappedOpenAIClient | None = None
+        self._anthropic: WrappedAnthropicClient | None = None
+        self._tools = ToolRunner(budget, telemetry, circuit_breakers)
+
+    @property
+    def openai(self) -> WrappedOpenAIClient:
+        if self._openai is None:
+            client = self._raw_openai_client
+            if client is None:
+                from openai import AsyncOpenAI
+
+                client = AsyncOpenAI()
+            self._openai = WrappedOpenAIClient(client, self.budget, self.telemetry)
+        return self._openai
+
+    @property
+    def anthropic(self) -> WrappedAnthropicClient:
+        if self._anthropic is None:
+            client = self._raw_anthropic_client
+            if client is None:
+                from anthropic import AsyncAnthropic
+
+                client = AsyncAnthropic()
+            self._anthropic = WrappedAnthropicClient(client, self.budget, self.telemetry)
+        return self._anthropic
+
+    def wrap_tool(self, name: str, func: Callable[..., Any]) -> Callable[..., Any]:
+        return self._tools.wrap(name, func)
+
+    async def call_tool(
+        self,
+        name: str,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return await self._tools.call(name, func, *args, **kwargs)

guardloop/exceptions.py

@@ -0,0 +1,92 @@
+"""Public exception hierarchy for controlled runtime stops."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+
+class GuardLoopError(Exception):
+    """Base class for all controlled GuardLoop exceptions."""
+
+    terminated_reason = "runtime_error"
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+
+class BudgetExceeded(GuardLoopError):
+    """Raised when a call would exceed the configured cost cap."""
+
+    terminated_reason = "budget_exceeded"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        limit: Decimal | None = None,
+        current: Decimal | None = None,
+        projected: Decimal | None = None,
+    ) -> None:
+        details = {"limit": limit, "current": current, "projected": projected}
+        super().__init__(message, details=details)
+
+
+class TokenLimitExceeded(GuardLoopError):
+    """Raised when a call would exceed the configured token cap."""
+
+    terminated_reason = "token_limit_exceeded"
+
+
+class ToolCallLimitExceeded(GuardLoopError):
+    """Raised when a tool call would exceed the configured tool-call cap."""
+
+    terminated_reason = "tool_call_limit_exceeded"
+
+
+class CircuitBreakerOpen(GuardLoopError):
+    """Raised when a tool circuit breaker rejects a call."""
+
+    terminated_reason = "circuit_breaker_open"
+
+    def __init__(
+        self,
+        *,
+        tool_name: str,
+        state: str,
+        failure_count: int,
+        remaining_open_seconds: float,
+    ) -> None:
+        details = {
+            "tool_name": tool_name,
+            "state": state,
+            "failure_count": failure_count,
+            "remaining_open_seconds": remaining_open_seconds,
+        }
+        super().__init__(
+            f"Circuit breaker for tool '{tool_name}' is open for another "
+            f"{remaining_open_seconds:.3f}s.",
+            details=details,
+        )
+
+
+class TimeLimitExceeded(GuardLoopError):
+    """Raised when the run exceeds the configured wall-clock cap."""
+
+    terminated_reason = "timeout"
+
+
+class ModelPricingMissing(GuardLoopError):
+    """Raised when no pricing entry exists for a provider/model pair."""
+
+    terminated_reason = "model_pricing_missing"
+
+
+class TokenLimitMissing(GuardLoopError):
+    """Raised when the runtime cannot reserve output tokens before an LLM call."""
+
+    terminated_reason = "token_limit_missing"
+
+
+AgentRuntimeError = GuardLoopError