langchain-agentx-python 1.3.8__tar.gz → 1.3.9__tar.gz

{langchain-agentx-python-1.3.8/langchain_agentx_python.egg-info → langchain-agentx-python-1.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 1.3.8
+Version: 1.3.9
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-1.3.8 → langchain-agentx-python-1.3.9}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.3.8"
+__version__ = "1.3.9"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-1.3.8 → langchain-agentx-python-1.3.9}/langchain_agentx/loop/config/loop_config.py

@@ -89,6 +89,20 @@ class TraceConfig:
     parent_conversation_session_id: str | None = None
 
 
+@dataclass(frozen=True)
+class ModelRetrySettings:
+    """Model HTTP 重试进度与 query_source 配置（对齐 CC QuerySource + api_retry yield）。
+
+    CC 对照：
+        - query_source → CC QuerySource（决定 background overload 是否重试，Phase 3）
+        - emit_progress_events → yield api_error / api_retry 进度
+        - persistent_retry → CLAUDE_CODE_UNATTENDED_RETRY（Phase 5；默认 False，仅 unattended/CI）
+    """
+    query_source: str | None = None
+    emit_progress_events: bool | None = None
+    persistent_retry: bool | None = None
+
+
 @dataclass(frozen=True)
 class SubagentLinkage:
     """子代理链接配置。
@@ -273,6 +287,7 @@ class AgentLoopConfig:
     tool_execution_engine: ToolExecutionEngineConfig = field(
         default_factory=ToolExecutionEngineConfig
     )
+    model_retry: ModelRetrySettings = field(default_factory=ModelRetrySettings)
 
     # -----------------------------------------------------------------------
     # 便捷构造器
@@ -362,6 +377,7 @@ __all__ = [
     "TraceConfig",
     "SubagentLinkage",
     "ToolExecutionEngineConfig",
+    "ModelRetrySettings",
     "AgentLoopConfig",
     "LoopServices",
 ]

langchain-agentx-python-1.3.9/langchain_agentx/loop/config/model_retry_config.py

@@ -0,0 +1,160 @@
+"""
+model_retry_config.py — 从 AgentLoopConfig 装配 ModelRetryConfig。
+
+职责：
+    解析 query_source / emit_progress_events（foreground 默认开，background 关）
+链路：create_loop_agent → LoopGraphBuilder._prepare_for_model_nodes → build_model_retry_config
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from langchain_agentx.loop.exit.query_source import QuerySource
+
+from ..model.retrier import ModelRetryConfig
+
+if TYPE_CHECKING:
+    from .loop_config import AgentLoopConfig, ModelRetrySettings
+
+_BACKGROUND_OVERLOAD_NO_RETRY_SOURCES = frozenset(
+    {
+        "compact",
+        "summary",
+        "title",
+        "classifier",
+        "background",
+        QuerySource.COMPACT,
+        QuerySource.AGENT_SUMMARY,
+        QuerySource.EXTRACT_MEMORIES,
+        QuerySource.SESSION_MEMORY,
+        QuerySource.MEMDIR_RELEVANCE,
+    }
+)
+
+_FOREGROUND_OVERLOAD_RETRY_SOURCES = frozenset(
+    {
+        "repl_main_thread",
+        "sdk",
+        "workflow_task",
+        QuerySource.MAIN_THREAD,
+    }
+)
+_BACKGROUND_CONTAINER_TYPES = frozenset(
+    {"background_task", "background", "batch", "worker"}
+)
+
+_CONTAINER_TO_QUERY_SOURCE: dict[str, str] = {
+    "interactive": "repl_main_thread",
+    "conversation": "repl_main_thread",
+    "workflow_task": "workflow_task",
+    "background_task": "compact",
+    "background": "compact",
+    "batch": "compact",
+    "worker": "compact",
+    "sdk": "sdk",
+}
+
+
+def resolve_model_retry_query_source(
+    *,
+    container_type: str | None,
+    settings: ModelRetrySettings | None = None,
+) -> str:
+    if settings is not None and settings.query_source:
+        return settings.query_source
+    normalized = (container_type or "interactive").strip()
+    return _CONTAINER_TO_QUERY_SOURCE.get(normalized, "sdk")
+
+
+def should_retry_overload_for_source(query_source: str | None) -> bool:
+    """对齐 CC shouldRetry529：background compact/summary 等不重试 overload。"""
+    if query_source is None or not str(query_source).strip():
+        return True
+    normalized = query_source.strip()
+    if normalized in _BACKGROUND_OVERLOAD_NO_RETRY_SOURCES:
+        return False
+    if normalized.startswith("repl_main_thread"):
+        return True
+    if normalized.startswith(QuerySource.AGENT_PREFIX):
+        return True
+    if normalized in _FOREGROUND_OVERLOAD_RETRY_SOURCES:
+        return True
+    return True
+
+
+def _parse_int_env(name: str) -> int | None:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return None
+    return int(raw)
+
+
+def _parse_bool_env(name: str) -> bool | None:
+    raw = os.environ.get(name, "").strip().lower()
+    if not raw:
+        return None
+    return raw in ("1", "true", "yes", "on")
+
+
+def resolve_persistent_retry(settings: ModelRetrySettings | None = None) -> bool:
+    """对齐 CC CLAUDE_CODE_UNATTENDED_RETRY；默认关闭，仅 unattended/CI 场景启用。"""
+    if settings is not None and settings.persistent_retry is not None:
+        return settings.persistent_retry
+    env_val = _parse_bool_env("LANGCHAIN_AGENTX_UNATTENDED_RETRY")
+    return env_val if env_val is not None else False
+
+
+def resolve_emit_progress_events(
+    *,
+    query_source: str,
+    container_type: str | None,
+    settings: ModelRetrySettings | None = None,
+) -> bool:
+    if settings is not None and settings.emit_progress_events is not None:
+        return settings.emit_progress_events
+    if query_source in _BACKGROUND_OVERLOAD_NO_RETRY_SOURCES:
+        return False
+    if (container_type or "") in _BACKGROUND_CONTAINER_TYPES:
+        return False
+    return True
+
+
+def build_model_retry_config(
+    config: AgentLoopConfig,
+    *,
+    fallback_model: Any | None = None,
+) -> ModelRetryConfig:
+    """从 AgentLoopConfig 构建 ModelCallRetrier 配置。"""
+    settings = config.model_retry
+    container_type = config.container_type
+    query_source = resolve_model_retry_query_source(
+        container_type=container_type,
+        settings=settings,
+    )
+    emit_progress = resolve_emit_progress_events(
+        query_source=query_source,
+        container_type=container_type,
+        settings=settings,
+    )
+    retry_kwargs: dict[str, Any] = {
+        "fallback_model": fallback_model if fallback_model is not None else config.fallback_model,
+        "query_source": query_source,
+        "emit_progress_events": emit_progress,
+    }
+    max_retries = _parse_int_env("LANGCHAIN_AGENTX_MAX_RETRIES")
+    if max_retries is not None:
+        retry_kwargs["max_retries"] = max_retries
+    if resolve_persistent_retry(settings):
+        retry_kwargs["persistent_retry"] = True
+    return ModelRetryConfig(**retry_kwargs)
+
+
+__all__ = [
+    "build_model_retry_config",
+    "resolve_emit_progress_events",
+    "resolve_model_retry_query_source",
+    "resolve_persistent_retry",
+    "should_retry_overload_for_source",
+]

{langchain-agentx-python-1.3.8 → langchain-agentx-python-1.3.9}/langchain_agentx/loop/graph/factory.py

@@ -1166,7 +1166,9 @@ class LoopGraphBuilder:
             )
         self._default_tools = default_tools
         self._model = model
-        _retrier = ModelCallRetrier(ModelRetryConfig())
+        from ..config.model_retry_config import build_model_retry_config
+
+        _retrier = ModelCallRetrier(build_model_retry_config(self._config))
 
         self._model_retrier = _retrier
 

{langchain-agentx-python-1.3.8 → langchain-agentx-python-1.3.9}/langchain_agentx/loop/model/model_node.py

@@ -45,6 +45,7 @@ from ..exit.resolution import build_continue_resolution, build_terminal_resoluti
 from ..exit.terminal import apply_terminal_reason_projection, build_loop_terminal
 from .retrier import ModelCallRetrier, RetryContext
 from .retry_bridge import emit_retry_events
+from .retry_exceptions import ModelCannotRetryError, ModelFallbackTriggeredError
 from .tool_and_model_binding import get_bound_model, handle_model_output
 from .tool_transcript_guard import repair_messages_for_llm_invoke
 
@@ -581,12 +582,12 @@ class ModelNode(Runnable):
         config: RunnableConfig | None = None,
     ) -> tuple[Any, list[Command]]:
         """同步重试与降级执行。"""
+        retry_ctx = RetryContext(
+            scope="background" if state.get("retry_scope") == "background" else "foreground"
+        )
         try:
             if self._retrier is None:
                 return self._invoke_bound(request, config=config), []
-            retry_ctx = RetryContext(
-                scope="background" if state.get("retry_scope") == "background" else "foreground"
-            )
             retry_result = self._retrier.invoke(
                 lambda: self._invoke_bound(request, config=config),
                 context=retry_ctx,
@@ -594,26 +595,29 @@ class ModelNode(Runnable):
             )
             emit_retry_events(retry_result.events)
             return retry_result.value, []
+        except ModelFallbackTriggeredError as fallback_trigger:
+            return self._invoke_with_fallback_model(
+                request,
+                state,
+                config=config,
+                fallback_model=fallback_trigger.fallback_model,
+                retry_ctx=retry_ctx,
+                log_reason="Consecutive overload triggered fallback model",
+            )
+        except ModelCannotRetryError as cannot_retry:
+            return _synthetic_api_error_model_response(cannot_retry.original, self._name), []
         except Exception as primary_exc:
             if self._fallback_model is None:
                 return _synthetic_api_error_model_response(primary_exc, self._name), []
-            logger.warning(
-                "Primary model invoke failed; retrying once with fallback_model",
-                exc_info=True,
+            return self._invoke_with_fallback_model(
+                request,
+                state,
+                config=config,
+                fallback_model=self._fallback_model,
+                retry_ctx=retry_ctx,
+                log_reason="Primary model invoke failed; retrying once with fallback_model",
+                primary_exc=primary_exc,
             )
-            req_fb = request.override(model=self._fallback_model)
-            try:
-                if self._retrier is None:
-                    return self._invoke_bound(req_fb, config=config), []
-                fb_result = self._retrier.invoke(
-                    lambda: self._invoke_bound(req_fb, config=config),
-                    context=retry_ctx,
-                    runnable_config=config,
-                )
-                emit_retry_events(fb_result.events)
-                return fb_result.value, []
-            except Exception as fb_exc:
-                return _synthetic_api_error_model_response(fb_exc, self._name), []
 
     async def _arun_async(
         self,
@@ -623,12 +627,12 @@ class ModelNode(Runnable):
         config: RunnableConfig | None = None,
     ) -> tuple[Any, list[Command]]:
         """异步重试与降级执行。"""
+        retry_ctx = RetryContext(
+            scope="background" if state.get("retry_scope") == "background" else "foreground"
+        )
         try:
             if self._retrier is None:
                 return await self._ainvoke_bound(request, config=config), []
-            retry_ctx = RetryContext(
-                scope="background" if state.get("retry_scope") == "background" else "foreground"
-            )
             retry_result = await self._retrier.ainvoke(
                 lambda: self._ainvoke_bound(request, config=config),
                 context=retry_ctx,
@@ -636,26 +640,87 @@ class ModelNode(Runnable):
             )
             emit_retry_events(retry_result.events)
             return retry_result.value, []
+        except ModelFallbackTriggeredError as fallback_trigger:
+            return await self._ainvoke_with_fallback_model(
+                request,
+                state,
+                config=config,
+                fallback_model=fallback_trigger.fallback_model,
+                retry_ctx=retry_ctx,
+                log_reason="Consecutive overload triggered fallback model",
+            )
+        except ModelCannotRetryError as cannot_retry:
+            return _synthetic_api_error_model_response(cannot_retry.original, self._name), []
         except Exception as primary_exc:
             if self._fallback_model is None:
                 return _synthetic_api_error_model_response(primary_exc, self._name), []
-            logger.warning(
-                "Primary model ainvoke failed; retrying once with fallback_model",
-                exc_info=True,
+            return await self._ainvoke_with_fallback_model(
+                request,
+                state,
+                config=config,
+                fallback_model=self._fallback_model,
+                retry_ctx=retry_ctx,
+                log_reason="Primary model ainvoke failed; retrying once with fallback_model",
+                primary_exc=primary_exc,
             )
-            req_fb = request.override(model=self._fallback_model)
-            try:
-                if self._retrier is None:
-                    return await self._ainvoke_bound(req_fb, config=config), []
-                fb_result = await self._retrier.ainvoke(
-                    lambda: self._ainvoke_bound(req_fb, config=config),
-                    context=retry_ctx,
-                    runnable_config=config,
-                )
-                emit_retry_events(fb_result.events)
-                return fb_result.value, []
-            except Exception as fb_exc:
-                return _synthetic_api_error_model_response(fb_exc, self._name), []
+
+    def _invoke_with_fallback_model(
+        self,
+        request: Any,
+        state: dict,
+        *,
+        config: RunnableConfig | None,
+        fallback_model: Any,
+        retry_ctx: RetryContext,
+        log_reason: str,
+        primary_exc: Exception | None = None,
+    ) -> tuple[Any, list[Command]]:
+        if primary_exc is not None:
+            logger.warning(log_reason, exc_info=True)
+        else:
+            logger.warning(log_reason)
+        req_fb = request.override(model=fallback_model)
+        try:
+            if self._retrier is None:
+                return self._invoke_bound(req_fb, config=config), []
+            fb_result = self._retrier.invoke(
+                lambda: self._invoke_bound(req_fb, config=config),
+                context=retry_ctx,
+                runnable_config=config,
+            )
+            emit_retry_events(fb_result.events)
+            return fb_result.value, []
+        except Exception as fb_exc:
+            return _synthetic_api_error_model_response(fb_exc, self._name), []
+
+    async def _ainvoke_with_fallback_model(
+        self,
+        request: Any,
+        state: dict,
+        *,
+        config: RunnableConfig | None,
+        fallback_model: Any,
+        retry_ctx: RetryContext,
+        log_reason: str,
+        primary_exc: Exception | None = None,
+    ) -> tuple[Any, list[Command]]:
+        if primary_exc is not None:
+            logger.warning(log_reason, exc_info=True)
+        else:
+            logger.warning(log_reason)
+        req_fb = request.override(model=fallback_model)
+        try:
+            if self._retrier is None:
+                return await self._ainvoke_bound(req_fb, config=config), []
+            fb_result = await self._retrier.ainvoke(
+                lambda: self._ainvoke_bound(req_fb, config=config),
+                context=retry_ctx,
+                runnable_config=config,
+            )
+            emit_retry_events(fb_result.events)
+            return fb_result.value, []
+        except Exception as fb_exc:
+            return _synthetic_api_error_model_response(fb_exc, self._name), []
 
     # ===== 退出逻辑与状态更新 =====