Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

47.5 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
from typing import Any, ClassVar, List, Literal, Optional, Tuple, cast

from pydantic import BaseModel, Field, model_validator

from openviking_cli.utils.logger import get_logger

logger = get_logger(__name__)

TEXT_SOURCE_CONTENT_ONLY = "content_only"
TEXT_SOURCE_SUMMARY_FIRST = "summary_first"
SUMMARY_TEXT_SOURCES = frozenset({TEXT_SOURCE_SUMMARY_FIRST})
TEXT_SOURCES = SUMMARY_TEXT_SOURCES | {TEXT_SOURCE_CONTENT_ONLY}


class EmbeddingCredential(BaseModel):
    """Single embedding credential configuration for multi-credential failover."""

    id: Optional[str] = Field(default=None, description="Unique identifier for this credential")
    provider: Optional[str] = Field(default=None, description="Provider type")
    model: Optional[str] = Field(
        default=None,
        description=(
            "Model name (or endpoint id) for this credential. "
            "Overrides the parent EmbeddingModelConfig.model when set, allowing "
            "each credential to point to a different deployment / endpoint."
        ),
    )
    api_key: Optional[str] = Field(default=None, description="API key")
    api_base: Optional[str] = Field(default=None, description="API base URL")
    api_version: Optional[str] = Field(default=None, description="API version")
    ak: Optional[str] = Field(default=None, description="Access Key ID for VikingDB API")
    sk: Optional[str] = Field(default=None, description="Access Key Secret for VikingDB API")
    region: Optional[str] = Field(default=None, description="Region for VikingDB API")
    host: Optional[str] = Field(default=None, description="Host for VikingDB API")
    extra_headers: Optional[dict[str, str]] = Field(default=None, description="Extra HTTP headers")


class EmbeddingModelConfig(BaseModel):
    """Configuration for a specific embedding model"""

    model: Optional[str] = Field(default=None, description="Model name")
    api_key: Optional[str] = Field(default=None, description="API key")
    api_base: Optional[str] = Field(default=None, description="API base URL")
    dimension: Optional[int] = Field(default=None, description="Embedding dimension")
    batch_size: int = Field(default=32, description="Batch size for embedding generation")
    input: str = Field(default="multimodal", description="Input type: 'text' or 'multimodal'")
    query_param: Optional[str] = Field(
        default=None,
        description=(
            "Parameter value for query-side embeddings when calling embed(is_query=True). "
            "For OpenAI-compatible models, this maps to 'input_type' (e.g., 'query', 'search_query'). "
            "For Jina models, this maps to 'task' (e.g., 'retrieval.query'). "
            "Setting this or document_param activates non-symmetric mode. "
            "Leave both unset for symmetric models."
        ),
    )
    document_param: Optional[str] = Field(
        default=None,
        description=(
            "Parameter value for document-side embeddings when calling embed(is_query=False). "
            "For OpenAI-compatible models, this maps to 'input_type' (e.g., 'passage', 'document'). "
            "For Jina models, this maps to 'task' (e.g., 'retrieval.passage'). "
            "Setting this or query_param activates non-symmetric mode. "
            "Leave both unset for symmetric models."
        ),
    )
    provider: Optional[str] = Field(
        default="volcengine",
        description=(
            "Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'dashscope', 'minimax', 'cohere', 'litellm', 'local'. "
            "For OpenRouter or other OpenAI-compatible providers, use 'litellm' with "
            "api_base and api_key, or 'openai' with api_base and extra_headers."
        ),
    )
    backend: Optional[str] = Field(
        default="volcengine",
        description="Backend type (Deprecated, use 'provider' instead): 'openai', 'volcengine', 'vikingdb', 'voyage', 'local'",
    )
    version: Optional[str] = Field(default=None, description="Model version")
    ak: Optional[str] = Field(default=None, description="Access Key ID for VikingDB API")
    sk: Optional[str] = Field(default=None, description="Access Key Secretfor VikingDB API")
    region: Optional[str] = Field(default=None, description="Region for VikingDB API")
    host: Optional[str] = Field(default=None, description="Host for VikingDB API")
    extra_headers: Optional[dict[str, str]] = Field(
        default=None,
        description=(
            "Extra HTTP headers for API requests. Passed as default_headers to the OpenAI client. "
            "Useful for OpenRouter (e.g., {'HTTP-Referer': '...', 'X-Title': '...'}) "
            "or other OpenAI-compatible providers that require custom headers."
        ),
    )
    encoding_format: Optional[Literal["float", "base64"]] = Field(
        default=None,
        description=(
            "Wire format for embedding values. Applies to OpenAI / Azure providers. "
            "Leave unset to use the OpenAI Python SDK default (currently 'base64', "
            "which is bandwidth-efficient and decoded client-side). Set to 'float' "
            "to send/receive plain JSON arrays. This is the recommended workaround "
            "when the upstream gateway cannot serialize base64 responses correctly."
        ),
    )
    extra_body: Optional[dict[str, Any]] = Field(
        default=None,
        description=(
            "Extra JSON body fields merged into every embeddings request. "
            "Applies to OpenAI / Azure providers. Useful for OpenAI-compatible "
            "gateways that accept vendor-specific fields, e.g. OpenRouter provider "
            "routing {'provider': {'sort': 'latency'}}. Explicit "
            "query_param/document_param keys take precedence on conflict."
        ),
    )
    api_version: Optional[str] = Field(
        default=None,
        description="API version for Azure OpenAI (e.g., '2025-01-01-preview').",
    )
    model_path: Optional[str] = Field(
        default=None,
        description="Explicit local GGUF model path for provider='local'.",
    )
    cache_dir: Optional[str] = Field(
        default=None,
        description="Local model cache directory for provider='local'.",
    )
    enable_fusion: Optional[bool] = Field(
        default=None,
        description="Enable multimodal fusion for DashScope provider (multimodal models only).",
    )
    res_level: Optional[int] = Field(
        default=None,
        description="Resolution level for DashScope multimodal models (multimodal models only).",
    )
    max_video_frames: Optional[int] = Field(
        default=None,
        description="Maximum video frames for DashScope multimodal models (multimodal models only).",
    )

    # New multi-credential configuration
    credentials: List[EmbeddingCredential] = Field(
        default_factory=list,
        description="Ordered list of credentials for failover. Call order matches array index (0 is highest priority).",
    )

    failback_timeout_seconds: float = Field(
        default=600.0, description="Time in seconds after which to attempt failback to primary"
    )
    failback_request_count: int = Field(
        default=50, description="Number of backup requests after which to attempt failback"
    )

    @model_validator(mode="before")
    @classmethod
    def sync_provider_backend(cls, data: Any) -> Any:
        if isinstance(data, dict):
            provider = data.get("provider")
            backend = data.get("backend")

            if backend is not None and provider is None:
                data["provider"] = backend
            for key in ("query_param", "document_param"):
                value = data.get(key)
                if isinstance(value, str):
                    data[key] = value.lower()
        return data

    _VALID_PROVIDERS: ClassVar[Tuple[str, ...]] = (
        "openai",
        "azure",
        "volcengine",
        "vikingdb",
        "jina",
        "ollama",
        "gemini",
        "voyage",
        "dashscope",
        "minimax",
        "cohere",
        "litellm",
        "local",
    )

    @classmethod
    def _validate_provider_auth(
        cls,
        *,
        label: str,
        provider: Optional[str],
        api_key: Optional[str],
        api_base: Optional[str],
        ak: Optional[str],
        sk: Optional[str],
        region: Optional[str],
    ) -> None:
        """Validate provider name and provider-specific auth requirements.

        Shared by both the top-level config validator (single-credential mode)
        and the per-credential validator (multi-credential mode).

        Args:
            label: Prefix used in error messages, e.g. "Embedding" or
                "credentials[ark-primary]".
            provider: Provider name (already lowercased / normalized).
            api_key, api_base, ak, sk, region: Resolved auth fields, with
                credential values taking precedence over parent fallbacks
                in multi-credential mode.
        """
        if not provider:
            raise ValueError(f"{label}: provider is required")
        if provider not in cls._VALID_PROVIDERS:
            raise ValueError(
                f"{label}: invalid provider '{provider}'. Must be one of: "
                + ", ".join(f"'{p}'" for p in cls._VALID_PROVIDERS)
            )

        if provider == "openai":
            # Allow missing api_key when api_base is set (e.g. local OpenAI-compatible servers)
            if not api_key and not api_base:
                raise ValueError(f"{label}: OpenAI provider requires 'api_key' to be set")
        elif provider == "azure":
            if not api_key:
                raise ValueError(f"{label}: Azure provider requires 'api_key' to be set")
            if not api_base:
                raise ValueError(
                    f"{label}: Azure provider requires 'api_base' (Azure endpoint) to be set"
                )
        elif provider in {
            "volcengine",
            "jina",
            "gemini",
            "voyage",
            "minimax",
            "cohere",
            "dashscope",
        }:
            if not api_key:
                provider_label = {
                    "volcengine": "Volcengine",
                    "jina": "Jina",
                    "gemini": "Gemini",
                    "voyage": "Voyage",
                    "minimax": "MiniMax",
                    "cohere": "Cohere",
                    "dashscope": "DashScope",
                }[provider]
                raise ValueError(f"{label}: {provider_label} provider requires 'api_key' to be set")
        elif provider == "vikingdb":
            missing = [n for n, v in (("ak", ak), ("sk", sk), ("region", region)) if not v]
            if missing:
                raise ValueError(
                    f"{label}: VikingDB provider requires the following fields: "
                    f"{', '.join(missing)}"
                )
        # ollama / litellm / local: no auth requirement enforced here

    @model_validator(mode="after")
    def validate_config(self):
        """Validate configuration completeness and consistency"""
        if self.backend and not self.provider:
            self.provider = self.backend

        if not self.model and not any(c.model for c in self.credentials):
            raise ValueError("Embedding model name is required")

        # When credentials are configured, defer provider/api_key validation to
        # per-credential checks; the parent-level provider/api_key may be left
        # blank because each credential carries its own settings.
        if self.credentials:
            self._validate_credentials()
            self._validate_credential_dimensions()
            return self

        self._validate_provider_auth(
            label="Embedding",
            provider=self.provider,
            api_key=self.api_key,
            api_base=self.api_base,
            ak=self.ak,
            sk=self.sk,
            region=self.region,
        )

        self._validate_provider_specific_options(
            label="Embedding",
            provider=self.provider,
            model=self.model,
        )

        return self

    def _validate_provider_specific_options(
        self, *, label: str, provider: Optional[str], model: Optional[str]
    ) -> None:
        """Validate provider-specific options that go beyond auth.

        These rules depend on the provider/model pair and on parent-level
        fields (``query_param``, ``document_param``, ``input``, ``dimension``,
        ``enable_fusion``, etc.) that are shared across all credentials. They
        must run for both the single-credential path (using ``self.provider``)
        and the multi-credential path (using each credential's resolved
        provider/model), otherwise invalid configurations slip past startup
        validation and surface only at runtime — after collection schema and
        embedding metadata may already have been written.
        """
        if not provider:
            return

        if provider == "gemini":
            _GEMINI_TASK_TYPES = {
                "RETRIEVAL_QUERY",
                "RETRIEVAL_DOCUMENT",
                "SEMANTIC_SIMILARITY",
                "CLASSIFICATION",
                "CLUSTERING",
                "QUESTION_ANSWERING",
                "FACT_VERIFICATION",
                "CODE_RETRIEVAL_QUERY",
            }
            for field_name, value in [
                ("query_param", self.query_param),
                ("document_param", self.document_param),
            ]:
                if value and value.upper() not in _GEMINI_TASK_TYPES:
                    raise ValueError(
                        f"{label}: invalid {field_name} '{value}' for Gemini. "
                        f"Valid task_types: {', '.join(sorted(_GEMINI_TASK_TYPES))}"
                    )

        elif provider == "dashscope":
            if self.input == "text" and (
                self.enable_fusion is not None
                or self.res_level is not None
                or self.max_video_frames is not None
            ):
                raise ValueError(
                    f"{label}: parameters enable_fusion, res_level, and max_video_frames "
                    "only apply to multimodal input mode"
                )

        elif provider == "litellm":
            # litellm handles auth via env vars or explicit api_key; no strict requirement
            if not self.dimension:
                raise ValueError(
                    f"{label}: LiteLLM provider requires 'dimension' to be set explicitly. "
                    "Check your embedding model's documentation for the correct dimension."
                )

        elif provider == "local":
            from openviking.models.embedder.local_embedders import get_local_model_spec

            get_local_model_spec(model)

    def _validate_credentials(self) -> None:
        """Validate each credential when credentials list is non-empty.

        Each credential must resolve a provider (from itself or the parent) and
        meet that provider's required fields. The parent-level provider/api_key
        are used as fallbacks where appropriate. Provider-specific options that
        depend on parent-level fields (e.g. LiteLLM dimension, Gemini task
        types, DashScope multimodal-only params) are also re-checked per
        resolved credential so the credentials path enforces the same invariants
        as the single-credential path.
        """
        for idx, cred in enumerate(self.credentials):
            cred_id = cred.id or f"credential-{idx}"
            label = f"credentials[{cred_id}]"
            resolved_provider = (cred.provider or self.provider or "").lower() or None
            resolved_model = cred.model or self.model
            self._validate_provider_auth(
                label=label,
                provider=resolved_provider,
                api_key=cred.api_key or self.api_key,
                api_base=cred.api_base or self.api_base,
                ak=cred.ak or self.ak,
                sk=cred.sk or self.sk,
                region=cred.region or self.region,
            )
            self._validate_provider_specific_options(
                label=label,
                provider=resolved_provider,
                model=resolved_model,
            )

    def _validate_credential_dimensions(self) -> None:
        """Ensure all credentials produce vectors of the same dimension.

        Mixing credentials whose embedders return different vector lengths
        causes ``dense vector dimension mismatch`` errors at write time and
        silently breaks retrieval. We therefore reject such configurations at
        startup. Dimensions are resolved using the same heuristics as
        ``get_effective_dimension`` (provider + model), with the explicit
        parent ``self.dimension`` always winning when set.
        """
        if len(self.credentials) <= 1:
            return

        resolved: list[tuple[str, int]] = []
        for idx, cred in enumerate(self.credentials):
            cred_id = cred.id or f"credential-{idx}"
            provider = (cred.provider or self.provider or "").lower()
            model = cred.model or self.model
            try:
                dim = self._resolve_dimension_for(provider, model)
            except ValueError:
                # Unknown dimension (e.g. ollama with no explicit dim and
                # unknown model): skip - the per-credential validation above
                # would have already required `dimension` if needed via
                # parent.dimension, and resolution failures here are non-fatal
                # because the credential may still work at runtime.
                continue
            if dim is None:
                continue
            resolved.append((cred_id, dim))

        distinct = {dim for _, dim in resolved}
        if len(distinct) > 1:
            details = ", ".join(f"{cid}={dim}" for cid, dim in resolved)
            raise ValueError(
                "Embedding credentials have conflicting vector dimensions: "
                f"{details}. All credentials must produce vectors of the same "
                "dimension; mixing different dimensions corrupts the vector "
                "store. Either align provider/model across credentials, or "
                "set 'dimension' explicitly on the parent embedding config "
                "to force a fixed schema dimension."
            )

    def _resolve_dimension_for(self, provider: str, model: Optional[str]) -> Optional[int]:
        """Resolve dimension for a (provider, model) pair using the same
        rules as ``get_effective_dimension``. The explicit parent dimension,
        when set, always wins."""
        if self.dimension is not None:
            return self.dimension

        provider = (provider or "").lower()
        if provider in {"openai", "azure"}:
            mapping = {
                "text-embedding-ada-002": 1536,
                "text-embedding-3-small": 1536,
                "text-embedding-3-large": 3072,
            }
            return mapping.get((model or "").lower())

        if provider == "voyage":
            from openviking.models.embedder.voyage_embedders import (
                get_voyage_model_default_dimension,
            )

            return get_voyage_model_default_dimension(model)

        if provider == "cohere":
            from openviking.models.embedder.cohere_embedders import (
                get_cohere_model_default_dimension,
            )

            return get_cohere_model_default_dimension(model)

        if provider == "jina":
            from openviking.models.embedder.jina_embedders import (
                get_jina_model_default_dimension,
            )

            return get_jina_model_default_dimension(model)

        if provider == "gemini":
            from openviking.models.embedder.gemini_embedders import GeminiDenseEmbedder

            return GeminiDenseEmbedder._default_dimension(model)

        if provider == "local":
            from openviking.models.embedder.local_embedders import (
                get_local_model_default_dimension,
            )

            return get_local_model_default_dimension(model)

        if provider == "dashscope":
            try:
                from openviking.models.embedder.dashscope_embedders import (
                    get_dashscope_model_default_dimension,
                )

                return get_dashscope_model_default_dimension(model)
            except ImportError:
                return 1024

        # Providers without a known dimension lookup (volcengine,
        # vikingdb, ollama for unlisted models, etc.) cannot be cross-checked
        # here without an explicit dimension. Return None so validation skips
        # them; same-provider credentials are typically dimension-compatible
        # by construction, and any real mismatch will surface at write time.
        return None

    def _effective_provider(self) -> Optional[str]:
        """Resolve the provider that actually drives this config.

        When credentials are configured, the first credential's provider takes
        precedence over the parent's (which may still hold its default value of
        ``volcengine``). Without this fallback, credential-only configurations
        targeting a non-default provider would silently use the parent's
        default for dimension/metadata resolution and produce a vector-space
        mismatch (e.g. parent volcengine -> 2048 dim while the actual OpenAI
        embedder returns 1536).
        """
        if self.credentials and self.credentials[0].provider:
            return self.credentials[0].provider
        return self.provider

    def _effective_model(self) -> Optional[str]:
        """Resolve the model that actually drives this config.

        Same rationale as ``_effective_provider``: credential-level model wins
        when present so dimension/metadata reflect the model the embedder will
        actually call.
        """
        if self.credentials and self.credentials[0].model:
            return self.credentials[0].model
        return self.model

    def get_effective_dimension(self) -> int:
        """Resolve the dimension used for schema creation and validation."""
        if self.dimension is not None:
            return self.dimension

        provider = (self._effective_provider() or "").lower()
        effective_model = self._effective_model()
        if provider in {"openai", "azure"}:
            openai_model_dimensions = {
                "text-embedding-ada-002": 1536,
                "text-embedding-3-small": 1536,
                "text-embedding-3-large": 3072,
            }
            model_lower = (effective_model or "").lower()
            if model_lower in openai_model_dimensions:
                return openai_model_dimensions[model_lower]

        if provider == "voyage":
            from openviking.models.embedder.voyage_embedders import (
                get_voyage_model_default_dimension,
            )

            return get_voyage_model_default_dimension(effective_model)

        if provider == "cohere":
            from openviking.models.embedder.cohere_embedders import (
                get_cohere_model_default_dimension,
            )

            return get_cohere_model_default_dimension(effective_model)

        if provider == "jina":
            from openviking.models.embedder.jina_embedders import (
                get_jina_model_default_dimension,
            )

            return get_jina_model_default_dimension(effective_model)

        if provider == "gemini":
            from openviking.models.embedder.gemini_embedders import GeminiDenseEmbedder

            return GeminiDenseEmbedder._default_dimension(effective_model)

        if provider == "ollama":
            # Common Ollama embedding models and their dimensions
            # Users should set dimension explicitly for other models
            ollama_model_dimensions = {
                "nomic-embed-text": 768,
                "nomic-embed-text-v1": 768,
                "nomic-embed-text-v1.5": 768,
                "mxbai-embed-large": 1024,
                "mxbai-embed-large-v1": 1024,
                "all-minilm": 384,
                "all-minilm-l6-v2": 384,
                "snowflake-arctic-embed": 1024,
                "snowflake-arctic-embed-l": 1024,
                "qwen3-embedding": 1024,
                "qwen3-embedding:0.6b": 1024,
                "qwen3-embedding:4b": 1024,
                "qwen3-embedding:8b": 1024,
                "embeddinggemma": 768,
                "embeddinggemma:300m": 768,
            }
            model_lower = (effective_model or "").lower()
            if model_lower in ollama_model_dimensions:
                return ollama_model_dimensions[model_lower]
            # For unknown Ollama models, require explicit dimension
            raise ValueError(
                f"Unknown dimension for Ollama model '{effective_model}'. "
                f"Please set 'dimension' explicitly in your embedding config. "
                f"Known models: {list(ollama_model_dimensions.keys())}"
            )

        if provider == "local":
            from openviking.models.embedder.local_embedders import get_local_model_default_dimension

            return get_local_model_default_dimension(effective_model)

        if provider == "dashscope":
            try:
                from openviking.models.embedder.dashscope_embedders import (
                    get_dashscope_model_default_dimension,
                )

                return get_dashscope_model_default_dimension(effective_model)
            except ImportError:
                # Fallback dimension if dashscope_embedders module doesn't exist yet
                return 1024

        return 2048


class EmbeddingCircuitBreakerConfig(BaseModel):
    failure_threshold: int = Field(
        default=5,
        ge=1,
        description="Consecutive failures required to open the embedding circuit breaker",
    )
    reset_timeout: float = Field(
        default=60.0,
        gt=0,
        description="Base circuit breaker reset timeout in seconds",
    )
    max_reset_timeout: float = Field(
        default=600.0,
        gt=0,
        description="Maximum circuit breaker reset timeout in seconds",
    )

    @model_validator(mode="after")
    def validate_bounds(self):
        if self.max_reset_timeout < self.reset_timeout:
            raise ValueError("embedding.circuit_breaker.max_reset_timeout must be >= reset_timeout")
        return self


class EmbeddingConfig(BaseModel):
    """
    Embedding configuration, supports OpenAI, VolcEngine, VikingDB, Jina, Gemini, Voyage, or LiteLLM APIs.

    Structure:
    - dense: Configuration for dense embedder
    - sparse: Configuration for sparse embedder
    - hybrid: Configuration for hybrid embedder (single model returning both)

    Environment variables are mapped to these configurations.
    """

    dense: Optional[EmbeddingModelConfig] = Field(default=None)
    sparse: Optional[EmbeddingModelConfig] = Field(default=None)
    hybrid: Optional[EmbeddingModelConfig] = Field(default=None)
    circuit_breaker: EmbeddingCircuitBreakerConfig = Field(
        default_factory=EmbeddingCircuitBreakerConfig
    )

    max_concurrent: int = Field(
        default=10,
        ge=1,
        description="Maximum concurrent document embedding requests; retrieval queries bypass this limit",
    )
    max_retries: int = Field(
        default=3,
        description="Maximum retry attempts for embedding provider calls (0 disables retry)",
    )
    text_source: str = Field(
        default=TEXT_SOURCE_CONTENT_ONLY,
        description="Text source for file vectorization: summary_first|content_only",
    )
    max_input_tokens: int = Field(
        default=4096,
        ge=100,
        description="Maximum estimated tokens sent to embeddings when raw text fallback is used",
    )
    allow_metadata_override: bool = Field(
        default=False,
        description=(
            "When true, allow starting up against an existing collection whose "
            "embedding metadata (provider/model) differs from the current config, "
            "as long as dimension is unchanged. The collection metadata will be "
            "rewritten to the new config and a warning will be logged. "
            "Useful when migrating an existing index to a new model deployment "
            "(e.g. switching ARK endpoint id) while keeping previously indexed "
            "vectors. Note: vector semantics may drift if the underlying model "
            "actually changed; only enable when you understand the implication."
        ),
    )

    @model_validator(mode="before")
    @classmethod
    def apply_default_local_dense(cls, data: Any) -> Any:
        if data is None:
            data = {}
        if not isinstance(data, dict):
            return data

        if not data.get("dense") and not data.get("sparse") and not data.get("hybrid"):
            data = dict(data)
            data["dense"] = {
                "provider": "local",
                "model": "bge-small-zh-v1.5-f16",
            }
        return data

    @model_validator(mode="after")
    def validate_config(self):
        """Validate configuration completeness and consistency"""
        if not self.dense and not self.sparse and not self.hybrid:
            raise ValueError(
                "At least one embedding configuration (dense, sparse, or hybrid) is required"
            )
        if self.text_source == "summary_only":
            logger.warning(
                "embedding.text_source=summary_only is deprecated; use summary_first instead. "
                "Files without a summary still fall back to content for vectorization."
            )
            self.text_source = TEXT_SOURCE_SUMMARY_FIRST
        if self.text_source not in TEXT_SOURCES:
            raise ValueError("embedding.text_source must be one of: summary_first, content_only")
        return self

    def _create_embedder(
        self,
        provider: str,
        embedder_type: str,
        config: EmbeddingModelConfig,
    ):
        """Factory method to create embedder instance based on provider and type.

        Args:
            provider: Provider type ('openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'litellm')
            embedder_type: Embedder type ('dense', 'sparse', 'hybrid')
            config: EmbeddingModelConfig instance

        Returns:
            Embedder instance

        Raises:
            ValueError: If provider/type combination is not supported
        """
        from openviking.models.embedder import (
            CohereDenseEmbedder,
            DashScopeDenseEmbedder,
            GeminiDenseEmbedder,
            JinaDenseEmbedder,
            LiteLLMDenseEmbedder,
            LocalDenseEmbedder,
            MinimaxDenseEmbedder,
            OpenAIDenseEmbedder,
            RetryEmbedder,
            VikingDBDenseEmbedder,
            VikingDBHybridEmbedder,
            VikingDBSparseEmbedder,
            VolcengineDenseEmbedder,
            VolcengineHybridEmbedder,
            VolcengineSparseEmbedder,
            VoyageDenseEmbedder,
        )

        if provider == "litellm" and LiteLLMDenseEmbedder is None:
            raise ValueError("LiteLLM is not installed. Install it with: pip install litellm")

        # Factory registry: (provider, type) -> (embedder_class, param_builder)
        runtime_config = {
            "max_retries": self.max_retries,
            "max_concurrent": self.max_concurrent,
            "max_input_tokens": self.max_input_tokens,
        }

        factory_registry = {
            ("openai", "dense"): (
                OpenAIDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key
                    or "no-key",  # Placeholder for local OpenAI-compatible servers
                    "api_base": cfg.api_base,
                    "api_version": cfg.api_version,
                    "dimension": cfg.dimension,
                    "provider": "openai",
                    "configured_provider": "openai",
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                    **(
                        {"encoding_format": cfg.encoding_format}
                        if cfg.encoding_format is not None
                        else {}
                    ),
                    **(
                        {"input_type": "multimodal"}
                        if "input" in cfg.model_fields_set and cfg.input == "multimodal"
                        else {}
                    ),
                    **({"extra_body": cfg.extra_body} if cfg.extra_body else {}),
                },
            ),
            ("azure", "dense"): (
                OpenAIDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "api_version": cfg.api_version,
                    "dimension": cfg.dimension,
                    "provider": "azure",
                    "configured_provider": "azure",
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                    **(
                        {"encoding_format": cfg.encoding_format}
                        if cfg.encoding_format is not None
                        else {}
                    ),
                    **({"extra_body": cfg.extra_body} if cfg.extra_body else {}),
                },
            ),
            ("volcengine", "dense"): (
                VolcengineDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "input_type": cfg.input,
                    "config": dict(runtime_config),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                },
            ),
            ("volcengine", "sparse"): (
                VolcengineSparseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "config": dict(runtime_config),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                },
            ),
            ("volcengine", "hybrid"): (
                VolcengineHybridEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "input_type": cfg.input,
                    "config": dict(runtime_config),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                },
            ),
            ("vikingdb", "dense"): (
                VikingDBDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "model_version": cfg.version,
                    "ak": cfg.ak,
                    "sk": cfg.sk,
                    "region": cfg.region,
                    "host": cfg.host,
                    "dimension": cfg.dimension,
                    "input_type": cfg.input,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                },
            ),
            ("vikingdb", "sparse"): (
                VikingDBSparseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "model_version": cfg.version,
                    "ak": cfg.ak,
                    "sk": cfg.sk,
                    "region": cfg.region,
                    "host": cfg.host,
                    "config": dict(runtime_config),
                },
            ),
            ("vikingdb", "hybrid"): (
                VikingDBHybridEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "model_version": cfg.version,
                    "ak": cfg.ak,
                    "sk": cfg.sk,
                    "region": cfg.region,
                    "host": cfg.host,
                    "dimension": cfg.dimension,
                    "input_type": cfg.input,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                },
            ),
            ("jina", "dense"): (
                JinaDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                },
            ),
            ("gemini", "dense"): (
                GeminiDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                },
            ),
            # Ollama: local OpenAI-compatible embedding server, no real API key needed
            ("ollama", "dense"): (
                OpenAIDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key
                    or "no-key",  # Ollama ignores the key, but client requires non-empty
                    "api_base": cfg.api_base or "http://localhost:11434/v1",
                    "dimension": cfg.dimension,
                    "configured_provider": "ollama",
                    "config": dict(runtime_config),
                },
            ),
            ("voyage", "dense"): (
                VoyageDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                },
            ),
            ("minimax", "dense"): (
                MinimaxDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                },
            ),
            ("dashscope", "dense"): (
                DashScopeDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "input_type": cfg.input,
                    "config": dict(runtime_config),
                    **(
                        {"enable_fusion": cfg.enable_fusion}
                        if cfg.enable_fusion is not None
                        else {}
                    ),
                    **({"res_level": cfg.res_level} if cfg.res_level is not None else {}),
                    **(
                        {"max_video_frames": cfg.max_video_frames}
                        if cfg.max_video_frames is not None
                        else {}
                    ),
                },
            ),
            ("cohere", "dense"): (
                CohereDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                },
            ),
            ("litellm", "dense"): (
                LiteLLMDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "api_key": cfg.api_key,
                    "api_base": cfg.api_base,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                    **({"query_param": cfg.query_param} if cfg.query_param else {}),
                    **({"document_param": cfg.document_param} if cfg.document_param else {}),
                    **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
                },
            ),
            ("local", "dense"): (
                LocalDenseEmbedder,
                lambda cfg: {
                    "model_name": cfg.model,
                    "model_path": cfg.model_path,
                    "cache_dir": cfg.cache_dir,
                    "dimension": cfg.dimension,
                    "config": dict(runtime_config),
                },
            ),
        }

        key = (provider, embedder_type)
        if key not in factory_registry:
            raise ValueError(
                f"Unsupported combination: provider='{provider}', type='{embedder_type}'. "
                f"Supported combinations: {list(factory_registry.keys())}"
            )

        embedder_class, param_builder = factory_registry[key]
        if embedder_class is None and key == ("gemini", "dense"):
            raise ValueError(
                "google-genai is not installed. Install it with: pip install openviking[gemini]"
            )
        params = param_builder(config)
        embedder = embedder_class(**params)
        if provider == "local":
            return embedder
        if isinstance(embedder, RetryEmbedder):
            return embedder
        return RetryEmbedder(embedder)

    def get_embedder(self):
        """Get embedder instance based on configuration.

        Returns:
            Embedder instance (Dense, Sparse, Hybrid, or Composite)

        Raises:
            ValueError: If configuration is invalid or unsupported
        """
        from openviking.models.embedder import CompositeHybridEmbedder
        from openviking.models.embedder.base import DenseEmbedderBase, SparseEmbedderBase

        if self.hybrid:
            if self.hybrid.credentials:
                return self._create_failover_embedder("hybrid", self.hybrid)
            provider = self._require_provider(self.hybrid.provider)
            return self._create_embedder(provider, "hybrid", self.hybrid)

        if self.dense and self.sparse:
            # Handle failover for both dense and sparse if credentials are configured
            dense_embedder = self._create_single_or_failover_embedder("dense", self.dense)
            sparse_embedder = self._create_single_or_failover_embedder("sparse", self.sparse)
            return CompositeHybridEmbedder(
                cast(DenseEmbedderBase, dense_embedder),
                cast(SparseEmbedderBase, sparse_embedder),
            )

        if self.dense:
            return self._create_single_or_failover_embedder("dense", self.dense)

        if self.sparse:
            return self._create_single_or_failover_embedder("sparse", self.sparse)

        raise ValueError("No embedding configuration found (dense, sparse, or hybrid)")

    def _create_single_or_failover_embedder(
        self, embedder_type: str, config: "EmbeddingModelConfig"
    ):
        """Create either a single embedder or a FailoverEmbedder based on credentials config."""
        if config.credentials:
            return self._create_failover_embedder(embedder_type, config)
        provider = self._require_provider(config.provider)
        return self._create_embedder(provider, embedder_type, config)

    def _create_failover_embedder(self, embedder_type: str, config: "EmbeddingModelConfig"):
        """Create a FailoverEmbedder with multiple credentials."""
        from openviking.models.embedder import FailoverEmbedder

        embedders = []
        credential_ids = []

        for cred in config.credentials:
            # Preserve whether `input` was explicitly set; the default multimodal
            # value must not opt OpenAI-compatible failover configs into image input.
            merged_config = EmbeddingModelConfig(
                model=cred.model or config.model,
                dimension=config.dimension,
                batch_size=config.batch_size,
                query_param=config.query_param,
                document_param=config.document_param,
                provider=cred.provider or config.provider,
                version=config.version,
                ak=cred.ak or config.ak,
                sk=cred.sk or config.sk,
                region=cred.region or config.region,
                host=cred.host or config.host,
                api_key=cred.api_key or config.api_key,
                api_base=cred.api_base or config.api_base,
                api_version=cred.api_version or config.api_version,
                extra_headers=cred.extra_headers or config.extra_headers,
                # Model-behavior fields are shared by all credentials of the
                # same model and live only on the parent config.
                encoding_format=config.encoding_format,
                extra_body=config.extra_body,
                model_path=config.model_path,
                cache_dir=config.cache_dir,
                enable_fusion=config.enable_fusion,
                res_level=config.res_level,
                max_video_frames=config.max_video_frames,
                **({"input": config.input} if "input" in config.model_fields_set else {}),
            )
            provider = self._require_provider(merged_config.provider)
            embedders.append(self._create_embedder(provider, embedder_type, merged_config))
            credential_ids.append(cred.id or f"credential-{len(credential_ids)}")

        if len(embedders) == 1:
            return embedders[0]

        return FailoverEmbedder(
            embedders=embedders,
            credential_ids=credential_ids,
            failback_timeout_seconds=config.failback_timeout_seconds,
            failback_request_count=config.failback_request_count,
        )

    @property
    def dimension(self) -> int:
        """Get dimension from active config."""
        return self.get_dimension()

    def get_dimension(self) -> int:
        """Helper to get dimension from active config"""
        if self.hybrid:
            return self.hybrid.get_effective_dimension()
        if self.dense:
            return self.dense.get_effective_dimension()
        if self.sparse:
            return self.sparse.get_effective_dimension()
        return 2048

    @staticmethod
    def _require_provider(provider: Optional[str]) -> str:
        if not provider:
            raise ValueError("Embedding provider is required")
        return provider.lower()