# 中文注释：
# 文件：echobot/agent/tools/base.py
# 说明：智能体工具层，实现文件、Shell、网络与消息等工具调用能力。

"""Tool Base Class - 工具基类
=================================================

此模块定义了所有工具的抽象基类。

Tool 抽象类的职责：
1. 定义工具的接口规范
2. 提供工具元数据（名称、描述、参数）
3. 提供 OpenAI 函数调用格式的转换

工具实现要求：
- 继承 Tool 抽象类
- 实现所有抽象属性和方法
- 异步执行（async def execute）

使用示例：
    class ReadFileTool(Tool):
        @property
        def name(self) -> str:
            return "read_file"
        
        @property
        def description(self) -> str:
            return "Read the contents of a file"
        
        @property
        def parameters(self) -> dict:
            return {...}
        
        async def execute(self, path: str, **kwargs) -> str:
            return file.read_text()
"""

from abc import ABC, abstractmethod
from typing import Any


class Tool(ABC):
    """
    工具抽象基类
    
    所有工具必须继承此类并实现以下属性和方法：
    
    属性：
    - name: 工具名称（用于函数调用）
    - description: 工具描述（供 LLM 理解用途）
    - parameters: JSON Schema 格式的参数定义
    
    方法：
    - execute(): 执行工具逻辑，返回字符串结果
    - to_schema(): 转换为 OpenAI 函数格式
    """
    
    @property
    @abstractmethod
    def name(self) -> str:
        """工具名称，用于函数调用标识"""
        pass
    
    @property
    @abstractmethod
    def description(self) -> str:
        """工具功能描述，帮助 LLM 理解何时使用此工具"""
        pass
    
    @property
    @abstractmethod
    def parameters(self) -> dict[str, Any]:
        """JSON Schema 格式的工具参数定义"""
        pass
    
    @abstractmethod
    async def execute(self, **kwargs: Any) -> str:
        """
        执行工具逻辑
        
        Args:
            **kwargs: 工具参数（由 LLM 提供）
        
        Returns:
            str: 执行结果文本
        """
        pass
    
    def to_schema(self) -> dict[str, Any]:
        """
        转换为 OpenAI 函数调用格式
        
        Returns:
            dict: 符合 OpenAI Function Calling 规范的 Schema
        """
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": self.parameters,
            }
        }
