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

langchain_agentx/loop/model/model_node.py

@@ -0,0 +1,648 @@
+"""
+model_node.py — ModelNode：模型调用图节点
+
+职责：
+    作为 LangGraph 的模型调用图节点，封装模型调用、重试与降级、
+    ToolCall 退化纠偏、退出逻辑判断、事件透传。
+
+链路位置：
+    factory._create_graph_skeleton() → graph.add_node("model", ModelNode(...))
+    → 替代原有 RunnableCallable(model_node, amodel_node, trace=False)
+
+当前裁剪范围：
+    - 不实现 stream/astream/transform（模型节点不走流式输出）
+    - 不改变 graph 拓扑结构（node name、edge 连接方式不变）
+    - 不处理多模型节点标记（fallback 调用目前无额外标记）
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from langchain.agents.structured_output import ResponseFormat
+from langchain_core.messages import AIMessage, SystemMessage
+from langchain_core.runnables import Runnable
+from langchain_core.runnables.config import RunnableConfig
+from langgraph.types import Command
+
+from ..config.runtime_settings import materialize_max_steps
+from ..context.settings import CompactionSettings, get_active_compaction_settings
+from ..exit.exit_logic import (
+    MAX_OUTPUT_TOKENS_RECOVERY_LIMIT,
+    RECOVERABLE_TERMINAL_REASONS,
+    determine_should_end,
+    extract_finish_reason,
+)
+from ..exit.reason_codes import (
+    TERMINAL_REASON_BLOCKING_LIMIT,
+    TERMINAL_REASON_MAX_TOKENS,
+    TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED,
+    TRANSITION_WITHHOLD_RECOVERY_RETRY,
+)
+from .retrier import ModelCallRetrier, RetryContext
+from .retry_bridge import build_retry_event_commands
+from .tool_and_model_binding import get_bound_model, handle_model_output
+from .tool_transcript_guard import repair_messages_for_llm_invoke
+
+logger = logging.getLogger(__name__)
+
+# =========================================================================
+# 辅助函数（从 model_nodes.py 迁移，保持语义一致）
+# =========================================================================
+
+
+def _synthetic_api_error_model_response(exc: Exception, name: str | None) -> Any:
+    """invoke/ainvoke 最终失败时合成 AIMessage，供 loop_controller CC §5.7 优先级 4 识别。"""
+    from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+    meta = {
+        "finish_reason": "error",
+        "langchain_agentx_api_error": True,
+        "error": {
+            "type": type(exc).__name__,
+            "message": str(exc),
+        },
+    }
+    ai = AIMessage(content=f"[LLM request failed] {exc}", response_metadata=meta)
+    if name:
+        ai.name = name
+    return _ModelResponse(result=[ai], structured_response=None)
+
+
+def _inject_model_into_agent_tool_calls(messages: list[Any], model: Any) -> None:
+    """在模型输出阶段为 Agent 工具调用补齐 model/tool_call_id 入参。"""
+    if not isinstance(model, str):
+        return
+    for msg in messages:
+        tool_calls = getattr(msg, "tool_calls", None)
+        if not isinstance(tool_calls, list):
+            continue
+        for tc in tool_calls:
+            if not isinstance(tc, dict) or tc.get("name") != "Agent":
+                continue
+            args = tc.get("args")
+            if not isinstance(args, dict):
+                continue
+            if not args.get("model"):
+                args["model"] = model
+            call_id = tc.get("id")
+            if isinstance(call_id, str) and call_id and not args.get("tool_call_id"):
+                args["tool_call_id"] = call_id
+
+
+def _messages_for_model_invoke(req: Any) -> list[Any]:
+    """组装本次 LLM 调用使用的消息列表；可选在 invoke 前做 tool 管线修复。"""
+    messages = list(req.messages or [])
+    s = get_active_compaction_settings()
+    if getattr(s, "enable_tool_transcript_repair_before_llm", True):
+        messages, stats = repair_messages_for_llm_invoke(messages)
+        if stats.get("repaired"):
+            logger.debug("tool_transcript_guard applied | %s", stats)
+    if req.system_message:
+        return [req.system_message, *messages]
+    return messages
+
+
+def _model_response_if_context_token_blocked(
+    *,
+    state_messages: List[Any],
+    name: str | None,
+    initial_response_format: ResponseFormat[Any] | None,
+    structured_output_tools: Dict[str, Any],
+    compaction_settings: CompactionSettings | None,
+) -> Any | None:
+    """若主上下文启发式已超过 CompactionSettings 顶线，返回合成 ModelResponse，否则 None。"""
+    from langchain_agentx.loop.context.blocking_guard import CompactionBlockingGuard
+    from langchain_agentx.loop.context.types import ContextCompactionContext
+    from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+    s = compaction_settings or get_active_compaction_settings()
+    if not s.enable_main_model_context_token_block:
+        return None
+    guard = CompactionBlockingGuard(settings=s)
+    est = guard.estimate_messages_tokens(state_messages)
+    if not guard.should_block(ContextCompactionContext(), estimated_tokens=est):
+        return None
+    tw = guard.calculate_token_warning_state(state_messages)
+    blocked_ai = AIMessage(
+        content=(
+            "[Stopped before LLM call: estimated conversation tokens "
+            f"({tw.estimated_tokens}) reached or exceeded the configured "
+            f"context ceiling ({tw.block_main_model_threshold_tokens}).]"
+        ),
+        response_metadata={
+            "finish_reason": "stop",
+            "langchain_agentx_terminal_reason": TERMINAL_REASON_BLOCKING_LIMIT,
+        },
+    )
+    if name:
+        blocked_ai.name = name
+    handled = handle_model_output(
+        blocked_ai,
+        initial_response_format,
+        structured_output_tools,
+    )
+    return _ModelResponse(
+        result=handled["messages"],
+        structured_response=handled.get("structured_response"),
+    )
+
+
+# =========================================================================
+# ModelNode — 模型调用图节点
+# =========================================================================
+
+
+class ModelNode(Runnable):
+    """模型调用图节点。
+
+    语义上标识自己是一个"模型节点"，让 LangGraph 的事件框架
+    能识别内部存在 chat_model run，从而正确发射 on_chat_model_stream。
+
+    继承 Runnable 以避免 LangGraph 自动包装为 RunnableCallable，
+    从而保持 on_chat_model_stream 事件传播。
+
+    职责：
+      - 模型调用（invoke / ainvoke）
+      - 重试与降级
+      - ToolCall 退化纠偏
+      - 退出逻辑判断
+      - 事件透传（不创建额外的 run 上下文）
+      - 结构化输出转换
+      - withhold recovery 状态机
+    """
+
+    def __init__(
+        self,
+        *,
+        model: Any,
+        default_tools: List[Any],
+        system_message: Any,
+        initial_response_format: ResponseFormat[Any] | None,
+        max_steps: int | None,
+        max_turns: int | None,
+        max_withhold_retries: int,
+        name: str | None,
+        structured_output_tools: Dict[str, Any],
+        tool_strategy_for_setup: Any,
+        retrier: ModelCallRetrier | None,
+        tool_node: Any,
+        dynamic_tool_error_template: str,
+        fallback_model: Any | None = None,
+        llm_callback_handler: Any | None = None,
+        compaction_settings: CompactionSettings | None = None,
+        max_output_tokens_cap: int | None = None,
+        dynamic_sections: list[Any] | None = None,
+        base_prompt: str | None = None,
+        override_prompt: str | None = None,
+        append_prompt: str | None = None,
+    ) -> None:
+        self._model = model
+        self._default_tools = default_tools
+        self._system_message = system_message
+        self._initial_response_format = initial_response_format
+        self._max_steps = max_steps
+        self._effective_max_steps = materialize_max_steps(max_steps)
+        self._max_turns = max_turns
+        self._max_withhold_retries = max_withhold_retries
+        self._name = name
+        self._structured_output_tools = structured_output_tools
+        self._tool_strategy_for_setup = tool_strategy_for_setup
+        self._retrier = retrier
+        self._tool_node = tool_node
+        self._dynamic_tool_error_template = dynamic_tool_error_template
+        self._fallback_model = fallback_model
+        self._llm_callback_handler = llm_callback_handler
+        self._compaction_settings = compaction_settings
+        self._max_output_tokens_cap = max_output_tokens_cap
+        self._dynamic_sections = list(dynamic_sections) if dynamic_sections else []
+        self._base_prompt = base_prompt
+        self._override_prompt = override_prompt
+        self._append_prompt = append_prompt
+        self._has_volatile_sections = any(
+            getattr(s, "volatile", False) for s in (dynamic_sections or [])
+        )
+
+    # ===== Runnable 接口 =====
+
+    def invoke(
+        self, input: dict, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> dict:
+        """Runnable 接口要求的 invoke 方法。
+
+        注意：不创建额外 run 上下文，让 config 中的 callback 直接穿透到内部 model.invoke。
+        """
+        return self._run(input, config or {})
+
+    async def ainvoke(
+        self, input: dict, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> dict:
+        """异步版本。"""
+        return await self._arun(input, config or {})
+
+    # ===== 核心执行路径 =====
+
+    def _run(self, state: dict, config: RunnableConfig) -> dict:
+        """核心同步执行逻辑。"""
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime)
+
+        synth = _model_response_if_context_token_blocked(
+            state_messages=state.get("messages", []),
+            name=self._name,
+            initial_response_format=self._initial_response_format,
+            structured_output_tools=self._structured_output_tools,
+            compaction_settings=self._compaction_settings,
+        )
+        if synth is not None:
+            model_response, retry_event_commands = synth, []
+        else:
+            model_response, retry_event_commands = self._run_sync(request, state, config=config)
+
+        return self._build_state_update(
+            state=state,
+            model_response=model_response,
+            retry_event_commands=retry_event_commands,
+            mode="sync",
+        )
+
+    async def _arun(self, state: dict, config: RunnableConfig) -> dict:
+        """核心异步执行逻辑。"""
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime)
+
+        synth = _model_response_if_context_token_blocked(
+            state_messages=state.get("messages", []),
+            name=self._name,
+            initial_response_format=self._initial_response_format,
+            structured_output_tools=self._structured_output_tools,
+            compaction_settings=self._compaction_settings,
+        )
+        if synth is not None:
+            model_response, retry_event_commands = synth, []
+        else:
+            model_response, retry_event_commands = await self._arun_async(request, state, config=config)
+
+        return self._build_state_update(
+            state=state,
+            model_response=model_response,
+            retry_event_commands=retry_event_commands,
+            mode="async",
+        )
+
+    # ===== 请求构建 =====
+
+    def _build_request(self, state: dict, runtime: Any) -> Any:
+        """从 state 构建 _ModelRequest。"""
+        from langchain.agents.middleware.types import ModelRequest as _ModelRequest
+
+        model_settings: Dict[str, Any] = {}
+        if state.get("max_output_tokens_override") is not None:
+            requested_override = int(state["max_output_tokens_override"])
+            cap = self._max_output_tokens_cap
+            if cap is not None:
+                requested_override = min(requested_override, int(cap))
+            model_settings["max_tokens"] = requested_override
+
+        system_message = self._system_message
+        if self._has_volatile_sections:
+            from ..prompt.builder import build_effective_system_prompt
+
+            section_cache = state.get("section_cache") or {}
+            effective = build_effective_system_prompt(
+                system_prompt=self._base_prompt,
+                override_system_prompt=self._override_prompt,
+                append_system_prompt=self._append_prompt,
+                dynamic_sections=self._dynamic_sections,
+                section_cache=section_cache,
+            )
+            system_message = (
+                SystemMessage(content=effective) if effective is not None else None
+            )
+
+        return _ModelRequest(
+            model=self._model,
+            tools=self._default_tools,
+            system_message=system_message,
+            response_format=self._initial_response_format,
+            messages=state.get("messages", []),
+            tool_choice=None,
+            state=state,
+            runtime=runtime,
+            model_settings=model_settings,
+        )
+
+    # ===== 模型调用 =====
+
+    def _invoke_bound(self, req: Any, *, config: RunnableConfig | None = None) -> Any:
+        """单次模型同步调用（含 binding、callback handler、输出后处理）。"""
+        from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+        model_, effective_response_format = get_bound_model(
+            request=req,
+            structured_output_tools=self._structured_output_tools,
+            initial_response_format=self._initial_response_format,
+            tool_strategy_for_setup=self._tool_strategy_for_setup,
+            tool_node=self._tool_node,
+            wrap_tool_call_wrapper=None,
+            awrap_tool_call_wrapper=None,
+            dynamic_tool_error_template=self._dynamic_tool_error_template,
+        )
+        model_ = self._bind_llm_callback_handler(model_, config)
+        messages = _messages_for_model_invoke(req)
+        output = model_.invoke(messages, config=config)
+        if self._name:
+            output.name = self._name
+        handled_output = handle_model_output(
+            output=output,
+            effective_response_format=effective_response_format,
+            structured_output_tools=self._structured_output_tools,
+        )
+        messages_list = handled_output["messages"]
+        _inject_model_into_agent_tool_calls(messages_list, req.model)
+        return _ModelResponse(
+            result=messages_list,
+            structured_response=handled_output.get("structured_response"),
+        )
+
+    async def _ainvoke_bound(self, req: Any, *, config: RunnableConfig | None = None) -> Any:
+        """单次模型异步调用。"""
+        from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+        model_, effective_response_format = get_bound_model(
+            request=req,
+            structured_output_tools=self._structured_output_tools,
+            initial_response_format=self._initial_response_format,
+            tool_strategy_for_setup=self._tool_strategy_for_setup,
+            tool_node=self._tool_node,
+            wrap_tool_call_wrapper=None,
+            awrap_tool_call_wrapper=None,
+            dynamic_tool_error_template=self._dynamic_tool_error_template,
+        )
+        model_ = self._bind_llm_callback_handler(model_, config)
+        messages = _messages_for_model_invoke(req)
+        output = await model_.ainvoke(messages, config=config)
+        if self._name:
+            output.name = self._name
+        handled_output = handle_model_output(
+            output=output,
+            effective_response_format=effective_response_format,
+            structured_output_tools=self._structured_output_tools,
+        )
+        messages_list = handled_output["messages"]
+        _inject_model_into_agent_tool_calls(messages_list, req.model)
+        return _ModelResponse(
+            result=messages_list,
+            structured_response=handled_output.get("structured_response"),
+        )
+
+    def _bind_llm_callback_handler(self, model: Any, config: RunnableConfig | None) -> Any:
+        """将 llm_callback_handler 注入模型调用的 callbacks。"""
+        if self._llm_callback_handler is None:
+            return model
+        callbacks: list[Any] = []
+        if isinstance(config, dict):
+            configured_callbacks = config.get("callbacks")
+            if isinstance(configured_callbacks, list):
+                callbacks.extend(configured_callbacks)
+            elif configured_callbacks is not None:
+                manager_handlers = getattr(configured_callbacks, "handlers", None)
+                if isinstance(manager_handlers, list):
+                    callbacks.extend(manager_handlers)
+        if self._llm_callback_handler not in callbacks:
+            callbacks.append(self._llm_callback_handler)
+        return model.with_config({"callbacks": callbacks})
+
+    # ===== 重试与降级 =====
+
+    def _run_sync(
+        self,
+        request: Any,
+        state: dict,
+        *,
+        config: RunnableConfig | None = None,
+    ) -> tuple[Any, list[Command]]:
+        """同步重试与降级执行。"""
+        retry_event_commands: list[Command] = []
+        try:
+            if self._retrier is None:
+                return self._invoke_bound(request, config=config), retry_event_commands
+            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,
+            )
+            retry_event_commands = build_retry_event_commands(retry_result.events)
+            return retry_result.value, retry_event_commands
+        except Exception as primary_exc:
+            if self._fallback_model is None:
+                return _synthetic_api_error_model_response(primary_exc, self._name), retry_event_commands
+            logger.warning(
+                "Primary model invoke failed; retrying once with fallback_model",
+                exc_info=True,
+            )
+            req_fb = request.override(model=self._fallback_model)
+            try:
+                if self._retrier is None:
+                    return self._invoke_bound(req_fb, config=config), retry_event_commands
+                fb_result = self._retrier.invoke(
+                    lambda: self._invoke_bound(req_fb, config=config),
+                    context=retry_ctx,
+                )
+                retry_event_commands.extend(build_retry_event_commands(fb_result.events))
+                return fb_result.value, retry_event_commands
+            except Exception as fb_exc:
+                return _synthetic_api_error_model_response(fb_exc, self._name), retry_event_commands
+
+    async def _arun_async(
+        self,
+        request: Any,
+        state: dict,
+        *,
+        config: RunnableConfig | None = None,
+    ) -> tuple[Any, list[Command]]:
+        """异步重试与降级执行。"""
+        retry_event_commands: list[Command] = []
+        try:
+            if self._retrier is None:
+                return await self._ainvoke_bound(request, config=config), retry_event_commands
+            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,
+            )
+            retry_event_commands = build_retry_event_commands(retry_result.events)
+            return retry_result.value, retry_event_commands
+        except Exception as primary_exc:
+            if self._fallback_model is None:
+                return _synthetic_api_error_model_response(primary_exc, self._name), retry_event_commands
+            logger.warning(
+                "Primary model ainvoke failed; retrying once with fallback_model",
+                exc_info=True,
+            )
+            req_fb = request.override(model=self._fallback_model)
+            try:
+                if self._retrier is None:
+                    return await self._ainvoke_bound(req_fb, config=config), retry_event_commands
+                fb_result = await self._retrier.ainvoke(
+                    lambda: self._ainvoke_bound(req_fb, config=config),
+                    context=retry_ctx,
+                )
+                retry_event_commands.extend(build_retry_event_commands(fb_result.events))
+                return fb_result.value, retry_event_commands
+            except Exception as fb_exc:
+                return _synthetic_api_error_model_response(fb_exc, self._name), retry_event_commands
+
+    # ===== 退出逻辑与状态更新 =====
+
+    def _build_state_update(
+        self,
+        *,
+        state: dict,
+        model_response: Any,
+        retry_event_commands: list[Command],
+        mode: str,
+    ) -> dict:
+        """构建状态更新 + Command 列表。"""
+        last_ai_message = self._find_last_ai_message(model_response.result)
+        should_end, terminal_reason = determine_should_end(
+            state, last_ai_message, self._max_steps, self._max_turns
+        )
+        finish_reason = extract_finish_reason(last_ai_message)
+        self._log_stop_if_needed(
+            should_end=should_end,
+            terminal_reason=terminal_reason,
+            mode=mode,
+            step=state.get("step", 0) + 1,
+            finish_reason=finish_reason,
+        )
+        finish_reasons = self._append_finish_reason(state, finish_reason)
+        recovery_update = self._resolve_withhold_recovery_update(
+            state=state,
+            should_end=should_end,
+            terminal_reason=terminal_reason,
+            finish_reason=finish_reason,
+        )
+        state_update: Dict[str, Any] = {
+            "step": state.get("step", 0) + 1,
+            "should_end": recovery_update["should_end"],
+            "finish_reason": finish_reason,
+            "terminal_reason": recovery_update["terminal_reason"],
+            "withheld_error": recovery_update["withheld_error"],
+            "withhold_retry_count": recovery_update["withhold_retry_count"],
+            "max_output_tokens_override": recovery_update["max_output_tokens_override"],
+            "max_output_tokens_recovery_count": recovery_update["max_output_tokens_recovery_count"],
+            "transition": recovery_update["transition"],
+            "finish_reasons": finish_reasons,
+        }
+        base_state: Dict[str, Any] = {"messages": model_response.result}
+        if model_response.structured_response is not None:
+            base_state["structured_response"] = model_response.structured_response
+            state_update["structured_response"] = model_response.structured_response
+
+        return [*retry_event_commands, Command(update=base_state), Command(update=state_update)]
+
+    def _find_last_ai_message(self, messages: list[Any]) -> AIMessage | None:
+        for msg in reversed(messages):
+            if isinstance(msg, AIMessage):
+                return msg
+        return None
+
+    def _log_stop_if_needed(
+        self,
+        *,
+        should_end: bool,
+        terminal_reason: str | None,
+        mode: str,
+        step: int,
+        finish_reason: str | None,
+    ) -> None:
+        if not should_end:
+            return
+        logger.info(
+            "LangChain-AgentX agent stopping (%s) | terminal_reason=%s, step=%s, finish_reason=%s",
+            mode,
+            terminal_reason,
+            step,
+            finish_reason,
+        )
+
+    def _append_finish_reason(self, state: dict, finish_reason: str | None) -> list[str]:
+        finish_reasons = list(state.get("finish_reasons", []))
+        if finish_reason:
+            finish_reasons.append(finish_reason)
+        return finish_reasons
+
+    def _resolve_withhold_recovery_update(
+        self,
+        *,
+        state: dict,
+        should_end: bool,
+        terminal_reason: str | None,
+        finish_reason: str | None,
+    ) -> Dict[str, Any]:
+        withheld_error = state.get("withheld_error")
+        withhold_retry_count = int(state.get("withhold_retry_count", 0) or 0)
+        max_output_tokens_override = state.get("max_output_tokens_override")
+        max_output_tokens_recovery_count = int(state.get("max_output_tokens_recovery_count", 0) or 0)
+        can_default_withhold_retry = withhold_retry_count < self._max_withhold_retries
+        can_max_tokens_recovery_retry = (
+            terminal_reason == TERMINAL_REASON_MAX_TOKENS
+            and max_output_tokens_override is not None
+            and max_output_tokens_recovery_count < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
+        )
+        if should_end and terminal_reason in RECOVERABLE_TERMINAL_REASONS and (
+            can_default_withhold_retry or can_max_tokens_recovery_retry
+        ):
+            withheld_error = {"reason": terminal_reason, "finish_reason": finish_reason}
+            if can_default_withhold_retry:
+                withhold_retry_count += 1
+            return {
+                "should_end": False,
+                "terminal_reason": None,
+                "withheld_error": withheld_error,
+                "withhold_retry_count": withhold_retry_count,
+                "max_output_tokens_override": max_output_tokens_override,
+                "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+                "transition": {
+                    "reason": TRANSITION_WITHHOLD_RECOVERY_RETRY,
+                    "error_reason": withheld_error["reason"],
+                    "attempt": withhold_retry_count,
+                },
+            }
+        if should_end and terminal_reason in RECOVERABLE_TERMINAL_REASONS:
+            return {
+                "should_end": should_end,
+                "terminal_reason": terminal_reason,
+                "withheld_error": None,
+                "withhold_retry_count": withhold_retry_count,
+                "max_output_tokens_override": max_output_tokens_override,
+                "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+                "transition": {
+                    "reason": TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED,
+                    "error_reason": terminal_reason,
+                    "attempt": withhold_retry_count,
+                },
+            }
+        if terminal_reason != TERMINAL_REASON_MAX_TOKENS:
+            max_output_tokens_override = None
+            max_output_tokens_recovery_count = 0
+        if not should_end:
+            withhold_retry_count = 0
+        return {
+            "should_end": should_end,
+            "terminal_reason": terminal_reason,
+            "withheld_error": None,
+            "withhold_retry_count": withhold_retry_count,
+            "max_output_tokens_override": max_output_tokens_override,
+            "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+            "transition": None,
+        }
+
+
+__all__ = ["ModelNode"]