# app/lib/embedding_providers/base.py
from abc import ABC, abstractmethod
from typing import List


class BaseProvider(ABC):
    """
    Abstract base class for embedding and completion providers.
    All provider implementations must inherit from this class.
    """

    @property
    @abstractmethod
    def dimension(self) -> int:
        """
        Return the dimensionality of embeddings produced by this provider.
        This is used to configure Qdrant collections.
        """
        pass

    @property
    @abstractmethod
    def provider_name(self) -> str:
        """
        Return the name of the provider (e.g., 'openai', 'openrouter', 'claude').
        """
        pass

    @property
    @abstractmethod
    def model_name(self) -> str:
        """
        Return the specific model being used (e.g., 'text-embedding-3-small', 'gpt-4').
        """
        pass

    @abstractmethod
    def get_embeddings(self, texts: List[str]) -> List[List[float]]:
        """
        Generate embeddings for a list of text strings.

        Args:
            texts: List of text strings to embed

        Returns:
            List of embedding vectors (each vector is a list of floats)

        Raises:
            ValueError: If texts is empty or contains invalid data
            RuntimeError: If API call fails
        """
        pass

    @abstractmethod
    def get_completion(self, prompt: str, context: str = "") -> str:
        """
        Generate a completion/response given a prompt and optional context.
        Used for RAG-based question answering.

        Args:
            prompt: The user's question or prompt
            context: Optional context from retrieved documents

        Returns:
            The generated response as a string

        Raises:
            ValueError: If prompt is empty
            RuntimeError: If API call fails
        """
        pass

    def supports_embeddings(self) -> bool:
        """
        Check if this provider supports embedding generation.
        Default: True (most providers support embeddings)
        """
        return True

    def supports_completions(self) -> bool:
        """
        Check if this provider supports completion/chat generation.
        Default: True (most providers support completions)
        """
        return True