langchain-agentx-python 1.3.6__tar.gz → 1.3.8__tar.gz

{langchain-agentx-python-1.3.6/langchain_agentx_python.egg-info → langchain-agentx-python-1.3.8}/PKG-INFO

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

{langchain-agentx-python-1.3.6 → langchain-agentx-python-1.3.8}/langchain_agentx/__init__.py

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

langchain-agentx-python-1.3.8/langchain_agentx/observability/events/workflow_container_projector.py

@@ -0,0 +1,649 @@
+"""
+workflow_container_projector.py — Workflow UI 容器树参考投影器
+
+职责：
+    - 将 LangchainAgentEvent 公共流投影为 CLI / Trace 可消费的容器树
+    - 按容器身份（workflow_path + scope + key）维护 active set，支持并发 parallel item
+    - 将 thinking / text / tool 正文挂到最深活跃容器（或显式 workflow_path 命中容器）
+
+链路位置：
+    - Layer 3: observability/events 消费侧参考实现
+    - 伴侣包（langchain_agentx_trace）应对齐本契约；SDK 禁止 import 伴侣包
+
+当前裁剪范围：
+    - 仅做参考投影与 fixture 生成，不负责终端渲染
+    - display.description 作为 subtitle，不与正文 preview 混淆
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+from langchain_agentx.observability.events.agent_event_projector import (
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+)
+
+WorkflowContainerScope = Literal[
+    "workflow",
+    "stage",
+    "item",
+    "branch",
+    "aggregate",
+    "subworkflow",
+]
+
+WorkflowContainerStatus = Literal[
+    "pending",
+    "running",
+    "completed",
+    "failed",
+    "skipped",
+    "cancelled",
+    "blocked",
+    "retrying",
+]
+
+ContentBlockKind = Literal["reasoning", "text", "tool"]
+
+
+class ContainerAction(str, Enum):
+    """容器状态机动作。"""
+
+    OPEN = "open"
+    CLOSE = "close"
+    APPEND_CONTENT = "append-content"
+
+
+_OPEN_EVENT_TYPES: frozenset[LangchainAgentEventType] = frozenset({
+    LangchainAgentEventType.WORKFLOW_START,
+    LangchainAgentEventType.SUBWORKFLOW_START,
+    LangchainAgentEventType.STAGE_START,
+    LangchainAgentEventType.PARALLEL_ITEM_START,
+    LangchainAgentEventType.PARALLEL_AGGREGATE_START,
+    LangchainAgentEventType.ROUTE_BRANCH_START,
+})
+
+_CLOSE_EVENT_TYPES: frozenset[LangchainAgentEventType] = frozenset({
+    LangchainAgentEventType.WORKFLOW_END,
+    LangchainAgentEventType.WORKFLOW_FAILED,
+    LangchainAgentEventType.SUBWORKFLOW_END,
+    LangchainAgentEventType.STAGE_DONE,
+    LangchainAgentEventType.STAGE_FAILED,
+    LangchainAgentEventType.PARALLEL_ITEM_DONE,
+    LangchainAgentEventType.PARALLEL_ITEM_FAILED,
+    LangchainAgentEventType.PARALLEL_AGGREGATE_DONE,
+    LangchainAgentEventType.PARALLEL_AGGREGATE_FAILED,
+    LangchainAgentEventType.ROUTE_BRANCH_DONE,
+    LangchainAgentEventType.ROUTE_BRANCH_FAILED,
+})
+
+_EVENT_TYPE_TO_SCOPE: dict[LangchainAgentEventType, WorkflowContainerScope] = {
+    LangchainAgentEventType.WORKFLOW_START: "workflow",
+    LangchainAgentEventType.WORKFLOW_END: "workflow",
+    LangchainAgentEventType.WORKFLOW_FAILED: "workflow",
+    LangchainAgentEventType.SUBWORKFLOW_START: "subworkflow",
+    LangchainAgentEventType.SUBWORKFLOW_END: "subworkflow",
+    LangchainAgentEventType.STAGE_START: "stage",
+    LangchainAgentEventType.STAGE_DONE: "stage",
+    LangchainAgentEventType.STAGE_FAILED: "stage",
+    LangchainAgentEventType.PARALLEL_ITEM_START: "item",
+    LangchainAgentEventType.PARALLEL_ITEM_DONE: "item",
+    LangchainAgentEventType.PARALLEL_ITEM_FAILED: "item",
+    LangchainAgentEventType.PARALLEL_AGGREGATE_START: "aggregate",
+    LangchainAgentEventType.PARALLEL_AGGREGATE_DONE: "aggregate",
+    LangchainAgentEventType.PARALLEL_AGGREGATE_FAILED: "aggregate",
+    LangchainAgentEventType.ROUTE_BRANCH_START: "branch",
+    LangchainAgentEventType.ROUTE_BRANCH_DONE: "branch",
+    LangchainAgentEventType.ROUTE_BRANCH_FAILED: "branch",
+}
+
+_CONTENT_EVENT_TYPES: frozenset[LangchainAgentEventType] = frozenset({
+    LangchainAgentEventType.REASONING_START,
+    LangchainAgentEventType.REASONING_DELTA,
+    LangchainAgentEventType.REASONING_END,
+    LangchainAgentEventType.TEXT_START,
+    LangchainAgentEventType.TEXT_DELTA,
+    LangchainAgentEventType.TEXT_END,
+    LangchainAgentEventType.TOOL_INPUT,
+    LangchainAgentEventType.TOOL_INPUT_START,
+    LangchainAgentEventType.TOOL_INPUT_DELTA,
+    LangchainAgentEventType.TOOL_CALL,
+    LangchainAgentEventType.TOOL_RESULT,
+    LangchainAgentEventType.TOOL_ERROR,
+    LangchainAgentEventType.TOOL_PROGRESS,
+})
+
+_SCOPE_PRIORITY: dict[WorkflowContainerScope, int] = {
+    "workflow": 0,
+    "subworkflow": 1,
+    "aggregate": 2,
+    "stage": 3,
+    "item": 3,
+    "branch": 3,
+}
+
+
+def build_container_id(
+    workflow_path: str,
+    scope: WorkflowContainerScope,
+    scope_key: str,
+) -> str:
+    """按 workflow_path + scope + key 生成唯一容器身份。"""
+    return f"{workflow_path}|{scope}:{scope_key}"
+
+
+def resolve_scope_key(event_type: LangchainAgentEventType, data: dict[str, Any]) -> str:
+    """从结构事件 data 提取 scope key。"""
+    if event_type in (
+        LangchainAgentEventType.WORKFLOW_START,
+        LangchainAgentEventType.WORKFLOW_END,
+        LangchainAgentEventType.WORKFLOW_FAILED,
+    ):
+        workflow_id = data.get("workflow_id")
+        if isinstance(workflow_id, str) and workflow_id:
+            return workflow_id
+        return str(data.get("workflow_path", "workflow"))
+
+    if event_type in (
+        LangchainAgentEventType.SUBWORKFLOW_START,
+        LangchainAgentEventType.SUBWORKFLOW_END,
+    ):
+        return str(data.get("child_workflow_id", "subworkflow"))
+
+    if event_type in (
+        LangchainAgentEventType.STAGE_START,
+        LangchainAgentEventType.STAGE_DONE,
+        LangchainAgentEventType.STAGE_FAILED,
+    ):
+        return str(data.get("stage_key", data.get("stage_index", "stage")))
+
+    if event_type in (
+        LangchainAgentEventType.PARALLEL_ITEM_START,
+        LangchainAgentEventType.PARALLEL_ITEM_DONE,
+        LangchainAgentEventType.PARALLEL_ITEM_FAILED,
+    ):
+        return str(data.get("item_key", data.get("item_index", "item")))
+
+    if event_type in (
+        LangchainAgentEventType.PARALLEL_AGGREGATE_START,
+        LangchainAgentEventType.PARALLEL_AGGREGATE_DONE,
+        LangchainAgentEventType.PARALLEL_AGGREGATE_FAILED,
+    ):
+        return str(data.get("aggregate_key", "aggregate"))
+
+    if event_type in (
+        LangchainAgentEventType.ROUTE_BRANCH_START,
+        LangchainAgentEventType.ROUTE_BRANCH_DONE,
+        LangchainAgentEventType.ROUTE_BRANCH_FAILED,
+    ):
+        return str(data.get("branch_key", data.get("branch_node", "branch")))
+
+    display = data.get("display")
+    if isinstance(display, dict):
+        debug_key = display.get("debug_key")
+        if isinstance(debug_key, str) and debug_key:
+            return debug_key
+
+    return "unknown"
+
+
+def _display_status(data: dict[str, Any], fallback: WorkflowContainerStatus) -> WorkflowContainerStatus:
+    display = data.get("display")
+    if isinstance(display, dict):
+        status = display.get("status")
+        if isinstance(status, str) and status:
+            return status  # type: ignore[return-value]
+    return fallback
+
+
+def _close_status(event_type: LangchainAgentEventType) -> WorkflowContainerStatus:
+    if event_type in (
+        LangchainAgentEventType.WORKFLOW_FAILED,
+        LangchainAgentEventType.STAGE_FAILED,
+        LangchainAgentEventType.PARALLEL_ITEM_FAILED,
+        LangchainAgentEventType.PARALLEL_AGGREGATE_FAILED,
+        LangchainAgentEventType.ROUTE_BRANCH_FAILED,
+    ):
+        return "failed"
+    return "completed"
+
+
+@dataclass
+class WorkflowContentBlock:
+    """容器下挂载的正文块（preview 层，非 subtitle）。"""
+
+    kind: ContentBlockKind
+    preview: str
+    tool_name: str | None = None
+
+
+@dataclass
+class WorkflowContainerNode:
+    """UI 容器节点。"""
+
+    container_id: str
+    scope: WorkflowContainerScope
+    workflow_path: str
+    workflow_depth: int
+    scope_key: str
+    title: str
+    subtitle: str
+    status: WorkflowContainerStatus
+    pattern: str
+    parent_container_id: str | None
+    content_blocks: list[WorkflowContentBlock] = field(default_factory=list)
+    is_open: bool = True
+
+
+@dataclass
+class WorkflowContainerTreeSnapshot:
+    """容器树快照（fixture / 测试 / CLI 预览）。"""
+
+    root_container_ids: list[str]
+    containers: dict[str, WorkflowContainerNode]
+    active_container_ids: list[str]
+
+
+@dataclass
+class WorkflowContainerActiveSet:
+    """按容器身份索引的活跃集（并发 item 不依赖单一栈）。"""
+
+    _open_order: list[str] = field(default_factory=list)
+    _nodes: dict[str, WorkflowContainerNode] = field(default_factory=dict)
+
+    def open(self, node: WorkflowContainerNode) -> None:
+        self._nodes[node.container_id] = node
+        if node.container_id not in self._open_order:
+            self._open_order.append(node.container_id)
+
+    def close(self, container_id: str, status: WorkflowContainerStatus) -> None:
+        node = self._nodes.get(container_id)
+        if node is None:
+            return
+        node.status = status
+        node.is_open = False
+        if container_id in self._open_order:
+            self._open_order.remove(container_id)
+
+    @property
+    def active_ids(self) -> list[str]:
+        return list(self._open_order)
+
+    def deepest_active(self) -> str | None:
+        if not self._open_order:
+            return None
+        return max(
+            self._open_order,
+            key=self.rank_container,
+        )
+
+    def resolve_content_target(
+        self,
+        *,
+        workflow_path: str | None,
+        scope_key: str | None,
+    ) -> str | None:
+        if scope_key:
+            for container_id in reversed(self._open_order):
+                node = self._nodes[container_id]
+                if node.scope_key == scope_key and node.is_open:
+                    if workflow_path is None or node.workflow_path == workflow_path:
+                        return container_id
+
+        if workflow_path:
+            candidates = [
+                cid
+                for cid in self._open_order
+                if self._nodes[cid].is_open
+                and (
+                    self._nodes[cid].workflow_path == workflow_path
+                    or workflow_path.startswith(self._nodes[cid].workflow_path + ">")
+                )
+            ]
+            if candidates:
+                return max(candidates, key=self.rank_container)
+
+        return self.deepest_active()
+
+    def close_descendants_of_path(self, workflow_path: str, status: WorkflowContainerStatus) -> None:
+        """关闭同一 workflow 子树下仍 open 的容器（workflow 结束时级联）。"""
+        to_close = [
+            cid
+            for cid in list(self._open_order)
+            if self._nodes[cid].workflow_path == workflow_path
+            or self._nodes[cid].workflow_path.startswith(workflow_path + ">")
+        ]
+        for container_id in to_close:
+            self.close(container_id, status)
+
+    def rank_container(self, container_id: str) -> tuple[int, int, int, int]:
+        node = self._nodes[container_id]
+        try:
+            open_index = self._open_order.index(container_id)
+        except ValueError:
+            open_index = -1
+        scope_priority = _SCOPE_PRIORITY.get(node.scope, 0)
+        return (
+            node.workflow_depth,
+            scope_priority,
+            len(node.workflow_path),
+            open_index,
+        )
+
+
+class WorkflowContainerStateMachine:
+    """事件 → 容器状态机（参考实现）。"""
+
+    def __init__(self) -> None:
+        self._active = WorkflowContainerActiveSet()
+        self._root_ids: list[str] = []
+
+    @property
+    def active_set(self) -> WorkflowContainerActiveSet:
+        return self._active
+
+    def apply(self, event: LangchainAgentEvent) -> ContainerAction | None:
+        event_type = event.event_type
+        data = event.data if isinstance(event.data, dict) else {}
+
+        if event_type in _OPEN_EVENT_TYPES:
+            self._open_container(event_type, data)
+            return ContainerAction.OPEN
+
+        if event_type in _CLOSE_EVENT_TYPES:
+            self._close_container(event_type, data)
+            return ContainerAction.CLOSE
+
+        if event_type in _CONTENT_EVENT_TYPES:
+            self._append_content(event)
+            return ContainerAction.APPEND_CONTENT
+
+        return None
+
+    def snapshot(self) -> WorkflowContainerTreeSnapshot:
+        return WorkflowContainerTreeSnapshot(
+            root_container_ids=list(self._root_ids),
+            containers=dict(self._active._nodes),
+            active_container_ids=self._active.active_ids,
+        )
+
+    def _open_container(
+        self,
+        event_type: LangchainAgentEventType,
+        data: dict[str, Any],
+    ) -> None:
+        scope = _EVENT_TYPE_TO_SCOPE[event_type]
+        workflow_path = str(data.get("workflow_path", ""))
+        workflow_depth = int(data.get("workflow_depth", 0))
+        scope_key = resolve_scope_key(event_type, data)
+        container_id = build_container_id(workflow_path, scope, scope_key)
+
+        display = data.get("display") if isinstance(data.get("display"), dict) else {}
+        title = str(display.get("title") or scope_key)
+        subtitle = str(display.get("description") or "")
+        pattern = str(display.get("pattern") or "")
+        status = _display_status(data, "running")
+
+        parent_id = self._resolve_parent_id(workflow_path, scope)
+        node = WorkflowContainerNode(
+            container_id=container_id,
+            scope=scope,
+            workflow_path=workflow_path,
+            workflow_depth=workflow_depth,
+            scope_key=scope_key,
+            title=title,
+            subtitle=subtitle,
+            status=status,
+            pattern=pattern,
+            parent_container_id=parent_id,
+            is_open=True,
+        )
+        self._active.open(node)
+        if scope == "workflow" and container_id not in self._root_ids:
+            self._root_ids.append(container_id)
+
+    def _close_container(
+        self,
+        event_type: LangchainAgentEventType,
+        data: dict[str, Any],
+    ) -> None:
+        scope = _EVENT_TYPE_TO_SCOPE[event_type]
+        workflow_path = str(data.get("workflow_path", ""))
+        scope_key = resolve_scope_key(event_type, data)
+        container_id = build_container_id(workflow_path, scope, scope_key)
+        status = _display_status(data, _close_status(event_type))
+        self._active.close(container_id, status)
+        if scope == "workflow":
+            self._active.close_descendants_of_path(workflow_path, status)
+
+    def _append_content(self, event: LangchainAgentEvent) -> None:
+        data = event.data if isinstance(event.data, dict) else {}
+        workflow_path = data.get("workflow_path")
+        path = workflow_path if isinstance(workflow_path, str) else None
+
+        scope_key = None
+        for key_name in ("stage_key", "item_key", "branch_key", "debug_key"):
+            value = data.get(key_name)
+            if isinstance(value, str) and value:
+                scope_key = value
+                break
+        if scope_key is None:
+            display = data.get("display")
+            if isinstance(display, dict):
+                debug_key = display.get("debug_key")
+                if isinstance(debug_key, str) and debug_key:
+                    scope_key = debug_key
+
+        target_id = self._active.resolve_content_target(
+            workflow_path=path,
+            scope_key=scope_key,
+        )
+        if target_id is None:
+            return
+
+        block = self._content_block_from_event(event)
+        if block is None:
+            return
+        self._active._nodes[target_id].content_blocks.append(block)
+
+    def _resolve_parent_id(
+        self,
+        workflow_path: str,
+        scope: WorkflowContainerScope,
+    ) -> str | None:
+        if scope == "workflow":
+            return None
+
+        open_nodes = [
+            node
+            for cid in self._active._open_order
+            if (node := self._active._nodes[cid]).is_open
+        ]
+        if not open_nodes:
+            return None
+
+        prefix_candidates = [
+            node
+            for node in open_nodes
+            if workflow_path == node.workflow_path
+            or workflow_path.startswith(node.workflow_path + ">")
+        ]
+        if prefix_candidates:
+            parent = max(prefix_candidates, key=lambda n: self._active.rank_container(n.container_id))
+            if parent.workflow_path == workflow_path and parent.scope == "workflow":
+                return parent.container_id
+            if workflow_path.startswith(parent.workflow_path + ">"):
+                return parent.container_id
+            if parent.workflow_path == workflow_path and parent.scope != scope:
+                return parent.container_id
+
+        workflow_candidates = [
+            node for node in open_nodes if node.scope == "workflow"
+        ]
+        if workflow_candidates:
+            return max(
+                workflow_candidates,
+                key=lambda n: self._active.rank_container(n.container_id),
+            ).container_id
+
+        return max(
+            open_nodes,
+            key=lambda n: self._active.rank_container(n.container_id),
+        ).container_id
+
+    @staticmethod
+    def _content_block_from_event(event: LangchainAgentEvent) -> WorkflowContentBlock | None:
+        event_type = event.event_type
+        data = event.data if isinstance(event.data, dict) else {}
+
+        if event_type in (
+            LangchainAgentEventType.REASONING_START,
+            LangchainAgentEventType.REASONING_DELTA,
+            LangchainAgentEventType.REASONING_END,
+        ):
+            preview = str(data.get("delta") or data.get("text") or data.get("reasoning") or "")
+            if not preview and event_type == LangchainAgentEventType.REASONING_START:
+                preview = "Thinking…"
+            return WorkflowContentBlock(kind="reasoning", preview=preview)
+
+        if event_type in (
+            LangchainAgentEventType.TEXT_START,
+            LangchainAgentEventType.TEXT_DELTA,
+            LangchainAgentEventType.TEXT_END,
+        ):
+            preview = str(data.get("delta") or data.get("text") or "")
+            return WorkflowContentBlock(kind="text", preview=preview)
+
+        if event_type in _CONTENT_EVENT_TYPES:
+            tool_name = event.tool_name or data.get("tool_name")
+            preview = str(
+                data.get("summary")
+                or data.get("output")
+                or data.get("input")
+                or data.get("delta")
+                or tool_name
+                or event_type.value
+            )
+            return WorkflowContentBlock(
+                kind="tool",
+                preview=preview,
+                tool_name=str(tool_name) if tool_name else None,
+            )
+
+        return None
+
+
+class WorkflowContainerTreeProjector:
+    """LangchainAgentEvent 流 → 容器树快照。"""
+
+    def __init__(self) -> None:
+        self._machine = WorkflowContainerStateMachine()
+
+    def consume(self, event: LangchainAgentEvent) -> ContainerAction | None:
+        return self._machine.apply(event)
+
+    def consume_all(self, events: list[LangchainAgentEvent]) -> WorkflowContainerTreeSnapshot:
+        for event in events:
+            self.consume(event)
+        return self.snapshot()
+
+    def snapshot(self) -> WorkflowContainerTreeSnapshot:
+        return self._machine.snapshot()
+
+
+def render_cli_tree(snapshot: WorkflowContainerTreeSnapshot) -> str:
+    """渲染接近设计文档示意的 CLI 树文本（fixture 对照用）。"""
+    lines: list[str] = []
+
+    def walk(container_id: str, indent: int) -> None:
+        node = snapshot.containers[container_id]
+        prefix = "  " * indent
+        status_label = node.status.capitalize()
+        header = f"{prefix}● {node.title} · {status_label}"
+        if node.pattern:
+            header += f" · {node.pattern}"
+        lines.append(header)
+
+        meta_parts: list[str] = []
+        if node.scope_key:
+            meta_parts.append(node.scope_key)
+        display_progress = node.subtitle
+        if meta_parts:
+            lines.append(f"{prefix}  {' · '.join(meta_parts)}")
+        if display_progress:
+            lines.append(f"{prefix}  {display_progress}")
+
+        for block in node.content_blocks:
+            if block.kind == "reasoning":
+                lines.append(f"{prefix}  ∴ {block.preview or 'Thinking…'}")
+            elif block.kind == "text":
+                lines.append(f"{prefix}  ⎿ {block.preview}")
+            else:
+                tool = block.tool_name or "tool"
+                lines.append(f"{prefix}  ⎿ [{tool}] {block.preview}")
+
+        child_ids = [
+            cid
+            for cid, child in snapshot.containers.items()
+            if child.parent_container_id == container_id
+        ]
+        child_ids.sort(key=lambda cid: snapshot.containers[cid].container_id)
+        for child_id in child_ids:
+            walk(child_id, indent + 1)
+
+    for root_id in snapshot.root_container_ids:
+        walk(root_id, 0)
+
+    return "\n".join(lines)
+
+
+def snapshot_to_dict(snapshot: WorkflowContainerTreeSnapshot) -> dict[str, Any]:
+    """序列化快照为 JSON fixture 友好结构。"""
+    return {
+        "root_container_ids": snapshot.root_container_ids,
+        "active_container_ids": snapshot.active_container_ids,
+        "containers": {
+            cid: {
+                "container_id": node.container_id,
+                "scope": node.scope,
+                "workflow_path": node.workflow_path,
+                "workflow_depth": node.workflow_depth,
+                "scope_key": node.scope_key,
+                "title": node.title,
+                "subtitle": node.subtitle,
+                "status": node.status,
+                "pattern": node.pattern,
+                "parent_container_id": node.parent_container_id,
+                "is_open": node.is_open,
+                "content_blocks": [
+                    {
+                        "kind": block.kind,
+                        "preview": block.preview,
+                        "tool_name": block.tool_name,
+                    }
+                    for block in node.content_blocks
+                ],
+            }
+            for cid, node in snapshot.containers.items()
+        },
+    }
+
+
+__all__ = [
+    "ContainerAction",
+    "WorkflowContainerScope",
+    "WorkflowContainerStatus",
+    "WorkflowContentBlock",
+    "WorkflowContainerNode",
+    "WorkflowContainerTreeSnapshot",
+    "WorkflowContainerActiveSet",
+    "WorkflowContainerStateMachine",
+    "WorkflowContainerTreeProjector",
+    "build_container_id",
+    "resolve_scope_key",
+    "render_cli_tree",
+    "snapshot_to_dict",
+]