"""Abstract base class for vector search providers."""

from abc import ABC, abstractmethod
from typing import Any, TypedDict


class SearchResult(TypedDict):
    """A single vector search result."""

    id: str
    distance: float
    content: str


class BaseVectorSearch(ABC):
    """Abstract base class for a vector search provider.

    This class defines the standard interface for creating a vector search
    index and running queries against it.
    """

    @abstractmethod
    def create_index(
        self, name: str, content_path: str, **kwargs: Any  # noqa: ANN401
    ) -> None:
        """Create a new vector search index with the provided content.

        Args:
            name: The desired name for the new index.
            content_path: Path to the data used to populate the index.
            **kwargs: Additional provider-specific arguments.

        """
        ...

    @abstractmethod
    def update_index(
        self, index_name: str, content_path: str, **kwargs: Any  # noqa: ANN401
    ) -> None:
        """Update an existing vector search index with new content.

        Args:
            index_name: The name of the index to update.
            content_path: Path to the data used to populate the index.
            **kwargs: Additional provider-specific arguments.

        """
        ...

    @abstractmethod
    def run_query(
        self,
        deployed_index_id: str,
        query: list[float],
        limit: int,
    ) -> list[SearchResult]:
        """Run a similarity search query against the index.

        Args:
            deployed_index_id: The ID of the deployed index.
            query: The embedding vector for the search query.
            limit: Maximum number of nearest neighbors to return.

        Returns:
            A list of matched items with id, distance, and content.

        """
        ...