langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tool_runtime/base.py

@@ -0,0 +1,319 @@
+"""
+runtime/base.py — RuntimeTool 抽象基类
+
+职责：
+    定义框架内部工具的核心 OOP 契约。每个工具继承 RuntimeTool，
+    只需实现 invoke()，其余生命周期 hook 均有 fail-open 默认实现。
+    框架通过 ToolExecutorPipeline 统一编排这些 hook，工具无需自行
+    实现完整控制流。
+
+与 CC 对比：
+    CC 中 Tool<Input, Output> 是 TypeScript interface，通过 buildTool(def)
+    工厂函数注入默认实现（TOOL_DEFAULTS），checkPermissions 默认 allow，
+    validateInput 默认 success。
+    本框架用 Python ABC 实现等价模式：hook 方法有 fail-open 默认实现，
+    子类只覆盖关心的部分。is_read_only / is_destructive / is_concurrency_safe
+    对应 CC Tool 的同名 flag。never_truncate 对应 CC maxResultSizeChars=Infinity。
+
+一个工具的完整流转（OOP 视角）：
+
+    ┌─────────────────────────────────────────────────────────────────┐
+    │                      RuntimeToolRegistry                        │
+    │  register(tool) ──► LangChainAdapter.build_structured_tool()   │
+    │                              │                                  │
+    │                              ▼                                  │
+    │                       StructuredTool  ◄── model.bind_tools()   │
+    └─────────────────────────────────────────────────────────────────┘
+                                   │
+                    AIMessage.tool_calls[i]
+                                   │
+                                   ▼
+    ┌─────────────────────────────────────────────────────────────────┐
+    │                          ToolNode                               │
+    │         StructuredTool.func(state, config, **kwargs)            │
+    └─────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌─────────────────────────────────────────────────────────────────┐
+    │                     LangChainAdapter                            │
+    │  build_tool_execution_context(tool_name, raw_input,             │
+    │                               state, config)                    │
+    │                      → ToolExecutionContext                     │
+    └─────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌─────────────────────────────────────────────────────────────────┐
+    │                   ToolExecutorPipeline.run()                    │
+    │                                                                 │
+    │  [Hook 1] tool.normalize_input(raw, ctx)                        │
+    │       │   路径规范化、默认值填充                                  │
+    │       ▼                                                         │
+    │  [Step 2] input_model.model_validate(normalized)                │
+    │       │   Pydantic schema 解析，失败 → error envelope           │
+    │       ▼                                                         │
+    │  [Hook 3] tool.validate_input(data, ctx)                        │
+    │       │   语义校验（文件存在？是否目录？）                         │
+    │       │   失败 → error envelope（模型可修正重试）                 │
+    │       ▼                                                         │
+    │  [Hook 4] tool.check_permissions(data, ctx)                     │
+    │       │   权限控制（路径越界？策略拒绝？）                         │
+    │       │   失败 → blocked envelope（不可绕过）                    │
+    │       ▼                                                         │
+    │  [Hook 5] tool.before_invoke(data, ctx)                         │
+    │       │   执行前钩子（日志、预热等）                               │
+    │       ▼                                                         │
+    │  [Core ] tool.invoke(data, ctx)  /  tool.ainvoke(data, ctx)     │
+    │       │   核心业务执行，异常 → exception_to_envelope()           │
+    │       ▼                                                         │
+    │  [Hook 7] tool.after_invoke(data, result, ctx)                  │
+    │       │   状态写入（last_read_map）、审计记录                     │
+    │       ▼                                                         │
+    │  [Step 8] state_bridge.update(ctx, result)                      │
+    │       ▼                                                         │
+    │  [Hook 9] tool.present(data, result, ctx)                       │
+    │       │   → ToolResultEnvelope                                  │
+    │       ▼                                                         │
+    │  [Step10] output_manager.truncate_if_needed(envelope)           │
+    │       │   超大输出 → 写文件 + 更新 summary + overflow_file       │
+    │       ▼                                                         │
+    │                    ToolResultEnvelope                           │
+    └─────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌─────────────────────────────────────────────────────────────────┐
+    │                     LangChainAdapter                            │
+    │  envelope_to_tool_output(envelope) → str                        │
+    │  ok:      summary + payload + hints                             │
+    │  blocked: "Permission denied: ..."                              │
+    │  error:   "Error: ..."                                          │
+    └─────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                    ToolMessage(content=str, tool_call_id=...)
+                                   │
+                                   ▼
+                         agent loop / loop_controller
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolHint,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+
+
+class RuntimeTool(ABC):
+    """
+    工具运行时抽象基类。
+
+    硬约定（Hook 输入契约）：
+        RuntimeTool 的所有生命周期 hook 都必须使用 ``dict[str, Any]`` 作为
+        ``data`` 形态，禁止依赖属性访问（如 ``data.command``）。
+        这是与 ToolExecutorPipeline 的固定契约：schema 解析后统一下发 dict。
+
+    子类必须定义：
+        name          — 工具名（唯一，面向模型暴露）
+        description   — 工具描述（面向模型暴露）
+        input_model   — Pydantic BaseModel，直接作为 StructuredTool.args_schema
+
+    子类可覆盖的生命周期 hook（默认均为 fail-open / no-op）：
+        normalize_input     — 输入预处理（路径规范化、默认值填充）
+        validate_input      — 语义校验（失败告知模型，可重试）
+        check_permissions   — 权限控制（失败策略拒绝，不可绕过）
+        before_invoke       — 执行前钩子
+        after_invoke        — 执行后钩子（状态写入、审计）
+        present             — 结果呈现（构造 ToolResultEnvelope）
+
+    子类必须实现：
+        invoke              — 核心业务执行（同步）
+
+    子类可选覆盖：
+        ainvoke             — 核心业务执行（异步），默认委托 executor 运行 invoke
+    """
+
+    # ---- 子类必须定义的类属性 ----
+    name: str
+    description: str
+
+    # input_model 必须是 pydantic BaseModel 子类
+    # 直接作为 StructuredTool.args_schema 暴露给模型
+    input_model: type
+
+    output_model: type | None = None
+
+    # ---- 行为标志（对应 CC Tool 的同名 flag）----
+    is_read_only: bool = False
+    """只读工具，不修改文件系统。"""
+
+    is_destructive: bool = False
+    """高风险写操作（write / edit / bash 等）。"""
+
+    is_concurrency_safe: bool = False
+    """是否支持并发执行。"""
+
+    never_truncate: bool = False
+    """
+    禁止 ToolOutputManager 截断输出。
+    对应 CC maxResultSizeChars=Infinity。
+    适用于自带分页机制的工具（如 ReadRuntimeTool 用 limit 参数控制）。
+    """
+
+    dedupe_identical_calls: bool = False
+    """
+    为 True 时，``ToolExecutorPipeline`` 在同 ``thread_id`` 下对「工具名 + 解析后参数字典」
+    命中缓存则直接返回上一次成功的 ``ToolResultEnvelope``（带 Hint），不再次 ``invoke``。
+    仅适用于只读、无副作用重复的安全工具；写/破坏性工具须保持 False。
+    """
+
+    max_result_size_chars: int = 20_000
+    """
+    单次输出字符上限，超出时由 ToolOutputManager 截断并持久化。
+    对应 CC Tool.maxResultSizeChars。
+    """
+
+    def __init__(
+        self,
+        *,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+    ) -> None:
+        self._policy = policy
+        self._state_bridge = state_bridge
+
+    # ---- 生命周期 Hook（默认 fail-open / no-op，子类按需覆盖）----
+
+    def normalize_input(
+        self,
+        raw: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> dict[str, Any]:
+        """
+        输入预处理：路径规范化、默认值填充、参数 clamp 等。
+        默认原样返回，子类覆盖时应返回修改后的新 dict。
+        """
+        return raw
+
+    def validate_input(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ValidationResult:
+        """
+        语义校验：参数格式、文件是否存在、是否为目录等。
+
+        失败时 pipeline 生成 status="error" 的 envelope，
+        模型收到 message 后可修正输入重试。
+
+        默认 ok=True（fail-open，对应 CC buildTool TOOL_DEFAULTS）。
+        注意：这里的 data 恒为 dict，工具实现不得使用 data.xxx 属性访问。
+        """
+        return ValidationResult(ok=True)
+
+    def check_permissions(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        """
+        权限控制：路径越界、策略拒绝等授权检查。
+
+        失败时 pipeline 生成 status="blocked" 的 envelope，
+        模型知晓被拒但不获得路径细节（策略不透明原则）。
+
+        默认实现：委托注入的 PolicyEngine。
+        - 注入了 policy → 自动受 policy 保护（所有工具无需覆盖此方法即可生效）
+        - 未注入 policy → 默认 allow（开发模式，fail-open）
+        工具有特殊需求（如 BashRuntimeTool 的命令级检查）可覆盖此方法，
+        在工具级检查后调用 super().check_permissions(data, ctx) 走通用 policy。
+        """
+        if self._policy is not None:
+            return self._policy.authorize(
+                tool_name=self.name,
+                input_data=data,
+                ctx=ctx,
+            )
+        return AuthorizationDecision(behavior="allow")
+
+    def before_invoke(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> None:
+        """执行前钩子（日志、预热等），默认 no-op。"""
+
+    @abstractmethod
+    def invoke(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> Any:
+        """
+        核心业务执行（同步）。子类必须实现。
+
+        返回值将传入 after_invoke 和 present，类型由子类定义。
+        抛出的异常由 pipeline 统一捕获并映射为 error envelope。
+        """
+        ...
+
+    async def ainvoke(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> Any:
+        """
+        核心业务执行（异步）。
+
+        默认在 executor 中运行同步 invoke，保持 sync/async 对称。
+        有真正异步 I/O 需求的工具（如 HTTP 请求）可覆盖此方法。
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, lambda: self.invoke(data, ctx))
+
+    def after_invoke(
+        self,
+        data: dict[str, Any],
+        result: Any,
+        ctx: ToolExecutionContext,
+    ) -> None:
+        """
+        执行后钩子：状态写入（last_read_map）、审计记录等。
+        默认 no-op，ReadRuntimeTool 等工具在此更新 StateBridge。
+        """
+
+    def present(
+        self,
+        data: dict[str, Any],
+        result: Any,
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        """
+        将内部执行结果映射为 ToolResultEnvelope。
+
+        子类应覆盖此方法，提供语义化的 summary / payload / hints。
+        默认实现将 result 转为 str 作为 summary，适合快速原型。
+        """
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=str(result),
+            payload={"raw": str(result)},
+        )
+
+    def __repr__(self) -> str:
+        flags = []
+        if self.is_read_only:
+            flags.append("read_only")
+        if self.is_destructive:
+            flags.append("destructive")
+        if self.never_truncate:
+            flags.append("never_truncate")
+        flag_str = f"[{', '.join(flags)}]" if flags else ""
+        return f"<{type(self).__name__} name={self.name!r} {flag_str}>".strip()

langchain_agentx/tool_runtime/errors.py

@@ -0,0 +1,190 @@
+"""
+runtime/errors.py — 工具运行时错误类型与 envelope 映射
+
+职责：
+    定义框架级运行时异常类型，并提供统一的异常 → ToolResultEnvelope 映射函数。
+    所有工具执行过程中未被捕获的异常，均通过 exception_to_envelope() 转换为
+    status="error" 的 envelope，确保 pipeline 始终返回结构化结果。
+
+与 CC 对比：
+    CC 中工具执行异常直接在 ToolNode 层被捕获并转为 ToolMessage(content=error_str)。
+    本框架将异常映射提前到 pipeline 内部，保持 envelope 协议的完整性，
+    同时将 traceback 隔离在 meta 中，不暴露给模型。
+"""
+
+from __future__ import annotations
+
+import traceback as tb
+
+from .models import ToolErrorInfo, ToolResultEnvelope
+
+
+# ---------------------------------------------------------------------------
+# 框架级异常类型
+# ---------------------------------------------------------------------------
+
+class ToolRuntimeError(Exception):
+    """工具运行时框架基础异常。"""
+
+    def __init__(self, message: str, code: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+
+
+class ToolRegistrationError(ToolRuntimeError):
+    """工具注册失败，通常因为工具名重复。"""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(
+            f"Tool '{tool_name}' is already registered. Tool names must be unique.",
+            code="TOOL_ALREADY_REGISTERED",
+        )
+        self.tool_name = tool_name
+
+
+class ToolNotFoundError(ToolRuntimeError):
+    """工具查询失败，工具名不存在于 registry。"""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(
+            f"Tool '{tool_name}' not found in registry.",
+            code="TOOL_NOT_FOUND",
+        )
+        self.tool_name = tool_name
+
+
+class ToolInputSchemaError(ToolRuntimeError):
+    """输入参数不符合 input_model schema，由 pipeline schema parse 阶段抛出。"""
+
+    def __init__(self, tool_name: str, detail: str) -> None:
+        super().__init__(
+            f"Input schema validation failed for tool '{tool_name}': {detail}",
+            code="INPUT_SCHEMA_ERROR",
+        )
+        self.tool_name = tool_name
+        self.detail = detail
+
+
+# ---------------------------------------------------------------------------
+# 异常 → ToolResultEnvelope 映射
+# ---------------------------------------------------------------------------
+
+def exception_to_envelope(
+    exc: Exception,
+    tool_name: str,
+    *,
+    include_traceback: bool = True,
+) -> ToolResultEnvelope:
+    """
+    将任意异常映射为 status="error" 的 ToolResultEnvelope。
+
+    traceback 写入 meta["traceback"]，不进入模型上下文。
+    面向模型的 summary 只包含简短错误说明，不暴露内部细节。
+
+    Args:
+        exc:               捕获到的异常对象。
+        tool_name:         当前执行的工具名。
+        include_traceback: 是否将 traceback 写入 meta（默认 True，用于调试）。
+
+    Returns:
+        status="error" 的 ToolResultEnvelope。
+    """
+    exc_type = type(exc).__name__
+    message = str(exc) if str(exc) else exc_type
+
+    # ToolRuntimeError 子类携带稳定 code
+    code = exc.code if isinstance(exc, ToolRuntimeError) else None
+
+    error_info = ToolErrorInfo(
+        message=message,
+        code=code,
+        exception_type=exc_type,
+    )
+
+    meta: dict = {"exception_type": exc_type}
+    if include_traceback:
+        meta["traceback"] = tb.format_exc()
+
+    return ToolResultEnvelope(
+        status="error",
+        tool_name=tool_name,
+        summary=f"Error: {message}",
+        error=error_info,
+        meta=meta,
+    )
+
+
+def blocked_envelope(
+    tool_name: str,
+    message: str,
+    policy_id: str | None = None,
+) -> ToolResultEnvelope:
+    """
+    构造 status="blocked" 的 ToolResultEnvelope。
+
+    check_permissions() 返回 deny 时由 pipeline 调用。
+    向模型返回通用拒绝信息，不暴露路径细节（策略不透明原则）。
+    """
+    return ToolResultEnvelope(
+        status="blocked",
+        tool_name=tool_name,
+        summary=f"Permission denied: {message}",
+        meta={"policy_id": policy_id} if policy_id else None,
+    )
+
+
+def validation_error_envelope(
+    tool_name: str,
+    message: str,
+    code: str | None = None,
+) -> ToolResultEnvelope:
+    """
+    构造 validate_input 失败的 status="error" ToolResultEnvelope。
+
+    模型会收到 message，可据此修正输入后重试。
+    """
+    return ToolResultEnvelope(
+        status="error",
+        tool_name=tool_name,
+        summary=f"Error: {message}",
+        error=ToolErrorInfo(message=message, code=code),
+    )
+
+
+def blocked_envelope(
+    tool_name: str,
+    message: str,
+    policy_id: str | None = None,
+) -> ToolResultEnvelope:
+    """
+    构造 status="blocked" 的 ToolResultEnvelope。
+
+    check_permissions() 返回 deny 时由 pipeline 调用。
+    向模型返回通用拒绝信息，不暴露路径细节（策略不透明原则）。
+    """
+    return ToolResultEnvelope(
+        status="blocked",
+        tool_name=tool_name,
+        summary=f"Permission denied: {message}",
+        meta={"policy_id": policy_id} if policy_id else None,
+    )
+
+
+def validation_error_envelope(
+    tool_name: str,
+    message: str,
+    code: str | None = None,
+) -> ToolResultEnvelope:
+    """
+    构造 validate_input 失败的 status="error" ToolResultEnvelope。
+
+    模型会收到 message，可据此修正输入后重试。
+    与 exception_to_envelope 的区别：无 traceback，面向模型可读。
+    """
+    return ToolResultEnvelope(
+        status="error",
+        tool_name=tool_name,
+        summary=f"Error: {message}",
+        error=ToolErrorInfo(message=message, code=code),
+    )

langchain_agentx/tool_runtime/identical_call_cache.py

@@ -0,0 +1,110 @@
+"""
+同工具 + 同解析后参数 的会话内结果复用（替代仅靠 middleware 注入「别重复调」的软提示）。
+
+- 按 ``(thread_id, tool_name, sha256(sorted_json(args)))`` 做键；命中则 **不再次 invoke**，
+  直接返回上一次的 ``ToolResultEnvelope`` 副本，并打上 ``meta.identical_call_dedup`` 与 Hint。
+- 仅 ``RuntimeTool.dedupe_identical_calls=True`` 时启用；写类/破坏性工具应保持 False。
+
+由 ``ToolExecutorPipeline`` 在权限通过之后、``before_invoke`` 之前查询；成功 ``ok`` 后写入缓存。
+
+示例（直观看这个模块在做什么）：
+
+1) 同一线程、同工具、同参数：第二次直接复用，不再执行工具
+
+   - 第一次调用：``thread_id=t1, tool=read, args={\"file_path\":\"/a.txt\"}``
+     -> 真正执行 read 工具，返回 envelope，写入 memo
+   - 第二次调用：``thread_id=t1, tool=read, args={\"file_path\":\"/a.txt\"}``
+     -> 命中 memo，直接返回上次 envelope（并标记 ``identical_call_dedup=True``）
+
+2) 不同线程隔离：不会串缓存
+
+   - 调用 A：``thread_id=t1, tool=read, args={\"file_path\":\"/a.txt\"}``
+   - 调用 B：``thread_id=t2, tool=read, args={\"file_path\":\"/a.txt\"}``
+   - 因 thread_id 不同，键不同，B 不会命中 A 的缓存，仍会执行工具
+
+3) 参数不同：不会误命中
+
+   - ``args={\"file_path\":\"/a.txt\"}`` 与 ``args={\"file_path\":\"/b.txt\"}``
+   - 参数摘要不同，键不同，仍会执行工具
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from collections import OrderedDict
+from typing import Any
+
+from .models import ToolExecutionContext, ToolHint, ToolResultEnvelope
+
+
+def dedup_cache_key(
+    ctx: ToolExecutionContext,
+    tool_name: str,
+    parsed_data: dict[str, Any],
+) -> str:
+    """稳定键：线程隔离 + 工具名 + 参数字典规范化后的摘要。"""
+    tid = ctx.thread_id or "__no_thread__"
+    payload = json.dumps(parsed_data, sort_keys=True, ensure_ascii=False)
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    return f"{tid}::{tool_name}::{digest}"
+
+
+def envelope_with_dedup_notice(
+    env: ToolResultEnvelope,
+    *,
+    ctx: ToolExecutionContext,
+) -> ToolResultEnvelope:
+    """返回深拷贝，并附加 dedup 元数据与面向模型的 Hint（会进入 ``envelope_to_tool_output``）。"""
+    out = copy.deepcopy(env)
+    meta = dict(out.meta or {})
+    meta["identical_call_dedup"] = True
+    meta["dedup_source_tool_call_id"] = ctx.tool_call_id
+    out.meta = meta
+    hints = list(out.hints or [])
+    hints.insert(
+        0,
+        ToolHint(
+            message=(
+                "Same tool and arguments as an earlier call in this thread; "
+                "reusing the previous successful result without executing again."
+            ),
+        ),
+    )
+    out.hints = hints
+    return out
+
+
+class IdenticalCallMemo:
+    """
+    进程内 LRU（按插入顺序淘汰）：仅缓存 ``status == \"ok\"`` 的 envelope。
+    """
+
+    def __init__(self, max_entries: int = 512) -> None:
+        self._max_entries = max(1, int(max_entries))
+        self._data: OrderedDict[str, ToolResultEnvelope] = OrderedDict()
+
+    def get(self, key: str) -> ToolResultEnvelope | None:
+        if key not in self._data:
+            return None
+        self._data.move_to_end(key)
+        return copy.deepcopy(self._data[key])
+
+    def put(self, key: str, envelope: ToolResultEnvelope) -> None:
+        if envelope.status != "ok":
+            return
+        self._data[key] = copy.deepcopy(envelope)
+        self._data.move_to_end(key)
+        while len(self._data) > self._max_entries:
+            self._data.popitem(last=False)
+
+    def clear(self) -> None:
+        self._data.clear()
+
+
+__all__ = [
+    "IdenticalCallMemo",
+    "dedup_cache_key",
+    "envelope_with_dedup_notice",
+]