"""图片多模态识别接口（预留，暂未实现）

将来接入多模态 LLM 识别图片内容（表情包梗、截图内容、图片类型等），
识别结果按 hash 缓存到 persona_image 表，分析层组装窗口时把图片描述
带给总结 LLM（"他发了一张猫猫梗图" ≫ "[图片×1]"）。

实现原则：
1. 识别走异步后台任务，绝不在消息采集路径同步调用 LLM
2. 同一 hash 只识别一次（表情包反复发不重复花钱）
3. 识别失败不影响采集（结果可空）
"""

from typing import Optional

from nonebot import logger


class BaseImageRecognizer:
    """图片识别基类：子类实现 describe"""

    async def describe(self, image_url: str) -> Optional[str]:
        raise NotImplementedError


class NoopImageRecognizer(BaseImageRecognizer):
    """占位实现：未启用时使用，什么都不做"""

    async def describe(self, image_url: str) -> Optional[str]:
        return None


# 当前识别器实例（预留：接入多模态 LLM 时替换为真实实现）
recognizer: BaseImageRecognizer = NoopImageRecognizer()
logger.debug("galgame_card | 图片识别接口已预留（当前为占位实现，未启用）")