"""
天目引擎协议（Protocol）。

定义统一的引擎接口，两个引擎实现（RapidOCR / PaddleOCR-VL）均遵循此协议。
调用方只需依赖协议，不依赖具体实现。
"""

from __future__ import annotations

from typing import Protocol, runtime_checkable


@runtime_checkable
class OCREngine(Protocol):
    """OCR 引擎统一协议。"""

    loaded: bool

    async def load(self) -> None:
        """初始化并加载模型。"""
        ...

    async def close(self) -> None:
        """释放模型资源。"""
        ...

    async def health(self) -> dict:
        """返回引擎健康状态。"""
        ...


class RapidOCRProtocol(OCREngine, Protocol):
    """RapidOCR 引擎协议（含 recognize 方法）。"""

    async def recognize(self, image_data: bytes | str) -> object:
        """执行 OCR 识别，返回结构化响应。"""
        ...


class PaddleOCRVlProtocol(OCREngine, Protocol):
    """PaddleOCR-VL 引擎协议（含 parse_document 方法）。"""

    async def parse_document(
        self,
        image_data: bytes | str,
        output_format: str = "markdown",
    ) -> object:
        """解析文档图片，返回结构化文本。"""
        ...