"""应用层 Protocol 端口定义。"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    import numpy as np

    from app.tree.index import TreeIndex
    from core.types import GeneratedQuestion


@runtime_checkable
class EmbeddingProvider(Protocol):
    """文本嵌入端口。

    属性:
        dim: 嵌入维度 D。
    """

    @property
    def dim(self) -> int: ...

    def embed(self, texts: str | list[str]) -> np.ndarray:
        """文本 → 嵌入向量（L2 归一化）。

        参数:
            texts: 单条文本或文本列表。

        返回:
            [N, D] ndarray，每行 L2 范数为 1.0。
        """
        ...


@runtime_checkable
class QuestionGenerator(Protocol):
    """LLM 驱动的题目生成端口（预留接口）。

    参数:
        video_id: 视频标识。
        task_type: 题型。
        tree: 视频树索引，提供锚节点上下文。
        exemplars: 风格示例题目列表。

    返回:
        生成的单条题目。
    """

    async def generate(
        self,
        video_id: str,
        task_type: str,
        tree: TreeIndex,
        *,
        exemplars: list[GeneratedQuestion],
    ) -> GeneratedQuestion: ...