langchain-agentx-python 0.9.4__tar.gz → 0.9.5__tar.gz

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/PKG-INFO

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

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/__init__.py

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

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/context/compaction_service.py

@@ -11,7 +11,7 @@
 - 支持 `mode` 参数区分 PROACTIVE（常规）与 REACTIVE_CONTEXT_WINDOW（溢出恢复）。
 
 注意：
-- 不修改 `should_end` / `finish_reason` 等 exit 字段；只产出 `messages` 增量补丁。
+- 不修改 `terminal` / `resolution` / `finish_reason` 等 exit 字段；只产出 `messages` 增量补丁。
 - `arun` 方法为 async 版本，支持进度回调（供 /compact 命令使用）。
 """
 

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/context/stages/microcompact.py

@@ -10,7 +10,7 @@ Microcompact 阶段：对 `ToolMessage` 做轻量规范化（对齐 CC microcomp
 - 使用 `model_copy` 保持 LangChain 消息字段完整。
 
 注意：
-- 不依赖 LangGraph；不修改 `should_end` / `finish_reason`。
+- 不依赖 LangGraph；不修改 `terminal` / `resolution` / `finish_reason`。
 """
 
 from __future__ import annotations

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/context/types.py

@@ -7,7 +7,7 @@
 
 设计要点：
 - 使用 dataclass，避免裸 dict 魔法键；
-- 不依赖 LangGraph；不修改 should_end / finish_reason。
+- 不依赖 LangGraph；不修改 `terminal` / `resolution` / `finish_reason`。
 
 注意：
 - `TokenWarningState` 供 `blocking_guard` 与 `compaction_pipeline_meta` 观测对齐 CC token 告警语义。

langchain-agentx-python-0.9.5/langchain_agentx/loop/exit/__init__.py

@@ -0,0 +1,20 @@
+"""LangChain AgentX 退出语义与状态字段。"""
+
+from .resolution import (
+    ContinueResolution,
+    LoopResolution,
+    TerminalResolution,
+    build_continue_resolution,
+    build_terminal_resolution,
+)
+from .terminal import LoopTerminal, build_loop_terminal
+
+__all__ = [
+    "ContinueResolution",
+    "LoopResolution",
+    "TerminalResolution",
+    "LoopTerminal",
+    "build_continue_resolution",
+    "build_terminal_resolution",
+    "build_loop_terminal",
+]

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/exit/exit_logic.py

@@ -3,13 +3,13 @@ Agent Loop 退出逻辑与扩展状态定义。
 
 本模块从 `factory.py` 中拆分出与 LangGraph 结构无关的纯业务逻辑：
 - 从 `AIMessage` 解析并标准化 `finish_reason`（与 LangChain AgentX 风格兼容）
-- `determine_should_end`：以 `finish_reason` 为主信号判断是否结束，直接返回 `terminal_reason`
+- `determine_should_end`：以 `finish_reason` 为主信号判断是否结束，返回 `(should_end, reason)` 供 ModelNode 写入 `terminal`
 - `AgentLoopState`（别名 `LoopAgentStateFields`）：本框架在 LangGraph 状态中**额外**承载的字段契约（含 CC 对齐、withhold/恢复、task 观测等）
 
-方案B：`end_reason` 已删除，`terminal_reason` 是唯一对外终态标签（CC 对齐枚举）。
+终态 SSOT：`terminal.reason`（`LoopTerminal`）；`terminal_reason` 仅为运行时 projection alias（见 `terminal.apply_terminal_reason_projection`）。
 三层职责：
   - `finish_reason`：Provider 协议层，这一轮 completion 为何停
-  - `terminal_reason`：框架终态层，整次 run 为何结束（对外唯一）
+  - `terminal.reason`：框架终态层，整次 run 为何结束（SSOT）
   - `transition`：控制流层，还要继续转哪条边
 
 与 LangChain 默认 agent 的主要区别：
@@ -21,11 +21,13 @@ Agent Loop 退出逻辑与扩展状态定义。
 
 from __future__ import annotations
 
-import logging
 from typing import Any, NotRequired, TypedDict
 
 from langchain_core.messages import AIMessage
 
+from .resolution import LoopResolution
+from .terminal import LoopTerminal
+
 from .reason_codes import (
     TERMINAL_REASON_BLOCKING_LIMIT,
     TERMINAL_REASON_COMPLETED,
@@ -37,8 +39,6 @@ from .reason_codes import (
 )
 from ..config.runtime_settings import UNBOUNDED_MAX_STEPS
 
-_logger = logging.getLogger(__name__)
-
 # 需要继续执行的 finish_reason 集合（与 OpenCode 一致）
 CONTINUE_FINISH_REASONS = frozenset({"tool-calls", "unknown"})
 
@@ -128,55 +128,35 @@ def determine_should_end(
     """判断当前这一步是否应该结束 Agent 循环。
 
     max_steps: int | None — None 表示不限制步数。
-    返回 (should_end, terminal_reason)。
-    terminal_reason 是对外唯一终态标签（CC 对齐枚举），should_end=False 时为 None。
+    返回 (should_end, reason)；reason 供 ModelNode 写入 `terminal.reason`（CC 对齐枚举），should_end=False 时为 None。
     """
-    # [位置1] 入口日志：记录 determine_should_end 的输入状态
-    # 只调用一次 extract_finish_reason，避免重复打印 "unrecognized finish_reason" 警告
     finish_reason = extract_finish_reason(response)
-    _logger.warning(
-        "[DETERMINE_ENTRY] finish_reason=%s | max_steps=%s | max_turns=%s | "
-        "step=%s | turn_count=%s | has_response=%s",
-        finish_reason, max_steps, max_turns,
-        state.get("step", 0),
-        int(state.get("turn_count", 0) or 0),
-        response is not None,
-    )
     step = state.get("step", 0)
     turn_count = int(state.get("turn_count", 0) or 0)
 
-    # 辅助函数：记录返回决策并返回值
-    def _log_and_return(should_end: bool, terminal_reason: str | None, fr: str | None) -> tuple[bool, str | None]:
-        _logger.warning(
-            "[EXIT_DECISION] should_end=%s | terminal_reason=%s | finish_reason=%s | "
-            "step=%s | max_steps=%s | max_turns=%s",
-            should_end, terminal_reason, fr, step, max_steps, max_turns,
-        )
-        return should_end, terminal_reason
-
     # max_turns 作为工具轮次上限（优先于 finish_reason 判定）
     if max_turns is not None and turn_count >= max_turns:
-        return _log_and_return(True, TERMINAL_REASON_MAX_TURNS, finish_reason)
+        return True, TERMINAL_REASON_MAX_TURNS
 
     meta_tr = metadata_override_terminal_reason(response)
     if meta_tr:
         if max_steps is not None and step >= max_steps:
-            return _log_and_return(True, TERMINAL_REASON_MAX_STEPS, finish_reason)
-        return _log_and_return(True, meta_tr, finish_reason)
+            return True, TERMINAL_REASON_MAX_STEPS
+        return True, meta_tr
 
     # 需要继续执行的 finish_reason，除非达到 max_steps
     if finish_reason in CONTINUE_FINISH_REASONS:
         if max_steps is not None and step >= max_steps:
-            return _log_and_return(True, TERMINAL_REASON_MAX_STEPS, finish_reason)
-        return _log_and_return(False, None, finish_reason)
+            return True, TERMINAL_REASON_MAX_STEPS
+        return False, None
 
     # 明确的"结束"类 finish_reason → 直接映射 terminal_reason
     if finish_reason == "stop":
-        return _log_and_return(True, TERMINAL_REASON_COMPLETED, finish_reason)
+        return True, TERMINAL_REASON_COMPLETED
     elif finish_reason == "length":
-        return _log_and_return(True, TERMINAL_REASON_MAX_TOKENS, finish_reason)
+        return True, TERMINAL_REASON_MAX_TOKENS
     elif finish_reason == "content-filter":
-        return _log_and_return(True, TERMINAL_REASON_CONTENT_FILTER, finish_reason)
+        return True, TERMINAL_REASON_CONTENT_FILTER
 
     # 没有 finish_reason 时，使用 tool_calls 兜底逻辑
     if finish_reason is None:
@@ -187,13 +167,13 @@ def determine_should_end(
             and len(response.tool_calls) > 0  # type: ignore[arg-type]
         )
         if not has_tool_calls:
-            return _log_and_return(True, TERMINAL_REASON_COMPLETED, finish_reason)
+            return True, TERMINAL_REASON_COMPLETED
         if max_steps is not None and step >= max_steps:
-            return _log_and_return(True, TERMINAL_REASON_MAX_STEPS, finish_reason)
-        return _log_and_return(False, None, finish_reason)
+            return True, TERMINAL_REASON_MAX_STEPS
+        return False, None
 
     # 其他未知 finish_reason：一律视为结束
-    return _log_and_return(True, TERMINAL_REASON_ERROR, finish_reason)
+    return True, TERMINAL_REASON_ERROR
 
 
 def create_initial_state(
@@ -210,7 +190,9 @@ def create_initial_state(
         "step": 0,
         "turn_count": 0,
         "transition": None,
-        "terminal_reason": None,
+        "terminal": None,
+        "resolution": None,
+        "loop_decision_candidate": None,
         "pending_task_batch_id": None,
         "pending_task_command_ids": [],
         "task_events": [],
@@ -234,7 +216,6 @@ def create_initial_state(
         "token_budget_continue_requested": False,
         # CC：流式/工具中断或 hook_stopped；由 middleware/tools 写入，loop_controller 消费后清空
         "abort_terminal_reason": None,
-        "should_end": False,
         "finish_reason": None,
         "finish_reasons": [],
         "section_cache": {},
@@ -244,10 +225,10 @@ def create_initial_state(
 class AgentLoopState(TypedDict):
     """Agent Loop 在 LangGraph 中扩展的状态字段（合并进总 state schema）。
 
-    方案B：end_reason 已删除，terminal_reason 是唯一对外终态标签（CC 对齐枚举）。
+    方案B：terminal + resolution 为 SSOT；terminal_reason 仅运行时 projection alias，不在 schema 声明。
     三层职责：
       - finish_reason：Provider 协议层，这一轮 completion 为何停
-      - terminal_reason：框架终态层，整次 run 为何结束（对外唯一）
+      - terminal.reason：框架终态层，整次 run 为何结束（SSOT）
       - transition：控制流层，还要继续转哪条边（路由观测）
     """
 
@@ -257,7 +238,9 @@ class AgentLoopState(TypedDict):
     pending_task_command_ids: list[str]  # 待确认批次内 command_id 列表
     task_events: list[dict[str, Any]]  # task runtime 观测事件（节点级）
     transition: dict[str, Any] | None  # 路由观测：还要继续转哪条边；非终态时为 None
-    terminal_reason: str | None  # 对外唯一终态标签（CC 对齐枚举，should_end=False 时为 None）
+    terminal: LoopTerminal | None  # Loop Core 结构化终态（新 SSOT）
+    resolution: LoopResolution | None  # loop_controller 最终 continue/terminal 决议
+    loop_decision_candidate: dict[str, Any] | None  # ModelNode / producer 侧候选决策输入
     withheld_error: dict[str, Any] | None  # 可恢复错误暂存（withhold）
     withhold_retry_count: int  # withhold 已重试次数
     collapse_retry_available: bool  # collapse_drain_retry 相关守卫
@@ -278,7 +261,6 @@ class AgentLoopState(TypedDict):
     token_budget_continuation_count: int  # CC：token budget nudge 已执行次数
     token_budget_continue_requested: bool  # 为 True 时 loop_controller 注入 nudge 并回到 model
     abort_terminal_reason: str | None  # CC 式中断终态：aborted_streaming / aborted_tools / hook_stopped
-    should_end: bool  # 内部路由信号，不对外暴露语义
     finish_reason: str | None  # Provider 协议层：这一轮 completion 为何停
     finish_reasons: list[str]  # finish_reason 历史（观测用）
     section_cache: dict[str, str | None]  # SystemPromptSection session 级缓存（key=name, value=compute() 结果）

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/exit/reason_codes.py

@@ -13,6 +13,11 @@ TERMINAL_REASON_CONTENT_FILTER = "content_filter"
 TERMINAL_REASON_BLOCKING_LIMIT = "blocking_limit"
 TERMINAL_REASON_STOP_HOOK_PREVENTED = "stop_hook_prevented"
 TERMINAL_REASON_ERROR = "error"
+TERMINAL_REASON_API_ERROR = "api_error"
+TERMINAL_REASON_GRAPH_RUNTIME_ERROR = "graph_runtime_error"
+TERMINAL_REASON_PROMPT_TOO_LONG = "prompt_too_long"
+TERMINAL_REASON_MAX_OUTPUT_TOKENS = "max_output_tokens"
+TERMINAL_REASON_INVARIANT_VIOLATION = "invariant_violation"
 # CC queryLoop return.reason：中断 / hook 终局（middleware 或 tools 后写入 abort_terminal_reason）
 TERMINAL_REASON_ABORTED_STREAMING = "aborted_streaming"
 TERMINAL_REASON_ABORTED_TOOLS = "aborted_tools"
@@ -43,6 +48,11 @@ DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS = 3
 ERROR_TERMINAL_REASONS = frozenset(
     {
         TERMINAL_REASON_ERROR,
+        TERMINAL_REASON_API_ERROR,
+        TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+        TERMINAL_REASON_PROMPT_TOO_LONG,
+        TERMINAL_REASON_MAX_OUTPUT_TOKENS,
+        TERMINAL_REASON_INVARIANT_VIOLATION,
         TERMINAL_REASON_MAX_TOKENS,
         TERMINAL_REASON_BLOCKING_LIMIT,
     }
@@ -57,6 +67,11 @@ __all__ = [
     "TERMINAL_REASON_BLOCKING_LIMIT",
     "TERMINAL_REASON_STOP_HOOK_PREVENTED",
     "TERMINAL_REASON_ERROR",
+    "TERMINAL_REASON_API_ERROR",
+    "TERMINAL_REASON_GRAPH_RUNTIME_ERROR",
+    "TERMINAL_REASON_PROMPT_TOO_LONG",
+    "TERMINAL_REASON_MAX_OUTPUT_TOKENS",
+    "TERMINAL_REASON_INVARIANT_VIOLATION",
     "TERMINAL_REASON_ABORTED_STREAMING",
     "TERMINAL_REASON_ABORTED_TOOLS",
     "TERMINAL_REASON_HOOK_STOPPED",

langchain-agentx-python-0.9.5/langchain_agentx/loop/exit/resolution.py

@@ -0,0 +1,58 @@
+"""
+resolution.py — Loop resolution contract.
+
+职责：
+    定义 Loop Core 的 continue / terminal 决议对象，供 loop_controller 与后续 stream driver 消费。
+
+链路位置：
+    loop_controller 产出 resolution；projection / stream driver 读取 resolution 派生信息。
+
+当前裁剪范围：
+    仅定义 contract 与最小构造辅助函数；不处理 graph 调用或事件投影。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+from .terminal import LoopTerminal
+
+
+class ContinueResolution(TypedDict):
+    kind: Literal["continue"]
+    transition: dict[str, Any]
+    destination: str
+
+
+class TerminalResolution(TypedDict):
+    kind: Literal["terminal"]
+    terminal: LoopTerminal
+    destination: str
+
+
+LoopResolution = ContinueResolution | TerminalResolution
+
+
+def build_continue_resolution(*, transition: dict[str, Any], destination: str) -> ContinueResolution:
+    return {
+        "kind": "continue",
+        "transition": dict(transition),
+        "destination": destination,
+    }
+
+
+def build_terminal_resolution(*, terminal: LoopTerminal, destination: str) -> TerminalResolution:
+    return {
+        "kind": "terminal",
+        "terminal": dict(terminal),
+        "destination": destination,
+    }
+
+
+__all__ = [
+    "ContinueResolution",
+    "TerminalResolution",
+    "LoopResolution",
+    "build_continue_resolution",
+    "build_terminal_resolution",
+]

langchain-agentx-python-0.9.5/langchain_agentx/loop/exit/terminal.py

@@ -0,0 +1,108 @@
+"""
+terminal.py — Loop terminal contract.
+
+职责：
+    定义 Loop Core 的结构化终态对象 LoopTerminal，并提供最小构造辅助函数。
+
+链路位置：
+    loop_controller / stream driver / finish projection 共用的终态契约层。
+
+当前裁剪范围：
+    仅定义 contract 与最小构造逻辑；不处理 projection、事件投影或 graph 调用。
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from .reason_codes import (
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_BLOCKING_LIMIT,
+    TERMINAL_REASON_CONTENT_FILTER,
+    TERMINAL_REASON_HOOK_STOPPED,
+    TERMINAL_REASON_STOP_HOOK_PREVENTED,
+    TERMINAL_REASON_API_ERROR,
+    TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+    TERMINAL_REASON_INVARIANT_VIOLATION,
+    TERMINAL_REASON_MAX_OUTPUT_TOKENS,
+    TERMINAL_REASON_MAX_TOKENS,
+    TERMINAL_REASON_PROMPT_TOO_LONG,
+)
+
+
+class LoopTerminal(TypedDict, total=False):
+    reason: str
+    is_error: bool
+    error_kind: str | None
+    recoverable: bool
+    recovery_exhausted: bool
+    provider_finish_reason: str | None
+    step: int
+    turn_count: int
+    errors: list[str]
+    metadata: dict[str, Any]
+
+
+_ERROR_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_MAX_TOKENS,
+        TERMINAL_REASON_MAX_OUTPUT_TOKENS,
+        TERMINAL_REASON_PROMPT_TOO_LONG,
+        TERMINAL_REASON_BLOCKING_LIMIT,
+        TERMINAL_REASON_CONTENT_FILTER,
+        TERMINAL_REASON_API_ERROR,
+        TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+        TERMINAL_REASON_HOOK_STOPPED,
+        TERMINAL_REASON_ABORTED_STREAMING,
+        TERMINAL_REASON_ABORTED_TOOLS,
+        TERMINAL_REASON_INVARIANT_VIOLATION,
+    }
+)
+
+
+def build_loop_terminal(
+    *,
+    reason: str,
+    step: int | None = None,
+    turn_count: int | None = None,
+    provider_finish_reason: str | None = None,
+    error_kind: str | None = None,
+    is_error: bool | None = None,
+    recoverable: bool = False,
+    recovery_exhausted: bool = False,
+    errors: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> LoopTerminal:
+    terminal: LoopTerminal = {
+        "reason": reason,
+        "is_error": (reason in _ERROR_TERMINAL_REASONS) if is_error is None else bool(is_error),
+        "error_kind": error_kind,
+        "recoverable": recoverable,
+        "recovery_exhausted": recovery_exhausted,
+        "provider_finish_reason": provider_finish_reason,
+        "errors": list(errors or ()),
+        "metadata": dict(metadata or {}),
+    }
+    if step is not None:
+        terminal["step"] = int(step)
+    if turn_count is not None:
+        terminal["turn_count"] = int(turn_count)
+    return terminal
+
+
+def read_terminal_reason(terminal: Any) -> str | None:
+    """从 LoopTerminal SSOT 读取 reason；projection 层统一入口。"""
+    if isinstance(terminal, dict):
+        reason = terminal.get("reason")
+        if isinstance(reason, str) and reason:
+            return reason
+    return None
+
+
+def apply_terminal_reason_projection(state: dict[str, Any]) -> None:
+    """将 state['terminal_reason'] 同步为 terminal.reason 的 projection alias。"""
+    state["terminal_reason"] = read_terminal_reason(state.get("terminal"))
+
+
+__all__ = ["LoopTerminal", "apply_terminal_reason_projection", "build_loop_terminal", "read_terminal_reason"]

{langchain-agentx-python-0.9.4 → langchain-agentx-python-0.9.5}/langchain_agentx/loop/graph/factory.py

@@ -20,8 +20,8 @@ LangChain AgentX Agent 状态图（文字版，含 loop_controller）：
       ↓
     hook_stop
       ↓
-    loop_controller（集中处理 should_end / terminal_reason / 工具调用）
-      ├─ should_end=True  → END
+    loop_controller（集中处理 resolution / terminal / 工具调用）
+      ├─ resolution.kind=terminal → END（或 task reconcile / recovery 分支）
       ├─ 有工具调用       → tools → (task_event_*/prune_and_compress) → model
       └─ 无工具调用       → END
 """
@@ -51,6 +51,8 @@ from ..exit.exit_logic import (
     CONTINUE_FINISH_REASONS,
     LoopAgentStateFields,
 )
+from ..exit.reason_codes import TERMINAL_REASON_GRAPH_RUNTIME_ERROR
+from ..exit.terminal import read_terminal_reason
 from .graph_edges import _make_model_to_model_edge, _make_tools_to_model_edge, _make_loop_controller_edge
 from .reactive_compact_node import ReactiveCompactNode
 from ..model.schema_and_format import (
@@ -1161,7 +1163,7 @@ class LoopGraphBuilder:
                                         "summary": event.summary,
                                         "agent_id": event.scope.agent_id,
                                         "terminal_reason": event.terminal_reason,
-                                        "loop_terminal_reason": state.get("terminal_reason"),
+                                        "loop_terminal_reason": read_terminal_reason(state.get("terminal")),
                                     }
                                 )
                     return {
@@ -1204,7 +1206,7 @@ class LoopGraphBuilder:
                                     "summary": event.summary,
                                     "agent_id": event.scope.agent_id,
                                     "terminal_reason": event.terminal_reason,
-                                    "loop_terminal_reason": state.get("terminal_reason"),
+                                    "loop_terminal_reason": read_terminal_reason(state.get("terminal")),
                                 }
                             )
                 return {
@@ -1554,7 +1556,7 @@ class LoopGraphBuilder:
                     collector.end_session(
                         session_id=session_id,
                         status="failed",
-                        terminal_reason=str(exc),
+                        terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
                     )
                 raise