langchain-agentx-python 0.4.6__tar.gz → 0.4.8__tar.gz

{langchain-agentx-python-0.4.6 → langchain-agentx-python-0.4.8}/PKG-INFO

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

{langchain-agentx-python-0.4.6 → langchain-agentx-python-0.4.8}/langchain_agentx/__init__.py

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

langchain-agentx-python-0.4.8/langchain_agentx/tool_runtime/auto_mode/__init__.py

@@ -0,0 +1,82 @@
+"""
+tool_runtime/auto_mode/ — Auto Mode 决策骨架包
+
+职责：
+    跨工具的 auto-mode 决策骨架，实现三段式决策：
+    L1 工具白名单 + L3 Bash 启发式 + L4 LLM 分类器
+
+模块划分（对应设计文档 §4.2.1）：
+    - config.py: AutoModeConfig（开关 / 阈值 / 模型）
+    - decision.py: AutoModeDecision dataclass + Reason 枚举
+    - state.py: AutoModeState（全局开关 + 累计 denial 计数）
+    - allowlist.py: SafeToolAllowlist（L1 静态白名单）
+    - events.py: AutoModeDecisionEvent（前端可观测）
+    - hook.py: AutoModeAuthHook（PRE_TOOL_USE Hook 集成）
+    - factory.py: build_auto_mode_hook（组件工厂）
+
+依赖方向约束（重要）：
+    骨架（auto_mode/*）不得直接 import tools/bash/{read_only_validation, bash_hardening}，
+    只允许 import tools/bash/auto_mode_adapter。
+    这是"跨工具骨架 vs 工具自家细节"的边界（§4.2.3）。
+
+CC 源码对照：
+    - src/utils/permissions/permissions.ts（决策入口）
+    - src/utils/permissions/classifierDecision.ts（L1 白名单）
+    - src/utils/permissions/yoloClassifier.ts（L4 LLM 分类器，Phase 2）
+    - src/utils/permissions/autoModeState.ts（状态管理）
+"""
+
+from .config import AutoModeConfig, AutoModeConfigError, validate_auto_mode_config
+from .decision import (
+    AutoModeDecision,
+    AutoModeReason,
+    _allow,
+    _ask,
+    _deny,
+    _passthrough,
+)
+from .state import AutoModeState, get_auto_mode_state
+from .allowlist import SafeToolAllowlist
+from .events import AutoModeDecisionEvent
+from .hook import AutoModeAuthHook
+from .factory import build_auto_mode_hook
+from .rule_stripping import (
+    CROSS_PLATFORM_CODE_EXEC,
+    DEFAULT_DANGEROUS_BASH_PATTERNS,
+    StrippedRule,
+    StripResult,
+    is_dangerous_bash_permission,
+    DangerousRuleStripper,
+)
+
+__all__ = [
+    # Config
+    "AutoModeConfig",
+    "AutoModeConfigError",
+    "validate_auto_mode_config",
+    # Decision
+    "AutoModeDecision",
+    "AutoModeReason",
+    "_allow",
+    "_ask",
+    "_deny",
+    "_passthrough",
+    # State
+    "AutoModeState",
+    "get_auto_mode_state",
+    # Allowlist
+    "SafeToolAllowlist",
+    # Events
+    "AutoModeDecisionEvent",
+    # Hook
+    "AutoModeAuthHook",
+    # Factory
+    "build_auto_mode_hook",
+    # Rule Stripping
+    "CROSS_PLATFORM_CODE_EXEC",
+    "DEFAULT_DANGEROUS_BASH_PATTERNS",
+    "StrippedRule",
+    "StripResult",
+    "is_dangerous_bash_permission",
+    "DangerousRuleStripper",
+]

langchain-agentx-python-0.4.8/langchain_agentx/tool_runtime/auto_mode/allowlist.py

@@ -0,0 +1,89 @@
+"""
+tool_runtime/auto_mode/allowlist.py — L1 工具白名单
+
+职责：
+    静态白名单查表器，对应 CC SAFE_YOLO_ALLOWLISTED_TOOLS。
+    命中白名单的工具直接 allow，零 LLM 调用。
+
+链路位置：
+    AutoModeAuthHook._decide() → SafeToolAllowlist.contains() → allow
+
+当前裁剪范围：
+    - 暂不包含 Edit / Write（L2 acceptEdits fast-path 待后续实现）
+    - 白名单基于 CC classifierDecision.ts:56-94 迁移
+
+CC 源码对照：
+    src/utils/permissions/classifierDecision.ts: SAFE_YOLO_ALLOWLISTED_TOOLS
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+
+class SafeToolAllowlist:
+    """静态白名单查表器。对应 CC SAFE_YOLO_ALLOWLISTED_TOOLS。
+
+    设计文档：docs/design-docs/tool-design/auto-mode-bash-classifier.html §5.3
+
+    命中白名单的工具直接 allow，无需调用 LLM 分类器。
+
+    白名单内容（对照 CC）：
+        - 只读文件操作：Read / Glob / Grep
+        - 任务管理（仅元数据）：TodoWrite / TaskCreate / TaskGet / TaskList /
+                                TaskUpdate / TaskStop / TaskOutput
+        - UI / 计划态：AskUserQuestion / EnterPlanMode / ExitPlanMode
+        - Skill 加载（无副作用）：Skill
+        - UserMessage（带外通信）
+
+    注意：
+        Edit / Write 不进默认白名单，走 acceptEdits fast-path（L2，待实现）。
+    """
+
+    # CC SAFE_YOLO_ALLOWLISTED_TOOLS 迁移
+    DEFAULT_TOOLS: frozenset[str] = frozenset({
+        # 只读文件操作
+        "Read",
+        "Glob",
+        "Grep",
+        # 任务管理（仅元数据）
+        "TodoWrite",
+        "TaskCreate",
+        "TaskGet",
+        "TaskList",
+        "TaskUpdate",
+        "TaskStop",
+        "TaskOutput",
+        # UI / 计划态
+        "AskUserQuestion",
+        "EnterPlanMode",
+        "ExitPlanMode",
+        # Skill 加载（无副作用）
+        "Skill",
+        # UserMessage（带外通信）
+        "UserMessage",
+    })
+
+    def __init__(self, extra: Iterable[str] | None = None):
+        """初始化白名单。
+
+        Args:
+            extra: 额外的安全工具名称（扩展默认白名单）
+        """
+        self._tools: frozenset[str] = frozenset(self.DEFAULT_TOOLS) | frozenset(extra or ())
+
+    def contains(self, tool_name: str) -> bool:
+        """检查工具是否在白名单中。
+
+        Args:
+            tool_name: 工具名称
+
+        Returns:
+            True 如果在白名单中，否则 False
+        """
+        return tool_name in self._tools
+
+    @property
+    def tools(self) -> frozenset[str]:
+        """返回当前白名单的所有工具（只读）。"""
+        return self._tools

langchain-agentx-python-0.4.8/langchain_agentx/tool_runtime/auto_mode/classifier/__init__.py

@@ -0,0 +1,42 @@
+"""
+tool_runtime/auto_mode/classifier/ — LLM 分类器子包
+
+职责：
+    实现 Auto Mode 的 L4 LLM 分类器，用于 fast-path miss 后的兜底决策。
+
+模块划分：
+    - schema.py: CLASSIFY_RESULT_TOOL_SCHEMA（工具调用 schema）
+    - transcript.py: TranscriptBuilder（构建分类器输入上下文）
+    - prompt.py: AutoModePromptBuilder（构建 system prompt）
+    - classifier.py: LLMClassifier（核心分类逻辑）
+    - parser.py: ToolUseParser（解析分类器返回）
+
+依赖方向约束：
+    本子模块可依赖 auto_mode 基础模块（config, decision），不得依赖 Bash 工具内部。
+
+CC 源码对照：
+    - src/utils/permissions/yoloClassifier.ts:1012 — classifyYoloAction
+    - src/utils/permissions/yoloClassifier.ts:344-345 — transcript 安全设计
+"""
+
+from .schema import CLASSIFY_RESULT_TOOL_SCHEMA
+from .transcript import TranscriptBuilder, get_transcript_builder
+from .prompt import AutoModePromptBuilder, get_prompt_builder
+from .classifier import LLMClassifier
+from .parser import ToolUseParser, parse_classifier_result
+
+__all__ = [
+    # Schema
+    "CLASSIFY_RESULT_TOOL_SCHEMA",
+    # Transcript
+    "TranscriptBuilder",
+    "get_transcript_builder",
+    # Prompt
+    "AutoModePromptBuilder",
+    "get_prompt_builder",
+    # Classifier
+    "LLMClassifier",
+    # Parser
+    "ToolUseParser",
+    "parse_classifier_result",
+]

langchain-agentx-python-0.4.8/langchain_agentx/tool_runtime/auto_mode/classifier/classifier.py

@@ -0,0 +1,368 @@
+"""
+tool_runtime/auto_mode/classifier/classifier.py — LLM 分类器核心
+
+职责：
+    实现 Auto Mode 的 L4 LLM 分类器，对 fast-path miss 的工具调用进行分类。
+
+链路位置：
+    AutoModeAuthHook.decide() → LLMClassifier.classify() → AutoModeDecision
+
+当前裁剪范围（Phase 2）：
+    - 基础分类流程
+    - 超时处理（fail-closed：返回 CLASSIFIER_UNAVAILABLE）
+    - 四级模型优先级：explicit_chat_model > explicit_factory > config.classifier_model > ctx.model
+    - require_separate_classifier_model 检查
+
+CC 源码对照：
+    - src/utils/permissions/yoloClassifier.ts:1012 — classifyYoloAction
+    - src/utils/permissions/yoloClassifier.ts:cache_control — action block 位置
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+from enum import Enum
+
+from .schema import CLASSIFY_RESULT_TOOL_SCHEMA
+from .transcript import TranscriptBuilder, TranscriptConfig, get_transcript_builder
+from .prompt import AutoModePromptBuilder, PromptConfig, get_prompt_builder
+from .parser import ToolUseParser, get_tool_use_parser, ParseError
+
+if TYPE_CHECKING:
+    from langchain_core.language_models.chat_models import BaseChatModel
+    from langchain_core.messages import BaseMessage
+
+    from ..config import AutoModeConfig
+    from ..decision import AutoModeDecision, AutoModeReason
+
+
+class ClassifierError(Exception):
+    """分类器错误。"""
+
+    def __init__(self, message: str, retryable: bool = False):
+        super().__init__(message)
+        self.retryable = retryable
+
+
+@dataclass
+class ClassifierInput:
+    """分类器输入。"""
+
+    tool_name: str
+    """工具名称。"""
+
+    tool_input: dict[str, Any]
+    """工具输入参数。"""
+
+    action_text: str
+    """操作描述（tool_name + tool_input 的组合）。"""
+
+    messages: list["BaseMessage"]
+    """对话历史消息。"""
+
+    chat_model: "BaseChatModel | None"
+    """
+    显式指定的 chat 模型实例（最高优先级）。
+    如果为 None，则从其他来源解析模型。
+    """
+
+
+@dataclass
+class ClassifierOutput:
+    """分类器输出。"""
+
+    decision: "AutoModeDecision"
+    """决策结果。"""
+
+    thinking: str | None
+    """分类器思考链（仅 L4 有值）。"""
+
+    elapsed_ms: float
+    """分类耗时（毫秒）。"""
+
+    model_used: str | None
+    """实际使用的模型标识。"""
+
+
+@dataclass
+class ClassifierConfig:
+    """分类器配置。"""
+
+    timeout_s: float = 8.0
+    """分类超时时间（秒）。"""
+
+    temperature: float = 0.0
+    """温度参数（0 = 确定性输出）。"""
+
+    max_tokens: int = 500
+    """最大输出 token 数。"""
+
+    require_separate_classifier_model: bool = False
+    """
+    是否要求使用独立的分类器模型。
+
+    如果为 True，当无法获取独立模型时会抛出异常。
+    这是为了避免使用主对话模型（可能已被污染）进行分类。
+    """
+
+    transcript_config: TranscriptConfig = field(default_factory=TranscriptConfig)
+    """Transcript 构建配置。"""
+
+    prompt_config: PromptConfig = field(default_factory=PromptConfig)
+    """Prompt 构建配置。"""
+
+
+class LLMClassifier:
+    """LLM 分类器。
+
+    对应 CC yoloClassifier.ts 的 classifyYoloAction 函数。
+
+    决策流程：
+        1. 解析 chat 模型（四级优先级）
+        2. 构建 transcript（安全过滤）
+        3. 构建 system prompt
+        4. 调用 LLM（强制 tool_choice=classify_result）
+        5. 解析返回结果
+        6. 转换为 AutoModeDecision
+
+    安全设计：
+        - 超时返回 CLASSIFIER_UNAVAILABLE（fail-closed）
+        - transcript 丢弃 assistant 文本（防止注入）
+        - require_separate_classifier_model 强制使用独立模型
+    """
+
+    def __init__(
+        self,
+        *,
+        config: ClassifierConfig | None = None,
+        transcript_builder: TranscriptBuilder | None = None,
+        prompt_builder: AutoModePromptBuilder | None = None,
+        parser: ToolUseParser | None = None,
+    ):
+        """初始化 LLMClassifier。
+
+        Args:
+            config: 分类器配置
+            transcript_builder: Transcript 构建器
+            prompt_builder: Prompt 构建器
+            parser: 工具调用解析器
+        """
+        self._config = config or ClassifierConfig()
+        self._transcript_builder = transcript_builder or get_transcript_builder(
+            self._config.transcript_config
+        )
+        self._prompt_builder = prompt_builder or get_prompt_builder(
+            self._config.prompt_config
+        )
+        self._parser = parser or get_tool_use_parser()
+
+    async def classify(
+        self,
+        input_data: ClassifierInput,
+    ) -> ClassifierOutput:
+        """执行分类。
+
+        Args:
+            input_data: 分类器输入
+
+        Returns:
+            ClassifierOutput
+
+        Raises:
+            ClassifierError: 分类失败
+        """
+        import time
+
+        start_time = time.perf_counter()
+
+        # 解析 chat 模型
+        chat_model = await self._resolve_chat_model(input_data)
+
+        # 构建输入
+        transcript_messages = self._transcript_builder.build_with_action_context(
+            messages=input_data.messages,
+            tool_name=input_data.tool_name,
+            tool_input=input_data.tool_input,
+            action_text=input_data.action_text,
+        )
+        system_prompt = self._prompt_builder.build()
+
+        # 调用 LLM（带超时）
+        try:
+            response = await asyncio.wait_for(
+                self._invoke_llm(chat_model, system_prompt, transcript_messages),
+                timeout=self._config.timeout_s,
+            )
+        except asyncio.TimeoutError:
+            # 超时返回 CLASSIFIER_UNAVAILABLE（fail-closed）
+            return self._build_unavailable_output(
+                elapsed_ms=_ms_since(start_time),
+                reason="classification_timeout",
+            )
+
+        # 解析结果
+        try:
+            result = self._parser.parse(response)
+        except ParseError as e:
+            # 解析失败返回 CLASSIFIER_UNAVAILABLE（fail-closed）
+            return self._build_unavailable_output(
+                elapsed_ms=_ms_since(start_time),
+                reason=f"parse_error: {e}",
+            )
+
+        # 转换为 AutoModeDecision
+        decision = self._result_to_decision(
+            result=result,
+            tool_name=input_data.tool_name,
+            elapsed_ms=_ms_since(start_time),
+        )
+
+        return ClassifierOutput(
+            decision=decision,
+            thinking=result.thinking,
+            elapsed_ms=_ms_since(start_time),
+            model_used=getattr(chat_model, "model_name", None) or str(type(chat_model).__name__),
+        )
+
+    async def _invoke_llm(
+        self,
+        chat_model: "BaseChatModel",
+        system_prompt: str,
+        messages: list["BaseMessage"],
+    ) -> "BaseMessage":
+        """调用 LLM。
+
+        Args:
+            chat_model: Chat 模型
+            system_prompt: System prompt
+            messages: 消息列表
+
+        Returns:
+            AIMessage
+        """
+        # 构建完整的消息列表
+        from langchain_core.messages import SystemMessage
+
+        full_messages = [SystemMessage(content=system_prompt)]
+        full_messages.extend(messages)
+
+        # 调用模型（强制使用 classify_result 工具）
+        response = await chat_model.ainvoke(
+            full_messages,
+            temperature=self._config.temperature,
+            max_tokens=self._config.max_tokens,
+            tools=[CLASSIFY_RESULT_TOOL_SCHEMA],
+            tool_choice={"type": "function", "name": "classify_result"},
+        )
+
+        return response
+
+    def _result_to_decision(
+        self,
+        result: Any,
+        tool_name: str,
+        elapsed_ms: float,
+    ) -> "AutoModeDecision":
+        """将分类结果转换为 AutoModeDecision。
+
+        Args:
+            result: ClassifierResult
+            tool_name: 工具名称
+            elapsed_ms: 耗时
+
+        Returns:
+            AutoModeDecision
+        """
+        from ..decision import AutoModeDecision, AutoModeReason, _allow, _deny
+
+        if result.should_block:
+            return _deny(
+                layer="L4",
+                reason=AutoModeReason.LLM_DENY,
+                explanation=result.reason,
+                classifier_thinking=result.thinking,
+                elapsed_ms=elapsed_ms,
+            )
+        else:
+            return _allow(
+                layer="L4",
+                reason=AutoModeReason.LLM_ALLOW,
+                explanation=result.reason,
+                classifier_thinking=result.thinking,
+                elapsed_ms=elapsed_ms,
+            )
+
+    def _build_unavailable_output(
+        self,
+        *,
+        elapsed_ms: float,
+        reason: str,
+    ) -> ClassifierOutput:
+        """构建分类器不可用输出（fail-closed）。
+
+        Args:
+            elapsed_ms: 耗时
+            reason: 不可用原因
+
+        Returns:
+            ClassifierOutput，decision 为 ask
+        """
+        from ..decision import AutoModeDecision, AutoModeReason, _ask
+
+        return ClassifierOutput(
+            decision=_ask(
+                layer="L4",
+                reason=AutoModeReason.CLASSIFIER_UNAVAILABLE,
+                explanation=f"Classifier unavailable: {reason}",
+                elapsed_ms=elapsed_ms,
+            ),
+            thinking=None,
+            elapsed_ms=elapsed_ms,
+            model_used=None,
+        )
+
+    async def _resolve_chat_model(
+        self,
+        input_data: ClassifierInput,
+    ) -> "BaseChatModel":
+        """解析 chat 模型（四级优先级）。
+
+        优先级：
+            1. input_data.chat_model（显式指定）
+            2. 工厂函数（如果提供）
+            3. config.classifier_model（如果配置了）
+            4. 从 input_data 解析 ctx.model（兜底，会记 WARNING）
+
+        Returns:
+            BaseChatModel
+
+        Raises:
+            ClassifierError: 无法解析模型
+        """
+        # 优先级 1：显式指定的模型
+        if input_data.chat_model is not None:
+            return input_data.chat_model
+
+        # 优先级 2-4：需要从外部注入的信息解析
+        # 这里返回占位符，实际由调用方提供
+        raise ClassifierError(
+            "No chat model available. "
+            "Please provide chat_model explicitly or configure classifier_model."
+        )
+
+
+def _ms_since(start_time: float) -> float:
+    """计算耗时（毫秒）。"""
+    import time
+    return (time.perf_counter() - start_time) * 1000
+
+
+__all__ = [
+    "ClassifierError",
+    "ClassifierInput",
+    "ClassifierOutput",
+    "ClassifierConfig",
+    "LLMClassifier",
+]