"""Transport-neutral vector-store contract and canonical vector models."""

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

from tht.vectorstore.records import VectorRecord
from tht.vectorstore.store import VectorHit


@dataclass(frozen=True)
class VectorCapabilities:
    search: bool = True
    existing_hashes: bool = False
    upsert: bool = False


@dataclass(frozen=True)
class VectorHealth:
    ok: bool
    detail: str | None = None


@dataclass(frozen=True)
class VectorWriteRecord:
    """A canonical record plus transport-neutral, precomputed vector data."""

    record: VectorRecord
    embedding: list[float]
    content_hash: str


class VectorStoreError(Exception):
    """Base error exposed by vector adapters."""


class VectorWriteUnavailable(VectorStoreError):
    """Raised when a deployment has no vector writer credential."""


@runtime_checkable
class VectorStore(Protocol):
    @property
    def capabilities(self) -> VectorCapabilities: ...

    def health(self) -> VectorHealth: ...

    def search(
        self,
        collections: list[str],
        embedding: list[float],
        *,
        limit: int,
        kinds: list[str] | None = None,
    ) -> list[VectorHit]: ...

    def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]: ...

    def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int: ...


__all__ = [
    "VectorCapabilities",
    "VectorHealth",
    "VectorHit",
    "VectorRecord",
    "VectorStore",
    "VectorStoreError",
    "VectorWriteRecord",
    "VectorWriteUnavailable",
]