langchain-agentx-python 2.2.4__tar.gz → 2.2.5__tar.gz

{langchain-agentx-python-2.2.4/langchain_agentx_python.egg-info → langchain-agentx-python-2.2.5}/PKG-INFO

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

{langchain-agentx-python-2.2.4 → langchain-agentx-python-2.2.5}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.2.4 → langchain-agentx-python-2.2.5}/langchain_agentx/workflow/base.py

@@ -65,7 +65,7 @@ from .execution import (
 )
 from .memory_drain_registry import MemoryDrainRegistry
 from .memory_session_policy import collect_agent_nodes, validate_loop_session_ids
-from .state import WorkflowState
+from .state import WorkflowState, project_workflow_node_update
 
 # Lazy import for event_adapter（避免循环依赖）
 # 实际使用时通过 _get_event_adapter() 延迟导入
@@ -453,21 +453,22 @@ class BaseWorkflow(ABC):
 
         与 run() 的区别：
             - run(): 返回完整 WorkflowState（用于顶层调用）
-            - as_node(): 返回完整 WorkflowState（作为其他 Workflow 的节点）
+            - as_node(): 返回相对父 state 的 channel delta（供 LangGraph reducer 合并）
 
         实现原理：
-            - 直接调用 run() 返回完整 state
+            - 调用 run() 得到子图终态
+            - 经 project_workflow_node_update 将 messages / item_results 投影为增量
             - 传递 parent_workflow 构建层级关系
             - 使用 outer_semaphore 控制并发（如果提供）
-            - LangGraph 的 reducer 会自动处理合并
 
         并发控制（问题 19）：
             - 如果 outer_workflow 提供 semaphore，子 workflow 的执行会被限流
             - 这解决了 DeepSearch 场景下 45 个 sub-workflow 同时启动的问题
 
-        注意（问题 18 - as_node() diff 算法硬 bug）：
-            - ✅ 新设计（正确）：直接返回完整 state，让 LangGraph reducer 处理合并
-            - ❌ 旧设计（错误）：手算 diff，硬编码字段名，假设 reducer 是 list append
+        注意（聚合通道契约 · 2026-09-04）：
+            - 节点必须返回 delta，禁止把父 state 全量回写进 messages / item_results
+            - 手写节点请用 delta_messages / delta_item_results
+            - as_node 已自动投影，避免嵌套子图 2^N 膨胀
         """
         async def node_fn(state: dict) -> dict:
             # 入口即快照父 _active_run_config，避免 run() 内 set/restore 与父并发时读漂移。
@@ -475,16 +476,18 @@ class BaseWorkflow(ABC):
             # === 并发控制（问题 19）===
             if outer_semaphore is not None:
                 async with outer_semaphore:
-                    return await self.run(
+                    result = await self.run(
                         state,
                         parent_workflow=parent_workflow,
                         run_config=inherited_run_config,
                     )
-            return await self.run(
-                state,
-                parent_workflow=parent_workflow,
-                run_config=inherited_run_config,
-            )
+            else:
+                result = await self.run(
+                    state,
+                    parent_workflow=parent_workflow,
+                    run_config=inherited_run_config,
+                )
+            return project_workflow_node_update(state, result)
 
         return node_fn
 

{langchain-agentx-python-2.2.4 → langchain-agentx-python-2.2.5}/langchain_agentx/workflow/node.py

@@ -93,16 +93,22 @@ class AgentNode:
         ctx: WorkflowNodeContext,
         invocation: LoopInvocation,
     ) -> dict[str, Any]:
-        del state, ctx
-        return {
-            "messages": graph_result.get("messages", []),
-            "item_results": [
+        from .state import delta_item_results, project_workflow_node_update
+
+        del ctx
+        update = project_workflow_node_update(
+            {"messages": state.get("messages", [])},
+            {"messages": graph_result.get("messages", [])},
+        )
+        update.update(
+            delta_item_results(
                 {
                     "node": self.name,
                     "session_id": invocation.session_id,
                 }
-            ],
-        }
+            )
+        )
+        return update
 
     def map_error(
         self,
@@ -110,16 +116,16 @@ class AgentNode:
         exc: Exception,
         ctx: WorkflowNodeContext,
     ) -> dict[str, Any]:
-        return {
-            "messages": state.get("messages", []),
-            "item_results": [
-                {
-                    "node": self.name,
-                    "session_id": ctx.loop_session_id,
-                    "error": str(exc),
-                }
-            ],
-        }
+        from .state import delta_item_results
+
+        del state
+        return delta_item_results(
+            {
+                "node": self.name,
+                "session_id": ctx.loop_session_id,
+                "error": str(exc),
+            }
+        )
 
     def _resolve_graph_factory(
         self,

langchain-agentx-python-2.2.5/langchain_agentx/workflow/state.py

@@ -0,0 +1,294 @@
+"""
+state.py — Workflow 状态定义与聚合通道契约
+
+职责：
+    - 定义 WorkflowState 基类（TypedDict + Annotated reducer）
+    - item_results 按身份键幂等合并（防 2^N 全量回写 OOM）
+    - 提供 delta_messages / delta_item_results 增量构造接口（防误用）
+    - as_node 用 project_workflow_node_update 将终态投影为 delta
+
+链路位置：
+    - 被 BaseWorkflow 和所有特殊 Workflow 使用
+    - 被业务 Workflow 继承扩展
+
+当前裁剪范围：
+    - 仅包含基础字段（messages, item_results, workflow_id 等）
+    - 业务特定字段由具体 Workflow 自行扩展
+    - 通道预算上限（P2）未做
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Annotated, Any, Hashable, Mapping, Sequence, TypedDict
+
+from langgraph.graph.message import add_messages
+from langchain_core.messages import AnyMessage
+
+logger = logging.getLogger(__name__)
+
+_STRICT_DELTA_ENV = "LANGCHAIN_AGENTX_WORKFLOW_STRICT_DELTA"
+
+# 显式主键优先；其次 task（编排任务）；再 node/repo/session 等复合键
+_EXPLICIT_IDENTITY_KEYS: tuple[str, ...] = ("result_id", "item_key", "id")
+_COMPOSITE_IDENTITY_KEYS: tuple[str, ...] = (
+    "node",
+    "repo_id",
+    "repo",
+    "session_id",
+    "from",
+)
+
+
+def item_result_identity(item: Any) -> Hashable | None:
+    """提取 item_results 条目的合并身份；无身份则返回 None（走 append）。"""
+    if not isinstance(item, dict):
+        try:
+            hash(item)
+        except TypeError:
+            return None
+        return ("value", item)
+
+    for key in _EXPLICIT_IDENTITY_KEYS:
+        value = item.get(key)
+        if value is not None:
+            return (key, value)
+
+    task = item.get("task")
+    if task is not None:
+        return ("task", task)
+
+    parts = tuple(
+        (key, item[key])
+        for key in _COMPOSITE_IDENTITY_KEYS
+        if item.get(key) is not None
+    )
+    if parts:
+        return ("composite", parts)
+    return None
+
+
+def _looks_like_full_rewrite(left: Sequence[Any], right: Sequence[Any]) -> bool:
+    """检测典型反模式：提交值 = 旧列表前缀 + 增量（state.get(...) + [...]）。"""
+    if not left or len(right) <= len(left):
+        return False
+    return list(right[: len(left)]) == list(left)
+
+
+def _maybe_raise_or_warn_full_rewrite(left: list[Any], right: list[Any]) -> None:
+    if not _looks_like_full_rewrite(left, right):
+        return
+    message = (
+        "item_results full-rewrite antipattern detected: "
+        f"submitted len={len(right)} looks like prior len={len(left)} + suffix. "
+        "Return delta only via delta_item_results(...); "
+        "do not submit state.get('item_results', []) + [...]."
+    )
+    if os.environ.get(_STRICT_DELTA_ENV, "").strip() in {"1", "true", "TRUE", "yes", "YES"}:
+        raise ValueError(message)
+    logger.warning(message)
+
+
+class ItemResultsMerge:
+    """item_results 通道归约器：按身份键幂等合并，并检测全量回写。"""
+
+    def __call__(
+        self,
+        left: list[Any] | None,
+        right: list[Any] | None,
+    ) -> list[Any]:
+        return self.merge(left, right)
+
+    def merge(
+        self,
+        left: list[Any] | None,
+        right: list[Any] | None,
+    ) -> list[Any]:
+        left_list = list(left or [])
+        right_list = list(right or [])
+        if not right_list:
+            return left_list
+        if not left_list:
+            return list(right_list)
+
+        _maybe_raise_or_warn_full_rewrite(left_list, right_list)
+
+        keyed: dict[Hashable, int] = {}
+        merged: list[Any] = []
+        for item in left_list:
+            identity = item_result_identity(item)
+            if identity is None:
+                merged.append(item)
+                continue
+            if identity in keyed:
+                merged[keyed[identity]] = item
+            else:
+                keyed[identity] = len(merged)
+                merged.append(item)
+
+        for item in right_list:
+            identity = item_result_identity(item)
+            if identity is None:
+                merged.append(item)
+                continue
+            if identity in keyed:
+                merged[keyed[identity]] = item
+            else:
+                keyed[identity] = len(merged)
+                merged.append(item)
+        return merged
+
+
+merge_item_results = ItemResultsMerge()
+
+
+def _normalize_varargs(items: tuple[Any, ...]) -> list[Any]:
+    if len(items) == 1 and isinstance(items[0], list):
+        return list(items[0])
+    return list(items)
+
+
+def delta_messages(*messages: Any) -> dict[str, list[Any]]:
+    """构造 messages 通道增量（节点应 return 本 dict 或其展开）。
+
+    只接收本次新增消息，禁止传入 state['messages'] 全量历史。
+    """
+    return {"messages": _normalize_varargs(messages)}
+
+
+def delta_item_results(*items: Any) -> dict[str, list[Any]]:
+    """构造 item_results 通道增量（节点应 return 本 dict 或其展开）。
+
+    只接收本次新增/更新条目；条目宜带身份键（result_id / item_key / task / node+…）。
+    禁止传入 state.get('item_results', []) + [...] 全量历史。
+    """
+    return {"item_results": _normalize_varargs(items)}
+
+
+def _message_identity(message: Any) -> Hashable | None:
+    msg_id = getattr(message, "id", None)
+    if msg_id is not None:
+        return ("id", msg_id)
+    return None
+
+
+def _messages_delta(before: Sequence[Any] | None, after: Sequence[Any] | None) -> list[Any]:
+    before_list = list(before or [])
+    after_list = list(after or [])
+    if not after_list:
+        return []
+    seen: set[Hashable] = set()
+    for message in before_list:
+        identity = _message_identity(message)
+        if identity is not None:
+            seen.add(identity)
+    delta: list[Any] = []
+    for message in after_list:
+        identity = _message_identity(message)
+        if identity is None:
+            # 无 id：仅当不在 before 相等集合中时纳入（弱 diff）
+            if message not in before_list:
+                delta.append(message)
+            continue
+        if identity not in seen:
+            seen.add(identity)
+            delta.append(message)
+    return delta
+
+
+def _item_results_delta(
+    before: Sequence[Any] | None,
+    after: Sequence[Any] | None,
+) -> list[Any]:
+    before_list = list(before or [])
+    after_list = list(after or [])
+    if not after_list:
+        return []
+
+    before_by_key: dict[Hashable, Any] = {}
+    before_unkeyed: list[Any] = []
+    for item in before_list:
+        identity = item_result_identity(item)
+        if identity is None:
+            before_unkeyed.append(item)
+        else:
+            before_by_key[identity] = item
+
+    delta: list[Any] = []
+    after_unkeyed: list[Any] = []
+    for item in after_list:
+        identity = item_result_identity(item)
+        if identity is None:
+            after_unkeyed.append(item)
+            continue
+        prior = before_by_key.get(identity)
+        if prior is None or prior != item:
+            delta.append(item)
+
+    remaining_unkeyed = list(before_unkeyed)
+    for item in after_unkeyed:
+        if item in remaining_unkeyed:
+            remaining_unkeyed.remove(item)
+        else:
+            delta.append(item)
+    return delta
+
+
+def project_workflow_node_update(
+    before: Mapping[str, Any],
+    after: Mapping[str, Any],
+) -> dict[str, Any]:
+    """将子 workflow 终态投影为父图节点应提交的 channel delta。
+
+    聚合通道（messages / item_results）只提交相对 before 的增量；
+    其它字段在值变化时原样写入（last-write-wins）。
+    """
+    update: dict[str, Any] = {}
+    for key, value in after.items():
+        if key == "messages":
+            delta = _messages_delta(before.get("messages"), value)
+            if delta:
+                update["messages"] = delta
+            continue
+        if key == "item_results":
+            delta = _item_results_delta(before.get("item_results"), value)
+            if delta:
+                update["item_results"] = delta
+            continue
+        if before.get(key) != value:
+            update[key] = value
+    return update
+
+
+class WorkflowState(TypedDict, total=False):
+    """Workflow 状态 schema，支持并发写入。
+
+    字段说明：
+    - messages: 消息列表（add_messages 按 id 幂等合并）
+    - item_results: 并行/叶节点产出（merge_item_results 按身份键幂等合并）
+    - workflow_id / task_key / current_step / orchestration_round / error: 单写字段
+
+    节点写入约定：
+    - 使用 delta_messages / delta_item_results 构造增量，禁止 {**state} 全量回写聚合通道
+    """
+
+    messages: Annotated[list[AnyMessage], add_messages]
+    item_results: Annotated[list[dict], merge_item_results]
+
+    workflow_id: str
+    task_key: str | None
+    current_step: str | None
+    orchestration_round: int
+    error: str | None
+
+
+__all__ = [
+    "WorkflowState",
+    "ItemResultsMerge",
+    "merge_item_results",
+    "item_result_identity",
+    "delta_messages",
+    "delta_item_results",
+    "project_workflow_node_update",
+]

{langchain-agentx-python-2.2.4 → langchain-agentx-python-2.2.5/langchain_agentx_python.egg-info}/PKG-INFO

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

{langchain-agentx-python-2.2.4 → langchain-agentx-python-2.2.5}/pyproject.toml

@@ -4,7 +4,7 @@
 
  [project]
  name = "langchain-agentx-python"
- version = "2.2.4"
+ version = "2.2.5"
  description = "LangChain/LangGraph-based agent utilities for CodeBaseX."
  readme = "README.md"
  requires-python = ">=3.11"

langchain-agentx-python-2.2.4/langchain_agentx/workflow/state.py

@@ -1,61 +0,0 @@
-"""
-state.py — Workflow 状态定义
-
-职责：
-    - 定义 WorkflowState 基类（TypedDict + Annotated reducer）
-    - 规范 Workflow 状态字段命名与 reducer 使用
-    - 提供文档模式定义，不强制继承
-
-链路位置：
-    - 被 BaseWorkflow 和所有特殊 Workflow 使用
-    - 被业务 Workflow 继承扩展
-
-当前裁剪范围：
-    - 仅包含基础字段（messages, item_results, workflow_id 等）
-    - 业务特定字段由具体 Workflow 自行扩展
-
-设计说明（问题 10）：
-    - WorkflowState 使用 TypedDict，这是 LangGraph 的最佳实践
-    - TypedDict + Annotated reducer 是 LangGraph 官方推荐的状态定义方式
-    - 不要使用普通 dict（没有类型检查和 reducer 支持）
-    - 不要使用 dataclass（LangGraph StateGraph 不直接支持）
-"""
-
-from __future__ import annotations
-
-from typing import Annotated, TypedDict
-from operator import add
-
-from langgraph.graph.message import add_messages
-from langchain_core.messages import AnyMessage
-
-
-class WorkflowState(TypedDict, total=False):
-    """Workflow 状态 schema，支持并发写入。
-
-    字段说明：
-    - messages: 消息列表（所有节点都会追加消息，使用 reducer）
-    - item_results: 并行任务结果列表（聚合所有 item 的输出，使用 reducer）
-    - workflow_id: 当前 Workflow ID（单写，由 BaseWorkflow 设置）
-    - task_key: 当前任务标识符（单写，Phase 2+）
-    - current_step: 当前步骤（单写，用于顺序 Workflow）
-    - error: 错误信息（单写，用于错误处理）
-
-    使用方式：
-    - 基础类型：WorkflowState（本定义）
-    - 扩展类型：class MyState(WorkflowState, total=False) 添加业务字段
-    """
-
-    # === 并发聚合字段（使用 reducer）===
-    messages: Annotated[list[AnyMessage], add_messages]
-    item_results: Annotated[list[dict], add]
-
-    # === 单写字段（无需 reducer）===
-    workflow_id: str
-    task_key: str | None
-    current_step: str | None
-    orchestration_round: int
-    error: str | None
-
-
-__all__ = ["WorkflowState"]