"""ObserverProvider Protocol — observer 降级链的统一接口"""

from __future__ import annotations

from typing import Protocol


class ObserverProvider(Protocol):
    """Observer provider 接口

    每个 provider 实现 available 检查 + generate/observe_session 调用。
    降级调度器按优先级遍历 providers，首个 available 的执行。
    """

    @property
    def name(self) -> str:
        """Provider 名称（用于 source 标记和日志）"""
        ...

    @property
    def model_name(self) -> str:
        """当前使用的模型名称（写入 context_json 用于溯源）"""
        ...

    @property
    def available(self) -> bool:
        """当前是否可用（含 cooldown 检查）"""
        ...

    async def generate(self, prompt: str) -> str | None:
        """生成 LLM 原始输出（per-tool-call XML 模式）

        Args:
            prompt: 格式化好的 prompt

        Returns:
            原始文本，或 None 表示失败/不可用
        """
        ...

    async def observe_session(self, prompt: str) -> list[dict] | None:
        """执行 session 观察（session-end JSON 模式）

        Args:
            prompt: 格式化好的 prompt（含 session facts）

        Returns:
            fact dict 列表，或 None 表示失败/不可用
        """
        ...

    async def close(self) -> None:
        """释放资源（httpx client 等）"""
        ...
