"""工具列表和分组的便捷函数。

提供简化的函数接口用于快速访问工具列表、分组和统计信息。
"""

import logging
from pathlib import Path
from typing import Any

from hezor_common.data_model.searching.data.api_models import (
    ToolsListResponse,
)
from hezor_common.transfer.base_sdk import MetaInfo
from hezor_common.transfer.datahub_sdk.base.constants import (
    DEFAULT_DATA_API_BASE_URL,
    DEFAULT_DATA_API_KEY,
)
from hezor_common.transfer.datahub_sdk.base.data_api_client import DataAPIClient

logger = logging.getLogger(__name__)


async def list_tools(
    base_url: str = DEFAULT_DATA_API_BASE_URL,
    api_key: str | None = DEFAULT_DATA_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600,
) -> ToolsListResponse:
    """列出所有工具的便捷函数。

    Parameters
    ----------
    base_url : str
        API基础URL
    api_key : str | None
        API密钥，用于Bearer token认证
    meta_info : MetaInfo | None
        元信息对象，用于生成请求头
    private_key_path : str | Path | None
        私钥文件路径，用于JWT签名
    password : bytes | None
        私钥密码
    meta_info_expires_in : int
        MetaInfo JWT token过期时间（秒）

    Returns
    -------
    ToolsListResponse
        工具列表响应，包含工具总数和工具列表

    Examples
    --------
    >>> response = await list_tools()
    >>> print(f"Total: {response.total}")
    >>> for tool in response.tools:
    ...     print(f"Tool: {tool.name}")
    """
    async with DataAPIClient(
        base_url=base_url,
        api_key=api_key,
        meta_info=meta_info,
        private_key_path=private_key_path,
        password=password,
        meta_info_expires_in=meta_info_expires_in,
    ) as client:
        return await client.list_tools()


async def get_tool_groups(
    base_url: str = DEFAULT_DATA_API_BASE_URL,
    api_key: str | None = DEFAULT_DATA_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600,
) -> list[str]:
    """获取所有工具分组的便捷函数。

    Parameters
    ----------
    base_url : str
        API基础URL
    api_key : str | None
        API密钥，用于Bearer token认证
    meta_info : MetaInfo | None
        元信息对象，用于生成请求头
    private_key_path : str | Path | None
        私钥文件路径，用于JWT签名
    password : bytes | None
        私钥密码
    meta_info_expires_in : int
        MetaInfo JWT token过期时间（秒）

    Returns
    -------
    list[str]
        工具分组名称列表

    Examples
    --------
    >>> groups = await get_tool_groups()
    >>> for group in groups:
    ...     print(f"Group: {group}")
    """
    async with DataAPIClient(
        base_url=base_url,
        api_key=api_key,
        meta_info=meta_info,
        private_key_path=private_key_path,
        password=password,
        meta_info_expires_in=meta_info_expires_in,
    ) as client:
        return await client.get_tool_groups()


async def get_tools_by_group(
    group: str | None = None,
    base_url: str = DEFAULT_DATA_API_BASE_URL,
    api_key: str | None = DEFAULT_DATA_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600,
) -> ToolsListResponse:
    """按分组获取工具的便捷函数。

    Parameters
    ----------
    group : str | None
        分组名称，如果不指定则返回所有工具
    base_url : str
        API基础URL
    api_key : str | None
        API密钥，用于Bearer token认证
    meta_info : MetaInfo | None
        元信息对象，用于生成请求头
    private_key_path : str | Path | None
        私钥文件路径，用于JWT签名
    password : bytes | None
        私钥密码
    meta_info_expires_in : int
        MetaInfo JWT token过期时间（秒）

    Returns
    -------
    ToolsListResponse
        工具列表响应，包含工具总数和工具列表

    Examples
    --------
    >>> response = await get_tools_by_group("餐饮/收入")
    >>> for tool in response.tools:
    ...     print(f"Tool: {tool.name}")
    """
    async with DataAPIClient(
        base_url=base_url,
        api_key=api_key,
        meta_info=meta_info,
        private_key_path=private_key_path,
        password=password,
        meta_info_expires_in=meta_info_expires_in,
    ) as client:
        return await client.get_tools_by_group(group)


async def get_tools_stats(
    base_url: str = DEFAULT_DATA_API_BASE_URL,
    api_key: str | None = DEFAULT_DATA_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600,
) -> dict[str, Any]:
    """获取工具调用统计汇总的便捷函数。

    Parameters
    ----------
    base_url : str
        API基础URL
    api_key : str | None
        API密钥，用于Bearer token认证
    meta_info : MetaInfo | None
        元信息对象，用于生成请求头
    private_key_path : str | Path | None
        私钥文件路径，用于JWT签名
    password : bytes | None
        私钥密码
    meta_info_expires_in : int
        MetaInfo JWT token过期时间（秒）

    Returns
    -------
    dict[str, Any]
        工具统计汇总信息

    Examples
    --------
    >>> stats = await get_tools_stats()
    >>> print(f"Total tools: {stats.get('total_tools')}")
    """
    async with DataAPIClient(
        base_url=base_url,
        api_key=api_key,
        meta_info=meta_info,
        private_key_path=private_key_path,
        password=password,
        meta_info_expires_in=meta_info_expires_in,
    ) as client:
        return await client.get_tools_stats()
