fasterrag 0.1.0b1__py3-none-any.whl

fasterrag/__init__.py

@@ -0,0 +1,26 @@
+"""fasterRag — a backend-only Retrieval-Augmented Generation framework.
+
+The importable package is one of three control surfaces (REST API, CLI, library) that
+all call the same service layer, so behavior, configuration, and errors are identical
+everywhere. The public compatibility contract is specified in ``docs/python-api.md``:
+names exported here and from documented submodules are stable under SemVer; anything
+under ``fasterrag._internal`` or absent from ``__all__`` is private.
+"""
+
+__version__ = "0.1.0b1"
+
+# CRITICAL: imported lazily through __getattr__, not at module import. Importing the facade
+# eagerly would pull the adapter factories, the chunking stack, and pydantic-settings into
+# every `import fasterrag` — including `fasterrag.__version__` in a packaging script, and
+# the CLI's own startup. The facade costs roughly a second to import; a version read should
+# not.
+__all__ = ["FasterRag", "__version__"]
+
+
+def __getattr__(name: str) -> object:
+    """Resolve the documented lazy exports on first access."""
+    if name == "FasterRag":
+        from fasterrag.facade import FasterRag
+
+        return FasterRag
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

fasterrag/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Vendor isolation boundary.
+
+Every third-party client lives behind an adapter interface, and no vendor type ever
+escapes this package: core code imports ``VectorDBAdapter``, never ``qdrant_client``.
+That is what makes ``vector_db.provider`` a one-line config change rather than a
+refactor (``docs/adr/ADR-0002``).
+"""

fasterrag/adapters/embeddings/__init__.py

@@ -0,0 +1,36 @@
+"""Embedding provider adapters, the factory, and the tiered-embedding router."""
+
+from fasterrag.adapters.embeddings.base import EmbeddingAdapter, EmbeddingResult
+from fasterrag.adapters.embeddings.cohere import CohereEmbedder
+from fasterrag.adapters.embeddings.factory import (
+    ENTRY_POINT_GROUP,
+    available_providers,
+    create_embedding_adapter,
+    resolve_adapter_class,
+)
+from fasterrag.adapters.embeddings.huggingface import HuggingFaceEmbedder
+from fasterrag.adapters.embeddings.ollama import OllamaEmbedder
+from fasterrag.adapters.embeddings.openai import OpenAIEmbedder
+from fasterrag.adapters.embeddings.sync import SentenceEmbedderBridge
+from fasterrag.adapters.embeddings.tiering import (
+    TieringRouter,
+    create_embedding_router,
+    matches,
+)
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "CohereEmbedder",
+    "EmbeddingAdapter",
+    "EmbeddingResult",
+    "HuggingFaceEmbedder",
+    "OllamaEmbedder",
+    "OpenAIEmbedder",
+    "SentenceEmbedderBridge",
+    "TieringRouter",
+    "available_providers",
+    "create_embedding_adapter",
+    "create_embedding_router",
+    "matches",
+    "resolve_adapter_class",
+]

fasterrag/adapters/embeddings/base.py

@@ -0,0 +1,317 @@
+"""Vendor-neutral embedding provider contract.
+
+Two calls, deliberately separated: documents and queries embed through different paths
+because several models require different instruction prefixes for each, and conflating
+them quietly costs retrieval quality.
+
+Adapters report ``model`` and ``model_version``. Those two values are recorded on every
+chunk and in the index lockfile, and they are the anchor drift detection compares against
+(D1, ``docs/data-model.md``) — an adapter that reports a vague version makes drift
+undetectable.
+
+Adapters report billed usage on ``EmbeddingResult.total_tokens`` when the provider states
+it, mirroring ``Completion.prompt_tokens`` on the generation side. It is the *provider's*
+figure, not ours: the embedding pool prices it through ``services.estimation`` so a bill can
+be reconciled against an invoice rather than against our own tokenizer's guess. A provider
+that states nothing reports ``None``, never ``0``.
+
+Adapters do not retry. They classify failures — setting ``retryable`` from what the
+provider actually said — and the embedding worker pool owns backoff, so retry policy
+lives in exactly one place (``docs/reliability.md`` §2).
+
+Two refusals say more than "retry" or "do not" (TASK-0478). A request refused for its size —
+``413``, or a token or batch limit named in the message — is an :class:`EmbedTooLargeError`:
+the same request will fail forever, but a smaller one may not, so the pool halves the batch
+instead of retrying it. A retryable refusal that names a pause in ``Retry-After`` (or
+OpenAI's ``retry-after-ms``) is an :class:`EmbedThrottledError` carrying it, so the pool can
+wait as long as it was asked rather than as long as its own backoff guesses. A plugin
+adapter raises either one to get the same treatment.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from email.utils import mktime_tz, parsedate_tz
+from typing import ClassVar, Final
+
+from fasterrag.adapters.vectordb.base import HealthStatus
+from fasterrag.config.schema import Settings
+from fasterrag.errors import ConfigError, EmbedError, ErrorCode
+
+__all__ = [
+    "ADAPTER_API_VERSION",
+    "EmbedThrottledError",
+    "EmbedTooLargeError",
+    "EmbeddingAdapter",
+    "EmbeddingResult",
+    "classify_provider_failure",
+    "require_extra",
+    "require_key",
+    "retry_after_seconds",
+    "sum_reported",
+]
+
+ADAPTER_API_VERSION: Final = "1.0"
+
+_AUTH_STATUSES: Final[frozenset[int]] = frozenset({401, 403})
+_TIMEOUT_STATUSES: Final[frozenset[int]] = frozenset({408, 504})
+_SERVER_ERROR_THRESHOLD: Final = 500
+_RATE_LIMITED: Final = 429
+_PROGRAMMING_ERRORS: Final[tuple[type[BaseException], ...]] = (TypeError, AttributeError)
+_PAYLOAD_TOO_LARGE: Final = 413
+_SIZE_STATUSES: Final[frozenset[int]] = frozenset({400, 413, 422, 500})
+_SIZE_MESSAGE: Final = re.compile(
+    r"context length|too many tokens|token limit|tokens per request|too large|too long"
+    r"|number of (?:texts|inputs)|too many (?:texts|inputs)|max(?:imum)? input",
+    re.IGNORECASE,
+)
+_SECONDS: Final = re.compile(r"^\s*\d+(?:\.\d+)?\s*$")
+_MILLISECONDS: Final = 1000.0
+
+
+class EmbedTooLargeError(EmbedError):
+    """The provider refused a request for its size: send less, not the same again."""
+
+    def __init__(self, detail: str, *, trace_id: str | None = None) -> None:
+        """Build the error; it is never retryable as sent."""
+        super().__init__(detail, trace_id=trace_id, retryable=False)
+
+
+class EmbedThrottledError(EmbedError):
+    """A retryable refusal that named how long to wait before the next attempt."""
+
+    def __init__(
+        self, detail: str, *, retry_after_seconds: float, trace_id: str | None = None
+    ) -> None:
+        """Build the error with the pause the provider asked for, in seconds."""
+        super().__init__(detail, trace_id=trace_id, retryable=True)
+        self.retry_after_seconds = retry_after_seconds
+
+
+def require_extra(provider: str, package: str, extra: str) -> ConfigError:
+    """Return the error explaining which optional install a provider needs."""
+    return ConfigError(
+        f"embeddings.provider is {provider!r}, which needs the {package} package; "
+        f"install it with 'pip install \"fasterrag[{extra}]\"'"
+    )
+
+
+def require_key(name: str | None, provider: str) -> str:
+    """Return the credential a provider needs, or explain what is missing."""
+    if not name:
+        raise ConfigError(f"embeddings.api_key_env must name a variable for provider {provider!r}")
+
+    value = os.environ.get(name)
+    if not value or not value.strip():
+        raise ConfigError(f"the {name} environment variable is not set")
+    return value
+
+
+def _headers(exc: BaseException) -> Mapping[str, str] | None:
+    """Return the response headers a vendor error carries, wherever its SDK put them."""
+    headers = getattr(exc, "headers", None)
+    if not isinstance(headers, Mapping):
+        headers = getattr(getattr(exc, "response", None), "headers", None)
+    if not isinstance(headers, Mapping):
+        return None
+    return {str(name).lower(): str(value) for name, value in headers.items()}
+
+
+def _number(value: str | None) -> float | None:
+    """Return a non-negative decimal header value, or ``None`` when it is not one."""
+    if value is None or not _SECONDS.match(value):
+        return None
+    number = float(value)
+    return number if math.isfinite(number) else None
+
+
+def retry_after_seconds(exc: BaseException) -> float | None:
+    """Return the pause a refusal asked for, from ``retry-after-ms`` or ``Retry-After``.
+
+    Seconds or an HTTP date; anything unreadable is ``None`` and a date already past is 0.
+    """
+    headers = _headers(exc)
+    if headers is None:
+        return None
+
+    milliseconds = _number(headers.get("retry-after-ms"))
+    if milliseconds is not None:
+        return milliseconds / _MILLISECONDS
+
+    raw = headers.get("retry-after")
+    seconds = _number(raw)
+    if seconds is not None or raw is None:
+        return seconds
+
+    parsed = parsedate_tz(raw)
+    if parsed is None:
+        return None
+    return max(float(mktime_tz(parsed)) - time.time(), 0.0)
+
+
+def _refused_for_size(exc: BaseException, status: int | None) -> bool:
+    """Return whether the provider refused the request because of how much it carried."""
+    if status == _PAYLOAD_TOO_LARGE:
+        return True
+    if status not in _SIZE_STATUSES:
+        return False
+    message = f"{exc} {getattr(exc, 'body', '')}"
+    return _SIZE_MESSAGE.search(message) is not None
+
+
+def classify_provider_failure(
+    exc: BaseException,
+    *,
+    provider: str,
+    operation: str,
+    key_env: str | None,
+) -> EmbedError:
+    """Translate a provider failure into a typed, correctly-classified error."""
+    status = getattr(exc, "status_code", None)
+    if not isinstance(status, int):
+        status = None
+
+    if status is None and isinstance(exc, _PROGRAMMING_ERRORS):
+        return EmbedError(
+            f"the {provider} adapter raised {type(exc).__name__} during {operation}; this is "
+            "a fault in the adapter or a client library version it was not written against, "
+            "not a provider outage",
+            code=ErrorCode.INTERNAL,
+            retryable=False,
+        )
+
+    if status in _AUTH_STATUSES:
+        named = key_env or "embeddings.api_key_env"
+        return EmbedError(
+            f"{provider} rejected the credentials during {operation}; check the key in the "
+            f"{named} environment variable",
+            retryable=False,
+        )
+
+    if _refused_for_size(exc, status):
+        return EmbedTooLargeError(
+            f"{provider} refused the request as too large during {operation} (status {status}); "
+            "the batch will be split, and an input refused on its own exceeds the model's limit"
+        )
+
+    if status in _TIMEOUT_STATUSES:
+        return EmbedError(
+            f"{provider} timed out during {operation}",
+            code=ErrorCode.EMBED_PROVIDER_TIMEOUT,
+            retryable=True,
+        )
+
+    if status == _RATE_LIMITED or (status is not None and status >= _SERVER_ERROR_THRESHOLD):
+        pause = retry_after_seconds(exc)
+        if pause is not None:
+            return EmbedThrottledError(
+                f"{provider} returned status {status} during {operation} and asked for a "
+                f"{pause:.1f}s pause",
+                retry_after_seconds=pause,
+            )
+        return EmbedError(
+            f"{provider} returned status {status} during {operation}",
+            retryable=True,
+        )
+
+    if status is not None:
+        return EmbedError(
+            f"{provider} returned status {status} during {operation}",
+            retryable=False,
+        )
+
+    if isinstance(exc, TimeoutError):
+        return EmbedError(
+            f"{provider} timed out during {operation}",
+            code=ErrorCode.EMBED_PROVIDER_TIMEOUT,
+            retryable=True,
+        )
+
+    return EmbedError(
+        f"{provider} was unreachable during {operation}: {type(exc).__name__}",
+        retryable=True,
+    )
+
+
+def sum_reported(values: Sequence[int | None]) -> int | None:
+    """Return the batch total, or ``None`` when any batch reported no usage.
+
+    All-or-nothing on purpose: a partial sum is an under-count, and an under-count
+    reconciles wrong against an invoice while looking like a receipt.
+    """
+    if any(value is None for value in values):
+        return None
+    return sum(value for value in values if value is not None)
+
+
+@dataclass(frozen=True, slots=True)
+class EmbeddingResult:
+    """Vectors for a batch, with the model that produced them."""
+
+    vectors: list[list[float]]
+    model: str
+    model_version: str
+    total_tokens: int | None = None
+    """Tokens the provider said it billed, or ``None`` when it reported none.
+
+    ``None`` and ``0`` are different facts and must stay different: ``0`` means nothing was
+    billed (a fully cached batch), while ``None`` means there is no receipt to reconcile
+    against an invoice. Collapsing the two prices unreported traffic as free.
+    """
+
+
+class EmbeddingAdapter(ABC):
+    """Vendor-neutral embedding contract."""
+
+    provider: ClassVar[str]
+
+    def __init__(self, settings: Settings) -> None:
+        """Build the adapter from validated configuration."""
+        self.settings = settings
+        self.config = settings.embeddings
+
+    @property
+    @abstractmethod
+    def model(self) -> str:
+        """Return the model identifier recorded on every chunk."""
+
+    @property
+    @abstractmethod
+    def model_version(self) -> str:
+        """Return the model version, the anchor drift detection compares against."""
+
+    @property
+    @abstractmethod
+    def dimensions(self) -> int | None:
+        """Return the vector size, or None until it is known."""
+
+    @abstractmethod
+    async def embed_documents(self, texts: Sequence[str]) -> EmbeddingResult:
+        """Embed passages for indexing, batched per ``embeddings.batch_size``."""
+
+    @abstractmethod
+    async def embed_query(self, text: str) -> list[float]:
+        """Embed a single query."""
+
+    @abstractmethod
+    async def health(self) -> HealthStatus:
+        """Report whether the provider is usable, without raising."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release any client or model the adapter holds."""
+
+    def batches(self, texts: Sequence[str]) -> list[Sequence[str]]:
+        """Split ``texts`` into request-sized batches.
+
+        Batched embedding is far cheaper than one call per text, so every adapter
+        batches; doing it here means no adapter can forget.
+        """
+        size = self.config.batch_size
+        return [texts[start : start + size] for start in range(0, len(texts), size)]

fasterrag/adapters/embeddings/cohere.py

@@ -0,0 +1,153 @@
+"""Cohere embedding provider.
+
+Cohere requires an ``input_type`` naming what is being embedded, and it genuinely changes
+the vectors: passages must be embedded as ``search_document`` and queries as
+``search_query``. Embedding both the same way is a silent retrieval-quality loss, which is
+why the contract separates the two calls.
+
+Cohere states what it billed on every embed response, and the adapter surfaces it as
+``EmbeddingResult.total_tokens`` so spend is reconciled against the provider's own figure
+rather than a local token estimate. Per the API reference for ``/v1/embed`` the response
+carries an optional ``meta.billed_units`` whose ``input_tokens`` counts the billable text
+units; the adapter reads that rather than ``meta.tokens``, because the invoice is charged
+on the billed units and the two are allowed to differ.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Final
+
+from fasterrag.adapters.embeddings.base import (
+    EmbeddingAdapter,
+    EmbeddingResult,
+    classify_provider_failure,
+    require_extra,
+    require_key,
+    sum_reported,
+)
+from fasterrag.adapters.vectordb.base import HealthStatus
+from fasterrag.config.schema import Settings
+from fasterrag.errors import ConfigError, EmbedError
+
+__all__ = ["CohereEmbedder"]
+
+_DOCUMENT_INPUT: Final = "search_document"
+_QUERY_INPUT: Final = "search_query"
+
+
+class CohereEmbedder(EmbeddingAdapter):
+    """Embeds through Cohere's embed API."""
+
+    provider = "cohere"
+
+    def __init__(self, settings: Settings) -> None:
+        """Build the adapter without opening a connection."""
+        super().__init__(settings)
+        self._client: Any | None = None
+        self._timeout = settings.reliability.timeouts.embeddings_ms / 1000
+
+    @property
+    def model(self) -> str:
+        """Return the configured model id."""
+        return self.config.model
+
+    @property
+    def model_version(self) -> str:
+        """Return the model version; the pinned model id is the most specific available."""
+        return self.config.model
+
+    @property
+    def dimensions(self) -> int | None:
+        """Return the configured dimensionality override, if any."""
+        return self.config.dimensions
+
+    def _connected(self) -> Any:
+        """Return the client, building it on first use."""
+        if self._client is None:
+            try:
+                from cohere import AsyncClient
+            except ImportError as exc:
+                raise require_extra(self.provider, "cohere", "cohere") from exc
+
+            self._client = AsyncClient(
+                api_key=require_key(self.config.api_key_env, self.provider),
+                timeout=self._timeout,
+            )
+        return self._client
+
+    async def _embed(
+        self, texts: Sequence[str], input_type: str
+    ) -> tuple[list[list[float]], int | None]:
+        """Embed one batch, returning vectors and the tokens Cohere says it billed."""
+        try:
+            response = await self._connected().embed(
+                texts=list(texts),
+                model=self.config.model,
+                input_type=input_type,
+                embedding_types=["float"],
+            )
+        except ConfigError:
+            raise
+        # CRITICAL: the catch stays broad because the SDK raises a deep hierarchy of
+        # transport and API errors. Every one must become a typed EmbedError so the worker
+        # pool can decide whether to retry instead of a vendor exception escaping.
+        except Exception as exc:
+            raise classify_provider_failure(
+                exc,
+                provider=self.provider,
+                operation="embed",
+                key_env=self.config.api_key_env,
+            ) from exc
+
+        vectors = getattr(response.embeddings, "float_", None) or getattr(
+            response.embeddings, "float", None
+        )
+        if vectors is None:
+            raise EmbedError("cohere returned no float embeddings", retryable=False)
+        return [list(vector) for vector in vectors], _billed_tokens(response)
+
+    async def embed_documents(self, texts: Sequence[str]) -> EmbeddingResult:
+        """Embed passages as search documents."""
+        vectors: list[list[float]] = []
+        billed: list[int | None] = []
+        for batch in self.batches(texts):
+            batch_vectors, tokens = await self._embed(batch, _DOCUMENT_INPUT)
+            vectors.extend(batch_vectors)
+            billed.append(tokens)
+
+        return EmbeddingResult(
+            vectors=vectors,
+            model=self.model,
+            model_version=self.model_version,
+            total_tokens=sum_reported(billed),
+        )
+
+    async def embed_query(self, text: str) -> list[float]:
+        """Embed a single query as a search query."""
+        vectors, _ = await self._embed([text], _QUERY_INPUT)
+        return vectors[0]
+
+    async def health(self) -> HealthStatus:
+        """Report reachability with a minimal, non-destructive call."""
+        try:
+            await self._embed(["health check"], _QUERY_INPUT)
+        except (ConfigError, EmbedError) as exc:
+            return HealthStatus(healthy=False, detail=exc.detail)
+        return HealthStatus(healthy=True, detail=f"{self.provider} reachable")
+
+    async def close(self) -> None:
+        """Close the client."""
+        self._client = None
+
+
+def _billed_tokens(response: Any) -> int | None:
+    """Return the input tokens Cohere billed, or None when it stated none.
+
+    Every level of ``meta`` is optional in the reference, so a missing one means "no
+    receipt" rather than "free".
+    """
+    meta = getattr(response, "meta", None)
+    billed = getattr(meta, "billed_units", None) if meta is not None else None
+    tokens = getattr(billed, "input_tokens", None) if billed is not None else None
+    return None if tokens is None else int(tokens)

fasterrag/adapters/embeddings/factory.py

@@ -0,0 +1,83 @@
+"""Selects the concrete embedding adapter from configuration.
+
+Mirrors the vector database factory: ``embeddings.provider`` is the whole selection
+surface, third parties register providers through the ``fasterrag.embeddings`` entry
+point, and built-in names always win so an installed package cannot take over
+``huggingface`` and silently reroute a deployment's vectors.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import EntryPoint, entry_points
+from typing import Final
+
+from fasterrag.adapters.embeddings.base import ADAPTER_API_VERSION, EmbeddingAdapter
+from fasterrag.adapters.plugin_api import require_compatible_api
+from fasterrag.config.schema import Settings
+from fasterrag.errors import ConfigError
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "available_providers",
+    "create_embedding_adapter",
+    "resolve_adapter_class",
+]
+
+ENTRY_POINT_GROUP: Final = "fasterrag.embeddings"
+
+_BUILTIN_ADAPTERS: Final[dict[str, str]] = {
+    "huggingface": "fasterrag.adapters.embeddings.huggingface:HuggingFaceEmbedder",
+    "openai": "fasterrag.adapters.embeddings.openai:OpenAIEmbedder",
+    "cohere": "fasterrag.adapters.embeddings.cohere:CohereEmbedder",
+    "ollama": "fasterrag.adapters.embeddings.ollama:OllamaEmbedder",
+}
+
+
+def _plugin_entry_points() -> dict[str, EntryPoint]:
+    """Return third-party embedding providers registered under the entry-point group."""
+    return {entry.name: entry for entry in entry_points(group=ENTRY_POINT_GROUP)}
+
+
+def available_providers() -> dict[str, str]:
+    """Return every selectable provider name mapped to where it came from."""
+    providers = dict.fromkeys(_BUILTIN_ADAPTERS, "built-in")
+    for name, entry in _plugin_entry_points().items():
+        if name not in providers:
+            providers[name] = f"plugin ({entry.value})"
+    return providers
+
+
+def _require_adapter_class(loaded: object, source: str) -> type[EmbeddingAdapter]:
+    """Confirm a resolved object really implements the embedding contract."""
+    if not (isinstance(loaded, type) and issubclass(loaded, EmbeddingAdapter)):
+        raise ConfigError(
+            f"{source} is not an EmbeddingAdapter subclass; a registered provider must "
+            "implement the adapter contract"
+        )
+    return loaded
+
+
+def resolve_adapter_class(provider: str) -> type[EmbeddingAdapter]:
+    """Return the adapter class registered for ``provider``."""
+    builtin = _BUILTIN_ADAPTERS.get(provider)
+    if builtin is not None:
+        module_name, _, attribute = builtin.partition(":")
+        return _require_adapter_class(getattr(import_module(module_name), attribute), builtin)
+
+    plugin = _plugin_entry_points().get(provider)
+    if plugin is not None:
+        source = f"{ENTRY_POINT_GROUP} entry point {provider!r}"
+        return require_compatible_api(
+            _require_adapter_class(plugin.load(), source), host=ADAPTER_API_VERSION, source=source
+        )
+
+    known = ", ".join(sorted(available_providers()))
+    raise ConfigError(
+        f"embeddings.provider {provider!r} is not registered; available providers: {known}"
+    )
+
+
+def create_embedding_adapter(settings: Settings) -> EmbeddingAdapter:
+    """Build the adapter named by ``embeddings.provider``."""
+    return resolve_adapter_class(settings.embeddings.provider)(settings)