工具调用范式三跃迁实测：决策边界·参数内化·统一表示

                 │  应该调用工具      │  不应调用工具
─────────────────┼──────────────────┼──────────────────
 模型调用了工具   │  ✅ True Positive  │  ❌ False Positive
                 │  正确调用          │  过度调用（浪费）
─────────────────┼──────────────────┼──────────────────
 模型没调工具    │  ❌ False Negative  │  ✅ True Negative
                 │  遗漏调用（危险）   │  正确拒绝

# 决策边界校准器：生产级实现
class ToolCallCalibrator:
    """三层校准：静态阈值 → 动态调整 → 运行时护栏"""

    def __init__(self, model_id: str, fp_budget: float = 0.10):
        # 每个模型有不同的默认校准阈值
        self.base_thresholds = {
            "gpt-4o": 0.72,        # 较高阈值抑制过度调用
            "claude-opus-4": 0.65,  # 天然校准好，阈值可低
            "gemini-2.5-pro": 0.74,
        }
        self.threshold = self.base_thresholds.get(model_id, 0.70)
        self.fp_budget = fp_budget
        self.call_history = []      # 滑动窗口统计

    def should_call_tool(self, intent_score: float, 
                         tool_cost: float,
                         context_remaining: int) -> bool:
        """
        三层决策：
        1. 意图分数是否超过基础阈值
        2. 动态调整：根据近期FP率修正
        3. 运行时护栏：上下文不足时强制提升阈值
        """
        # Layer 1: 基础阈值
        if intent_score < self.threshold:
            return False

        # Layer 2: 动态调整
        recent_fp_rate = self._calc_recent_fp_rate(window=50)
        if recent_fp_rate > self.fp_budget:
            adjusted = self.threshold + (recent_fp_rate - self.fp_budget)
            if intent_score < adjusted:
                return False

        # Layer 3: 上下文护栏
        if context_remaining < 2000:  # 上下文紧张时更保守
            if intent_score < self.threshold + 0.15:
                return False

        return True

    def _calc_recent_fp_rate(self, window: int) -> float:
        recent = self.call_history[-window:]
        if not recent:
            return 0.0
        fp_count = sum(1 for c in recent if c["was_fp"])
        return fp_count / len(recent)

graph TD
    A[用户Query] --> B{工具路由器<br/>Tool Router}
    B -->|匹配工具A| C[加载LoRA_A<br/>工具A参数模块]
    B -->|匹配工具B| D[加载LoRA_B<br/>工具B参数模块]
    B -->|无需工具| E[基座模型直接回答]
    C --> F[参数化推理<br/>生成调用指令]
    D --> F
    F --> G[执行工具调用]
    G --> H[结果注入<br/>返回最终回答]

    style B fill:#ff6b6b,stroke:#333
    style C fill:#4ecdc4,stroke:#333
    style D fill:#4ecdc4,stroke:#333
    style E fill:#95e1d3,stroke:#333

LangChain tools format ≠ OpenAI function format ≠ Anthropic tool format ≠ MCP tool schema
     ↓                      ↓                        ↓                     ↓
  73种字段名             12种字段名               15种字段名            22种字段名

# UniToolCall 统一表示 → 多格式导出
from unitoolcall import ToolSchema, FormatConverter

tool = ToolSchema(
    name="search_flights",
    description="Search for available flights between two cities",
    parameters={
        "origin": {"type": "string", "description": "Departure city IATA code"},
        "destination": {"type": "string", "description": "Arrival city IATA code"},
        "date": {"type": "string", "format": "date"},
    },
    required=["origin", "destination"],
    # UniToolCall扩展字段
    risk_level="low",
    estimated_latency_ms=500,
    idempotent=True,
)

# 一键转换为各平台格式
openai_fmt = FormatConverter.to_openai(tool)    # OpenAI function calling
anthropic_fmt = FormatConverter.to_anthropic(tool)  # Anthropic tool_use
mcp_fmt = FormatConverter.to_mcp(tool)          # MCP tool schema
langchain_fmt = FormatConverter.to_langchain(tool)  # LangChain StructuredTool

graph TB
    subgraph "第一层：决策边界"
        D1[When2Call基准] --> D2[校准阈值引擎]
        D3["To Call or Not to Call<br/>期望值模型"] --> D2
        D2 --> DECISION{调/不调？}
    end

    subgraph "第二层：工具表示"
        R1[传统：上下文注入]
        R2[ParaTool：参数内化]
        R3[UniToolCall：统一表示]
        R3 --> R1
        R3 --> R2
    end

    subgraph "第三层：执行与评测"
        E1[Schema校验]
        E2[并行/串行编排]
        E3[6维评测矩阵]
    end

    DECISION -->|调用| R1
    DECISION -->|调用| R2
    R1 --> E1
    R2 --> E1
    E1 --> E2
    E2 --> E3

    style DECISION fill:#ff6b6b,stroke:#333
    style R2 fill:#4ecdc4,stroke:#333
    style R3 fill:#45b7d1,stroke:#333

"""
三跃迁融合架构：生产级工具调用栈
"""
from dataclasses import dataclass
from typing import Optional

@dataclass
class ToolCallStack:
    """融合三跃迁的完整工具调用栈"""

    # Layer 1: 决策边界（When2Call + 校准器）
    calibrator: ToolCallCalibrator

    # Layer 2a: 统一表示（UniToolCall）
    tool_registry: UnifiedToolRegistry  # 所有工具的统一表示

    # Layer 2b: 参数内化（ParaTool，可选）
    adapter_manager: Optional[ParaToolAdapterManager]

    # Layer 3: 执行与评测
    executor: ToolExecutor
    evaluator: SixDimEvaluator

    async def run(self, query: str, context: dict) -> dict:
        # Step 1: 决策边界 — 该不该调？
        intent = await self._analyze_intent(query)
        if not self.calibrator.should_call_tool(
            intent_score=intent.score,
            tool_cost=intent.estimated_cost,
            context_remaining=context.get("tokens_remaining", 8000)
        ):
            return {"action": "direct_answer", "reason": "below_threshold"}

        # Step 2: 工具选择 — 调哪个？
        tool_match = self.tool_registry.match(query, intent)

        # Step 3: 参数填充（参数内化 or 上下文注入）
        if self.adapter_manager and self.adapter_manager.has_adapter(tool_match.id):
            # ParaTool路径：零上下文消耗
            call_params = await self.adapter_manager.infer(
                tool_id=tool_match.id, query=query
            )
        else:
            # 传统路径：Schema引导
            call_params = await self._schema_guided_fill(tool_match, query)

        # Step 4: 执行 + 校验
        result = await self.executor.execute(tool_match, call_params)

        # Step 5: 六维评测（异步，不阻塞主流程）
        await self.evaluator.async_evaluate(
            query=query,
            tool=tool_match,
            params=call_params,
            result=result,
            intent=intent
        )

        return result

graph LR
    L1["L1: 裸调用<br/>Raw Invocation"] --> L2["L2: Schema约束<br/>Schema-Gated"]
    L2 --> L3["L3: 决策校准<br/>Decision-Calibrated"]
    L3 --> L4["L4: 参数内化<br/>Parameter-Internalized"]
    L4 --> L5["L5: 认知闭环<br/>Cognitive Loop"]

    style L1 fill:#95e1d3,stroke:#333
    style L2 fill:#4ecdc4,stroke:#333
    style L3 fill:#45b7d1,stroke:#333
    style L4 fill:#f7dc6f,stroke:#333
    style L5 fill:#ff6b6b,stroke:#333

# 业务感知的阈值配置
THRESHOLD_PROFILES = {
    "financial": {"base": 0.45, "fp_budget": 0.30, "fn_budget": 0.02},
    "content":   {"base": 0.80, "fp_budget": 0.05, "fn_budget": 0.15},
    "security":  {"base": 0.50, "fp_budget": 0.10, "fn_budget": 0.01,
                  "human_review_zone": (0.40, 0.65)},  # 人工确认区
}