"""Abstract base class for VectorStore plugins."""
from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class VectorStore(ABC):
    """Interface for vector similarity search backends.

    Implementations: SQLiteVectorStore, QdrantVectorStore
    """

    @abstractmethod
    def upsert(self, id: str, vector: list[float], payload: dict) -> None:
        """Insert or update a vector with payload."""
        ...

    @abstractmethod
    def search(
        self,
        query_vector: list[float],
        limit: int = 10,
        filters: dict[str, Any] | None = None,
    ) -> list[dict]:
        """Search for similar vectors.

        Returns list of dicts with keys: id, score, payload
        """
        ...

    @abstractmethod
    def delete(self, id: str) -> None:
        """Delete a vector by ID."""
        ...

    @abstractmethod
    def update_payload(self, id: str, payload: dict) -> None:
        """Update the payload of an existing vector."""
        ...

    def count(self) -> int:
        """Return the number of stored vectors. Optional override."""
        raise NotImplementedError
