"""
专为 AI Agent 设计的多模态搜索工具集 (Bocha)

版本: 1.1
最后更新: 2025-08-22

此脚本将复杂的 Bocha AI Search 功能分解为一系列目标明确、参数极少的独立工具，
专为 AI Agent 调用而设计。Agent 只需根据任务意图（如常规搜索、查找结构化数据或时效性新闻）
选择合适的工具，无需理解复杂的参数组合。

核心特性:
- 强大多模态能力: 能同时返回网页、图片、AI总结、追问建议，以及丰富的“模态卡”结构化数据。
- 模态卡支持: 针对天气、股票、汇率、百科、医疗等特定查询，可直接返回结构化数据卡片，便于Agent直接解析和使用。

主要工具:
- comprehensive_search: 执行全面搜索，返回网页、图片、AI总结及可能的模态卡。
- search_for_structured_data: 专门用于查询天气、股票、汇率等可触发“模态卡”的结构化信息。
- web_search_only: 执行纯网页搜索，不请求AI总结，速度更快。
- search_last_24_hours: 获取过去24小时内的最新信息。
- search_last_week: 获取过去一周内的主要报道。
"""

import os
import json
import sys
from typing import List, Dict, Any, Optional, Literal

# 运行前请确保已安装 requests 库: pip install requests
try:
    import requests
except ImportError:
    raise ImportError("requests 库未安装，请运行 `pip install requests` 进行安装。")

# 添加utils目录到Python路径
current_dir = os.path.dirname(os.path.abspath(__file__))
root_dir = os.path.dirname(os.path.dirname(current_dir))
utils_dir = os.path.join(root_dir, 'utils')
if utils_dir not in sys.path:
    sys.path.append(utils_dir)

from retry_helper import with_graceful_retry, SEARCH_API_RETRY_CONFIG

# --- 1. 数据结构定义 ---
from dataclasses import dataclass, field

@dataclass
class WebpageResult:
    """网页搜索结果"""
    name: str
    url: str
    snippet: str
    display_url: Optional[str] = None
    date_last_crawled: Optional[str] = None

@dataclass
class ImageResult:
    """图片搜索结果"""
    name: str
    content_url: str
    host_page_url: Optional[str] = None
    thumbnail_url: Optional[str] = None
    width: Optional[int] = None
    height: Optional[int] = None

@dataclass
class ModalCardResult:
    """
    模态卡结构化数据结果
    这是 Bocha 搜索的核心特色，用于返回特定类型的结构化信息。
    """
    card_type: str  # 例如: weather_china, stock, baike_pro, medical_common
    content: Dict[str, Any]  # 解析后的JSON内容

@dataclass
class BochaResponse:
    """封装 Bocha API 的完整返回结果，以便在工具间传递"""
    query: str
    conversation_id: Optional[str] = None
    answer: Optional[str] = None  # AI生成的总结答案
    follow_ups: List[str] = field(default_factory=list) # AI生成的追问
    webpages: List[WebpageResult] = field(default_factory=list)
    images: List[ImageResult] = field(default_factory=list)
    modal_cards: List[ModalCardResult] = field(default_factory=list)


# --- 2. 核心客户端与专用工具集 ---

class BochaMultimodalSearch:
    """
    一个包含多种专用多模态搜索工具的客户端。
    每个公共方法都设计为供 AI Agent 独立调用的工具。
    """
    
    BASE_URL = "https://api.bochaai.com/v1/ai-search"

    def __init__(self, api_key: Optional[str] = None):
        """
        初始化客户端。
        Args:
            api_key: Bocha API密钥，若不提供则从环境变量 BOCHA_API_KEY 读取。
        """
        if api_key is None:
            api_key = os.getenv("BOCHA_API_KEY")
            if not api_key:
                raise ValueError("Bocha API Key未找到！请设置 BOCHA_API_KEY 环境变量或在初始化时提供")
        
        self._headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': '*/*'
        }

    def _parse_search_response(self, response_dict: Dict[str, Any], query: str) -> BochaResponse:
        """从API的原始字典响应中解析出结构化的BochaResponse对象"""
        
        final_response = BochaResponse(query=query)
        final_response.conversation_id = response_dict.get('conversation_id')

        messages = response_dict.get('messages', [])
        for msg in messages:
            role = msg.get('role')
            if role != 'assistant':
                continue

            msg_type = msg.get('type')
            content_type = msg.get('content_type')
            content_str = msg.get('content', '{}')
            
            try:
                content_data = json.loads(content_str)
            except json.JSONDecodeError:
                # 如果内容不是合法的JSON字符串（例如纯文本的answer），则直接使用
                content_data = content_str

            if msg_type == 'answer' and content_type == 'text':
                final_response.answer = content_data
            
            elif msg_type == 'follow_up' and content_type == 'text':
                final_response.follow_ups.append(content_data)

            elif msg_type == 'source':
                if content_type == 'webpage':
                    web_results = content_data.get('value', [])
                    for item in web_results:
                        final_response.webpages.append(WebpageResult(
                            name=item.get('name'),
                            url=item.get('url'),
                            snippet=item.get('snippet'),
                            display_url=item.get('displayUrl'),
                            date_last_crawled=item.get('dateLastCrawled')
                        ))
                elif content_type == 'image':
                    final_response.images.append(ImageResult(
                        name=content_data.get('name'),
                        content_url=content_data.get('contentUrl'),
                        host_page_url=content_data.get('hostPageUrl'),
                        thumbnail_url=content_data.get('thumbnailUrl'),
                        width=content_data.get('width'),
                        height=content_data.get('height')
                    ))
                # 所有其他 content_type 都视为模态卡
                else:
                    final_response.modal_cards.append(ModalCardResult(
                        card_type=content_type,
                        content=content_data
                    ))
                    
        return final_response


    @with_graceful_retry(SEARCH_API_RETRY_CONFIG, default_return=BochaResponse(query="搜索失败"))
    def _search_internal(self, **kwargs) -> BochaResponse:
        """内部通用的搜索执行器，所有工具最终都调用此方法"""
        query = kwargs.get("query", "Unknown Query")
        payload = {
            "stream": False,  # Agent工具通常使用非流式以获取完整结果
        }
        payload.update(kwargs)
        
        try:
            response = requests.post(self.BASE_URL, headers=self._headers, json=payload, timeout=30)
            response.raise_for_status()  # 如果HTTP状态码是4xx或5xx，则抛出异常
            
            response_dict = response.json()
            if response_dict.get("code") != 200:
                print(f"API返回错误: {response_dict.get('msg', '未知错误')}")
                return BochaResponse(query=query)

            return self._parse_search_response(response_dict, query)

        except requests.exceptions.RequestException as e:
            print(f"搜索时发生网络错误: {str(e)}")
            raise e  # 让重试机制捕获并处理
        except Exception as e:
            print(f"处理响应时发生未知错误: {str(e)}")
            raise e  # 让重试机制捕获并处理

    # --- Agent 可用的工具方法 ---

    def comprehensive_search(self, query: str, max_results: int = 10) -> BochaResponse:
        """
        【工具】全面综合搜索: 执行一次标准的、包含所有信息类型的综合搜索。
        返回网页、图片、AI总结、追问建议和可能的模态卡。这是最常用的通用搜索工具。
        Agent可提供搜索查询(query)和可选的最大结果数(max_results)。
        """
        print(f"--- TOOL: 全面综合搜索 (query: {query}) ---")
        return self._search_internal(
            query=query,
            count=max_results,
            answer=True  # 开启AI总结
        )
        
    def web_search_only(self, query: str, max_results: int = 15) -> BochaResponse:
        """
        【工具】纯网页搜索: 只获取网页链接和摘要，不请求AI生成答案。
        适用于需要快速获取原始网页信息，而不需要AI额外分析的场景。速度更快，成本更低。
        """
        print(f"--- TOOL: 纯网页搜索 (query: {query}) ---")
        return self._search_internal(
            query=query,
            count=max_results,
            answer=False # 关闭AI总结
        )

    def search_for_structured_data(self, query: str) -> BochaResponse:
        """
        【工具】结构化数据查询: 专门用于可能触发“模态卡”的查询。
        当Agent意图是查询天气、股票、汇率、百科定义、火车票、汽车参数等结构化信息时，应优先使用此工具。
        它会返回所有信息，但Agent应重点关注结果中的 `modal_cards` 部分。
        """
        print(f"--- TOOL: 结构化数据查询 (query: {query}) ---")
        # 实现上与 comprehensive_search 相同，但通过命名和文档引导Agent的意图
        return self._search_internal(
            query=query,
            count=5, # 结构化查询通常不需要太多网页结果
            answer=True
        )

    def search_last_24_hours(self, query: str) -> BochaResponse:
        """
        【工具】搜索24小时内信息: 获取关于某个主题的最新动态。
        此工具专门查找过去24小时内发布的内容。适用于追踪突发事件或最新进展。
        """
        print(f"--- TOOL: 搜索24小时内信息 (query: {query}) ---")
        return self._search_internal(query=query, freshness='oneDay', answer=True)

    def search_last_week(self, query: str) -> BochaResponse:
        """
        【工具】搜索本周信息: 获取关于某个主题过去一周内的主要报道。
        适用于进行周度舆情总结或回顾。
        """
        print(f"--- TOOL: 搜索本周信息 (query: {query}) ---")
        return self._search_internal(query=query, freshness='oneWeek', answer=True)


# --- 3. 测试与使用示例 ---

def print_response_summary(response: BochaResponse):
    """简化的打印函数，用于展示测试结果"""
    if not response or not response.query:
        print("未能获取有效响应。")
        return
        
    print(f"\n查询: '{response.query}' | 会话ID: {response.conversation_id}")
    if response.answer:
        print(f"AI摘要: {response.answer[:150]}...")
    
    print(f"找到 {len(response.webpages)} 个网页, {len(response.images)} 张图片, {len(response.modal_cards)} 个模态卡。")

    if response.modal_cards:
        first_card = response.modal_cards[0]
        print(f"第一个模态卡类型: {first_card.card_type}")

    if response.webpages:
        first_result = response.webpages[0]
        print(f"第一条网页结果: {first_result.name}")

    if response.follow_ups:
        print(f"建议追问: {response.follow_ups}")

    print("-" * 60)


if __name__ == "__main__":
    # 在运行前，请确保您已设置 BOCHA_API_KEY 环境变量
    
    try:
        # 初始化多模态搜索客户端，它内部包含了所有工具
        search_client = BochaMultimodalSearch()

        # 场景1: Agent进行一次常规的、需要AI总结的综合搜索
        response1 = search_client.comprehensive_search(query="人工智能对未来教育的影响")
        print_response_summary(response1)

        # 场景2: Agent需要查询特定结构化信息 - 天气
        response2 = search_client.search_for_structured_data(query="上海明天天气怎么样")
        print_response_summary(response2)
        # 深度解析第一个模态卡
        if response2.modal_cards and response2.modal_cards[0].card_type == 'weather_china':
             print("天气模态卡详情:", json.dumps(response2.modal_cards[0].content, indent=2, ensure_ascii=False))


        # 场景3: Agent需要查询特定结构化信息 - 股票
        response3 = search_client.search_for_structured_data(query="东方财富股票")
        print_response_summary(response3)

        # 场景4: Agent需要追踪某个事件的最新进展
        response4 = search_client.search_last_24_hours(query="C929大飞机最新消息")
        print_response_summary(response4)

        # 场景5: Agent只需要快速获取网页信息，不需要AI总结
        response5 = search_client.web_search_only(query="Python dataclasses用法")
        print_response_summary(response5)
        
        # 场景6: Agent需要回顾一周内关于某项技术的新闻
        response6 = search_client.search_last_week(query="量子计算商业化")
        print_response_summary(response6)
        
        '''下面是测试程序的输出：
        --- TOOL: 全面综合搜索 (query: 人工智能对未来教育的影响) ---

查询: '人工智能对未来教育的影响' | 会话ID: bf43bfe4c7bb4f7b8a3945515d8ab69e
AI摘要: 人工智能对未来教育有着多方面的影响。

从积极影响来看：
- 在教学资源方面，人工智能有助于教育资源的均衡分配[引用:4]。例如通过人工智能云平台，可以实现优质资源的共享，这对于偏远地区来说意义重大，能让那里的学生也接触到优质的教育内 容，一定程度上缓解师资短缺的问题，因为AI驱动的智能教学助手或虚拟...
找到 10 个网页, 1 张图片, 1 个模态卡。
第一个模态卡类型: video
第一条网页结果: 人工智能如何影响教育变革
建议追问: [['人工智能将如何改变未来的教育模式？', '在未来教育中，人工智能会给教师带来哪些挑战？', '未来教育中，学生如何利用人工智能提升学习效果？']]
------------------------------------------------------------
--- TOOL: 结构化数据查询 (query: 上海明天天气怎么样) ---

查询: '上海明天天气怎么样' | 会话ID: e412aa1548cd43a295430e47a62adda2
AI摘要: 根据所给信息，无法确定上海明天的天气情况。

首先，所提供的信息都是关于2025年8月22日的天气状况，包括当天的气温、降水、风力、湿度以及高温预警等信息[引用:1][引用:2][引用:3][引用:5]。然而，这些信息没有涉及到明天（8月23 日）天气的预测内容。虽然提到了副热带高压一直到8月底高温都...
找到 5 个网页, 1 张图片, 2 个模态卡。
第一个模态卡类型: video
第一条网页结果: 今日冲击38!上海八月高温天数和夏季持续高温天数有望双双破纪录_天气_低压_气象站
建议追问: [['能告诉我上海明天的气温范围吗？', '上海明天会有降雨吗？', '上海明天的天气是晴天还是阴天呢？']]
------------------------------------------------------------
--- TOOL: 结构化数据查询 (query: 东方财富股票) ---

查询: '东方财富股票' | 会话ID: 584d62ed97834473b967127852e1eaa0
AI摘要: 仅根据提供的上下文，无法确切获取东方财富股票的相关信息。

从给出的这些数据来看，并没有直接表明与东方财富股票相关的特定数据。例如，没有东方财富股票的涨跌幅情况、成交量、市值等具体数据[引用:1][引用:3]。也没有涉及东方财富股票在研报 、评级方面的信息[引用:2]。同时，上下文里关于股票价格、成交...
找到 5 个网页, 1 张图片, 2 个模态卡。
第一个模态卡类型: video
第一条网页结果: 股票价格_分时成交_行情_走势图—东方财富网
建议追问: [['东方财富股票近期的走势如何？', '东方财富股票有哪些主要的投资亮点？', '东方财富股票的历史最高和最低股价是多少？']]
------------------------------------------------------------
--- TOOL: 搜索24小时内信息 (query: C929大飞机最新消息) ---

查询: 'C929大飞机最新消息' | 会话ID: 5904021dc29d497e938e04db18d7f2e2
AI摘要: 根据提供的上下文，没有关于C929大飞机的直接消息，无法确切给出C929大飞机的最新消息。

目前提供的上下文涵盖了众多航空领域相关事件，但多是围绕波音787、空客A380相关专家的人事变动、国产飞机“C909云端之旅”、科德数控的营收情况、俄制航空发动机供应相关以及其他非C929大飞机相关的内容。...
找到 10 个网页, 1 张图片, 1 个模态卡。
第一个模态卡类型: video
第一条网页结果: 放弃美国千万年薪,波音787顶尖专家回国,或可协助破解C929
建议追问: [['C929大飞机目前的研发进度如何？', '有没有关于C929大飞机预计首飞时间的消息？', 'C929大飞机在技术创新方面有哪些新进展？']]
------------------------------------------------------------
--- TOOL: 纯网页搜索 (query: Python dataclasses用法) ---

查询: 'Python dataclasses用法' | 会话ID: 74c742759d2e4b17b52d8b735ce24537
找到 15 个网页, 1 张图片, 1 个模态卡。
第一个模态卡类型: video
第一条网页结果: 不可不知的dataclasses  python小知识_python dataclasses-CSDN博客
------------------------------------------------------------
--- TOOL: 搜索本周信息 (query: 量子计算商业化) ---

AI摘要: 量子计算商业化正在逐步推进。

量子计算商业化有着多方面的体现和推动因素。从国际上看，美国能源部橡树岭国家实验室选择IQM Radiance作为其首台本地部署的量子计算机，计划于2025年第三季度交付并集成至高性能计算系统中[引用:4]；英国量子计算公司Oxford Ionics的全栈离子阱量子计算...
找到 10 个网页, 1 张图片, 1 个模态卡。
第一个模态卡类型: video
第一条网页结果: 量子计算商业潜力释放正酣,微美全息(WIMI.US)创新科技卡位“生态高地”
建议追问: [['量子计算商业化目前有哪些成功的案例？', '哪些公司在推动量子计算商业化进程？', '量子计算商业化面临的主要挑战是什么？']]
------------------------------------------------------------'''

    except ValueError as e:
        print(f"初始化失败: {e}")
        print("请确保 BOCHA_API_KEY 环境变量已正确设置。")
    except Exception as e:
        print(f"测试过程中发生未知错误: {e}")