agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/production/exceptions.py

@@ -0,0 +1,136 @@
+"""AgentForge exception hierarchy.
+
+Every exception the framework raises is a subclass of `AgentForgeError`.
+This is the only place new top-level exception classes are defined; per
+.claude/standards/coding.md, modules subclass these for their own
+errors but never `raise Exception(...)`.
+"""
+
+from __future__ import annotations
+
+
+class AgentForgeError(Exception):
+    """Base exception for all AgentForge errors.
+
+    Catch this to handle any framework-raised error generically.
+    Production code should narrow to a more specific subclass.
+    """
+
+
+# Locked names per the framework's public API; suppress N818 globally
+# in this file so individual classes don't need per-line noqa.
+# ruff: noqa: N818
+
+
+class BudgetExceeded(AgentForgeError):
+    """Raised when `BudgetPolicy.check` detects a USD or token cap breach.
+
+    The agent run terminates immediately; partial state is preserved on
+    `RunResult`.
+    """
+
+
+class GuardrailViolation(AgentForgeError):
+    """Raised when a non-budget guardrail trips.
+
+    Examples: iteration cap reached, error streak limit hit. Distinct
+    from `BudgetExceeded` so callers can branch on the cause.
+    """
+
+
+class ModuleError(AgentForgeError):
+    """Raised at agent construction when the resolver cannot find a
+    registered module by name.
+
+    Surfaced at startup (P11 — fail at startup, not at runtime), with a
+    clear message telling the developer which package to install or
+    which entry point is missing.
+    """
+
+
+class ProviderError(AgentForgeError):
+    """Base for errors originating in an LLM / embedding provider.
+
+    Concrete subclasses below cover the cross-provider failure modes
+    every reasoning loop needs to branch on. Provider drivers map
+    their SDK exceptions into one of these at the boundary; callers
+    catch `ProviderError` for general handling or narrow to a
+    specific subclass for retry / surfacing logic.
+    """
+
+
+class RateLimitError(ProviderError):
+    """The provider throttled the request (HTTP 429 / `ThrottlingException`).
+
+    Retryable with exponential backoff. Provider drivers honour
+    `Retry-After` headers when present.
+    """
+
+
+class AuthenticationError(ProviderError):
+    """The provider rejected credentials (HTTP 401 / 403).
+
+    Not retryable. The agent run terminates and the developer fixes
+    credentials at the deployment layer.
+    """
+
+
+class ModelNotFoundError(ProviderError):
+    """The provider does not recognise the requested model id.
+
+    Surfaced at the first call rather than at construction because
+    most providers don't expose a synchronous "does this model exist"
+    check. Not retryable.
+    """
+
+
+class ServiceError(ProviderError):
+    """The provider returned a transient server error (HTTP 5xx).
+
+    Retryable. Drivers retry up to `max_retries` times with bounded
+    exponential backoff before propagating.
+    """
+
+
+class TimeoutError(ProviderError):
+    """A request to the provider exceeded the configured timeout.
+
+    Distinct from the stdlib `TimeoutError` (which subclasses
+    `OSError`); this one subclasses `ProviderError` so it can be
+    caught by the same handler as other provider failures. Retryable.
+    """
+
+
+class CapabilityNotSupported(AgentForgeError):
+    """Raised when an optional capability is invoked on a driver that
+    does not declare it.
+
+    Per ADR-0009, capability negotiation is honest — drivers declare
+    their supported set and this exception fires if a consumer skipped
+    the `supports(...)` check.
+    """
+
+
+class A2ACallError(AgentForgeError):
+    """Raised when an A2A call to a remote peer fails (feat-014).
+
+    Wraps the underlying HTTP / transport error; carries the peer
+    URL and the error code from the response body when available.
+    """
+
+
+class A2AAuthError(A2ACallError):
+    """The peer rejected the supplied credentials (HTTP 401/403).
+
+    Distinct from `A2ACallError` so callers can branch on retry
+    semantics — auth errors are not retryable without rotating
+    the credential.
+    """
+
+
+class A2ATimeout(A2ACallError):
+    """The A2A call exceeded its configured timeout.
+
+    Retryable with backoff. Subclasses `A2ACallError` so generic
+    A2A handlers catch all transport failures at one level.
+    """

agentforge_core/production/fallback.py

@@ -0,0 +1,321 @@
+"""`FallbackChain` — cross-provider failover wrapping multiple
+`LLMClient`s (feat-007).
+
+Implements the `LLMClient` ABC, so any strategy that accepts an
+`LLMClient` accepts a chain transparently.
+
+Usage:
+
+    from agentforge import Agent, FallbackChain
+
+    chain = FallbackChain(
+        [
+            "anthropic:claude-sonnet-4.7",
+            "bedrock:anthropic.claude-sonnet-4.7",
+            "openai:gpt-4o",
+        ],
+        retry_on=(RateLimitError, ProviderError),
+        attempts_per_provider=1,
+    )
+    agent = Agent(model=chain, tools=[...])
+
+Behaviour:
+  - On `retry_on` exception → try next provider (after retrying the
+    current provider `attempts_per_provider` times).
+  - Last provider's exception bubbles up if every provider exhausts.
+  - `last_used_provider` tracks the index of the provider that
+    answered the most recent call (diagnostic only).
+  - `capabilities()` returns the **intersection** of every wrapped
+    provider's capabilities — a chain can only honestly claim what
+    every fallback can deliver.
+  - `call_with_cache` / `call_with_thinking` raise
+    `CapabilityNotSupported` unless every wrapped provider declares
+    the capability.
+  - `close()` cascades in reverse-construction order.
+
+Out of scope (v0.1):
+  - Streaming (`stream`) — not yet supported by `FallbackChain`;
+    callers using streaming should pick a single provider.
+  - Provider-level retry backoff — providers handle their own
+    retries internally.
+  - Per-call `retry_on` override — chain-level configuration only.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from agentforge_core.contracts.llm import LLMClient
+from agentforge_core.production.exceptions import (
+    CapabilityNotSupported,
+    ModuleError,
+    ProviderError,
+    RateLimitError,
+)
+from agentforge_core.resolver import Resolver, parse_model_string
+from agentforge_core.values.messages import LLMResponse, Message, ToolSpec
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_RETRY_ON: tuple[type[Exception], ...] = (RateLimitError, ProviderError)
+_DEFAULT_ATTEMPTS_PER_PROVIDER = 1
+
+
+class FallbackChain(LLMClient):
+    """Wrap multiple `LLMClient`s with cross-provider failover.
+
+    Args:
+        providers: A non-empty list of providers. Each entry is
+            either a model string (`"<provider>:<model_id>"`,
+            resolved via the global `Resolver`) or a typed
+            `LLMClient` instance.
+        retry_on: Exception types that trigger a fallback to the
+            next provider. Default: `(RateLimitError, ProviderError)`.
+            Other exceptions (e.g. `AuthenticationError`) bubble
+            immediately — falling back on those is usually wrong.
+        attempts_per_provider: How many times to retry the *current*
+            provider before moving to the next. Default 1 (no
+            retry; first failure → next provider).
+
+    Raises:
+        ValueError: empty providers list, non-positive
+            `attempts_per_provider`, or an unrecognised provider
+            string.
+    """
+
+    def __init__(
+        self,
+        providers: list[str | LLMClient],
+        *,
+        retry_on: tuple[type[Exception], ...] = _DEFAULT_RETRY_ON,
+        attempts_per_provider: int = _DEFAULT_ATTEMPTS_PER_PROVIDER,
+    ) -> None:
+        if not providers:
+            msg = "FallbackChain requires at least one provider"
+            raise ValueError(msg)
+        if attempts_per_provider < 1:
+            msg = f"attempts_per_provider must be >= 1, got {attempts_per_provider}"
+            raise ValueError(msg)
+        self._clients: list[LLMClient] = [_resolve_provider(p) for p in providers]
+        self._retry_on = retry_on
+        self._attempts_per_provider = attempts_per_provider
+        self._last_used_provider: int | None = None
+
+    # ------------------------------------------------------------------
+    # Diagnostics
+    # ------------------------------------------------------------------
+
+    @property
+    def last_used_provider(self) -> int | None:
+        """Index (0-based) of the provider that answered the most
+        recent call. `None` until the first call succeeds."""
+        return self._last_used_provider
+
+    @property
+    def providers(self) -> tuple[LLMClient, ...]:
+        """Resolved providers in chain order. Useful for tests."""
+        return tuple(self._clients)
+
+    # ------------------------------------------------------------------
+    # LLMClient surface
+    # ------------------------------------------------------------------
+
+    async def call(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+    ) -> LLMResponse:
+        return await self._dispatch_with_fallback("call", system, messages, tools=tools)
+
+    async def close(self) -> None:
+        """Close every wrapped provider in reverse-construction order.
+
+        Reverse order so a partial-construction failure during
+        `__init__` doesn't leak resources held by earlier providers.
+        Exceptions during close are logged and swallowed; the goal
+        is best-effort cleanup, not failure.
+        """
+        for client in reversed(self._clients):
+            try:
+                await client.close()
+            except Exception:
+                log.exception(
+                    "FallbackChain: error closing %s; continuing",
+                    type(client).__name__,
+                )
+
+    def capabilities(self) -> set[str]:
+        """Intersection of every wrapped provider's capabilities.
+
+        A chain can only honestly claim a capability that every
+        fallback can deliver — otherwise a fallback might fail to
+        honour a feature the caller relied on declaring.
+        """
+        if not self._clients:
+            return set()
+        common = set(self._clients[0].capabilities())
+        for client in self._clients[1:]:
+            common &= client.capabilities()
+        return common
+
+    # ------------------------------------------------------------------
+    # Optional capabilities — capability-intersection rule
+    # ------------------------------------------------------------------
+
+    async def call_with_cache(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+        *,
+        cache_breakpoints: list[int],
+    ) -> LLMResponse:
+        if "caching" not in self.capabilities():
+            msg = (
+                "FallbackChain does not support 'caching'. Every "
+                "wrapped provider must declare the capability for the "
+                "chain to honour it; check chain.supports('caching') "
+                "before calling."
+            )
+            raise CapabilityNotSupported(msg)
+        return await self._dispatch_with_fallback(
+            "call_with_cache",
+            system,
+            messages,
+            tools=tools,
+            cache_breakpoints=cache_breakpoints,
+        )
+
+    async def call_with_thinking(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+        *,
+        thinking_budget_tokens: int,
+    ) -> LLMResponse:
+        if "thinking" not in self.capabilities():
+            msg = (
+                "FallbackChain does not support 'thinking'. Every "
+                "wrapped provider must declare the capability for the "
+                "chain to honour it; check chain.supports('thinking') "
+                "before calling."
+            )
+            raise CapabilityNotSupported(msg)
+        return await self._dispatch_with_fallback(
+            "call_with_thinking",
+            system,
+            messages,
+            tools=tools,
+            thinking_budget_tokens=thinking_budget_tokens,
+        )
+
+    def stream(
+        self,
+        system: str,  # noqa: ARG002 — interface compatibility; we raise unconditionally
+        messages: list[Message],  # noqa: ARG002
+        tools: list[ToolSpec] | None = None,  # noqa: ARG002
+    ) -> AsyncIterator[Any]:
+        """Streaming is not supported on `FallbackChain` in v0.1.
+
+        Streaming with cross-provider fallback semantics is genuinely
+        harder than the unary call: events from provider N might
+        partially arrive before a fallback to N+1 kicks in, leaving
+        the caller with incoherent partial output. Callers needing
+        streaming should pick a single provider.
+        """
+        msg = (
+            "FallbackChain does not support 'streaming' in v0.1. "
+            "Pick a single provider for streaming use cases."
+        )
+        raise CapabilityNotSupported(msg)
+
+    # ------------------------------------------------------------------
+    # Internal — fallback dispatch
+    # ------------------------------------------------------------------
+
+    async def _dispatch_with_fallback(
+        self,
+        method_name: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """Iterate providers; for each, try `attempts_per_provider`
+        times; on `retry_on` exception move to the next provider.
+
+        The last provider's exception bubbles up if every provider
+        is exhausted.
+        """
+        last_exc: Exception | None = None
+        for index, client in enumerate(self._clients):
+            method = getattr(client, method_name)
+            for attempt in range(self._attempts_per_provider):
+                try:
+                    response: LLMResponse = await method(*args, **kwargs)
+                except self._retry_on as exc:
+                    last_exc = exc
+                    log.warning(
+                        "FallbackChain: provider %d/%d (%s) raised %s (attempt %d/%d); %s",
+                        index + 1,
+                        len(self._clients),
+                        type(client).__name__,
+                        type(exc).__name__,
+                        attempt + 1,
+                        self._attempts_per_provider,
+                        "trying next provider"
+                        if attempt + 1 == self._attempts_per_provider
+                        else "retrying",
+                    )
+                    continue
+                else:
+                    self._last_used_provider = index
+                    return response
+        # Every provider exhausted.
+        assert last_exc is not None
+        raise last_exc
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+
+def _resolve_provider(provider: Any) -> LLMClient:
+    """Turn a `str` model spec or `LLMClient` instance into an
+    `LLMClient` instance via the global resolver.
+
+    Accepts `Any` (not `str | LLMClient`) so the runtime
+    `isinstance` guards remain reachable for type-checkers — the
+    public `FallbackChain.__init__` signature is the typed gate;
+    this internal helper hardens against accidental mistypes.
+    """
+    if isinstance(provider, LLMClient):
+        return provider
+    if not isinstance(provider, str):
+        msg = f"FallbackChain providers must be str or LLMClient, got {type(provider).__name__}"
+        raise TypeError(msg)
+    name, model_id = parse_model_string(provider)
+    try:
+        cls = Resolver.global_().resolve("providers", name)
+    except ModuleError as exc:
+        msg = (
+            f"FallbackChain: no LLM provider registered for {name!r}. "
+            f"Install agentforge-{name} (e.g. "
+            f"`uv add agentforge-{name}`) or pass a typed LLMClient "
+            f"instance instead of the {provider!r} string."
+        )
+        raise ValueError(msg) from exc
+    instance = cls(model_id=model_id)
+    if not isinstance(instance, LLMClient):
+        msg = (
+            f"FallbackChain: resolved provider {name!r} ({cls.__name__}) "
+            f"does not implement LLMClient."
+        )
+        raise TypeError(msg)
+    return instance
+
+
+__all__ = ["FallbackChain"]

agentforge_core/production/log_filter.py

@@ -0,0 +1,49 @@
+"""`RunIdFilter` — attach `run_id` to every log record.
+
+Auto-installed on the root logger by `Agent.__init__` (per ADR-0010,
+P4). Idempotent — multiple installs do not accumulate filters.
+
+Disable via `logging.run_id_filter: false` in `agentforge.yaml`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from agentforge_core.production.run_context import _current_run
+
+_FILTER_NAME = "agentforge.run_id_filter"
+
+
+class RunIdFilter(logging.Filter):
+    """Attach `run_id` from the active `RunContext` (or `"-"`) to records."""
+
+    def __init__(self) -> None:
+        super().__init__(name=_FILTER_NAME)
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        ctx = _current_run.get()
+        record.run_id = ctx.run_id if ctx is not None else "-"
+        return True
+
+
+def install_run_id_filter(logger: logging.Logger | None = None) -> RunIdFilter:
+    """Install `RunIdFilter` on `logger` (root by default), idempotent.
+
+    Returns the live filter (the existing one if already installed).
+    """
+    target = logger if logger is not None else logging.getLogger()
+    for existing in target.filters:
+        if isinstance(existing, RunIdFilter):
+            return existing
+    new_filter = RunIdFilter()
+    target.addFilter(new_filter)
+    return new_filter
+
+
+def uninstall_run_id_filter(logger: logging.Logger | None = None) -> None:
+    """Remove `RunIdFilter` from `logger` (root by default), if present."""
+    target = logger if logger is not None else logging.getLogger()
+    for existing in list(target.filters):
+        if isinstance(existing, RunIdFilter):
+            target.removeFilter(existing)

agentforge_core/production/log_format.py

@@ -0,0 +1,117 @@
+"""`JsonFormatter` — structured JSON log records for production.
+
+Per feat-009 §4.5: `logging.format: "json"` switches `agentforge` to
+emit one-JSON-object-per-line records, ready for ingestion by log
+aggregators (Loki, CloudWatch, Datadog, etc.). Default stays `"text"`
+to keep local development greppable.
+
+The formatter respects whatever `RunIdFilter` added — `run_id` lands
+on every record. Standard fields: `ts`, `level`, `logger`, `msg`,
+`run_id`. Anything else attached to the record via `extra=` (or via
+filters) is included verbatim.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+_HANDLER_NAME = "agentforge.json_handler"
+
+# LogRecord attributes set by stdlib that we don't want to leak into
+# the JSON payload (already represented via dedicated fields, or
+# internal).
+_RESERVED: frozenset[str] = frozenset(
+    {
+        "args",
+        "asctime",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "message",
+        "module",
+        "msecs",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "thread",
+        "threadName",
+        "taskName",
+    }
+)
+
+
+class JsonFormatter(logging.Formatter):
+    """Emit one JSON object per record.
+
+    Output shape:
+        {"ts": "2026-05-11T16:42:01.123Z",
+         "level": "INFO",
+         "logger": "agentforge.agent",
+         "msg": "the message",
+         "run_id": "01HX...",
+         ...any custom extras...}
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, tz=UTC).isoformat().replace("+00:00", "Z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        # `run_id` lands here when `RunIdFilter` installed it.
+        if hasattr(record, "run_id"):
+            payload["run_id"] = record.run_id
+        # Surface any extras the caller attached via `logger.info(..., extra={...})`.
+        for key, value in record.__dict__.items():
+            if key in _RESERVED or key in payload or key.startswith("_"):
+                continue
+            payload[key] = value
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, default=str)
+
+
+def install_json_formatter(
+    logger: logging.Logger | None = None,
+    *,
+    level: int = logging.INFO,
+) -> logging.Handler:
+    """Attach a `StreamHandler` with `JsonFormatter` to `logger` (root
+    by default). Idempotent — repeated calls return the existing
+    handler.
+
+    Returns the handler so callers can adjust level / stream.
+    """
+    target = logger if logger is not None else logging.getLogger()
+    for existing in target.handlers:
+        if getattr(existing, "name", None) == _HANDLER_NAME:
+            return existing
+    handler = logging.StreamHandler()
+    handler.name = _HANDLER_NAME
+    handler.setLevel(level)
+    handler.setFormatter(JsonFormatter())
+    target.addHandler(handler)
+    if target.level == logging.NOTSET or target.level > level:
+        target.setLevel(level)
+    return handler
+
+
+def uninstall_json_formatter(logger: logging.Logger | None = None) -> None:
+    """Remove the JSON handler if present (idempotent)."""
+    target = logger if logger is not None else logging.getLogger()
+    for existing in list(target.handlers):
+        if getattr(existing, "name", None) == _HANDLER_NAME:
+            target.removeHandler(existing)