"""Knowledge Graph 向量搜索工具。

提供便捷函数用于执行向量搜索。
"""

import logging
from pathlib import Path

from hezor_common.data_model.searching import (
    VectorSearchResponse,
)
from hezor_common.transfer.base_sdk import MetaInfo
from hezor_common.transfer.knowledge_graph_sdk.base.constants import (
    DEFAULT_API_BASE_URL,
    DEFAULT_API_KEY,
)
from hezor_common.transfer.knowledge_graph_sdk.base.knowledge_graph_api_client import (
    KnowledgeGraphAPIClient,
)

logger = logging.getLogger(__name__)


async def vector_search(
    question: str,
    limit: int = 10,
    score_threshold: float = 0.5,
    offset: int = 0,
    enable_entity_extraction: bool = True,
    base_url: str = DEFAULT_API_BASE_URL,
    api_key: str | None = DEFAULT_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    timeout: float = 120.0,
) -> VectorSearchResponse:
    """执行向量搜索（便捷函数）。

    这是一个便捷函数，内部使用 KnowledgeGraphAPIClient 执行向量搜索。

    Parameters
    ----------
    question : str
        搜索问题
    limit : int
        返回结果数量限制，范围 1-50，默认 10
    score_threshold : float
        相似度阈值，范围 0.0-1.0，默认 0.5
    offset : int
        结果偏移量，用于分页，默认 0
    enable_entity_extraction : bool
        是否启用实体抽取，默认 true
    base_url : str
        API 基础 URL
    api_key : str | None
        API 密钥
    meta_info : MetaInfo | None
        元信息对象
    private_key_path : str | Path | None
        私钥文件路径
    password : bytes | None
        私钥密码
    timeout : float
        请求超时时间（秒）

    Returns
    -------
    VectorSearchResponse
        搜索响应结果，包含按集合分组的搜索结果

    Raises
    ------
    httpx.HTTPError
        如果 HTTP 请求失败
    ValueError
        如果响应数据格式错误

    Examples
    --------
    >>> from hezor_common.transfer.knowledge_graph_sdk import vector_search
    >>> response = await vector_search(
    ...     question="菜品有哪些",
    ...     limit=10,
    ...     score_threshold=0.5
    ... )
    >>> print(f"Question: {response.question}")
    >>> print(f"Found {len(response.search_results.entities)} entities")
    """
    async with KnowledgeGraphAPIClient(
        base_url=base_url,
        api_key=api_key,
        meta_info=meta_info,
        private_key_path=private_key_path,
        password=password,
        timeout=timeout,
    ) as client:
        return await client.vector_search(
            question=question,
            limit=limit,
            score_threshold=score_threshold,
            offset=offset,
            enable_entity_extraction=enable_entity_extraction,
        )


__all__ = ["vector_search"]
