"""VectorProvider protocol — interface for vector search backends.

Core code depends on this protocol. Plugin implementations (chromadb_vector, etc.)
implement it. Swappable via loader.py registration.
"""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class VectorProvider(Protocol):
    """Protocol for vector search backends (ChromaDB, Pinecone, etc.)."""

    def initialize(self) -> None:
        """Initialize the vector store connection/client."""
        ...

    def add(self, content: str, metadata: dict | None = None) -> str:
        """Add a document. Returns the generated ID."""
        ...

    def search(self, query: str, n_results: int = 5) -> list[dict[str, Any]]:
        """Search for similar documents. Returns list of {id, content, metadata, distance}."""
        ...

    def delete(self, doc_id: str) -> bool:
        """Delete a document by ID. Returns True if deleted."""
        ...

    def count(self) -> int:
        """Return the number of documents in the store."""
        ...

    def rebuild_index(self, docs_dir: Any = None, state_dir: Any = None) -> int:
        """Rebuild the index from source files. Returns count of indexed documents."""
        ...
