Skip to content

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

5.5 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
from typing import Dict, Optional

from pydantic import BaseModel, Field, model_validator


class RerankConfig(BaseModel):
    """Configuration for rerank API. Supports VikingDB, Cohere, OpenAI-compatible, LiteLLM, and Jev (TypeSafe) providers."""

    provider: Optional[str] = Field(
        default=None,
        description="Rerank provider: 'vikingdb', 'cohere', 'openai', 'litellm', or 'jev'. Auto-detected from config if omitted.",
    )

    # VikingDB fields
    ak: Optional[str] = Field(default=None, description="VikingDB Access Key")
    sk: Optional[str] = Field(default=None, description="VikingDB Secret Key")
    host: str = Field(
        default="api-vikingdb.vikingdb.cn-beijing.volces.com", description="VikingDB API host"
    )
    model_name: str = Field(default="doubao-seed-rerank", description="Rerank model name")
    model_version: str = Field(default="251028", description="Rerank model version")

    # Shared provider fields
    api_key: Optional[str] = Field(
        default=None, description="API key for Cohere, OpenAI-compatible, or Jev providers"
    )
    api_base: Optional[str] = Field(default=None, description="Custom endpoint URL")
    model: Optional[str] = Field(
        default=None, description="Model name for OpenAI-compatible, LiteLLM, or Jev providers"
    )
    mode: Optional[str] = Field(
        default="noul",
        description="Jev rerank mode: 'noul' or 'choice'",
    )

    candidates_visible: bool = Field(
        default=True,
        description=(
            "Jev rerank candidate visibility: true shares all candidates in state; "
            "false places each candidate in its own question (noul mode only)"
        ),
    )

    extra_headers: Optional[Dict[str, str]] = Field(
        default=None, description="Extra HTTP headers for OpenAI-compatible providers"
    )

    timeout: float = Field(
        default=30.0,
        description=(
            "HTTP request timeout in seconds for rerank calls. Increase for local "
            "LLM servers with model cold-start latency."
        ),
    )

    threshold: float = Field(
        default=0.1, description="Relevance threshold (score > threshold is relevant)"
    )

    max_input_tokens: int = Field(
        default=0,
        ge=0,
        description=(
            "Maximum estimated raw-text tokens for each query-document pair sent to "
            "the rerank provider; 0 disables truncation"
        ),
    )

    log_payloads: bool = Field(
        default=False,
        description=(
            "Log complete rerank request and response payloads. Disabled by default "
            "because payloads may contain sensitive query and document content."
        ),
    )

    def _effective_provider(self) -> Optional[str]:
        """Auto-detect provider from config fields when not explicitly set."""
        if self.provider:
            return self.provider.lower()
        if self.api_base and "typesafe" in self.api_base:
            return "jev"
        if self.api_key and self.api_base:
            return "openai"
        if self.api_key:
            return "cohere"
        if self.ak and self.sk:
            return "vikingdb"
        return None

    @model_validator(mode="after")
    def validate_provider_fields(self) -> "RerankConfig":
        if 0 < self.max_input_tokens < 128:
            raise ValueError("Rerank max_input_tokens must be 0 or at least 128")

        provider = self._effective_provider()
        if provider == "jev" and self.mode is not None:
            self.mode = self.mode.strip().lower()
            if self.mode not in ("noul", "choice"):
                raise ValueError("Jev rerank mode must be one of ['noul', 'choice']")
            if self.mode == "choice" and not self.candidates_visible:
                raise ValueError("Jev choice rerank requires candidates_visible=True")

        if provider and provider not in [
            "vikingdb",
            "cohere",
            "openai",
            "litellm",
            "jev",
        ]:
            raise ValueError(
                "Rerank provider must be one of "
                "['vikingdb', 'cohere', 'openai', 'litellm', 'jev'], got "
                f"'{provider}'"
            )
        if provider == "openai":
            if not self.api_key or not self.api_base:
                raise ValueError(
                    "OpenAI-compatible rerank provider requires 'api_key' and 'api_base'"
                )
        if provider == "litellm":
            if not self.model:
                raise ValueError("LiteLLM rerank provider requires 'model'")
        if provider in ("cohere", "jev"):
            if not self.api_key:
                label = "Cohere" if provider == "cohere" else "Jev"
                raise ValueError(f"{label} rerank provider requires 'api_key'")
        if provider == "vikingdb":
            if not self.ak or not self.sk:
                raise ValueError("VikingDB rerank provider requires 'ak' and 'sk'")
        return self

    def is_available(self) -> bool:
        """Check if rerank is configured."""
        p = self._effective_provider()
        if p in ("cohere", "jev"):
            return self.api_key is not None
        if p == "openai":
            return self.api_key is not None and self.api_base is not None
        if p == "litellm":
            return self.model is not None
        if p == "vikingdb":
            return self.ak is not None and self.sk is not None
        return False