"""LLM Provider 抽象接口与数据模型。"""

from __future__ import annotations

import abc
from dataclasses import dataclass, field


@dataclass
class ChatMessage:
    role: str  # "system" | "user" | "assistant"
    content: str


@dataclass
class LLMResponse:
    content: str
    model: str
    provider: str
    # 是否经过出域（公网）通道，便于审计轨迹记录
    egress: bool = False
    raw: dict = field(default_factory=dict)


class LLMProvider(abc.ABC):
    """所有 LLM 实现的统一接口。

    业务代码只依赖本接口；切换公网/本地仅改配置，不改调用方。
    """

    #: provider 名称
    name: str = "base"
    #: 是否走公网（出域）。prod 环境禁止 egress=True 的 provider。
    egress: bool = False

    @abc.abstractmethod
    def chat(self, messages: list[ChatMessage], **kwargs) -> LLMResponse:
        """同步对话补全。"""
        raise NotImplementedError

    @abc.abstractmethod
    def health(self) -> bool:
        """探活：provider 是否可用。"""
        raise NotImplementedError