"""检索请求与响应的数据模型"""

from pydantic import BaseModel, Field


class SearchRequest(BaseModel):
    """检索请求"""

    query: str = Field(description="查询文本")
    top_k: int | None = Field(default=None, description="返回结果数，为空时使用 settings.retrieval_final_k")


class SearchHit(BaseModel):
    """单条检索命中结果"""

    text: str = Field(description="原文 chunk 内容")
    doc_id: str = Field(description="所属文档 ID")
    title: str = Field(default="", description="文档标题")
    section_path: str = Field(default="", description="chunk 所在的章节路径")
    score: float = Field(description="相关性得分")
    doc_summary: str = Field(default="", description="L1 文档总结，仅用于上下文标注")


class SearchResponse(BaseModel):
    """检索响应"""

    query: str = Field(description="原始查询文本")
    hits: list[SearchHit] = Field(default_factory=list, description="命中结果列表")
    routed_categories: list[str] = Field(default_factory=list, description="query 路由命中的类目")
    fallback: bool = Field(default=False, description="是否走了全库兜底路径")