"""LLM 提供商基类。"""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Generator


class LLMBase(ABC):
    """LLM 提供商抽象基类。"""

    @abstractmethod
    def chat(self, system_prompt: str, user_prompt: str) -> str:
        """发送对话请求，返回助手回复的文本内容。

        Args:
            system_prompt: 系统提示词。
            user_prompt: 用户提示词。

        Returns:
            LLM 生成的文本内容。
        """

    @abstractmethod
    def chat_with_history(
        self,
        system_prompt: str,
        messages: list[dict[str, str]],
    ) -> str:
        """带历史消息的对话请求（用于反馈重新生成）。

        Args:
            system_prompt: 系统提示词。
            messages: 消息历史，每条格式为 {"role": "user"|"assistant", "content": "..."}。

        Returns:
            LLM 生成的文本内容。
        """

    def stream_chat(
        self, system_prompt: str, user_prompt: str
    ) -> Generator[str, None, None]:
        """流式对话请求，逐块 yield 生成内容。

        默认实现回退到非流式接口，子类可覆盖以实现真正的 streaming。
        """
        yield self.chat(system_prompt, user_prompt)

    def stream_chat_with_history(
        self,
        system_prompt: str,
        messages: list[dict[str, str]],
    ) -> Generator[str, None, None]:
        """带历史的流式对话请求。

        默认实现回退到非流式接口，子类可覆盖。
        """
        yield self.chat_with_history(system_prompt, messages)
