langchain-agentx-python 1.0.0__tar.gz → 1.0.2__tar.gz

{langchain-agentx-python-1.0.0 → langchain-agentx-python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 1.0.0
+Version: 1.0.2
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License
@@ -245,6 +245,34 @@ agent = create_loop_agent(...)
 
 具体的能力和使用方式可以参考源码中的 docstring 以及各模块下的 `README.md`。
 
+## 工具进度显示
+
+长耗时工具（如 `BashRuntimeTool`）可在执行期间通过 `ToolExecutionContext.emit_progress()` 向 CLI 实时报告进度。事件经 LangGraph `dispatch_custom_event("tool_progress", ...)` 发出，CLI 通过 `astream_events` 接收。
+
+```python
+# 工具 invoke 内（同步路径）
+ctx.emit_progress(
+    phase="running",
+    data={"output": chunk, "total_lines": line_count, "elapsed_time_seconds": elapsed},
+)
+
+# 异步工具
+await ctx.aemit_progress(phase="query_update", data={"query": query})
+```
+
+**向后兼容**：进度为可选能力。未发射 progress 或 CLI 未监听时，工具仍按 `ToolResultEnvelope` 正常返回。`emit_progress` 在无 LangGraph 上下文时静默失败，不中断工具主流程。
+
+**文档**：
+- 设计：[`docs/design-docs/tool-runtime/tool-progress-design.html`](docs/design-docs/tool-runtime/tool-progress-design.html)
+- 事件契约：[`docs/design-docs/tool-runtime/tool-progress-event-contract.html`](docs/design-docs/tool-runtime/tool-progress-event-contract.html)
+- 工具作者门禁：[`docs/guides/tool-implementation-checklist.html#section-4-2`](docs/guides/tool-implementation-checklist.html#section-4-2)
+
+**测试**：
+
+```bash
+pytest tests/regression/tool_progress/ tests/tool_runtime/progress/ langchain_agentx/tool_runtime/test_emit_progress.py -v
+```
+
 ## 发布新版本流程
 
 > **重要特性**：本项目的构建脚本会**自动排除所有测试文件**，生成纯净的生产包。当前有 140+ 个测试文件在构建时会被自动过滤，确保发布的包轻量、干净。

{langchain-agentx-python-1.0.0 → langchain-agentx-python-1.0.2}/README.md

@@ -25,6 +25,34 @@ agent = create_loop_agent(...)
 
 具体的能力和使用方式可以参考源码中的 docstring 以及各模块下的 `README.md`。
 
+## 工具进度显示
+
+长耗时工具（如 `BashRuntimeTool`）可在执行期间通过 `ToolExecutionContext.emit_progress()` 向 CLI 实时报告进度。事件经 LangGraph `dispatch_custom_event("tool_progress", ...)` 发出，CLI 通过 `astream_events` 接收。
+
+```python
+# 工具 invoke 内（同步路径）
+ctx.emit_progress(
+    phase="running",
+    data={"output": chunk, "total_lines": line_count, "elapsed_time_seconds": elapsed},
+)
+
+# 异步工具
+await ctx.aemit_progress(phase="query_update", data={"query": query})
+```
+
+**向后兼容**：进度为可选能力。未发射 progress 或 CLI 未监听时，工具仍按 `ToolResultEnvelope` 正常返回。`emit_progress` 在无 LangGraph 上下文时静默失败，不中断工具主流程。
+
+**文档**：
+- 设计：[`docs/design-docs/tool-runtime/tool-progress-design.html`](docs/design-docs/tool-runtime/tool-progress-design.html)
+- 事件契约：[`docs/design-docs/tool-runtime/tool-progress-event-contract.html`](docs/design-docs/tool-runtime/tool-progress-event-contract.html)
+- 工具作者门禁：[`docs/guides/tool-implementation-checklist.html#section-4-2`](docs/guides/tool-implementation-checklist.html#section-4-2)
+
+**测试**：
+
+```bash
+pytest tests/regression/tool_progress/ tests/tool_runtime/progress/ langchain_agentx/tool_runtime/test_emit_progress.py -v
+```
+
 ## 发布新版本流程
 
 > **重要特性**：本项目的构建脚本会**自动排除所有测试文件**，生成纯净的生产包。当前有 140+ 个测试文件在构建时会被自动过滤，确保发布的包轻量、干净。

{langchain-agentx-python-1.0.0 → langchain-agentx-python-1.0.2}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.0.0 → langchain-agentx-python-1.0.2}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -1391,10 +1391,7 @@ class LangGraphToLangchainAgentEventAdapter:
             )
             return
 
-        if not self.enable_subagent_events:
-            return
-
-        # 处理主 agent 的工具进度事件（Bash、WebSearch 等）
+        # 主 agent 工具进度（Bash、WebSearch 等）— 不受 enable_subagent_events 影响
         if event_name == "tool_progress":
             data = event.get("data", {})
             if not isinstance(data, dict):
@@ -1414,6 +1411,9 @@ class LangGraphToLangchainAgentEventAdapter:
             )
             return
 
+        if not self.enable_subagent_events:
+            return
+
         # 处理子 agent 事件（兼容旧的 subagent_progress）
         if event_name != "subagent_progress":
             return

{langchain-agentx-python-1.0.0 → langchain-agentx-python-1.0.2}/langchain_agentx/tool_runtime/models.py

@@ -170,21 +170,27 @@ class ToolExecutionContext:
             - 不抛异常，避免污染工具主流程
 
         注意：
-            不需要传递 config 参数，LangGraph 会自动从 contextvar 获取回调链上下文。
+            优先使用 ``ctx.runnable_config`` 派发（RuntimeToolsNode 整链）；
+            否则依赖 LangGraph contextvar 回调链。
         """
         from langchain_core.callbacks import dispatch_custom_event
 
+        payload = {
+            "tool_name": self.tool_name,
+            "tool_call_id": self.tool_call_id,
+            "agent_id": self.agent_id,
+            "phase": phase,
+            "data": data,
+        }
         try:
-            dispatch_custom_event(
-                "tool_progress",
-                {
-                    "tool_name": self.tool_name,
-                    "tool_call_id": self.tool_call_id,
-                    "agent_id": self.agent_id,
-                    "phase": phase,
-                    "data": data,
-                },
-            )
+            if self.runnable_config is not None:
+                dispatch_custom_event(
+                    "tool_progress",
+                    payload,
+                    config=self.runnable_config,
+                )
+            else:
+                dispatch_custom_event("tool_progress", payload)
         except RuntimeError:
             # 无 parent run ID（非 LangGraph 上下文或测试场景）时静默返回
             pass
@@ -209,17 +215,22 @@ class ToolExecutionContext:
         """
         from langchain_core.callbacks import adispatch_custom_event
 
+        payload = {
+            "tool_name": self.tool_name,
+            "tool_call_id": self.tool_call_id,
+            "agent_id": self.agent_id,
+            "phase": phase,
+            "data": data,
+        }
         try:
-            await adispatch_custom_event(
-                "tool_progress",
-                {
-                    "tool_name": self.tool_name,
-                    "tool_call_id": self.tool_call_id,
-                    "agent_id": self.agent_id,
-                    "phase": phase,
-                    "data": data,
-                },
-            )
+            if self.runnable_config is not None:
+                await adispatch_custom_event(
+                    "tool_progress",
+                    payload,
+                    config=self.runnable_config,
+                )
+            else:
+                await adispatch_custom_event("tool_progress", payload)
         except RuntimeError:
             pass
         except Exception:

langchain-agentx-python-1.0.2/langchain_agentx/tool_runtime/progress/__init__.py

@@ -0,0 +1,31 @@
+"""progress/__init__.py — 工具进度模块
+
+职责：
+    导出进度事件和采样器的公共 API，供工具和测试使用。
+
+链路位置：
+    langchain_agentx.tool_runtime.progress → SDK/CLI
+
+当前裁剪范围：
+    导出 ToolProgressEvent, SamplingStrategy, SamplingConfig, ProgressSampler
+"""
+
+from langchain_agentx.tool_runtime.progress.event import (
+    ToolProgressEvent,
+    create_tool_progress_event,
+)
+from langchain_agentx.tool_runtime.progress.sampler import (
+    SamplingStrategy,
+    SamplingConfig,
+    ProgressSampler,
+)
+
+__all__ = [
+    # Event
+    "ToolProgressEvent",
+    "create_tool_progress_event",
+    # Sampler
+    "SamplingStrategy",
+    "SamplingConfig",
+    "ProgressSampler",
+]

langchain-agentx-python-1.0.2/langchain_agentx/tool_runtime/progress/event.py

@@ -0,0 +1,96 @@
+"""event.py — 工具进度事件数据模型
+
+职责：
+    定义工具进度事件（tool_progress）的数据结构，用于工具向 CLI 报告执行进度。
+
+链路位置：
+    RuntimeTool → dispatch_custom_event → astream_events → CLI
+
+当前裁剪范围：
+    - 仅支持当前/总数类型的进度（行数、字节数等）
+    - 不支持百分比类型的进度
+    - 暂不支持多阶段进度（如"下载中/编译中"）
+
+对应 CC 源码：
+    - src/types/tools.ts — BashProgress 类型定义
+    - src/components/shell/ShellProgressMessage.tsx — 进度格式化
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, TypedDict, Any
+
+
+class ToolProgressEvent(TypedDict):
+    """工具进度事件数据模型。
+
+    工具执行期间通过 dispatch_custom_event 发送此事件，
+    CLI 通过 astream_events 接收并渲染进度信息。
+
+    Attributes:
+        event_type: 固定为 "tool_progress"
+        tool_name: 工具名称（如 "bash"）
+        tool_use_id: 工具调用 ID
+        current: 当前进度值（如已执行行数）
+        total: 总值（如总行数），未知时为 None
+        unit: 进度单位（如 "lines"、"bytes"），未知时为 None
+        elapsed_seconds: 已耗时（秒）
+        message: 进度消息（如执行的命令），可为 None
+        timestamp: 事件时间戳
+    """
+
+    event_type: Literal["tool_progress"]
+    tool_name: str
+    tool_use_id: str
+    current: int
+    total: int | None
+    unit: str | None
+    elapsed_seconds: float
+    message: str | None
+    timestamp: str  # ISO 8601 格式
+
+
+def create_tool_progress_event(
+    *,
+    tool_name: str,
+    tool_use_id: str,
+    current: int,
+    total: int | None = None,
+    unit: str | None = None,
+    elapsed_seconds: float = 0.0,
+    message: str | None = None,
+) -> ToolProgressEvent:
+    """创建工具进度事件的工厂函数。
+
+    Args:
+        tool_name: 工具名称
+        tool_use_id: 工具调用 ID
+        current: 当前进度值
+        total: 总值（可选）
+        unit: 进度单位（可选）
+        elapsed_seconds: 已耗时（秒）
+        message: 进度消息（可选）
+
+    Returns:
+        ToolProgressEvent: 进度事件对象
+    """
+    from datetime import datetime
+
+    return ToolProgressEvent(
+        event_type="tool_progress",
+        tool_name=tool_name,
+        tool_use_id=tool_use_id,
+        current=current,
+        total=total,
+        unit=unit,
+        elapsed_seconds=elapsed_seconds,
+        message=message,
+        timestamp=datetime.utcnow().isoformat(),
+    )
+
+
+__all__ = [
+    "ToolProgressEvent",
+    "create_tool_progress_event",
+]

langchain-agentx-python-1.0.2/langchain_agentx/tool_runtime/progress/sampler.py

@@ -0,0 +1,184 @@
+"""sampler.py — 进度采样器
+
+职责：
+    封装进度采样逻辑，提供定时/定量采样策略，避免工具直接处理采样判断。
+
+链路位置：
+    RuntimeTool → ProgressSampler → dispatch_custom_event
+
+当前裁剪范围：
+    - 支持定时采样（基于时间间隔）
+    - 支持定量采样（基于进度增量）
+    - 不支持自适应采样（根据输出速度动态调整）
+
+对应 CC 源码：
+    - src/utils/task/TaskOutput.ts — #tick() 轮询器（1秒间隔）
+    - src/utils/task/TaskOutput.ts — PROGRESS_TAIL_BYTES (4096) 样本大小
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+
+class SamplingStrategy(Enum):
+    """采样策略类型。"""
+
+    TIMER = "timer"  # 定时采样：每隔 N 秒采样一次
+    COUNT = "count"  # 定量采样：每增加 N 采样一次
+    SIGNAL = "signal"  # 信号驱动：由外部信号触发采样
+
+
+@dataclass
+class SamplingConfig:
+    """采样配置。
+
+    Attributes:
+        strategy: 采样策略类型
+        interval_seconds: 定时采样间隔（秒），默认 1.0（对齐 CC）
+        min_interval_seconds: 最小采样间隔（秒），默认 0.1
+        count_delta: 定量采样增量，默认 100（行/字节）
+    """
+
+    strategy: Literal["timer", "count", "signal"] = "timer"
+    interval_seconds: float = 1.0
+    min_interval_seconds: float = 0.1
+    count_delta: int = 100
+
+
+class ProgressSampler:
+    """进度采样器。
+
+    提供进度采样功能，支持定时/定量/信号驱动策略。
+    工具通过此采样器判断是否应该报告进度。
+
+    使用示例：
+        ```python
+        sampler = ProgressSampler(
+            config=SamplingConfig(strategy="timer", interval_seconds=1.0)
+        )
+        sampler.start()
+
+        # 在工具执行循环中
+        for i, line in enumerate(output):
+            if sampler.should_sample():
+                dispatch_progress(current=i, total=total)
+
+        sampler.elapsed_seconds()  # 获取已耗时
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        config: SamplingConfig | None = None,
+    ) -> None:
+        """初始化采样器。
+
+        Args:
+            config: 采样配置，默认使用定时策略（1秒间隔）
+        """
+        self._config = config or SamplingConfig()
+        self._start_time = time.perf_counter()
+        self._last_sample_time = 0.0
+        self._last_sample_value = 0
+        self._current_value = 0
+        self._total_value: int | None = None
+
+    def start(self) -> None:
+        """启动采样器（重置计时器）。
+
+        在工具开始执行时调用。
+        """
+        self._start_time = time.perf_counter()
+        self._last_sample_time = 0.0
+        self._last_sample_value = 0
+        self._current_value = 0
+        self._total_value = None
+
+    def update(self, current: int, total: int | None = None) -> None:
+        """更新当前进度值。
+
+        Args:
+            current: 当前进度值（如已执行行数）
+            total: 总值（如总行数），仅首次设置有效
+        """
+        self._current_value = current
+        if self._total_value is None and total is not None:
+            self._total_value = total
+
+    def should_sample(self) -> bool:
+        """判断是否应该采样（报告进度）。
+
+        根据配置的策略判断：
+        - timer: 距离上次采样是否超过 interval_seconds
+        - count: 距离上次采样是否超过 count_delta
+        - signal: 总是返回 True（由外部控制）
+
+        Returns:
+            bool: 是否应该采样
+        """
+        strategy = self._config.strategy
+        elapsed = time.perf_counter() - self._start_time
+
+        if strategy == "signal":
+            return True
+
+        if strategy == "timer":
+            if elapsed - self._last_sample_time >= self._config.interval_seconds:
+                self._last_sample_time = elapsed
+                return True
+            return False
+
+        if strategy == "count":
+            delta = self._current_value - self._last_sample_value
+            if delta >= self._config.count_delta:
+                self._last_sample_value = self._current_value
+                return True
+            return False
+
+        return False
+
+    def elapsed_seconds(self) -> float:
+        """获取已耗时（秒）。
+
+        Returns:
+            float: 从 start() 调用到现在的耗时
+        """
+        return time.perf_counter() - self._start_time
+
+    def current(self) -> int:
+        """获取当前进度值。
+
+        Returns:
+            int: 当前进度值
+        """
+        return self._current_value
+
+    def total(self) -> int | None:
+        """获取总值。
+
+        Returns:
+            int | None: 总值，如果未知则为 None
+        """
+        return self._total_value
+
+    def progress_fraction(self) -> float | None:
+        """获取进度比例（0.0 - 1.0）。
+
+        Returns:
+            float | None: 进度比例，如果总值未知则为 None
+        """
+        if self._total_value is None or self._total_value == 0:
+            return None
+        return min(1.0, self._current_value / self._total_value)
+
+
+__all__ = [
+    "SamplingStrategy",
+    "SamplingConfig",
+    "ProgressSampler",
+]