Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

4.9 KB
Raw Blame
"""Vector-store provider registry and factory.

Mirrors ``embeddings/embeddings_config.py``: a flat list of valid providers, a
lazily-populated class registry, and a single resolution entry point. Only
FAISS is registered today, and there is no settings key selecting a provider
yet — ``resolve_provider`` always returns ``"faiss"``. The seam exists so a
future backend is a bounded addition (register the class, add a setting) rather
than a rewrite of the call sites.
"""

from typing import Dict, Optional, Type

from .base import BaseVectorStore

VALID_VECTOR_STORE_PROVIDERS = ["faiss"]

_DEFAULT_PROVIDER = "faiss"

# Providers whose store persists to a local file this process owns end to end,
# i.e. ``BaseVectorStore.is_local_file``. Duplicated here as a *cheap* lookup so
# callers that only need to branch on it -- notably the deletion cascade, which
# must choose between unlinking index files and dropping a remote collection --
# don't have to import the backend module just to read a class attribute.
# Importing ``faiss_store`` pulls in the native ``faiss`` extension, which is a
# lot of machinery to load on a path that is about to delete things.
#
# MUST stay in sync with each class's ``is_local_file``; a test asserts it.
# Only local-file providers are listed: an unlisted provider falls through to
# the real class (see ``provider_is_local_file``), which a remote provider has
# to be imported for anyway to call ``drop_collection``.
_LOCAL_FILE_PROVIDERS = frozenset({"faiss"})

# Lazily-populated {provider_key: class}. Populated on first use to avoid
# importing faiss at module import time.
_PROVIDER_CLASSES: Dict[str, Type[BaseVectorStore]] = {}


def _load_provider_classes() -> Dict[str, Type[BaseVectorStore]]:
    if not _PROVIDER_CLASSES:
        from .implementations.segmented_faiss import SegmentedFaissStore

        _PROVIDER_CLASSES[SegmentedFaissStore.provider_key] = (
            SegmentedFaissStore
        )
    return _PROVIDER_CLASSES


def resolve_provider(settings_snapshot: Optional[dict] = None) -> str:
    """Return the configured vector-store provider key.

    No settings key selects this yet — always ``"faiss"``. The
    ``settings_snapshot`` parameter is accepted now so callers don't change when
    a setting is introduced later.
    """
    return _DEFAULT_PROVIDER


def _normalize_provider_key(key: str) -> str:
    """Normalize a provider key from a settings/DB value.

    Such a value may carry surrounding whitespace/quotes/case (mirrors
    ``embeddings_config.get_embeddings``).
    """
    return key.strip().strip("\"'").strip().lower()


def provider_is_local_file(
    provider: Optional[str] = None,
    settings_snapshot: Optional[dict] = None,
) -> bool:
    """Return whether ``provider`` stores its vectors in a local file.

    This is the discriminator between "unlink the index files" and "drop the
    remote collection" on deletion paths (see ``BaseVectorStore.is_local_file``).

    Answers from :data:`_LOCAL_FILE_PROVIDERS` without importing the backend
    when it can; otherwise falls back to the authoritative class attribute.
    """
    key = _normalize_provider_key(
        provider or resolve_provider(settings_snapshot)
    )  # gitleaks:allow
    if key in _LOCAL_FILE_PROVIDERS:
        return True
    return get_vector_store_class(key, settings_snapshot).is_local_file


def only_local_file_providers_registered() -> bool:
    """Return whether every known provider is a local-file store.

    True today (FAISS only). While it holds, which provider a user selected
    cannot change how a deletion cleans up vectors -- every row's files are
    unlinked and nothing is dropped remotely -- so a deletion does not need
    the user's settings snapshot to be trustworthy. The first server-backed
    provider (listed in :data:`VALID_VECTOR_STORE_PROVIDERS` or registered in
    the class registry) makes this False, and callers must then fail closed
    when the snapshot cannot be read (see
    ``cascade_helper.read_vector_cleanup_settings_snapshot``).
    """
    known = set(VALID_VECTOR_STORE_PROVIDERS) | set(_PROVIDER_CLASSES)
    return {_normalize_provider_key(key) for key in known} <= (
        _LOCAL_FILE_PROVIDERS
    )


def get_vector_store_class(
    provider: Optional[str] = None,
    settings_snapshot: Optional[dict] = None,
) -> Type[BaseVectorStore]:
    """Return the :class:`BaseVectorStore` subclass for ``provider``.

    Callers construct instances via the class's ``.create(...)`` / ``.load(...)``
    classmethods (a vector store is stateful, unlike the stateless embeddings
    providers, so the factory hands back the class rather than an instance).
    """
    key = provider or resolve_provider(settings_snapshot)  # gitleaks:allow
    key = _normalize_provider_key(key)
    classes = _load_provider_classes()
    if key not in classes:
        raise ValueError(
            f"Unknown vector-store provider '{key}'. "
            f"Valid providers: {sorted(classes)}"
        )
    return classes[key]