Agent/examples/find knowledge/tool/teacher.py

"""
Teacher Model Tool - 教师模型工具

当遇到复杂问题或需要专家建议时，可以向教师模型提问获得帮助。
教师模型使用更强大的模型（默认 openai/gpt-5.4）来提供指导和建议。
"""

import asyncio
import os
from typing import Any, Dict, Optional

from agent.tools import tool
from agent.llm import create_openrouter_llm_call


# 默认教师模型配置
DEFAULT_TEACHER_MODEL = "openai/gpt-5.4"

# 可以通过环境变量覆盖
TEACHER_MODEL = os.getenv("TEACHER_MODEL", DEFAULT_TEACHER_MODEL)


@tool(
    name="ask_teacher",
    description=(
        "向教师模型提问，获取专家级的建议和指导。"
        "适用场景："
        "1. 遇到复杂问题需要深入分析时"
        "2. 需要验证当前思路是否正确时"
        "3. 需要专业建议来做决策时"
        "4. 需要帮助理解复杂概念或任务时"
        "教师模型会提供详细的分析和建议，但最终决策仍由你做出。"
    ),
    parameters={
        "type": "object",
        "properties": {
            "question": {
                "type": "string",
                "description": (
                    "向教师模型提出的问题。应该清晰、具体地描述你的问题或困惑。"
                    "可以包含背景信息、当前进展、遇到的困难等。"
                )
            },
            "context": {
                "type": "string",
                "description": (
                    "问题的上下文信息（可选）。"
                    "包括：当前任务、已有的信息、已尝试的方法等。"
                    "提供更多上下文可以帮助教师模型给出更准确的建议。"
                )
            },
            "model": {
                "type": "string",
                "description": (
                    f"使用的教师模型（可选，默认：{TEACHER_MODEL}）。"
                    "可选值：openai/gpt-5.4, openai/o1, anthropic/claude-opus-4-5 等"
                )
            }
        },
        "required": ["question"]
    }
)
async def ask_teacher(
    question: str,
    context: Optional[str] = None,
    model: Optional[str] = None,
    **kwargs
) -> Dict[str, Any]:
    """
    向教师模型提问，获取专家建议

    Args:
        question: 要提问的问题
        context: 问题的上下文信息（可选）
        model: 使用的教师模型（可选）
        **kwargs: 其他参数（从工具调用传入）

    Returns:
        包含教师模型回答的字典
    """
    try:
        # 使用指定的模型或默认模型
        teacher_model = model or TEACHER_MODEL

        # 构建系统提示
        system_prompt = """你是一个经验丰富的AI助手教师模型。你的职责是：

1. 提供清晰、准确的分析和建议
2. 帮助理解复杂的问题和概念
3. 提供多角度的思考方向
4. 指出潜在的问题和风险
5. 给出具体可行的建议

回答时请：
- 结构清晰，分点说明
- 提供具体的理由和依据
- 如果有多种方案，说明各自的优缺点
- 保持客观和专业
- 如果不确定，明确说明不确定性"""

        # 构建用户消息
        user_message = question
        if context:
            user_message = f"**背景信息**：\n{context}\n\n**问题**：\n{question}"

        # 构建消息列表
        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_message}
        ]

        # 调用教师模型
        llm_call = create_openrouter_llm_call(model=teacher_model)
        response = await llm_call(
            messages=messages,
            temperature=0.7,
            max_tokens=4000
        )

        # 提取回答
        answer = response.get("content", "")

        # 返回结果
        return {
            "status": "success",
            "model": teacher_model,
            "question": question,
            "answer": answer,
            "usage": {
                "prompt_tokens": response.get("prompt_tokens", 0),
                "completion_tokens": response.get("completion_tokens", 0),
                "total_tokens": response.get("prompt_tokens", 0) + response.get("completion_tokens", 0)
            }
        }

    except Exception as e:
        return {
            "status": "error",
            "error": str(e),
            "question": question
        }