@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_agent_core/src/vds_agent_core/llm/embedding.py

@@ -0,0 +1,815 @@
+"""Embedding client abstraction — Protocol + provider registry.
+
+Phase 225 Track-A foundation. Provides a uniform `EmbeddingClient` Protocol
+backed by a registry of provider factories (`EMBEDDING_PROVIDERS`) so new
+providers can be wired in without modifying core agent_core source files
+(per NFR-225.9 drop-in extensibility).
+
+Boundary discipline:
+    - All provider HTTP calls go through httpx.AsyncClient (mockable).
+    - Error messages are sanitized (no secrets in logs).
+    - No provider-specific env vars (`VDS_AGENT_CORE_EMBED__OLLAMA_*` etc.) —
+      the namespace stays clean per NFR-225.8.
+    - `for_agent()` lives in W2 (per-agent provider config) — not here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import sys
+from collections.abc import Callable
+from threading import Lock
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+import structlog
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from vds_agent_core.config import VDS_BASE_SETTINGS_CONFIG
+from vds_agent_core.security.credentials import sanitize_text
+
+logger = structlog.get_logger(__name__)
+
+# One-shot warn flag for NFR-225.11 (dim-verification disabled warning).
+_DIM_WARN_ISSUED = False
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class ConfigError(ValueError):
+    """Raised when embedding configuration is invalid (FR-225.16)."""
+
+
+class EmbeddingProviderError(Exception):
+    """Raised when an embedding provider returns an error.
+
+    `message` MUST already be sanitized (no raw API keys / Bearer tokens).
+    """
+
+    def __init__(self, status: int | None, provider: str, message: str) -> None:
+        self.status = status
+        self.provider = provider
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[{self.provider}] HTTP {self.status}: {self.message}"
+
+
+# ---------------------------------------------------------------------------
+# Sanitization helper (NFR-225.10) — W7 v20.6.1 dedup-D-2 + logic-B-2/HIGH-1:
+# canonical patterns live in vds_agent_core.security.credentials. This shim
+# preserves the module-private name for backward compat with W1-W6 internal
+# call sites (and the W6 test files that import _sanitize_error directly).
+# ---------------------------------------------------------------------------
+
+
+def _sanitize_error(msg: str | None) -> str:
+    """Strip secrets from an error message before logging or re-raising.
+
+    Delegates to ``vds_agent_core.security.credentials.sanitize_text``.
+    The canonical patterns now also redact URL query params and JSON body
+    credential fields (W7 logic-HIGH-1 + B-2 fix).
+    """
+    return sanitize_text(msg)
+
+
+# ---------------------------------------------------------------------------
+# Provider defaults (FR-225.20)
+# ---------------------------------------------------------------------------
+
+
+PROVIDER_DEFAULTS: dict[str, dict[str, Any]] = {
+    "ollama": {
+        "model": "bge-m3",
+        "dimension": 1024,
+        "base_url": "http://host.docker.internal:11434",
+    },
+    "openai": {
+        "model": "text-embedding-3-small",
+        "dimension": 1536,
+        "base_url": "https://api.openai.com/v1",
+    },
+    "cohere": {
+        "model": "embed-english-v3.0",
+        "dimension": 1024,
+        "base_url": "https://api.cohere.ai/v1",
+    },
+    "voyage": {
+        "model": "voyage-3",
+        "dimension": 1024,
+        "base_url": "https://api.voyageai.com/v1",
+    },
+    "mistral": {
+        "model": "mistral-embed",
+        "dimension": 1024,
+        "base_url": "https://api.mistral.ai/v1",
+    },
+    "jina": {
+        "model": "jina-embeddings-v3",
+        "dimension": 1024,
+        "base_url": "https://api.jina.ai/v1",
+    },
+    "local": {
+        "model": "BAAI/bge-m3",
+        "dimension": 1024,
+        "base_url": None,
+    },
+    "hash": {},
+    "litellm": {},
+}
+
+
+# ---------------------------------------------------------------------------
+# Provider registry (FR-225.19, ADR-99)
+# ---------------------------------------------------------------------------
+
+
+# Populated at module bottom AFTER all client classes are defined.
+EMBEDDING_PROVIDERS: dict[str, Callable[[EmbeddingRuntimeConfig], EmbeddingClient]] = {}
+
+# W7 v20.6.1 logic-B-3 fix: serialize register/dispatch concurrent updates.
+# Python dict assignment is GIL-atomic for individual ops, but the
+# check-then-set pattern (line 152: ``if not force and name in dict``) needs
+# atomicity across both operations to honor the conflict rule.
+_PROVIDER_REGISTRY_LOCK = Lock()
+
+
+def register_provider(
+    name: str,
+    factory: Callable[[EmbeddingRuntimeConfig], EmbeddingClient],
+    *,
+    force: bool = False,
+) -> None:
+    """Register a new embedding provider factory.
+
+    Per ADR-99 H-3 conflict rule: collisions fail fast unless ``force=True``.
+    W7 v20.6.1 logic-B-3 fix: check-then-set wrapped in
+    ``_PROVIDER_REGISTRY_LOCK`` so two threads racing on the same key cannot
+    both pass the conflict check.
+    """
+    with _PROVIDER_REGISTRY_LOCK:
+        if not force and name in EMBEDDING_PROVIDERS:
+            raise ConfigError(
+                f"Provider {name!r} already registered. Pass force=True to override."
+            )
+        EMBEDDING_PROVIDERS[name] = factory
+
+
+def _parse_provider_from_model(model_str: str) -> str | None:
+    """Return provider prefix for ``provider/model`` strings, else ``None``.
+
+    W7 v20.6.1 logic-HIGH-2 fix: tolerate a leading slash so an operator
+    typo (``"/openai/text-embedding-3-small"``) still routes to ``openai``
+    instead of silently falling back to the default provider.
+    """
+    if not model_str:
+        return None
+    cleaned = model_str.lstrip("/")
+    if "/" not in cleaned:
+        return None
+    prefix, _, _ = cleaned.partition("/")
+    return prefix or None
+
+
+def _check_qdrant_collection_dim() -> int | None:
+    """Return live Qdrant collection dimension, or None if unavailable.
+
+    Stub for W1 — W4 wires this to a real Qdrant probe.
+    """
+    return None
+
+
+def _compose_http_error(exc: httpx.HTTPStatusError) -> str:
+    """Build the full sanitization input from an HTTPStatusError.
+
+    W7 v20.6.1 logic-B-2 fix: the previous code passed only ``str(exc)`` to
+    ``_sanitize_error``. ``str(exc)`` does NOT include the response body,
+    which is where providers (notably OpenAI) sometimes echo the bearer
+    token in their JSON error message. This helper concatenates the
+    exception summary with ``exc.response.text`` so the sanitizer can
+    redact tokens regardless of where they appear.
+    """
+    parts: list[str] = [str(exc)]
+    response = getattr(exc, "response", None)
+    if response is not None:
+        try:
+            body = response.text
+        except Exception:
+            body = ""
+        # Coerce body to str — under unittest.mock, ``response.text`` may be
+        # a MagicMock attribute access result; only str values can join.
+        if body and isinstance(body, str):
+            parts.append(body)
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class EmbeddingClient(Protocol):
+    """Generic embedding client contract. All providers satisfy this."""
+
+    async def embed(self, text: str, *, model: str) -> list[float]: ...
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]: ...
+
+    def estimate_cost(self, text: str, *, model: str) -> float: ...
+
+    async def aclose(self) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Cost estimation
+# ---------------------------------------------------------------------------
+
+
+_COST_PER_1K_TOKENS: dict[str, float] = {
+    "text-embedding-3-small": 0.00002,
+    "text-embedding-3-large": 0.00013,
+    "embed-english-v3.0": 0.0001,
+    "voyage-3": 0.00012,
+}
+
+
+def _estimate_tokens(text: str) -> int:
+    """Rough heuristic: ~4 chars per token, min 1."""
+    return max(1, len(text) // 4)
+
+
+# ---------------------------------------------------------------------------
+# Client implementations
+# ---------------------------------------------------------------------------
+
+
+class OllamaEmbeddingClient:
+    """Local Ollama embedding client (default for VDS).
+
+    Uses `/api/embed` (Ollama 0.2+ unified endpoint).
+    """
+
+    provider_name = "ollama"
+
+    def __init__(self, config: EmbeddingRuntimeConfig) -> None:
+        self._config = config
+        self._client = httpx.AsyncClient(timeout=config.timeout_seconds)
+
+    @classmethod
+    def from_settings(cls, config: EmbeddingRuntimeConfig) -> OllamaEmbeddingClient:
+        return cls(config)
+
+    async def embed(self, text: str, *, model: str) -> list[float]:
+        url = f"{self._config.base_url.rstrip('/')}/api/embed"
+        try:
+            resp = await self._client.post(url, json={"model": model, "input": text})
+            resp.raise_for_status()
+            data = resp.json()
+            # W7 v20.6.1 logic-B-1 fix: guard against empty embeddings arrays
+            # (Ollama returning ``{"embeddings": []}`` previously crashed with
+            # IndexError instead of a controlled provider error).
+            embeddings = data.get("embeddings") or []
+            if not embeddings:
+                raise EmbeddingProviderError(
+                    None, self.provider_name, "empty embeddings array from provider"
+                )
+            return list(embeddings[0])
+        except httpx.HTTPStatusError as exc:
+            msg = _sanitize_error(_compose_http_error(exc))
+            logger.warning("ollama_embed_http_error", error=msg)
+            raise EmbeddingProviderError(exc.response.status_code, self.provider_name, msg) from None
+        except httpx.RequestError as exc:
+            msg = _sanitize_error(str(exc))
+            logger.warning("ollama_embed_request_error", error=msg)
+            raise EmbeddingProviderError(None, self.provider_name, msg) from None
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]:
+        url = f"{self._config.base_url.rstrip('/')}/api/embed"
+        try:
+            resp = await self._client.post(url, json={"model": model, "input": texts})
+            resp.raise_for_status()
+            data = resp.json()
+            # W7 v20.6.1 logic-B-1 fix: empty list still allowed for batch
+            # (caller may pass empty texts), but None is rejected.
+            embeddings = data.get("embeddings")
+            if embeddings is None:
+                raise EmbeddingProviderError(
+                    None, self.provider_name, "missing embeddings field from provider"
+                )
+            return [list(v) for v in embeddings]
+        except httpx.HTTPStatusError as exc:
+            msg = _sanitize_error(_compose_http_error(exc))
+            logger.warning("ollama_embed_batch_http_error", error=msg)
+            raise EmbeddingProviderError(exc.response.status_code, self.provider_name, msg) from None
+        except httpx.RequestError as exc:
+            msg = _sanitize_error(str(exc))
+            logger.warning("ollama_embed_batch_request_error", error=msg)
+            raise EmbeddingProviderError(None, self.provider_name, msg) from None
+
+    def estimate_cost(self, text: str, *, model: str) -> float:
+        return 0.0
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+class OpenAIEmbeddingClient:
+    """OpenAI-compatible embedding client.
+
+    Used by openai/cohere/voyage/mistral/jina via `provider_name` discriminator.
+    All these providers expose `/embeddings` with the OpenAI shape (matryoshka
+    `dimensions` parameter is OpenAI-specific but harmlessly accepted by others
+    where supported).
+    """
+
+    def __init__(self, config: EmbeddingRuntimeConfig, *, provider_name: str = "openai") -> None:
+        self._config = config
+        self.provider_name = provider_name
+        self._client = httpx.AsyncClient(timeout=config.timeout_seconds)
+
+    @classmethod
+    def from_settings(
+        cls,
+        config: EmbeddingRuntimeConfig,
+        *,
+        provider_name: str = "openai",
+    ) -> OpenAIEmbeddingClient:
+        return cls(config, provider_name=provider_name)
+
+    def _resolved_base_url(self) -> str:
+        """If operator left default ollama base_url, fall back to provider default."""
+        ollama_default = PROVIDER_DEFAULTS["ollama"]["base_url"]
+        if self._config.base_url == ollama_default:
+            provider_default = PROVIDER_DEFAULTS.get(self.provider_name, {}).get("base_url")
+            return provider_default or "https://api.openai.com/v1"
+        return self._config.base_url
+
+    async def embed(self, text: str, *, model: str) -> list[float]:
+        results = await self.embed_batch([text], model=model)
+        return results[0]
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]:
+        url = f"{self._resolved_base_url().rstrip('/')}/embeddings"
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self._config.api_key:
+            headers["Authorization"] = f"Bearer {self._config.api_key}"
+        payload: dict[str, Any] = {
+            "model": model,
+            "input": texts,
+            "dimensions": self._config.dimension,
+        }
+        try:
+            resp = await self._client.post(url, json=payload, headers=headers)
+            resp.raise_for_status()
+            data = resp.json()
+            return [list(d["embedding"]) for d in data["data"]]
+        except httpx.HTTPStatusError as exc:
+            # W7 v20.6.1 logic-B-2 fix: include the response body so any
+            # token echoed in the JSON error payload (e.g. OpenAI 401 saying
+            # "invalid token sk-leak") is sanitized. ``_sanitize_error``
+            # delegates to the canonical ``security.credentials.sanitize_text``
+            # which now also redacts URL params and JSON body fields.
+            msg = _sanitize_error(_compose_http_error(exc))
+            logger.warning(
+                "openai_compat_embed_http_error",
+                provider=self.provider_name,
+                error=msg,
+            )
+            raise EmbeddingProviderError(exc.response.status_code, self.provider_name, msg) from None
+        except httpx.RequestError as exc:
+            msg = _sanitize_error(str(exc))
+            logger.warning(
+                "openai_compat_embed_request_error",
+                provider=self.provider_name,
+                error=msg,
+            )
+            raise EmbeddingProviderError(None, self.provider_name, msg) from None
+
+    def estimate_cost(self, text: str, *, model: str) -> float:
+        # Strip provider/ prefix if present (e.g. "openai/text-embedding-3-small")
+        bare_model = model.rsplit("/", maxsplit=1)[-1]
+        rate = _COST_PER_1K_TOKENS.get(bare_model, 0.0001)
+        tokens = _estimate_tokens(text)
+        return rate * (tokens / 1000.0)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+class LiteLLMEmbeddingClient:
+    """LiteLLM-backed embedding client (one of N supported backends).
+
+    Lazy import of `litellm` — gives a clear error if the optional dep is
+    absent. LiteLLM tracks cost on its own; estimate_cost() returns 0.0.
+    """
+
+    provider_name = "litellm"
+
+    def __init__(self, config: EmbeddingRuntimeConfig) -> None:
+        self._config = config
+
+    @classmethod
+    def from_settings(cls, config: EmbeddingRuntimeConfig) -> LiteLLMEmbeddingClient:
+        return cls(config)
+
+    async def embed(self, text: str, *, model: str) -> list[float]:
+        try:
+            import litellm
+        except ImportError as e:
+            raise ImportError(
+                "Install vds-agent-core[litellm] for LiteLLM embedding support"
+            ) from e
+        try:
+            resp = await litellm.aembedding(model=model, input=text)
+            return list(resp["data"][0]["embedding"])
+        except Exception as exc:
+            msg = _sanitize_error(str(exc))
+            logger.warning("litellm_embed_error", error=msg)
+            raise EmbeddingProviderError(None, self.provider_name, msg) from None
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]:
+        try:
+            import litellm
+        except ImportError as e:
+            raise ImportError(
+                "Install vds-agent-core[litellm] for LiteLLM embedding support"
+            ) from e
+        try:
+            resp = await litellm.aembedding(model=model, input=texts)
+            return [list(d["embedding"]) for d in resp["data"]]
+        except Exception as exc:
+            msg = _sanitize_error(str(exc))
+            logger.warning("litellm_embed_batch_error", error=msg)
+            raise EmbeddingProviderError(None, self.provider_name, msg) from None
+
+    def estimate_cost(self, text: str, *, model: str) -> float:
+        return 0.0
+
+    async def aclose(self) -> None:
+        return None
+
+
+class LocalEmbeddingClient:
+    """sentence-transformers-backed local embedding client.
+
+    Lazy import + lazy model load — heavyweight torch deps stay opt-in.
+    """
+
+    provider_name = "local"
+
+    def __init__(self, config: EmbeddingRuntimeConfig) -> None:
+        self._config = config
+        self._model: Any = None
+
+    @classmethod
+    def from_settings(cls, config: EmbeddingRuntimeConfig) -> LocalEmbeddingClient:
+        return cls(config)
+
+    def _get_model(self, model_name: str) -> Any:
+        if self._model is None:
+            try:
+                from sentence_transformers import SentenceTransformer
+            except ImportError as e:
+                raise ImportError(
+                    "Install sentence-transformers for local embedding support "
+                    "(pip install sentence-transformers)"
+                ) from e
+            self._model = SentenceTransformer(model_name)
+        return self._model
+
+    async def embed(self, text: str, *, model: str) -> list[float]:
+        m = self._get_model(model)
+        vec = await asyncio.to_thread(m.encode, text)
+        # numpy → list
+        return [float(x) for x in vec]
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]:
+        m = self._get_model(model)
+        arr = await asyncio.to_thread(m.encode, texts)
+        return [[float(x) for x in row] for row in arr]
+
+    def estimate_cost(self, text: str, *, model: str) -> float:
+        return 0.0
+
+    async def aclose(self) -> None:
+        self._model = None
+
+
+class HashEmbeddingClient:
+    """Deterministic placeholder embedding for tests / fail-open.
+
+    Generates a fixed-dimension vector via SHA-256 byte tiling. Same input
+    → same output; useful for cache hits and structural test paths.
+    """
+
+    provider_name = "hash"
+
+    def __init__(self, config: EmbeddingRuntimeConfig) -> None:
+        self._config = config
+
+    @classmethod
+    def from_settings(cls, config: EmbeddingRuntimeConfig) -> HashEmbeddingClient:
+        return cls(config)
+
+    def _vector_for(self, text: str) -> list[float]:
+        digest = hashlib.sha256(text.encode("utf-8")).digest()  # 32 bytes
+        dim = self._config.dimension
+        out: list[float] = []
+        for i in range(dim):
+            b = digest[i % len(digest)]
+            out.append((b - 128) / 128.0)
+        return out
+
+    async def embed(self, text: str, *, model: str) -> list[float]:
+        return self._vector_for(text)
+
+    async def embed_batch(self, texts: list[str], *, model: str) -> list[list[float]]:
+        return [self._vector_for(t) for t in texts]
+
+    def estimate_cost(self, text: str, *, model: str) -> float:
+        return 0.0
+
+    async def aclose(self) -> None:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Settings
+# ---------------------------------------------------------------------------
+
+
+class EmbeddingRuntimeConfig(BaseSettings):
+    """Embedding runtime configuration.
+
+    env_prefix=`VDS_AGENT_CORE_EMBED__` — open-set provider string keeps the
+    namespace clean (no per-provider env vars, NFR-225.8).
+
+    Subclasses (audit, memory) override `model_config` with their own
+    env_prefix to avoid stomping shared keys.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="VDS_AGENT_CORE_EMBED__",
+        **VDS_BASE_SETTINGS_CONFIG,
+    )
+
+    enabled: bool = True
+    provider: str = "ollama"
+    base_url: str = "http://host.docker.internal:11434"
+    api_key: str | None = None
+    model_simple: str = "bge-m3"
+    model_standard: str = "bge-m3"
+    model_complex: str = "bge-m3"
+    dimension: int = Field(default=1024, gt=0)
+    cache_ttl_seconds: int = 86400
+    fail_open: bool = False
+    timeout_seconds: float = 30.0
+    verify_dim_against_qdrant: bool = True
+
+    @model_validator(mode="after")
+    def _validate_dimensions(self) -> EmbeddingRuntimeConfig:
+        # (a) Dim stability vs live Qdrant collection (FR-225.16a)
+        if self.verify_dim_against_qdrant:
+            collection_dim = _check_qdrant_collection_dim()
+            if collection_dim is not None and collection_dim != self.dimension:
+                raise ConfigError(
+                    f"Dimension mismatch: collection={collection_dim}, "
+                    f"requested={self.dimension}. Run migration first."
+                )
+
+        # (b) OpenAI matryoshka safety (FR-225.16b)
+        if (
+            self.provider == "openai"
+            and self.model_standard.endswith("text-embedding-3-small")
+            and self.dimension != 1536
+        ):
+            raise ConfigError(
+                "text-embedding-3-small does not support dimension truncation; "
+                "native dim is 1536. Use text-embedding-3-large for matryoshka, "
+                "or set DIMENSION=1536."
+            )
+
+        # (c) First-deploy guard (FR-225.16c, v20.6.1 H-6).
+        # If `provider` was left default but model prefix names a different
+        # provider, use the prefix-derived provider for this check — the
+        # auto-route resolution will use the prefix at build_client() time,
+        # so we must validate against the same provider the client will use.
+        explicit_provider = "provider" in self.model_fields_set
+        prefix_provider = _parse_provider_from_model(self.model_standard)
+        check_provider = self.provider
+        if not explicit_provider and prefix_provider and prefix_provider in PROVIDER_DEFAULTS:
+            check_provider = prefix_provider
+
+        expected = PROVIDER_DEFAULTS.get(check_provider, {}).get("dimension")
+        if expected is not None and self.dimension not in (expected, 1024):
+            raise ConfigError(
+                f"Dimension {self.dimension} invalid for provider "
+                f"{check_provider!r}; expected {expected} or 1024"
+            )
+
+        return self
+
+
+class EmbeddingSettings(EmbeddingRuntimeConfig):
+    """Config-backed factory for EmbeddingClient instances.
+
+    Build a client via `build_client()`. For health probes (FR-225.14), call
+    `await settings.health_check()` at boot.
+    """
+
+    def __init__(self, **data: Any) -> None:
+        super().__init__(**data)
+        global _DIM_WARN_ISSUED
+        if not self.verify_dim_against_qdrant and not _DIM_WARN_ISSUED:
+            _DIM_WARN_ISSUED = True
+            logger.warning(
+                "dimension_verification_disabled",
+                message=(
+                    "Dimension verification against Qdrant is DISABLED. "
+                    "Switching embedding models without running migration "
+                    "may corrupt the collection."
+                ),
+            )
+
+    @classmethod
+    def for_agent(
+        cls,
+        agent_id: str,
+        *,
+        profile: str | None = None,
+        api_settings: Any = None,
+        overrides: dict[str, Any] | None = None,
+    ) -> EmbeddingSettings:
+        """Build per-agent embedding settings via the 3-layer cascade (FR-226.2).
+
+        Mirrors :meth:`vds_agent_core.llm.provider.LLMSettings.for_agent`. Reads
+        Path A from ``VDS_AGENT_<AGENT_ID>_EMBED__*`` env vars and Path B from
+        ``api_settings.embedding_settings``. Path B wins on conflict; the
+        construction is side-effect-free (FR-226.11).
+        """
+        from vds_agent_core.llm._cascade import resolve_for_agent
+
+        return resolve_for_agent(
+            cls,
+            agent_id,
+            kind="embedding",
+            env_prefix_template="VDS_AGENT_{sanitized}_EMBED__",
+            api_attr="embedding_settings",
+            profile=profile,
+            api_settings=api_settings,
+            overrides=overrides,
+        )
+
+    def select_model(self, tier: str = "standard") -> str:
+        models = {
+            "simple": self.model_simple,
+            "standard": self.model_standard,
+            "complex": self.model_complex,
+        }
+        return models.get(tier, self.model_standard)
+
+    def build_client(self) -> EmbeddingClient:
+        """Build an EmbeddingClient per FR-225.6 explicit-vs-defaulted resolution."""
+        explicit_provider = "provider" in self.model_fields_set
+        prefix_provider = _parse_provider_from_model(self.model_standard)
+
+        if explicit_provider:
+            provider = self.provider
+            if prefix_provider and prefix_provider != provider:
+                logger.warning(
+                    "provider_model_mismatch",
+                    provider=provider,
+                    model=self.model_standard,
+                    message=(
+                        f"Explicit provider={provider!r} differs from model "
+                        f"prefix {prefix_provider!r}"
+                    ),
+                )
+        elif prefix_provider:
+            provider = prefix_provider
+        else:
+            provider = self.provider  # default "ollama"
+
+        factory = EMBEDDING_PROVIDERS.get(provider)
+        if factory is None:
+            raise ConfigError(
+                f"Unknown embedding provider: {provider!r}. "
+                f"Registered: {sorted(EMBEDDING_PROVIDERS)}"
+            )
+        return factory(self)
+
+    @classmethod
+    def from_config(
+        cls,
+        *,
+        env_prefix: str | None = None,
+        **overrides: Any,
+    ) -> EmbeddingSettings:
+        """Construct settings, optionally overriding env_prefix.
+
+        For per-package env namespacing, prefer subclassing with a custom
+        `model_config`. This shorthand simply forwards overrides.
+        """
+        if env_prefix is not None:
+            new_config = SettingsConfigDict(
+                env_prefix=env_prefix,
+                **VDS_BASE_SETTINGS_CONFIG,
+            )
+            subcls = type(
+                f"_DynamicEmbeddingSettings_{env_prefix.strip('_')}",
+                (cls,),
+                {"model_config": new_config},
+            )
+            return subcls(**overrides)
+        return cls(**overrides)
+
+    async def health_check(self) -> None:
+        """Probe the configured provider at boot (FR-225.14, R-225.8).
+
+        On success: silent.
+        On failure with fail_open=False: log error and sys.exit(1).
+        On failure with fail_open=True: log warning and continue.
+
+        HIGH-2 (W6 v20.6.1 fix): ``client`` is bound to ``None`` BEFORE the
+        ``try:`` so a ``ConfigError`` from ``build_client()`` (e.g. unknown
+        provider) does not trigger ``UnboundLocalError`` in the ``finally``.
+        The ``finally`` now guards the ``aclose()`` against an uninitialized
+        client.
+        """
+        client: EmbeddingClient | None = None
+        try:
+            client = self.build_client()
+            vector = await client.embed(
+                "health-probe",
+                model=self.select_model("standard"),
+            )
+            if len(vector) != self.dimension:
+                raise ConfigError(
+                    f"Provider {self.provider!r} model "
+                    f"{self.select_model('standard')!r} returned "
+                    f"{len(vector)} dims; expected {self.dimension}"
+                )
+        except (httpx.RequestError, EmbeddingProviderError, ConfigError) as exc:
+            if self.fail_open:
+                logger.warning(
+                    "embedding_health_check_failed_fallback_to_hash",
+                    error=_sanitize_error(str(exc)),
+                )
+            else:
+                logger.error(
+                    "embedding_health_check_failed_fatal",
+                    error=_sanitize_error(str(exc)),
+                )
+                sys.exit(1)
+        finally:
+            if client is not None:
+                await client.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Registry population (must come AFTER all client classes are defined)
+# ---------------------------------------------------------------------------
+
+
+# OpenAI-compatible providers all dispatch to OpenAIEmbeddingClient with a
+# provider_name discriminator. W7 v20.6.1 dedup-D-3 fix: build the factory
+# entries from a list (closure-bound provider_name) rather than four
+# duplicated lambdas. Adding a new OpenAI-compat provider is now a one-line
+# tuple extension.
+_OPENAI_COMPAT_PROVIDERS: tuple[str, ...] = ("cohere", "voyage", "mistral", "jina")
+
+
+def _make_openai_compat_factory(
+    provider_name: str,
+) -> Callable[[EmbeddingRuntimeConfig], EmbeddingClient]:
+    """Bind ``provider_name`` into the factory closure.
+
+    Defined as a top-level function (rather than a lambda inside a
+    comprehension) so the closure semantics are explicit and the factory
+    is repr-friendly during debugging.
+    """
+
+    def _factory(config: EmbeddingRuntimeConfig) -> EmbeddingClient:
+        return OpenAIEmbeddingClient.from_settings(config, provider_name=provider_name)
+
+    _factory.__name__ = f"_openai_compat_factory_{provider_name}"
+    return _factory
+
+
+EMBEDDING_PROVIDERS.update(
+    {
+        "ollama": OllamaEmbeddingClient.from_settings,
+        "openai": OpenAIEmbeddingClient.from_settings,
+        **{name: _make_openai_compat_factory(name) for name in _OPENAI_COMPAT_PROVIDERS},
+        "litellm": LiteLLMEmbeddingClient.from_settings,
+        "local": LocalEmbeddingClient.from_settings,
+        "hash": HashEmbeddingClient.from_settings,
+    }
+)