"""Pydantic models for the QA (智能问答) API.

智能问答接口的请求数据模型。
响应复用 research 模块的 ResearchChunk，通过 SSE 流式返回。
QA 材料检索接口返回结构化 JSON 结果。
"""

from __future__ import annotations

from typing import Any

from pydantic import BaseModel, Field


class QARequest(BaseModel):
    """Payload for ``POST /qa``."""

    question: str = Field(..., min_length=1, max_length=2000, description="问答问题")
    session_id: str | None = Field(None, description="可选的问答会话 ID")
    seed_doc_ids: list[str] | None = Field(None, description="显式导入的文档 ID 列表")


class QASearchRequest(BaseModel):
    """Payload for ``POST /qa/search`` — 仅检索材料，不调用 LLM 生成回答。"""

    question: str = Field(..., min_length=1, max_length=2000, description="问答问题")
    seed_doc_ids: list[str] | None = Field(None, description="显式导入的文档 ID 列表")


class QASearchDocument(BaseModel):
    """检索命中的单篇文档信息。"""

    doc_id: str = Field(..., description="文档 ID")
    title: str = Field(default="", description="文档标题")
    doc_number: str | None = Field(None, description="文号")
    issuing_org: str | None = Field(None, description="发文机关")
    doc_type: str | None = Field(None, description="公文种类")
    publish_date: str | None = Field(None, description="发布日期")
    score: float | None = Field(None, description="相关性得分")
    passages: list[str] = Field(default_factory=list, description="匹配的文本摘录")
    source_type: str = Field(default="search", description="来源类型: search | seed | graph | guide")
    source_label: str | None = Field(None, description="来源中文标签")
    profile_id: str | None = Field(None, description="办事指南 profile ID（仅 guide 类型）")
    matched_fields: list[str] | None = Field(None, description="匹配的指南字段（仅 guide 类型）")
    matched_field_labels: list[str] | None = Field(None, description="匹配字段的中文标签（仅 guide 类型）")
    summary: str | None = Field(None, description="办事指南摘要（仅 guide 类型）")


class QASearchResponse(BaseModel):
    """``POST /qa/search`` 的响应 — 检索阶段的完整结果。"""

    question: str = Field(..., description="原始问题")
    keywords: list[str] = Field(default_factory=list, description="LLM 提取的关键词")
    intent: str = Field(default="GENERAL", description="图谱意图分类")
    total: int = Field(default=0, description="命中文档总数")
    documents: list[QASearchDocument] = Field(default_factory=list, description="检索到的文档列表")
    context_text: str = Field(default="", description="格式化的参考材料文本（可直接用于 LLM 输入）")
    graph_evidence_text: str = Field(default="", description="图谱结构化证据文本")
    guide_evidence_text: str = Field(default="", description="办事指南证据文本")