langchain-agentx-python 1.6.4__tar.gz → 1.6.6__tar.gz

{langchain-agentx-python-1.6.4/langchain_agentx_python.egg-info → langchain-agentx-python-1.6.6}/PKG-INFO

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

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/observability/events/workflow_aware_event_adapter.py

@@ -55,21 +55,29 @@ class WorkflowAwareLangGraphEventAdapter:
         self, events: AsyncIterator[Dict[str, Any]]
     ) -> AsyncIterator[LangchainAgentEvent]:
         async for raw_event in events:
-            self._sync_workflow_session_id(raw_event)
+            root_session_id = self._extract_session_id(raw_event)
+            if root_session_id:
+                self._workflow_adapter.set_root_fallback_session_id(root_session_id)
 
             for workflow_event in self._workflow_adapter.consume(raw_event):
                 mapped = self._workflow_mapper.map(workflow_event)
                 if mapped is not None:
                     yield mapped
 
+            loop_session_id = self._workflow_adapter.resolve_active_loop_session_id()
+            if loop_session_id:
+                self._agent_projector.state.session_id = loop_session_id
+            elif root_session_id:
+                self._agent_projector.state.session_id = root_session_id
+
             async for agent_event in self._agent_projector.consume(raw_event):
                 yield agent_event
 
     def _sync_workflow_session_id(self, raw_event: Dict[str, Any]) -> None:
-        session_id = self._extract_session_id(raw_event)
-        if session_id:
-            self._workflow_adapter.state.session_id = session_id
-            self._agent_projector.state.session_id = session_id
+        """Deprecated: session 同步已内联至 adapt()（先 reconcile stack 再派生 loop session）。"""
+        root_session_id = self._extract_session_id(raw_event)
+        if root_session_id:
+            self._workflow_adapter.set_root_fallback_session_id(root_session_id)
 
     @staticmethod
     def _extract_session_id(raw_event: Dict[str, Any]) -> str | None:

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/workflow/__init__.py

@@ -35,6 +35,7 @@ __all__ = [
     "CatalogBackedWorkflowDisplayResolver",
     "CompositeWorkflowDisplayResolver",
     "WorkflowDisplayEnricher",
+    "collect_effective_structure_contract",
     # 事件适配器
     "WorkflowLifecycleEventData",
     "SubworkflowEventData",
@@ -91,6 +92,7 @@ _MODULE_BY_NAME = {
     "CatalogBackedWorkflowDisplayResolver": ".display_resolver",
     "CompositeWorkflowDisplayResolver": ".display_resolver",
     "WorkflowDisplayEnricher": ".display_enricher",
+    "collect_effective_structure_contract": ".structure_collector",
     # event adapter exports
     "WorkflowLifecycleEventData": ".event_adapter",
     "SubworkflowEventData": ".event_adapter",

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/workflow/base.py

@@ -298,11 +298,19 @@ class BaseWorkflow(ABC):
         return self.build_graph().compile()
 
     def export_local_event_adapter_structure(self) -> dict:
-        """导出本 workflow 实例的局部 structure（不沿 delegate 解析）。"""
+        """导出本 workflow 实例的局部 structure 片段（local-view only）。
+
+        不沿 delegate 解析；不含 nested ``scopes[path]`` 全集或 runtime binding registry。
+        Consumer / validator / 开流 adapter 应使用 ``collect_effective_structure_contract()``。
+        """
         return {}
 
     def export_event_adapter_structure(self) -> dict:
-        """导出 event adapter 所需的 workflow_structure（wrapper 沿 delegate 解析）。"""
+        """导出 delegate 解析后的本层 structure 片段（local-view only）。
+
+        仅供 ``WorkflowStructureCollector`` 输入或模式级单测；不是 consumer SSOT。
+        完整 effective contract 请使用 ``collect_effective_structure_contract()``。
+        """
         source = self._resolve_structure_delegate_workflow()
         if source is self:
             return self.export_local_event_adapter_structure()
@@ -312,20 +320,14 @@ class BaseWorkflow(ABC):
         self,
         workflow_structure: dict | None,
     ) -> dict:
-        """合并 derived scoped structure + caller override，并对 Structured Workflow 做 fail-fast 校验。"""
-        from .structure_collector import (
-            WorkflowStructureCollector,
-            merge_scoped_structure_with_override,
-        )
-        from .structure_validation import validate_event_adapter_structure
+        """合并 derived scoped structure + caller override，并对 Structured Workflow 做 fail-fast 校验。
 
-        derived = WorkflowStructureCollector().collect(self)
-        effective_structure = merge_scoped_structure_with_override(
-            derived,
-            workflow_structure,
-        )
-        validate_event_adapter_structure(self, effective_structure)
-        return effective_structure
+        内部委托 ``collect_effective_structure_contract()``；保留此方法供
+        ``astream_langchain_events()`` 与既有测试调用。
+        """
+        from .structure_collector import collect_effective_structure_contract
+
+        return collect_effective_structure_contract(self, workflow_structure)
 
     async def run(
         self,

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/workflow/event_adapter/adapter.py

@@ -26,6 +26,10 @@ from langchain_agentx.workflow.event_adapter.types import (
 from langchain_agentx.workflow.event_adapter.stack import WorkflowStack
 from langchain_agentx.workflow.event_adapter.depth_resolver import DepthResolver
 from langchain_agentx.workflow.event_adapter.scope_resolver import WorkflowScopeResolver
+from langchain_agentx.workflow.event_adapter.session_router import WorkflowSessionRouter
+from langchain_agentx.workflow.event_adapter.structure_lifecycle_guard import (
+    StructureLifecycleGuard,
+)
 from langchain_agentx.workflow.display_enricher import WorkflowDisplayEnricher
 from langchain_agentx.workflow.event_adapter.handlers import (
     StageHandler,
@@ -76,9 +80,7 @@ class WorkflowEventAdapter:
         self.workflow_id = workflow_id
         self.config = config or {}
         self.state = WorkflowAdapterState()
-
-        # 注入 session_id
-        self.state.session_id = session_id
+        self._root_fallback_session_id = session_id
 
         # 初始化 total_stages（从 config 传入）
         self.state.total_stages = self.config.get("total_stages", 0)
@@ -91,6 +93,12 @@ class WorkflowEventAdapter:
         self._stack = WorkflowStack(workflow_id)
         self._depth_resolver = DepthResolver()
         self._scope_resolver = WorkflowScopeResolver(self.config, self._stack)
+        self._session_router = WorkflowSessionRouter(
+            self._scope_resolver,
+            self._stack,
+            root_workflow_id=workflow_id,
+        )
+        self._lifecycle_guard = StructureLifecycleGuard()
         self._stage_handler = StageHandler(
             self.state, self._stack, self._scope_resolver, self.config
         )
@@ -104,6 +112,17 @@ class WorkflowEventAdapter:
         # 初始化状态
         self.state.root_workflow_id = workflow_id
 
+    def set_root_fallback_session_id(self, session_id: str | None) -> None:
+        """设置 root workflow 容器事件与无 task_key 场景的 fallback session_id。"""
+        self._root_fallback_session_id = session_id
+        self.state.session_id = session_id
+
+    def resolve_active_loop_session_id(self) -> str | None:
+        """按当前 active scope 派生 agent/loop session_id。"""
+        return self._session_router.resolve_active_loop_session_id(
+            root_fallback_session_id=self._root_fallback_session_id,
+        )
+
     def consume(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """消费单个 LangGraph 事件，返回 WorkflowEvent 列表
 
@@ -186,7 +205,15 @@ class WorkflowEventAdapter:
             if e.event_type != WorkflowEventType.SUBWORKFLOW_END:
                 e.workflow_depth = self._stack.current_depth
                 e.parent_workflow_id = self._stack.parent_workflow_id
-            e.session_id = self.state.session_id
+            e.session_id = self._session_router.resolve_session_id(
+                e,
+                root_fallback_session_id=self._root_fallback_session_id,
+            )
+            self.state.session_id = e.session_id
+
+        events = self._filter_lifecycle_events(events)
+
+        for e in events:
             self._enrich_lifecycle_display(e)
 
         # === 更新序列号 ===
@@ -202,6 +229,9 @@ class WorkflowEventAdapter:
 
     def _reconcile_stack_from_event(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """编排：推断栈对齐目标 → reconcile → 产出 SUBWORKFLOW_* 事件。"""
+        if self._should_skip_reconcile_during_nested_aggregate(event):
+            return []
+
         events: List[WorkflowEvent] = []
         previous_depth = self._stack.current_depth
         previous_child_id = (
@@ -222,24 +252,79 @@ class WorkflowEventAdapter:
         self._stack.reconcile_to_depth(alignment.target_depth, alignment.segment_ids)
 
         new_depth = self._stack.current_depth
-        if new_depth > previous_depth:
+        if new_depth > previous_depth and self._should_emit_subworkflow_lifecycle(
+            self._stack.build_path()
+        ):
             events.append(self._build_event(
                 WorkflowEventType.SUBWORKFLOW_START,
                 {"child_workflow_id": self._stack.current_workflow_id},
             ))
-        elif exiting_nested:
-            events.append(WorkflowEvent(
+        elif exiting_nested and child_path and self._should_emit_subworkflow_lifecycle(
+            child_path
+        ):
+            sub_end = WorkflowEvent(
                 event_type=WorkflowEventType.SUBWORKFLOW_END,
                 data={"child_workflow_id": previous_child_id},
                 workflow_id=previous_child_id,
                 workflow_path=child_path or self._stack.build_path(),
                 workflow_depth=child_depth if child_depth is not None else 0,
-                session_id=self.state.session_id,
                 parent_workflow_id=child_parent_id,
-            ))
+            )
+            sub_end.session_id = self._session_router.resolve_session_id(
+                sub_end,
+                root_fallback_session_id=self._root_fallback_session_id,
+            )
+            events.append(sub_end)
 
         return events
 
+    def _open_nested_aggregate_owner_path(self) -> str | None:
+        """返回仍 open 的 nested parallel-aggregate scope path（Doc31-R2-A）。"""
+        for identity in self._lifecycle_guard.open_identities:
+            if "|scope:" not in identity:
+                continue
+            owner_path, scope_key = identity.rsplit("|scope:", 1)
+            if ">" not in owner_path:
+                continue
+            entry = self._scope_resolver.scope_entry_at(f"{owner_path}>{scope_key}")
+            if entry and entry.get("scope_kind") == "aggregate":
+                return owner_path
+        return None
+
+    def _should_skip_reconcile_during_nested_aggregate(
+        self, event: Dict[str, Any]
+    ) -> bool:
+        """Loop aggregate 内层 agent 空 ns 事件不得抖栈退出 nested scope。"""
+        owner_path = self._open_nested_aggregate_owner_path()
+        if not owner_path:
+            return False
+        previous_depth = self._stack.current_depth
+        if previous_depth <= 0:
+            return False
+        alignment = self._depth_resolver.derive_stack_alignment(event)
+        return alignment.target_depth < previous_depth
+
+    def _should_emit_subworkflow_lifecycle(self, scope_path: str) -> bool:
+        """仅 scope_origin=nested_workflow 时发 subworkflow-* 结构事件。"""
+        from langchain_agentx.workflow.structure_collector import (
+            SCOPE_ORIGIN_NESTED_WORKFLOW,
+        )
+
+        entry = self._scope_resolver.scope_entry_at(scope_path)
+        if not entry:
+            return False
+        return entry.get("scope_origin") == SCOPE_ORIGIN_NESTED_WORKFLOW
+
+    def _filter_lifecycle_events(
+        self, events: List[WorkflowEvent]
+    ) -> List[WorkflowEvent]:
+        """结构生命周期 open/close 幂等过滤；graph-node 等内容事件不受影响。"""
+        filtered: List[WorkflowEvent] = []
+        for event in events:
+            if self._lifecycle_guard.should_emit(event):
+                filtered.append(event)
+        return filtered
+
     def _build_event(
         self,
         event_type: WorkflowEventType,
@@ -260,7 +345,6 @@ class WorkflowEventAdapter:
             workflow_id=self._stack.current_workflow_id,
             workflow_path=self._stack.build_path(),
             workflow_depth=self._stack.current_depth,
-            session_id=self.state.session_id,
             parent_workflow_id=self._stack.parent_workflow_id,
         )
 
@@ -289,7 +373,6 @@ class WorkflowEventAdapter:
             workflow_id=self._stack.current_workflow_id,
             workflow_path=self._stack.build_path(),
             workflow_depth=self._stack.current_depth,
-            session_id=self.state.session_id,
             parent_workflow_id=self._stack.parent_workflow_id,
         )
 

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/workflow/event_adapter/handlers/stage_handler.py

@@ -75,6 +75,9 @@ class StageHandler:
         stage_total = resolve_stage_total(scope)
 
         if event_type == "on_chain_start":
+            lifecycle_key = f"{self._stack.build_path()}|{stage_key}"
+            if lifecycle_key in self._state.finished_stage_lifecycle_keys:
+                return events
             self._state.current_stage = stage_index
             data = {
                 "stage_index": stage_index,
@@ -114,6 +117,9 @@ class StageHandler:
                 workflow_path=self._stack.build_path(),
                 workflow_depth=self._stack.current_depth,
             ))
+            self._state.finished_stage_lifecycle_keys.add(
+                f"{self._stack.build_path()}|{stage_key}"
+            )
 
         elif event_type == "on_chain_error":
             error_data = event.get("data", {})

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.6}/langchain_agentx/workflow/event_adapter/scope_resolver.py

@@ -27,7 +27,9 @@ from .stack import WorkflowStack
 
 logger = logging.getLogger(__name__)
 
-_SCOPE_METADATA_FIELDS = frozenset({"workflow_id", "scope_key", "scope_kind", "graph_key"})
+_SCOPE_METADATA_FIELDS = frozenset(
+    {"workflow_id", "scope_key", "scope_kind", "scope_origin", "graph_key"}
+)
 
 
 class WorkflowScopeResolver:
@@ -54,10 +56,21 @@ class WorkflowScopeResolver:
 
     def current_scope(self) -> dict[str, Any]:
         """返回当前事件时刻应使用的 structure scope（不含 registry 元数据字段）。"""
-        scope_key = self.current_scope_key()
+        return self._strip_scope_metadata(self.current_scope_entry())
+
+    def scope_entry_at(self, scope_key: str) -> dict[str, Any] | None:
+        """按 path 查 scopes registry entry；miss 时返回 None（不抛错）。"""
         entry = self._scopes.get(scope_key)
         if isinstance(entry, dict):
-            return self._strip_scope_metadata(entry)
+            return dict(entry)
+        return None
+
+    def current_scope_entry(self) -> dict[str, Any]:
+        """返回 scopes[path] 原始 entry（含 workflow_id / graph_key / scope_origin 等）。"""
+        scope_key = self.current_scope_key()
+        entry = self.scope_entry_at(scope_key)
+        if entry is not None:
+            return entry
 
         self._record_scope_miss(scope_key)
         detail_parts = [

langchain-agentx-python-1.6.6/langchain_agentx/workflow/event_adapter/session_router.py

@@ -0,0 +1,190 @@
+"""
+session_router.py — Workflow 结构/agent 事件 session_id 路由
+
+职责：
+    - 按 active runtime scope 与 task_key 派生 loop session_id
+    - 统一走 WorkflowSessionIdPolicy.build_session_id(workflow_id, task_key)
+    - root workflow 容器事件使用 root fallback session（LangGraph input _session_id）
+
+链路位置：
+    - Layer 3: Workflow 事件适配器
+    - 由 WorkflowEventAdapter 在事件产出后绑定 session_id
+
+当前裁剪范围：
+    - 仅派生 session_id，不维护 mutable 全局单槽
+    - aggregate 使用 aggregate_key 作为 task_key，无 special case
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .scope_resolver import WorkflowScopeResolver
+from .stack import WorkflowStack
+from .types import WorkflowEvent, WorkflowEventType
+
+_STAGE_EVENTS = frozenset(
+    {
+        WorkflowEventType.STAGE_START,
+        WorkflowEventType.STAGE_DONE,
+        WorkflowEventType.STAGE_FAILED,
+    }
+)
+_PARALLEL_ITEM_EVENTS = frozenset(
+    {
+        WorkflowEventType.PARALLEL_ITEM_START,
+        WorkflowEventType.PARALLEL_ITEM_DONE,
+        WorkflowEventType.PARALLEL_ITEM_FAILED,
+    }
+)
+_AGGREGATE_EVENTS = frozenset(
+    {
+        WorkflowEventType.PARALLEL_AGGREGATE_START,
+        WorkflowEventType.PARALLEL_AGGREGATE_DONE,
+        WorkflowEventType.PARALLEL_AGGREGATE_FAILED,
+    }
+)
+_ROUTE_EVENTS = frozenset(
+    {
+        WorkflowEventType.ROUTE_BRANCH_START,
+        WorkflowEventType.ROUTE_BRANCH_DONE,
+        WorkflowEventType.ROUTE_BRANCH_FAILED,
+    }
+)
+_ROOT_CONTAINER_EVENTS = frozenset(
+    {
+        WorkflowEventType.WORKFLOW_START,
+        WorkflowEventType.WORKFLOW_END,
+        WorkflowEventType.WORKFLOW_FAILED,
+    }
+)
+
+
+def _build_policy_session_id(workflow_id: str, task_key: str) -> str:
+    from langchain_agentx.workflow.execution import (
+        WorkflowNodeContext,
+        WorkflowSessionIdPolicy,
+    )
+
+    return WorkflowSessionIdPolicy.build_session_id(
+        WorkflowNodeContext(workflow_id=workflow_id, task_key=task_key),
+    )
+
+
+class WorkflowSessionRouter:
+    """按 active scope contract 派生 structure / loop session_id。"""
+
+    def __init__(
+        self,
+        scope_resolver: WorkflowScopeResolver,
+        stack: WorkflowStack,
+        *,
+        root_workflow_id: str,
+    ) -> None:
+        self._scope_resolver = scope_resolver
+        self._stack = stack
+        self._root_workflow_id = root_workflow_id
+
+    def resolve_session_id(
+        self,
+        event: WorkflowEvent,
+        *,
+        root_fallback_session_id: str | None = None,
+    ) -> str | None:
+        """为已产出的 WorkflowEvent 绑定 session_id。"""
+        if (
+            event.event_type in _ROOT_CONTAINER_EVENTS
+            and event.workflow_depth == 0
+        ):
+            return root_fallback_session_id
+
+        task_key = self._task_key_from_event(event)
+        if not task_key:
+            return root_fallback_session_id
+
+        owner_workflow_id = self._owner_workflow_id()
+        return _build_policy_session_id(owner_workflow_id, task_key)
+
+    def resolve_active_loop_session_id(
+        self,
+        *,
+        root_fallback_session_id: str | None = None,
+    ) -> str | None:
+        """为当前 stack 下的 agent 事件派生 loop session_id（无 WorkflowEvent 上下文）。"""
+        entry = self._scope_resolver.current_scope_entry()
+        scope_kind = entry.get("scope_kind")
+        graph_key = entry.get("graph_key")
+
+        if scope_kind == "workflow_root":
+            return root_fallback_session_id
+
+        if graph_key and scope_kind in (
+            "stage",
+            "parallel_item",
+            "route",
+            "aggregate",
+        ):
+            owner_workflow_id = str(entry.get("workflow_id") or self._owner_workflow_id())
+            return _build_policy_session_id(owner_workflow_id, str(graph_key))
+
+        task_key = self._task_key_from_scope_entry(entry)
+        if task_key:
+            owner_workflow_id = str(entry.get("workflow_id") or self._owner_workflow_id())
+            return _build_policy_session_id(owner_workflow_id, task_key)
+
+        return root_fallback_session_id
+
+    def _owner_workflow_id(self) -> str:
+        entry = self._scope_resolver.current_scope_entry()
+        workflow_id = entry.get("workflow_id")
+        if workflow_id:
+            return str(workflow_id)
+        if self._stack.current_depth == 0:
+            return self._root_workflow_id
+        return self._stack.current_workflow_id
+
+    def _task_key_from_event(self, event: WorkflowEvent) -> str | None:
+        data: dict[str, Any] = event.data if isinstance(event.data, dict) else {}
+
+        if event.event_type in _STAGE_EVENTS:
+            key = data.get("stage_key")
+            return str(key) if key else None
+
+        if event.event_type in _PARALLEL_ITEM_EVENTS:
+            key = data.get("item_key")
+            return str(key) if key else None
+
+        if event.event_type in _AGGREGATE_EVENTS:
+            key = data.get("aggregate_key")
+            return str(key) if key else None
+
+        if event.event_type in _ROUTE_EVENTS:
+            key = data.get("branch_key")
+            return str(key) if key else None
+
+        if event.event_type in (
+            WorkflowEventType.SUBWORKFLOW_START,
+            WorkflowEventType.SUBWORKFLOW_END,
+        ):
+            return self._task_key_from_scope_entry(
+                self._scope_resolver.current_scope_entry()
+            )
+
+        if event.event_type in (
+            WorkflowEventType.GRAPH_NODE_START,
+            WorkflowEventType.GRAPH_NODE_END,
+        ):
+            node = data.get("node")
+            return str(node) if node else None
+
+        return None
+
+    @staticmethod
+    def _task_key_from_scope_entry(entry: dict[str, Any]) -> str | None:
+        graph_key = entry.get("graph_key")
+        if graph_key:
+            return str(graph_key)
+        return None
+
+
+__all__ = ["WorkflowSessionRouter"]