langchain-agentx-python 0.1.5__tar.gz → 0.1.6__tar.gz

{langchain-agentx-python-0.1.5/langchain_agentx_python.egg-info → langchain-agentx-python-0.1.6}/PKG-INFO

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

{langchain-agentx-python-0.1.5 → langchain-agentx-python-0.1.6}/langchain_agentx/__init__.py

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

langchain-agentx-python-0.1.6/langchain_agentx/workflow/__init__.py

@@ -0,0 +1,24 @@
+"""Workflow 容器导出。"""
+
+from .base import BaseWorkflow
+from .batch import BatchWorkflow
+from .dag import DagWorkflow
+
+# Workflow 事件适配器导出（Phase 4）
+from .event_adapter import (
+    WorkflowEventAdapter,
+    WorkflowEvent,
+    WorkflowEventType,
+    WorkflowAdapterState,
+)
+
+__all__ = [
+    "BaseWorkflow",
+    "DagWorkflow",
+    "BatchWorkflow",
+    # 事件适配器
+    "WorkflowEventAdapter",
+    "WorkflowEvent",
+    "WorkflowEventType",
+    "WorkflowAdapterState",
+]

langchain-agentx-python-0.1.6/langchain_agentx/workflow/base.py

@@ -0,0 +1,544 @@
+"""
+base.py — BaseWorkflow 基础设施层
+
+职责：
+    - 定义 Workflow 的标准接口（build_graph + run + as_node）
+    - 提供通用能力（Hook 发射、Trace 映射、并发控制）
+    - 支持层级关系（workflow_session_id、workflow_path）
+    - 支持内存提取清理（drain_pending_memory_extractions）
+
+链路位置：
+    - Layer 2: 基础设施层
+    - 被 Layer 3 (特殊 Workflow) 继承
+    - 可作为其他 Workflow 的节点（as_node）
+
+当前裁剪范围：
+    - 不提供具体的拓扑结构（由 Layer 3 实现）
+    - 仅支持 Workflow 级 Hook 事件（WORKFLOW_START、WORKFLOW_END）
+    - 不支持 per-item Hook 事件（Phase 2+）
+
+设计原则（Phase 1）：
+    - 使用 AgentNode 路径，废弃 graph_factory / _invoke_agent / _astream_agent
+    - parent_workflow 在运行时注入（run() / as_node() 参数），避免循环依赖
+    - as_node() 直接返回完整 state，让 LangGraph reducer 处理合并
+    - max_concurrency 仅存储配置值，不实例化 Semaphore（由子类按需创建）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator
+from uuid import uuid4
+
+from langgraph.graph import StateGraph
+from langchain_core.runnables import RunnableConfig
+
+from ..loop.hook.types import HookContext, HookEvent
+from ..loop.hook.registry import HookRegistry
+from ..loop.hook.engine import HookEngine
+from ..memory.memdir.agent_memory import drain_pending_agent_memory_extraction
+from .state import WorkflowState
+
+# Lazy import for event_adapter（避免循环依赖）
+# 实际使用时通过 _get_event_adapter() 延迟导入
+
+
+logger = logging.getLogger(__name__)
+
+
+class BaseWorkflow(ABC):
+    """基础设施层基类：定义 Workflow 的标准契约和通用能力。
+
+    双重身份：
+    - 作为基类：Layer 3 继承 BaseWorkflow，复用通用能力
+    - 作为组件：run() 方法签名与 LangGraph 节点函数一致，可作为其他 Workflow 的节点
+
+    设计原则（Phase 1）：
+    - __init__ 只接收 workflow_id 和 hook_registry，不存储 parent_workflow
+    - parent_workflow 在运行时注入（run() / as_node() 参数），避免循环依赖
+    - max_concurrency 仅存储配置值，不实例化 Semaphore（由子类按需创建）
+    """
+
+    def __init__(
+        self,
+        workflow_id: str,
+        hook_registry: HookRegistry,
+        trace_collector: Any = None,
+        max_concurrency: int | None = None,
+        graph_factory: Any = None,
+    ):
+        """初始化 BaseWorkflow。
+
+        Args:
+            workflow_id: Workflow 标识符
+            hook_registry: Hook 注册表
+            trace_collector: Trace 收集器（可选）
+            max_concurrency: 并发控制限制（仅存储，不实例化 Semaphore）
+            graph_factory: 兼容层参数（用于 Batch/Dag 迁移，可选）
+        """
+        self._workflow_id = workflow_id
+        self._hook_registry = hook_registry
+        self._hook_engine = HookEngine(hook_registry.build_snapshot())
+        self._trace_collector = trace_collector
+        self._max_concurrency = max_concurrency or 4
+
+        # 初始化 _workflow_path（在 run() 中会更新）
+        self._workflow_path = workflow_id
+        self._workflow_session_id = None
+
+        # === 兼容层：支持 Batch/Dag 迁移 ===
+        self._graph_factory = graph_factory
+        self._semaphore = asyncio.Semaphore(self._max_concurrency)
+        self.container_type = "workflow_task"
+
+        # 注意：parent_workflow 移到 run() 参数，避免 __init__ 时的循环依赖（问题 20）
+        # 注意：graph_factory 仅用于兼容 Batch/Dag，新代码应使用 build_graph()
+
+    @abstractmethod
+    def build_graph(self) -> StateGraph:
+        """子类实现：构建 LangGraph 图。
+
+        返回的 StateGraph 中：
+        - 节点可以是 AgentNode.build() 返回的节点函数（Layer 1）
+        - 也可以是其他 Workflow（Layer 2 或 Layer 3）
+        """
+        pass
+
+    def compile(self):
+        """编译并返回可执行的图。"""
+        return self.build_graph().compile()
+
+    async def run(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+    ) -> dict:
+        """执行 Workflow（对外 API，用于顶层调用）。
+
+        Args:
+            initial_state: 初始状态
+            parent_workflow: 父 Workflow（用于构建层级关系，问题 20）
+
+        Returns:
+            完整的 WorkflowState，包含所有字段的状态
+
+        注意：
+            - 作为顶层 Workflow 调用时使用此方法
+            - 作为其他 Workflow 的子节点时，应使用 as_node() 方法
+
+        层级关系（§2.7 问题 12、20）：
+            - parent_workflow 在运行时注入，而不是 __init__
+            - 构建完整的 workflow_path（如 "wiki-build>wiki-l1"）
+
+        内存提取（§2.7 问题 16）：
+            - Workflow 结束时需要清理 pending 的 memory extraction
+            - 通过 try-finally 确保无论成功或失败都会执行清理
+        """
+        # === 构建层级关系（问题 20）===
+        # parent_workflow 在运行时注入，而不是 __init__
+        if parent_workflow is None:
+            workflow_path = self._workflow_id
+        else:
+            workflow_path = f"{parent_workflow._workflow_path}>{self._workflow_id}"
+
+        # 生成唯一的 workflow_session_id
+        workflow_session_id = f"workflow-{self._workflow_id}-{uuid4().hex[:8]}"
+
+        # 保存当前 workflow_path（用于子 Workflow 构建）
+        self._workflow_path = workflow_path
+        self._workflow_session_id = workflow_session_id
+
+        await self._emit_hook(HookEvent.WORKFLOW_START, {
+            "workflow_id": self._workflow_id,
+            "workflow_session_id": workflow_session_id,
+            "workflow_path": workflow_path,
+        })
+
+        graph = self.compile()
+
+        try:
+            result = await graph.ainvoke(initial_state)
+
+            await self._emit_hook(HookEvent.WORKFLOW_END, {
+                "workflow_id": self._workflow_id,
+                "workflow_session_id": workflow_session_id,
+                "workflow_path": workflow_path,
+            })
+
+            return result
+
+        finally:
+            # === 内存提取清理（问题 16）===
+            # 确保无论成功或失败都清理 pending 的 memory extraction
+            # 注意：drain 与 trace_collector 无关，memory extraction 的清理永远执行
+            await self._drain_pending_memory_extractions()
+
+    def as_node(
+        self,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        outer_semaphore: asyncio.Semaphore | None = None,
+    ) -> callable:
+        """返回符合 LangGraph 节点语义的 callable（用于子图嵌套）。
+
+        Args:
+            parent_workflow: 父 Workflow（用于构建层级关系，问题 20）
+            outer_semaphore: 外层并发控制信号量（问题 19）
+
+        与 run() 的区别：
+            - run(): 返回完整 WorkflowState（用于顶层调用）
+            - as_node(): 返回完整 WorkflowState（作为其他 Workflow 的节点）
+
+        实现原理：
+            - 直接调用 run() 返回完整 state
+            - 传递 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
+        """
+        async def node_fn(state: dict) -> dict:
+            # === 并发控制（问题 19）===
+            if outer_semaphore is not None:
+                async with outer_semaphore:
+                    return await self.run(state, parent_workflow=parent_workflow)
+            else:
+                return await self.run(state, parent_workflow=parent_workflow)
+
+        return node_fn
+
+    async def _invoke_agent(
+        self,
+        messages: list,
+        task_key: str,
+        parent_session_id: str | None = None,
+    ) -> dict:
+        """兼容层：为 Batch/Dag 提供 agent 调用接口。
+
+        迁移自 base.py:59-74，保留原有行为。
+
+        Args:
+            messages: 消息列表
+            task_key: 任务标识符，用于构建 session_id
+            parent_session_id: 父会话 ID（可选）
+
+        Returns:
+            agent 执行结果字典
+
+        Raises:
+            RuntimeError: 如果 graph_factory 未提供
+        """
+        if self._graph_factory is None:
+            raise RuntimeError(
+                "_invoke_agent() requires graph_factory parameter. "
+                "This method is for Batch/Dag compatibility only."
+            )
+
+        session_id = f"{self._workflow_id}-{task_key}"
+        async with self._semaphore:
+            graph = self._graph_factory(
+                session_id=session_id,
+                parent_conversation_session_id=parent_session_id,
+                is_subagent=parent_session_id is not None,
+                container_type=self.container_type,
+            )
+            result = await graph.ainvoke({"messages": messages})
+            return dict(result) if isinstance(result, dict) else {"result": result}
+
+    async def astream_events(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        subgraphs: bool = True,
+        version: str = "v2",
+        **kwargs
+    ) -> AsyncIterator[dict]:
+        """流式执行 Workflow，返回所有事件（包括嵌套子图）。
+
+        Args:
+            initial_state: 初始状态
+            parent_workflow: 父 Workflow（用于构建层级关系）
+            subgraphs: 是否包含嵌套子图事件，默认 True
+            version: 事件格式版本，"v1" 或 "v2"
+            **kwargs: 传递给 LangGraph astream_events 的其他参数
+
+        Yields:
+            事件字典，格式由 LangGraph astream_events 定义
+
+        事件格式（v2）：
+            {
+                "event": "on_chain_start" | "on_chain_end" | "on_chain_stream" | ...,
+                "data": {...},
+                "metadata": {
+                    "langgraph_node": str,
+                    "langgraph_checkpoint_ns": str,  # 命名空间路径
+                    ...
+                }
+            }
+
+        Hook 事件：
+            - WORKFLOW_START 在开始时发射
+            - WORKFLOW_END 在结束时发射
+
+        注意（v2 合并）：
+            - workflow_path 作为 local 变量传递，避免并发状态错乱
+            - 不写入 self._workflow_path / self._workflow_session_id
+        """
+        # === 构建层级关系 ===
+        if parent_workflow is None:
+            workflow_path = self._workflow_id
+        else:
+            workflow_path = f"{parent_workflow._workflow_path}>{self._workflow_id}"
+
+        # 生成唯一的 workflow_session_id（local 变量）
+        workflow_session_id = f"workflow-{self._workflow_id}-{uuid4().hex[:8]}"
+
+        # === 发射 WORKFLOW_START Hook ===
+        await self._emit_hook(HookEvent.WORKFLOW_START, {
+            "workflow_id": self._workflow_id,
+            "workflow_session_id": workflow_session_id,
+            "workflow_path": workflow_path,
+        })
+
+        try:
+            # === 流式执行，传递 subgraphs 参数 ===
+            graph = self.compile()
+
+            # 注意：不注入 workflow_path 到 configurable（经验证不会透传到事件 metadata）
+            # workflow_path 由 WorkflowEventAdapter 通过 langgraph_checkpoint_ns 维护
+            config: RunnableConfig = {}
+
+            async for event in graph.astream_events(
+                initial_state,
+                config=config,
+                subgraphs=subgraphs,
+                version=version,
+                **kwargs,
+            ):
+                yield event
+
+            # === 发射 WORKFLOW_END Hook ===
+            await self._emit_hook(HookEvent.WORKFLOW_END, {
+                "workflow_id": self._workflow_id,
+                "workflow_session_id": workflow_session_id,
+                "workflow_path": workflow_path,
+            })
+
+        finally:
+            # === 内存提取清理 ===
+            await self._drain_pending_memory_extractions()
+
+    async def run_stream(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        filter_events: bool = True,
+        **kwargs
+    ) -> AsyncIterator[tuple[str, dict]]:
+        """便捷的流式执行方法，返回过滤后的事件。
+
+        Args:
+            initial_state: 初始状态
+            parent_workflow: 父 Workflow
+            filter_events: 是否过滤事件，只返回关键事件
+            **kwargs: 传递给 astream_events 的其他参数
+
+        Yields:
+            (event_type, event_data) 元组
+
+        当 filter_events=True 时，只返回：
+        - ("node_start", {...}) - 节点开始
+        - ("node_end", {...}) - 节点结束
+        - ("workflow_start", {...}) - Workflow 开始
+        - ("workflow_end", {...}) - Workflow 结束
+        - ("item_start", {...}) - 并行项开始
+        - ("item_done", {...}) - 并行项完成
+
+        当 filter_events=False 时，返回所有原始事件。
+        """
+        if not filter_events:
+            async for event in self.astream_events(initial_state, parent_workflow=parent_workflow, **kwargs):
+                event_type = event.get("event", "unknown")
+                yield (event_type, event)
+        else:
+            async for event in self.astream_events(initial_state, parent_workflow=parent_workflow, **kwargs):
+                event_name = event.get("event", "")
+                metadata = event.get("metadata", {})
+                node = metadata.get("langgraph_node", "")
+                ns = metadata.get("langgraph_checkpoint_ns", "")
+
+                # 获取当前 workflow_path（从 parent 或 self）
+                if parent_workflow:
+                    workflow_path = f"{parent_workflow._workflow_path}>{self._workflow_id}"
+                else:
+                    workflow_path = self._workflow_id
+
+                # 过滤出关键事件
+                if event_name == "on_chain_start":
+                    if node:
+                        yield ("node_start", {
+                            "node": node,
+                            "ns": ns,
+                            "workflow_path": workflow_path,
+                        })
+                    else:
+                        yield ("workflow_start", {
+                            "workflow_id": self._workflow_id,
+                            "workflow_path": workflow_path,
+                        })
+
+                elif event_name == "on_chain_end":
+                    if node:
+                        yield ("node_end", {
+                            "node": node,
+                            "ns": ns,
+                            "workflow_path": workflow_path,
+                        })
+                    else:
+                        yield ("workflow_end", {
+                            "workflow_id": self._workflow_id,
+                            "workflow_path": workflow_path,
+                        })
+
+                # 检测并行项（parallel_N 格式的节点）
+                if node and node.startswith("parallel_"):
+                    if event_name == "on_chain_start":
+                        yield ("item_start", {
+                            "node": node,
+                            "ns": ns,
+                            "workflow_path": workflow_path,
+                        })
+                    elif event_name == "on_chain_end":
+                        yield ("item_done", {
+                            "node": node,
+                            "ns": ns,
+                            "workflow_path": workflow_path,
+                        })
+
+    async def astream_workflow_events(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        enable_agent_events: bool = False,
+        workflow_structure: dict | None = None,
+        **kwargs
+    ) -> AsyncIterator[Any]:
+        """流式执行 Workflow，返回结构化事件（新 API）。
+
+        Args:
+            initial_state: 初始状态
+            parent_workflow: 父 Workflow
+            enable_agent_events: 是否同时输出 Agent 内部事件（需配合 CompositeEventAdapter）
+            workflow_structure: 结构信息，包含：
+                - total_stages: ChainingWorkflow 的 stage 总数
+                - total_parallel: ParallelizationWorkflow 的并行节点数
+                - routes: RoutingWorkflow 的路由 key 列表
+            **kwargs: 传递给 astream_events 的其他参数
+
+        Yields:
+            WorkflowEvent: 结构化的 Workflow 事件
+
+        嵌套语义说明：
+            - 本方法**只能在根 Workflow 上调用**
+            - 嵌套子 Workflow 通过 SUBWORKFLOW_START/END 事件表达
+            - workflow_path 从根开始构建（如 "wiki-build>parallel_0"）
+            - 不允许在子 Workflow 上单独创建 adapter（避免路径不连续）
+
+        示例：
+            ```python
+            workflow = ChainingWorkflow(
+                workflow_id="my-workflow",
+                stages=[...],
+                hook_registry=registry,
+            )
+
+            async for event in workflow.astream_workflow_events(
+                initial_state={"messages": [...]},
+                workflow_structure={"total_stages": 3},
+            ):
+                if event.event_type == WorkflowEventType.STAGE_DONE:
+                    print(f"Stage {event.data['stage_index']} done")
+            ```
+        """
+        from .event_adapter import WorkflowEventAdapter, WorkflowEvent
+
+        # === 构建配置 ===
+        config = {}
+        if workflow_structure:
+            config.update(workflow_structure)
+
+        # === 生成 session_id ===
+        workflow_session_id = f"workflow-{self._workflow_id}-{uuid4().hex[:8]}"
+
+        # === 创建适配器 ===
+        adapter = WorkflowEventAdapter(
+            self._workflow_id,
+            session_id=workflow_session_id,
+            config=config,
+        )
+
+        # === 流式处理事件 ===
+        async for event in self.astream_events(initial_state, parent_workflow=parent_workflow, **kwargs):
+            for wf_event in adapter.consume(event):
+                yield wf_event
+
+    # === 通用能力（由 Layer 3 复用）===
+
+    async def _emit_hook(self, event: HookEvent, ctx: dict) -> None:
+        """发射 Hook 事件，构造 HookContext。
+
+        Args:
+            event: Hook 事件类型
+            ctx: 上下文数据（包含 workflow_id, workflow_session_id, workflow_path 等）
+        """
+        hook_ctx = HookContext(
+            event=event,
+            state=ctx.get("state", {}),
+            session_id=ctx.get("session_id"),
+            tool_name=ctx.get("tool_name"),
+            tool_input=ctx.get("tool_input"),
+            tool_result=ctx.get("tool_result"),
+            # ← Workflow 级字段（Phase 1）
+            workflow_id=ctx.get("workflow_id"),
+            workflow_session_id=ctx.get("workflow_session_id"),
+            workflow_path=ctx.get("workflow_path"),
+        )
+        await self._hook_engine.execute(hook_ctx)
+
+    async def _drain_pending_memory_extractions(self) -> None:
+        """清理 pending 的 memory extraction 任务。
+
+        这是为了确保 Workflow 结束时不会遗留未完成的 memory extraction。
+        与 create_loop_agent 内部的逻辑保持一致。
+
+        实现说明：
+            - 依赖于 trace_collector 的接口
+            - 如果 trace_collector 为 None，则跳过清理
+            - 清理失败不应抛出异常，只记录日志
+        """
+        try:
+            # 调用模块级函数清理 memory extraction
+            # 注意：这是 memory 子系统的模块级函数，不是 TraceCollector 的方法
+            # 签名：drain_pending_agent_memory_extraction(timeout_ms: int = 60_000)
+            await drain_pending_agent_memory_extraction(
+                timeout_ms=60_000,  # 默认 60 秒超时
+            )
+        except Exception as e:
+            # 清理失败不应抛出异常，避免掩盖主流程的错误
+            # 记录日志即可
+            logger.warning(f"Failed to drain pending memory extractions: {e}")
+
+
+__all__ = ["BaseWorkflow"]