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

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

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

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

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

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/task_runtime/tasks/ai_analysis/evaluation.py

@@ -41,7 +41,7 @@ class EvaluationAnalysisTask(BackgroundAiTask):
             "输出格式：根因 / 涉及模块 / 建议排查点"
         )
 
-        result = await self._invoke_agent(
+        result = await self._run_loop_task(
             messages=[HumanMessage(content=prompt)],
             task_key=session_id,
         )

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

@@ -55,6 +55,9 @@ __all__ = [
     "WorkflowGraphFactory",
     "CompiledStateGraph",
     "make_workflow_graph_factory",
+    "make_agent_node_graph_factory",
+    "build_tool_loader_for_node",
+    "resolve_loop_services",
 ]
 
 _MODULE_BY_NAME = {
@@ -108,6 +111,9 @@ _MODULE_BY_NAME = {
     "WorkflowGraphFactory": ".runtime",
     "CompiledStateGraph": ".runtime",
     "make_workflow_graph_factory": ".runtime",
+    "make_agent_node_graph_factory": ".loop_factory",
+    "build_tool_loader_for_node": ".loop_factory",
+    "resolve_loop_services": ".loop_factory",
 }
 
 

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/base.py

@@ -18,7 +18,8 @@ base.py — BaseWorkflow 基础设施层
     - 不支持 per-item Hook 事件（Phase 2+）
 
 设计原则（Phase 1）：
-    - 使用 AgentNode 路径，废弃 graph_factory / _invoke_agent / _astream_agent
+    - graph_factory 注入 WorkflowAgentLoopExecutor（factory-first：Dag/Batch/AgentNode；
+      invocation-first：LoopTaskNode / Rich Node 可 graph_factory=None，仅 run_invocation）
     - parent_workflow 在运行时注入（run() / as_node() 参数），避免循环依赖
     - as_node() 直接返回完整 state，让 LangGraph reducer 处理合并
     - max_concurrency 仅存储配置值，不实例化 Semaphore（由子类按需创建）
@@ -56,6 +57,11 @@ from ..workspace import (
     resolve_agent_home_string,
     resolve_workspace_root_path,
 )
+from .execution import (
+    WorkflowAgentLoopExecutor,
+    WorkflowNodeContext,
+    WorkflowSessionIdPolicy,
+)
 from .memory_drain_registry import MemoryDrainRegistry
 from .memory_session_policy import collect_agent_nodes, validate_loop_session_ids
 from .state import WorkflowState
@@ -101,7 +107,7 @@ class BaseWorkflow(ABC):
             hook_registry: Hook 注册表
             trace_collector: Trace 收集器（可选；显式优先于 capabilities.trace_collector）
             max_concurrency: 并发控制限制（仅存储，不实例化 Semaphore）
-            graph_factory: 兼容层参数（用于 Batch/Dag 迁移，可选）
+            graph_factory: Loop graph 工厂；Dag/Batch/AgentNode 经 Executor 注入
             capabilities: RuntimeCapabilities 单例；未提供时可用 ``workspace_root`` / ``agent_home_segment``
                 自动构造（缺省规则与 ``resolve_agent_state_config`` 一致）；二者皆缺省时
                 触发 deprecation 警告并使用解析器默认链。
@@ -150,14 +156,15 @@ class BaseWorkflow(ABC):
         self._workflow_path = workflow_id
         self._workflow_session_id = None
 
-        # === 兼容层：支持 Batch/Dag 迁移 ===
+        # === Executor 依赖：Dag/Batch/LoopTaskNode 经 _get_workflow_loop_executor() 使用 ===
         self._graph_factory = graph_factory
         self._semaphore = asyncio.Semaphore(self._max_concurrency)
         self.container_type = "workflow_task"
         self._memory_drain_registry = MemoryDrainRegistry()
+        self._workflow_loop_executor: WorkflowAgentLoopExecutor | None = None
 
         # 注意：parent_workflow 移到 run() 参数，避免 __init__ 时的循环依赖（问题 20）
-        # 注意：graph_factory 仅用于兼容 Batch/Dag，新代码应使用 build_graph()
+        # graph_factory 由 WorkflowAgentLoopExecutor 消费，非第二套执行入口
 
     @property
     def capabilities(self) -> RuntimeCapabilities:
@@ -179,10 +186,40 @@ class BaseWorkflow(ABC):
         if nodes:
             validate_loop_session_ids(nodes, workflow_id=self._workflow_id)
 
+    def _validate_pattern_spec_sessions(
+        self,
+        entries: Iterable[tuple[str, Any]],
+        *,
+        scope: str,
+    ) -> None:
+        """build_graph 前：spec task_key 唯一（SSOT）+ AgentNode 静态 session 保留规则。"""
+        entry_list = list(entries)
+        WorkflowSessionIdPolicy.validate_unique_task_keys(
+            [key for key, _ in entry_list],
+            workflow_id=self._workflow_id,
+            scope=scope,
+            labels=[key for key, _ in entry_list],
+        )
+        nodes: list[Any] = []
+        for _, node in entry_list:
+            nodes.extend(collect_agent_nodes([node]))
+        if nodes:
+            validate_loop_session_ids(nodes, workflow_id=self._workflow_id)
+
     def iter_child_workflows(self) -> Iterable[BaseWorkflow]:
         """返回直接嵌套的子 workflow（由 pattern 子类覆盖）。"""
         return ()
 
+    def _get_workflow_loop_executor(self) -> WorkflowAgentLoopExecutor:
+        """返回 workflow loop 执行器（factory-first 与 invocation-first 共用）。"""
+        if self._workflow_loop_executor is None:
+            self._workflow_loop_executor = WorkflowAgentLoopExecutor(
+                graph_factory=self._graph_factory,
+                trace_collector=self._trace_collector,
+                semaphore=self._semaphore,
+            )
+        return self._workflow_loop_executor
+
     def _finalize_ui_wiring(self) -> None:
         """递归收集 catalog registry，并在缺省情况下装配 composite resolver。"""
         if self._ui_catalog_registry is not None:
@@ -220,6 +257,10 @@ class BaseWorkflow(ABC):
         self._validate_manual_ui_catalog_if_needed()
         return self.build_graph().compile()
 
+    def export_event_adapter_structure(self) -> dict:
+        """导出 event adapter 所需的 workflow_structure（子类 override）。"""
+        return {}
+
     async def run(
         self,
         initial_state: dict,
@@ -326,44 +367,35 @@ class BaseWorkflow(ABC):
 
         return node_fn
 
-    async def _invoke_agent(
+    async def _run_loop_task(
         self,
         messages: list,
         task_key: str,
         parent_session_id: str | None = None,
+        *,
+        caller_config: dict[str, Any] | None = None,
     ) -> dict:
-        """兼容层：为 Batch/Dag 提供 agent 调用接口。
-
-        使用 WorkflowAgentRuntime 显式契约，替代原有的 **kwargs 传递。
-
-        Args:
-            messages: 消息列表
-            task_key: 任务标识符，用于构建 session_id
-            parent_session_id: 父会话 ID（可选）
+        """程序化 loop 步骤 SSOT：Dag/Batch/BackgroundAiTask 经 Executor 执行单次 agent loop。
 
-        Returns:
-            agent 执行结果字典
-
-        Raises:
-            RuntimeError: 如果 graph_factory 未提供
+        graph 节点路径请使用 WorkflowNodeAdapter + LoopTaskNode，不要调用本方法。
         """
         if self._graph_factory is None:
             raise RuntimeError(
-                "_invoke_agent() requires graph_factory parameter. "
-                "This method is for Batch/Dag compatibility only."
+                "BaseWorkflow._run_loop_task requires graph_factory (factory-first); "
+                "invocation-first nodes must build LoopInvocation and use "
+                "WorkflowAgentLoopExecutor.run_invocation instead."
             )
-
-        from langchain_agentx.workflow.runtime import WorkflowAgentRuntime
-
-        runtime = WorkflowAgentRuntime(
-            session_id=f"{self._workflow_id}-{task_key}",
-            parent_conversation_session_id=parent_session_id,
-            is_subagent=parent_session_id is not None,
+        context = WorkflowNodeContext(
+            workflow_id=self._workflow_id,
+            task_key=task_key,
+            parent_session_id=parent_session_id,
+        )
+        executor = self._get_workflow_loop_executor()
+        return await executor.ainvoke(
+            context=context,
+            messages=messages,
+            caller_config=caller_config,
         )
-        async with self._semaphore:
-            graph = self._graph_factory(runtime)
-            result = await graph.ainvoke({"messages": messages})
-            return dict(result) if isinstance(result, dict) else {"result": result}
 
     async def astream_events(
         self,
@@ -486,10 +518,12 @@ class BaseWorkflow(ABC):
         workflow_adapter_config = config.get("workflow_adapter")
         if not isinstance(workflow_adapter_config, dict):
             workflow_adapter_config = {}
-        if workflow_structure:
+        derived_structure = self.export_event_adapter_structure()
+        effective_structure = {**derived_structure, **(workflow_structure or {})}
+        if effective_structure:
             workflow_adapter_config = {
                 **workflow_adapter_config,
-                **workflow_structure,
+                **effective_structure,
             }
         effective_ui_catalog = ui_catalog or self._ui_catalog
         effective_display_resolver = display_resolver or self._display_resolver

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/batch.py

@@ -100,6 +100,24 @@ class BatchWorkflow(BaseWorkflow):
     async def _process_item(self, item: Any, index: int) -> Any:
         """子类实现单个 item 的处理逻辑。"""
 
+    async def _run_item_loop(
+        self,
+        messages: list[Any],
+        *,
+        item_key: str,
+        parent_session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """批处理 item 的 loop 执行 SSOT（task_key = item_key）。
+
+        Key 域：programmatic step key（见 ``task_key_domains.py`` 与
+        ``docs/design-docs/workflow/workflow-task-key-domains.html``）。
+        """
+        return await self._run_loop_task(
+            messages=messages,
+            task_key=item_key,
+            parent_session_id=parent_session_id,
+        )
+
     @abstractmethod
     def merge_results(self, results: list[Any]) -> Any:
         """子类实现多个 item 结果的聚合逻辑。"""

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/dag.py

@@ -93,8 +93,11 @@ class DagWorkflow(BaseWorkflow):
 
         step_name 作为 task_key，最终生成 session_id = f"{workflow_id}-{step_name}"，
         trace 可按步骤名检索执行链路。
+
+        Key 域：programmatic step key（见 ``task_key_domains.py`` 与
+        ``docs/design-docs/workflow/workflow-task-key-domains.html``）。
         """
-        return await self._invoke_agent(
+        return await self._run_loop_task(
             messages=messages,
             task_key=step_name,
             parent_session_id=parent_session_id,

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/event_adapter/adapter.py

@@ -67,9 +67,12 @@ class WorkflowEventAdapter:
             config: 配置字典，可包含：
                 - stage_node_prefix: stage 节点前缀（默认 "stage_"）
                 - parallel_node_prefix: parallel 节点前缀（默认 "parallel_"）
-                - aggregate_node_name: aggregate 节点名（默认 "aggregate"）
-                - route_node_prefix: route 节点前缀（默认 "route_"）
-                - total_stages: ChainingWorkflow 的 stage 总数
+                - aggregate_key / aggregate_node_name: 聚合节点名
+                - route_node_prefix: route 旧前缀（默认 "route_"，仅兼容）
+                - route_keys: 路由分支 key 列表（新语义，精确匹配）
+                - stage_keys / stage_index_by_key: stage 顺序映射
+                - parallel_item_keys / item_index_by_key: parallel item 顺序映射
+                - total_stages / total_parallel_items: 旧字段 fallback
         """
         self.workflow_id = workflow_id
         self.config = config or {}

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/event_adapter/handlers/parallel_handler.py

@@ -28,6 +28,12 @@ from langchain_agentx.workflow.event_adapter.handlers.display_support import (
     enricher_from_config,
     stack_pattern,
 )
+from langchain_agentx.workflow.event_adapter.structure_utils import (
+    matches_parallel_item_node,
+    resolve_aggregate_key,
+    resolve_item_index,
+    resolve_item_total,
+)
 
 
 class ParallelHandler:
@@ -60,19 +66,14 @@ class ParallelHandler:
         self._stack = stack
         self._config = config
         self._prefix = config.get("parallel_node_prefix", "parallel_")
-        self._aggregate_node = config.get("aggregate_node_name", "aggregate")
+        self._aggregate_node = resolve_aggregate_key(config)
         self._enricher = enricher_from_config(config)
 
     def matches(self, node: str) -> bool:
-        """判断节点是否由本 Handler 负责（v2.5 新增）
-
-        Args:
-            node: 节点名
-
-        Returns:
-            True 如果节点是 parallel_* 格式或 aggregate 节点
-        """
-        return node.startswith(self._prefix) or node == self._aggregate_node
+        """判断节点是否由本 Handler 负责（parallel_item_keys + aggregate）。"""
+        if node == self._aggregate_node:
+            return True
+        return matches_parallel_item_node(self._config, node, prefix=self._prefix)
 
     def consume(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """处理并行节点事件
@@ -91,8 +92,8 @@ class ParallelHandler:
         if node == self._aggregate_node:
             return self._handle_aggregate(event, event_type, node)
 
-        # 处理 parallel_* 节点
-        if node.startswith(self._prefix):
+        # 处理 parallel item 节点（structure key SSOT）
+        if matches_parallel_item_node(self._config, node, prefix=self._prefix):
             return self._handle_parallel_item(event, event_type, node)
 
         return events
@@ -180,11 +181,8 @@ class ParallelHandler:
         """处理 parallel_* 并行项事件"""
         events: List[WorkflowEvent] = []
 
-        # 提取并行项索引
-        try:
-            item_index = int(node.replace(self._prefix, ""))
-        except ValueError:
-            item_index = -1
+        # 提取并行项索引（structure 映射优先，旧数字后缀 fallback）
+        item_index = resolve_item_index(self._config, node, prefix=self._prefix)
 
         if event_type == "on_chain_start":
             data = {
@@ -253,7 +251,7 @@ class ParallelHandler:
     ) -> None:
         if self._enricher is None:
             return
-        item_total = self._config.get("total_parallel_items")
+        item_total = resolve_item_total(self._config)
         display = self._enricher.enrich_item(
             workflow_id=self._stack.current_workflow_id,
             workflow_path=self._stack.build_path(),

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/event_adapter/handlers/route_handler.py

@@ -27,6 +27,10 @@ from langchain_agentx.workflow.event_adapter.handlers.display_support import (
     enricher_from_config,
     stack_pattern,
 )
+from langchain_agentx.workflow.event_adapter.structure_utils import (
+    matches_route_node,
+    resolve_branch_key,
+)
 
 
 class RouteHandler:
@@ -69,7 +73,7 @@ class RouteHandler:
         Returns:
             True 如果节点是 route_* 格式
         """
-        return node.startswith(self._prefix)
+        return matches_route_node(self._config, node, prefix=self._prefix)
 
     def consume(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """处理路由节点事件
@@ -84,8 +88,10 @@ class RouteHandler:
         event_type = event.get("event", "")
         node = event.get("metadata", {}).get("langgraph_node", "")
 
-        # 提取分支 key（去掉 route_ 前缀）
-        branch_key = node.replace(self._prefix, "") if node.startswith(self._prefix) else node
+        if not matches_route_node(self._config, node, prefix=self._prefix):
+            return events
+
+        branch_key = resolve_branch_key(self._config, node, prefix=self._prefix)
 
         if event_type == "on_chain_start":
             # 记录活跃分支

{langchain-agentx-python-1.3.9 → langchain-agentx-python-1.4.1}/langchain_agentx/workflow/event_adapter/handlers/stage_handler.py

@@ -28,6 +28,13 @@ from langchain_agentx.workflow.event_adapter.handlers.display_support import (
     enricher_from_config,
     stack_pattern,
 )
+from langchain_agentx.workflow.event_adapter.structure_utils import (
+    matches_route_node,
+    matches_stage_node,
+    resolve_branch_key,
+    resolve_stage_index,
+    resolve_stage_total,
+)
 
 
 class StageHandler:
@@ -64,15 +71,8 @@ class StageHandler:
         self._enricher = enricher_from_config(config)
 
     def matches(self, node: str) -> bool:
-        """判断节点是否由本 Handler 负责（v2.5 新增）
-
-        Args:
-            node: 节点名
-
-        Returns:
-            True 如果节点是 stage_* 格式
-        """
-        return node.startswith(self._prefix)
+        """判断节点是否由本 Handler 负责（structure stage_keys SSOT）。"""
+        return matches_stage_node(self._config, node, prefix=self._prefix)
 
     def consume(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """处理 stage 节点事件
@@ -87,24 +87,18 @@ class StageHandler:
         event_type = event.get("event", "")
         node = event.get("metadata", {}).get("langgraph_node", "")
 
-        # 只处理 stage_* 节点
-        if not node.startswith(self._prefix):
+        if not matches_stage_node(self._config, node, prefix=self._prefix):
             return events
 
-        # 提取 stage 索引
-        try:
-            stage_index = int(node.replace(self._prefix, ""))
-        except ValueError:
-            return events  # 无效索引，不产生事件
-
-        # 从 config 获取 stage_total
-        stage_total = self._config.get("total_stages", 0)
+        stage_key = node
+        stage_index = resolve_stage_index(self._config, node, prefix=self._prefix)
+        stage_total = resolve_stage_total(self._config)
 
         if event_type == "on_chain_start":
             self._state.current_stage = stage_index
             data = {
                 "stage_index": stage_index,
-                "stage_key": node,
+                "stage_key": stage_key,
                 "stage_total": stage_total,
             }
             self._attach_stage_display(
@@ -124,7 +118,7 @@ class StageHandler:
         elif event_type == "on_chain_end":
             data = {
                 "stage_index": stage_index,
-                "stage_key": node,
+                "stage_key": stage_key,
                 "stage_total": stage_total,
             }
             self._attach_stage_display(
@@ -146,7 +140,7 @@ class StageHandler:
             error_info = error_data.get("error") if isinstance(error_data, dict) else str(error_data)
             data = {
                 "stage_index": stage_index,
-                "stage_key": node,
+                "stage_key": stage_key,
                 "stage_total": stage_total,
                 "error": str(error_info),
                 "error_type": type(error_info).__name__ if isinstance(error_info, Exception) else "WorkflowStageError",

langchain-agentx-python-1.4.1/langchain_agentx/workflow/event_adapter/structure_utils.py

@@ -0,0 +1,105 @@
+"""
+structure_utils.py — event adapter workflow_structure 解析辅助
+
+职责：
+    - 从 workflow_adapter config 解析 stage / parallel / route 索引与总数
+    - 为 handler 提供 structure key 驱动的 lookup（显式 spec key SSOT）
+
+链路位置：
+    event adapter handlers → structure_utils
+
+当前裁剪范围：
+    - 仅解析 config 字段，不访问 workflow 实例
+    - 不再支持 stage_0 / route_pdf 等旧数字后缀或前缀剥离 fallback
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def resolve_stage_index(config: dict[str, Any], node: str, *, prefix: str = "") -> int:
+    """从 stage_index_by_key 解析 stage_index；未知 key 返回 -1。"""
+    del prefix
+    index_map = config.get("stage_index_by_key") or {}
+    if node in index_map:
+        return int(index_map[node])
+    return -1
+
+
+def resolve_stage_total(config: dict[str, Any]) -> int:
+    stage_keys = config.get("stage_keys") or []
+    return len(stage_keys)
+
+
+def resolve_item_index(config: dict[str, Any], node: str, *, prefix: str = "") -> int:
+    """从 item_index_by_key 解析 item_index；未知 key 返回 -1。"""
+    del prefix
+    index_map = config.get("item_index_by_key") or {}
+    if node in index_map:
+        return int(index_map[node])
+    return -1
+
+
+def resolve_item_total(config: dict[str, Any]) -> int | None:
+    item_keys = config.get("parallel_item_keys") or []
+    if not item_keys:
+        return None
+    return len(item_keys)
+
+
+def resolve_aggregate_key(config: dict[str, Any]) -> str:
+    return str(
+        config.get("aggregate_key")
+        or config.get("aggregate_node_name")
+        or "aggregate"
+    )
+
+
+def route_keys_set(config: dict[str, Any]) -> set[str]:
+    return set(config.get("route_keys") or [])
+
+
+def resolve_branch_key(config: dict[str, Any], node: str, *, prefix: str = "") -> str:
+    """branch_key 与 graph 节点名一致（显式 route spec key）。"""
+    del prefix
+    return node
+
+
+def matches_route_node(config: dict[str, Any], node: str, *, prefix: str = "") -> bool:
+    del prefix
+    return node in route_keys_set(config)
+
+
+def stage_keys_set(config: dict[str, Any]) -> set[str]:
+    return set(config.get("stage_keys") or [])
+
+
+def parallel_item_keys_set(config: dict[str, Any]) -> set[str]:
+    return set(config.get("parallel_item_keys") or [])
+
+
+def matches_stage_node(config: dict[str, Any], node: str, *, prefix: str = "") -> bool:
+    del prefix
+    return node in stage_keys_set(config)
+
+
+def matches_parallel_item_node(config: dict[str, Any], node: str, *, prefix: str = "") -> bool:
+    del prefix
+    return node in parallel_item_keys_set(config)
+
+
+__all__ = [
+    "matches_parallel_item_node",
+    "matches_route_node",
+    "matches_stage_node",
+    "parallel_item_keys_set",
+    "resolve_aggregate_key",
+    "resolve_branch_key",
+    "resolve_item_index",
+    "resolve_item_total",
+    "resolve_stage_index",
+    "resolve_stage_total",
+    "route_keys_set",
+    "stage_keys_set",
+]