"""
Protocols for embedding backends (structural typing, no inheritance required).

Used by the embedding service so that any backend (ClipAsServiceImageEncoder,
ClipImageModel, etc.) can be used as long as it implements the same interface.
"""

from typing import List, Optional, Protocol

import numpy as np


class ImageEncoderProtocol(Protocol):
    """Contract for image encoders used by the embedding service /embed/image endpoint."""

    def encode_image_urls(
        self,
        urls: List[str],
        batch_size: Optional[int] = None,
        normalize_embeddings: bool = True,
    ) -> List[np.ndarray]:
        """
        Encode a list of image URLs to vectors.

        Returns:
            List of vectors, same length as urls. Invalid inputs should raise instead
            of returning partial None placeholders.
        """
        ...

    def encode_clip_texts(
        self,
        texts: List[str],
        batch_size: Optional[int] = None,
        normalize_embeddings: bool = True,
    ) -> List[np.ndarray]:
        """
        Encode natural-language strings with the CLIP/CN-CLIP text tower (same space as images).

        Returns:
            List of vectors, same length as texts.
        """
        ...