"""
VLM Provider 抽象基类
"""

from abc import ABC, abstractmethod
from typing import List


class VLMProvider(ABC):
    """
    视觉语言模型 Provider 抽象接口
    所有 VLM 后端实现都应该继承此类并实现 chat_vision 方法
    """

    @abstractmethod
    def chat_vision(
        self,
        prompt: str,
        image_paths: List[str],
        temperature: float = 0.1,
        timeout_sec: int = 120,
    ) -> str:
        """
        调用 VLM 进行图像理解

        Args:
            prompt: 用户提示词
            image_paths: 图片路径列表（支持单张或多张）
            temperature: 采样温度（0.0-1.0）
            timeout_sec: 超时时间（秒）

        Returns:
            模型生成的文本响应

        Raises:
            Exception: 调用失败时抛出异常
        """
        pass

    def __repr__(self):
        return f"<{self.__class__.__name__}>"