"""
  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.
          """
          ...