"""跨模块共享类型。"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pathlib import Path as _Path


@dataclass(frozen=True)
class LLMResponse:
    """LLM/VLM 调用的统一返回值。

    由 adapters 层生成，core 层消费。frozen=True 确保响应不可变。
    """

    content: str
    thinking: str
    model: str
    provider: str
    prompt_tokens: int
    completion_tokens: int
    latency_ms: int
    ttft_ms: float | None
    max_inter_token_ms: float | None
    cache_hit: bool
    call_id: str


@dataclass(frozen=True)
class GeneratedQuestion:
    """单条生成/加载的题目。

    跨层共享类型，被 core/evolution/ 和 app/harness/、app/question_gen/ 使用。
    frozen=True 确保题目不可变。

    属性:
        question_id: 题目唯一标识。
        video_id: 所属视频标识。
        task_type: 题型（如 "Action Reasoning"）。
        question: 题目文本。
        options: 选项元组（如 ("A. ...", "B. ...", "C. ...", "D. ...")）。
        answer: 正确答案字母（如 "B"）。
        source_nodes: 来源节点 ID 元组。
        difficulty: 难度等级。
        family: 问题家族名称（如 "RETRIEVAL"，v2 出题管线使用，None 表示未指定）。
        skill_target: 目标技能标识（v2 出题管线使用，None 表示未指定）。
        difficulty_steps: 推理步数估计（v2 出题管线使用，None 表示未指定）。
        sub_pattern: 出题子模式标识（AR 特化策略使用，None 表示无）。
    """

    question_id: str
    video_id: str
    task_type: str
    question: str
    options: tuple[str, ...]
    answer: str
    source_nodes: tuple[str, ...]
    difficulty: str
    family: str | None = field(default=None)
    skill_target: str | None = field(default=None)
    difficulty_steps: int | None = field(default=None)
    sub_pattern: str | None = field(default=None)


@dataclass(frozen=True)
class PoolConfig:
    """池构建策略的统一配置。

    两组字段由两个具体策略各取所需，未使用的字段被忽略。

    属性:
        task_types: 限定题型元组；None 表示全部类别。
        seed: 随机种子，保证可复现。
        baseline_run_id: 基线 run 标识。
        diag_size: 诊断池大小（GlobalStrategy 用）。
        diag_correct_ratio: 诊断池中对题占比（GlobalStrategy 用）。
        val_size: 验证池大小（GlobalStrategy 用）。
        val_correct_ratio: 验证池中对题占比（GlobalStrategy 用）。
        test_size: held-out 测试池大小（GlobalStrategy 用）。
        eval_min_per_class: 验证池中每类保底样本数（GlobalStrategy 用）。
        train_ratio: train/(train+val) 比例（PerCategoryStrategy 用）。
        test_questions_dir: 外部 test 题源路径（PerCategoryStrategy 用）。
    """

    task_types: tuple[str, ...] | None
    seed: int
    baseline_run_id: str
    diag_size: int
    diag_correct_ratio: float
    val_size: int
    val_correct_ratio: float
    test_size: int
    eval_min_per_class: int
    train_ratio: float
    test_questions_dir: _Path | None
    batch_correct_ratio: float | None = None
