app/embeddings/base.py

"""Abstract base class for all embedding clients."""

from abc import ABC, abstractmethod


class EmbeddingClient(ABC):
    """Interface for obtaining dense vector representations of text.

    Implementors must provide both single and batched variants.  The batched
    variant should be preferred for throughput when indexing many chunks.

    Example::

        client = MockEmbeddingClient()
        vector = client.get_embedding("hello world")
        vectors = client.get_embeddings(["hello", "world"])
    """

    @abstractmethod
    def get_embedding(self, text: str) -> list[float]:
        """Return the embedding vector for a single text string.

        Args:
            text: Input text (should be ≤ model token limit).

        Returns:
            Dense float vector of the model's output dimensionality.
        """
        ...

    @abstractmethod
    def get_embeddings(self, texts: list[str]) -> list[list[float]]:
        """Return embedding vectors for a batch of text strings.

        Args:
            texts: List of input strings.

        Returns:
            List of dense float vectors in the same order as ``texts``.
        """
        ...

    @property
    @abstractmethod
    def dimension(self) -> int:
        """The output dimensionality of the embedding model.

        Returns:
            Integer vector dimension (e.g. 1536 for text-embedding-3-small).
        """
        ...