langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/model/retrier.py

@@ -0,0 +1,307 @@
+"""
+Loop model 调用重试器。
+
+职责：
+- 以 OOP 方式编排重试循环与等待策略
+- 产出对用户可见的重试事件（scheduled/heartbeat）
+- 复用默认异常分类（retry_on）
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Generic, Literal, Protocol, TypeVar
+
+from .retry_events import ModelRetryEvent
+from .retry_policy import RetryDelayPolicy, RetryHeartbeatPolicy
+
+T = TypeVar("T")
+RetryScope = Literal["foreground", "background"]
+
+
+@dataclass(slots=True)
+class RetryContext:
+    scope: RetryScope = "foreground"
+
+
+def default_retry_on(exc: Exception) -> bool:
+    """判断异常是否应该重试。排除用户取消；覆盖常见限流/连接/服务端错误。"""
+    if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+        return False
+    try:
+        if isinstance(exc, asyncio.CancelledError):
+            return False
+    except Exception:
+        return False
+
+    status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+    if isinstance(status, int) and status in (429, 500, 502, 503, 504, 529):
+        return True
+
+    try:
+        from openai import APIConnectionError, InternalServerError, RateLimitError
+
+        if isinstance(exc, (RateLimitError, APIConnectionError, InternalServerError)):
+            return True
+    except ImportError:
+        pass
+
+    try:
+        import httpx
+
+        if isinstance(exc, (httpx.ConnectError, httpx.TimeoutException, httpx.RemoteProtocolError)):
+            return True
+    except ImportError:
+        pass
+
+    return False
+
+
+def _extract_status_code(exc: Exception) -> int | None:
+    status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+    return status if isinstance(status, int) else None
+
+
+class AuthRecoveryHandler(Protocol):
+    def recover(self, exc: Exception) -> bool: ...
+
+    async def arecover(self, exc: Exception) -> bool: ...
+
+
+@dataclass(slots=True)
+class RetryClassifier:
+    retry_on: Callable[[Exception], bool]
+    allow_background_529_retry: bool = False
+    has_auth_recovery_handler: bool = False
+
+    def should_retry(self, exc: Exception, ctx: RetryContext) -> bool:
+        status = _extract_status_code(exc)
+        if status == 529 and ctx.scope == "background" and not self.allow_background_529_retry:
+            return False
+        if status in (401, 403):
+            return self.has_auth_recovery_handler
+        if status in (408, 409):
+            return True
+        return self.retry_on(exc)
+
+    def should_attempt_auth_recovery(self, exc: Exception) -> bool:
+        return _extract_status_code(exc) in (401, 403)
+
+
+@dataclass(slots=True)
+class ModelRetryConfig:
+    max_retries: int = 10
+    initial_delay: float = 0.5
+    backoff_factor: float = 2.0
+    max_delay: float = 32.0
+    jitter: bool = True
+    heartbeat_threshold_seconds: float = 30.0
+    heartbeat_interval_seconds: float = 30.0
+    retry_on: Callable[[Exception], bool] = default_retry_on
+    allow_background_529_retry: bool = False
+    auth_recovery_handler: AuthRecoveryHandler | None = None
+
+
+@dataclass(slots=True)
+class RetryExecutionResult(Generic[T]):
+    value: T
+    events: list[ModelRetryEvent]
+
+
+@dataclass(slots=True)
+class ModelCallRetrier:
+    config: ModelRetryConfig
+
+    def invoke(
+        self,
+        fn: Callable[[], T],
+        *,
+        context: RetryContext | None = None,
+    ) -> RetryExecutionResult[T]:
+        events: list[ModelRetryEvent] = []
+        delay_policy = self._delay_policy()
+        hb_policy = self._heartbeat_policy()
+        classifier = self._classifier()
+        ctx = context or RetryContext()
+        attempt = 0
+        auth_recovery_attempted = False
+        while True:
+            try:
+                return RetryExecutionResult(value=fn(), events=events)
+            except Exception as exc:
+                if (not auth_recovery_attempted) and self._recover_auth_sync(exc, classifier):
+                    auth_recovery_attempted = True
+                    continue
+                if attempt >= self.config.max_retries or not classifier.should_retry(exc, ctx):
+                    raise
+                self._sleep_before_next(
+                    attempt=attempt,
+                    exc=exc,
+                    events=events,
+                    delay_policy=delay_policy,
+                    heartbeat_policy=hb_policy,
+                )
+                auth_recovery_attempted = False
+                attempt += 1
+
+    async def ainvoke(
+        self,
+        fn: Callable[[], Awaitable[T]],
+        *,
+        context: RetryContext | None = None,
+    ) -> RetryExecutionResult[T]:
+        events: list[ModelRetryEvent] = []
+        delay_policy = self._delay_policy()
+        hb_policy = self._heartbeat_policy()
+        classifier = self._classifier()
+        ctx = context or RetryContext()
+        attempt = 0
+        auth_recovery_attempted = False
+        while True:
+            try:
+                return RetryExecutionResult(value=await fn(), events=events)
+            except Exception as exc:
+                if (not auth_recovery_attempted) and await self._recover_auth_async(exc, classifier):
+                    auth_recovery_attempted = True
+                    continue
+                if attempt >= self.config.max_retries or not classifier.should_retry(exc, ctx):
+                    raise
+                await self._asleep_before_next(
+                    attempt=attempt,
+                    exc=exc,
+                    events=events,
+                    delay_policy=delay_policy,
+                    heartbeat_policy=hb_policy,
+                )
+                auth_recovery_attempted = False
+                attempt += 1
+
+    def _sleep_before_next(
+        self,
+        *,
+        attempt: int,
+        exc: Exception,
+        events: list[ModelRetryEvent],
+        delay_policy: RetryDelayPolicy,
+        heartbeat_policy: RetryHeartbeatPolicy,
+    ) -> None:
+        import time
+
+        delay = delay_policy.compute_delay_seconds(attempt=attempt, exc=exc)
+        self._record_wait_events(
+            events=events,
+            attempt=attempt,
+            exc=exc,
+            delay_seconds=delay,
+            heartbeat_policy=heartbeat_policy,
+        )
+        time.sleep(delay)
+
+    async def _asleep_before_next(
+        self,
+        *,
+        attempt: int,
+        exc: Exception,
+        events: list[ModelRetryEvent],
+        delay_policy: RetryDelayPolicy,
+        heartbeat_policy: RetryHeartbeatPolicy,
+    ) -> None:
+        delay = delay_policy.compute_delay_seconds(attempt=attempt, exc=exc)
+        self._record_wait_events(
+            events=events,
+            attempt=attempt,
+            exc=exc,
+            delay_seconds=delay,
+            heartbeat_policy=heartbeat_policy,
+        )
+        await asyncio.sleep(delay)
+
+    def _record_wait_events(
+        self,
+        *,
+        events: list[ModelRetryEvent],
+        attempt: int,
+        exc: Exception,
+        delay_seconds: float,
+        heartbeat_policy: RetryHeartbeatPolicy,
+    ) -> None:
+        total_ms = max(0, int(delay_seconds * 1000))
+        attempt_no = attempt + 1
+        events.append(
+            ModelRetryEvent(
+                event_type="scheduled",
+                retry_in_ms=total_ms,
+                attempt=attempt_no,
+                max_retries=self.config.max_retries,
+                error_type=type(exc).__name__,
+                error_message=str(exc),
+            )
+        )
+        if not heartbeat_policy.should_emit_heartbeat(delay_seconds):
+            return
+
+        interval_ms = max(1000, int(heartbeat_policy.interval_seconds * 1000))
+        remaining = total_ms - interval_ms
+        while remaining > 0:
+            events.append(
+                ModelRetryEvent(
+                    event_type="heartbeat",
+                    retry_in_ms=remaining,
+                    attempt=attempt_no,
+                    max_retries=self.config.max_retries,
+                    error_type=type(exc).__name__,
+                    error_message=str(exc),
+                )
+            )
+            remaining -= interval_ms
+
+    def _delay_policy(self) -> RetryDelayPolicy:
+        return RetryDelayPolicy(
+            initial_delay=self.config.initial_delay,
+            backoff_factor=self.config.backoff_factor,
+            max_delay=self.config.max_delay,
+            jitter=self.config.jitter,
+        )
+
+    def _heartbeat_policy(self) -> RetryHeartbeatPolicy:
+        return RetryHeartbeatPolicy(
+            threshold_seconds=self.config.heartbeat_threshold_seconds,
+            interval_seconds=self.config.heartbeat_interval_seconds,
+        )
+
+    def _classifier(self) -> RetryClassifier:
+        return RetryClassifier(
+            retry_on=self.config.retry_on,
+            allow_background_529_retry=self.config.allow_background_529_retry,
+            has_auth_recovery_handler=self.config.auth_recovery_handler is not None,
+        )
+
+    def _recover_auth_sync(self, exc: Exception, classifier: RetryClassifier) -> bool:
+        handler = self.config.auth_recovery_handler
+        if handler is None or not classifier.should_attempt_auth_recovery(exc):
+            return False
+        try:
+            return bool(handler.recover(exc))
+        except Exception:
+            return False
+
+    async def _recover_auth_async(self, exc: Exception, classifier: RetryClassifier) -> bool:
+        handler = self.config.auth_recovery_handler
+        if handler is None or not classifier.should_attempt_auth_recovery(exc):
+            return False
+        try:
+            return bool(await handler.arecover(exc))
+        except Exception:
+            return False
+
+
+__all__ = [
+    "ModelRetryConfig",
+    "ModelCallRetrier",
+    "RetryContext",
+    "RetryClassifier",
+    "AuthRecoveryHandler",
+    "RetryExecutionResult",
+    "default_retry_on",
+]

langchain_agentx/loop/model/retry_bridge.py

@@ -0,0 +1,58 @@
+"""
+模型重试事件到 loop message 的桥接。
+
+职责：
+- 将 retrier 产出的事件转为 SystemMessage
+- 由 model_node 统一并入 Command(update={"messages": ...})
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from langchain_core.messages import SystemMessage
+from langgraph.types import Command
+
+from .retry_events import (
+    RETRY_EVENT_METADATA_FLAG,
+    RETRY_EVENT_SUBTYPE,
+    ModelRetryEvent,
+)
+
+
+def _format_retry_event_message(event: ModelRetryEvent) -> str:
+    seconds = max(0, int(round(event.retry_in_ms / 1000)))
+    if event.event_type == "heartbeat":
+        prefix = "Retry still pending"
+    else:
+        prefix = "Retry scheduled"
+    return (
+        f"[{prefix}] in {seconds}s "
+        f"(attempt {event.attempt}/{event.max_retries}) "
+        f"{event.error_type}: {event.error_message}"
+    )
+
+
+def build_retry_event_commands(events: Iterable[ModelRetryEvent]) -> list[Command]:
+    commands: list[Command] = []
+    for event in events:
+        msg = SystemMessage(
+            content=_format_retry_event_message(event),
+            response_metadata={
+                RETRY_EVENT_METADATA_FLAG: True,
+                "subtype": RETRY_EVENT_SUBTYPE,
+                "event_type": event.event_type,
+                "retry_in_ms": event.retry_in_ms,
+                "attempt": event.attempt,
+                "max_retries": event.max_retries,
+                "error": {
+                    "type": event.error_type,
+                    "message": event.error_message,
+                },
+            },
+        )
+        commands.append(Command(update={"messages": [msg]}))
+    return commands
+
+
+__all__ = ["build_retry_event_commands"]

langchain_agentx/loop/model/retry_events.py

@@ -0,0 +1,35 @@
+"""
+模型重试事件类型定义。
+
+职责：
+- 提供 retrier 与 loop node 间的事件契约
+- 约束对用户可见的重试提示字段（attempt/retry_in_ms/error）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+RetryEventType = Literal["scheduled", "heartbeat"]
+RETRY_EVENT_METADATA_FLAG = "langchain_agentx_retry_event"
+RETRY_EVENT_SUBTYPE = "api_retry"
+
+
+@dataclass(slots=True)
+class ModelRetryEvent:
+    event_type: RetryEventType
+    retry_in_ms: int
+    attempt: int
+    max_retries: int
+    error_type: str
+    error_message: str
+
+
+__all__ = [
+    "ModelRetryEvent",
+    "RetryEventType",
+    "RETRY_EVENT_METADATA_FLAG",
+    "RETRY_EVENT_SUBTYPE",
+]

langchain_agentx/loop/model/retry_policy.py

@@ -0,0 +1,56 @@
+"""
+模型重试策略对象。
+
+职责：
+- 计算每次重试等待时长（优先 Retry-After）
+- 管理 heartbeat 分段策略（长等待期间每 N 秒提示）
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+
+def _extract_retry_after_seconds(exc: Exception) -> int | None:
+    headers = getattr(exc, "headers", None)
+    if headers is None:
+        return None
+    retry_after = None
+    if hasattr(headers, "get"):
+        retry_after = headers.get("retry-after") or headers.get("Retry-After")
+    if retry_after is None:
+        return None
+    try:
+        return max(0, int(str(retry_after).strip()))
+    except Exception:
+        return None
+
+
+@dataclass(slots=True)
+class RetryDelayPolicy:
+    initial_delay: float = 0.5
+    backoff_factor: float = 2.0
+    max_delay: float = 32.0
+    jitter: bool = True
+
+    def compute_delay_seconds(self, *, attempt: int, exc: Exception) -> float:
+        retry_after = _extract_retry_after_seconds(exc)
+        if retry_after is not None:
+            return float(retry_after)
+        base = min(self.initial_delay * (self.backoff_factor ** attempt), self.max_delay)
+        if not self.jitter:
+            return base
+        return base * random.uniform(0.75, 1.25)
+
+
+@dataclass(slots=True)
+class RetryHeartbeatPolicy:
+    threshold_seconds: float = 30.0
+    interval_seconds: float = 30.0
+
+    def should_emit_heartbeat(self, delay_seconds: float) -> bool:
+        return delay_seconds > self.threshold_seconds
+
+
+__all__ = ["RetryDelayPolicy", "RetryHeartbeatPolicy"]

langchain_agentx/loop/model/schema_and_format.py

@@ -0,0 +1,153 @@
+"""
+LangChain AgentX agent 的 schema 合并与响应格式工具。
+
+本模块从 `factory.py` 中拆分出以下与图结构无关的纯工具逻辑：
+- 基于多份 TypedDict schema 合并出 state / input / output schema
+- 处理 `OmitFromSchema` / `Annotated` 等元数据，控制字段是否出现在输入或输出中
+- 探测当前模型是否支持 provider 侧结构化输出（provider strategy）
+- 处理 structured output 错误并决定是否重试，以及给模型的错误提示内容
+
+这些工具保持与 LangChain 官方语义一致，可在不同 agent 工厂中复用。
+"""
+
+from __future__ import annotations
+
+from typing import Any, get_args, get_origin, get_type_hints
+
+from langchain.agents.middleware.types import OmitFromSchema
+from langchain.agents.structured_output import (
+    AutoStrategy,
+    MultipleStructuredOutputsError,
+    OutputToolBinding,
+    ProviderStrategy,
+    ProviderStrategyBinding,
+    ResponseFormat,
+    StructuredOutputError,
+    StructuredOutputValidationError,
+    ToolStrategy,
+)
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.tools import BaseTool
+from typing_extensions import Annotated, NotRequired, Required, TypedDict
+
+
+STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
+
+FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT = [
+    # if model profile data are not available, these models are assumed to support
+    # structured output
+    "grok",
+    "gpt-5",
+    "gpt-4.1",
+    "gpt-4o",
+    "gpt-oss",
+    "o3-pro",
+    "o3-mini",
+]
+
+
+def _resolve_schema(schemas: set[type], schema_name: str, omit_flag: str | None = None) -> type:
+    """Resolve schema by merging schemas and optionally respecting `OmitFromSchema` annotations."""
+    all_annotations: dict[str, Any] = {}
+
+    for schema in schemas:
+        hints = get_type_hints(schema, include_extras=True)
+
+        for field_name, field_type in hints.items():
+            should_omit = False
+
+            if omit_flag:
+                metadata = _extract_metadata(field_type)
+                for meta in metadata:
+                    if isinstance(meta, OmitFromSchema) and getattr(meta, omit_flag) is True:
+                        should_omit = True
+                        break
+
+            if not should_omit:
+                all_annotations[field_name] = field_type
+
+    return TypedDict(schema_name, all_annotations)  # type: ignore[operator]
+
+
+def _extract_metadata(type_: type) -> list[Any]:
+    """Extract metadata from a field type, handling `Required`/`NotRequired` and `Annotated` wrappers."""
+    if get_origin(type_) in {Required, NotRequired}:
+        inner_type = get_args(type_)[0]
+        if get_origin(inner_type) is Annotated:
+            return list(get_args(inner_type)[1:])
+
+    if get_origin(type_) is Annotated:
+        return list(get_args(type_)[1:])
+
+    return []
+
+
+def _supports_provider_strategy(
+    model: str | BaseChatModel, tools: list[BaseTool | dict[str, Any]] | None = None
+) -> bool:
+    """Check if a model supports provider-specific structured output."""
+    model_name: str | None = None
+    if isinstance(model, str):
+        model_name = model
+    elif isinstance(model, BaseChatModel):
+        model_name = (
+            getattr(model, "model_name", None)
+            or getattr(model, "model", None)
+            or getattr(model, "model_id", "")
+        )
+        model_profile = model.profile
+        if (
+            model_profile is not None
+            and model_profile.get("structured_output")
+            and not (
+                tools
+                and isinstance(model_name, str)
+                and "gemini" in model_name.lower()
+                and "gemini-3" not in model_name.lower()
+            )
+        ):
+            return True
+
+    return (
+        any(part in model_name.lower() for part in FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT)
+        if model_name
+        else False
+    )
+
+
+def _handle_structured_output_error(
+    exception: Exception,
+    response_format: ResponseFormat[Any],
+) -> tuple[bool, str]:
+    """Handle structured output error. Returns `(should_retry, retry_tool_message)`."""
+    if not isinstance(response_format, ToolStrategy):
+        return False, ""
+
+    handle_errors = response_format.handle_errors
+
+    if handle_errors is False:
+        return False, ""
+    if handle_errors is True:
+        return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))
+    if isinstance(handle_errors, str):
+        return True, handle_errors
+    if isinstance(handle_errors, type):
+        if issubclass(handle_errors, Exception) and isinstance(exception, handle_errors):
+            return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))
+        return False, ""
+    if isinstance(handle_errors, tuple):
+        if any(isinstance(exception, exc_type) for exc_type in handle_errors):
+            return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))
+        return False, ""
+    return True, handle_errors(exception)
+
+
+__all__ = [
+    "STRUCTURED_OUTPUT_ERROR_TEMPLATE",
+    "FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT",
+    "_resolve_schema",
+    "_extract_metadata",
+    "_supports_provider_strategy",
+    "_handle_structured_output_error",
+]
+