Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
retrieval: add Jev rerank provider (#5247)
chenjwec13c5b113bb
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.mdindex ecd510fad..f26bc455e 100644--- a/docs/en/configuration/01-server.md+++ b/docs/en/configuration/01-server.md@@ -142,14 +142,15 @@ Changing the model or `dimension` can make existing vector collections incompati| Field | Type / values | Default | Purpose ||---|---|---|---|-| `provider` | `vikingdb`, `cohere`, `openai`, `litellm` / `null` | `null` | Rerank service; inferred from credentials when omitted |-| `model` | string / `null` | `null` | OpenAI-compatible or LiteLLM rerank model |+| `provider` | `vikingdb`, `cohere`, `openai`, `litellm`, `jev` / `null` | `null` | Rerank service; inferred from credentials when omitted |+| `model` | string / `null` | `null` | OpenAI-compatible, LiteLLM, or Jev rerank model || `threshold` | number | `0.1` | Minimum score considered relevant || `max_input_tokens` | integer; `0` or `>= 128` | `0` | Maximum estimated tokens per query-document pair; `0` disables truncation |+| `log_payloads` | boolean | `false` | Log complete rerank request and response payloads; may expose query and document content |Rerank has no separate `enabled` field. It becomes available when the required provider credentials are configured.-Setting `provider` explicitly requires the credentials that provider needs: `ak` and `sk` for `vikingdb`, `api_key` for `cohere`, `api_key` and `api_base` for `openai`, `model` for `litellm`. An incomplete block is rejected when the configuration loads.+`jev` supports direct TypeSafe access (`https://api.typesafe.ai`, model `jev-latest`) and Vercel AI Gateway's TypeSafe-compatible endpoint (`https://ai-gateway.vercel.sh/typesafe`, model `typesafe-ai/jev`) through the existing `api_base` and `model` fields; both speak the same protocol. It sends the query and candidate documents as structured `state`, asks one independent relevance question per candidate, and uses each yes probability as its rerank score. Setting `provider` explicitly requires the credentials that provider needs: `ak` and `sk` for `vikingdb`, `api_key` for `cohere` and `jev`, `api_key` and `api_base` for `openai`, `model` for `litellm`. An incomplete block is rejected when the configuration loads.## Retrieval Settingsdiff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex edddfd75a..a936b7bf3 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -944,7 +944,8 @@ PDF parsing configuration. Three strategies are supported: `local` (local pdfplu### rerank-Reranking model for search result refinement. Supports VikingDB (Volcengine), Cohere, and OpenAI-compatible APIs.+Reranking model for search result refinement. Supports VikingDB (Volcengine), Cohere,+OpenAI-compatible APIs, LiteLLM, and Jev.**Volcengine (VikingDB):**@@ -976,19 +977,67 @@ Reranking model for search result refinement. Supports VikingDB (Volcengine), Co}```+**Jev (TypeSafe System One) provider:**++```json+{+ "rerank": {+ "provider": "jev",+ "api_key": "your-typesafe-api-key",+ "model": "jev-latest",+ "timeout": 120,+ "log_payloads": false,+ "threshold": 0.1+ }+}+```++To use Jev through Vercel AI Gateway, point `api_base` at Vercel's+[TypeSafe-compatible endpoint](https://vercel.com/docs/ai-gateway/sdks-and-apis/typesafe)+and use Vercel's model ID. The request and response formats are identical to+TypeSafe direct access; the adapter does not special-case Vercel:++```json+{+ "rerank": {+ "provider": "jev",+ "api_key": "your-vercel-ai-gateway-api-key",+ "api_base": "https://ai-gateway.vercel.sh/typesafe",+ "model": "typesafe-ai/jev",+ "threshold": 0.1+ }+}+```++Notes for Vercel:++- Use a long-lived AI Gateway API key created with+ `vercel ai-gateway api-keys create`, not the OIDC token from `vercel env pull`,+ which expires after 12 hours.+- The Vercel team must have a credit card on file for AI Gateway; otherwise+ requests fail with 403 `customer_verification_required`.+- `api_base` must include the `/typesafe` suffix. `https://ai-gateway.vercel.sh/v1`+ is Vercel's own evaluate protocol and is not supported by the adapter.++The Jev adapter sends the query and candidate documents as structured System One+`state`, then asks one independent Noul relevance question per candidate. Each returned+yes probability becomes that document's rerank score. All questions are evaluated in+parallel in one request, and scores do not compete or have to sum to 1.+**Parameters**| Parameter | Type | Description ||-----------|------|-------------|-| `provider` | str | `"vikingdb"`, `"cohere"`, or `"openai"`. Auto-detected if omitted. |+| `provider` | str | `"vikingdb"`, `"cohere"`, `"openai"`, `"litellm"`, or `"jev"`. Auto-detected if omitted. || `ak` | str | VikingDB Access Key (vikingdb provider only) || `sk` | str | VikingDB Secret Key (vikingdb provider only) || `model_name` | str | Model name (vikingdb provider only, default: `doubao-seed-rerank`) |-| `api_key` | str | API key (for `openai` or `cohere` providers) |-| `api_base` | str | Endpoint URL (for `openai` provider) |-| `model` | str | Model name (for `openai` providers) |-| `timeout` | float | HTTP request timeout in seconds for OpenAI-compatible providers. Increase for slow or cold-starting local rerank servers. Default: `30.0` |-| `max_input_tokens` | int | Maximum estimated raw-text tokens in each query-document pair sent to the reranker. Oversized inputs retain their beginning and end. `0` disables truncation. Default: `0` |+| `api_key` | str | API key (for `openai`, `cohere`, or `jev` providers) |+| `api_base` | str | Endpoint URL (for `openai` or `jev`; Jev defaults to `https://api.typesafe.ai`, Vercel uses `https://ai-gateway.vercel.sh/typesafe`) |+| `model` | str | Model name for OpenAI-compatible, LiteLLM, or Jev providers |+| `timeout` | float | HTTP request timeout in seconds for HTTP rerank providers, including Jev. Default: `30.0` |+| `max_input_tokens` | int | Maximum estimated raw-text tokens in each query-document pair sent to the reranker. Oversized inputs retain their beginning and end. `0` disables. Default: `0` |+| `log_payloads` | bool | Log complete rerank request and response payloads. May expose query and document content. Default: `false` || `threshold` | float | Score threshold between `0.0` and `1.0`; results below this are filtered out. Default: `0.1` || `extra_headers` | object | Custom HTTP headers (for OpenAI-compatible providers, optional) |@@ -996,6 +1045,8 @@ Reranking model for search result refinement. Supports VikingDB (Volcengine), Co- `vikingdb`: Volcengine VikingDB Rerank API (uses AK/SK)- `cohere`: Cohere Rerank API- `openai`: OpenAI-compatible Rerank API+- `litellm`: LiteLLM Rerank API+- `jev`: Jev (TypeSafe System One) structured-decision API; each document receives an independent Noul relevance scoreIf rerank is not configured, search uses vector similarity only.@@ -1964,7 +2015,7 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry"extra_request_body": {}},"rerank": {- "provider": "vikingdb|cohere|openai|litellm",+ "provider": "vikingdb|cohere|openai|litellm|jev","api_key": "string","model": "string","api_base": "string",diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.mdindex 7d81bec08..956de6ce8 100644--- a/docs/zh/configuration/01-server.md+++ b/docs/zh/configuration/01-server.md@@ -142,14 +142,15 @@ API 型 `embedding`、`vlm`、`query_planner` 和 `rerank` 配置会复用部分| 字段 | 类型 / 可选值 | 默认值 | 作用 ||---|---|---|---|-| `provider` | `vikingdb`、`cohere`、`openai`、`litellm` / `null` | `null` | Rerank 服务类型;省略时根据凭证字段推断 |-| `model` | string / `null` | `null` | OpenAI 兼容或 LiteLLM Rerank 模型 |+| `provider` | `vikingdb`、`cohere`、`openai`、`litellm`、`jev` / `null` | `null` | Rerank 服务类型;省略时根据凭证字段推断 |+| `model` | string / `null` | `null` | OpenAI 兼容、LiteLLM 或 Jev Rerank 模型 || `threshold` | number | `0.1` | 判定结果相关的最低分数 || `max_input_tokens` | integer;`0` 或 `>= 128` | `0` | 每个 query-document pair 的最大估算 token;`0` 表示不截断 |+| `log_payloads` | boolean | `false` | 记录完整 rerank 请求和响应;日志可能包含 query 和文档内容 |Rerank 没有单独的 `enabled` 字段;配置了对应 provider 所需的凭证后才会启用。-显式指定 `provider` 时必须提供该 provider 所需的凭证:`vikingdb` 需要 `ak` 和 `sk`,`cohere` 需要 `api_key`,`openai` 需要 `api_key` 和 `api_base`,`litellm` 需要 `model`。凭证不全的配置在加载时即被拒绝。+`jev` 通过现有 `api_base` 和 `model` 字段同时支持 TypeSafe 直连(`https://api.typesafe.ai`,模型 `jev-latest`)和 Vercel AI Gateway 的 TypeSafe 兼容端点(`https://ai-gateway.vercel.sh/typesafe`,模型 `typesafe-ai/jev`),两者协议相同。它将 query 和候选文档作为结构化 `state`,为每个候选提出一个独立的相关性问题,并将各自的 yes 概率作为 rerank 分数。显式指定 `provider` 时必须提供该 provider 所需的凭证:`vikingdb` 需要 `ak` 和 `sk`,`cohere` 和 `jev` 需要 `api_key`,`openai` 需要 `api_key` 和 `api_base`,`litellm` 需要 `model`。凭证不全的配置在加载时即被拒绝。## 检索配置diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex e7f4b6f54..8ae3f227b 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -912,7 +912,8 @@ PDF 解析配置。支持三种策略:`local`(本地 pdfplumber)、`mineru### rerank-用于搜索结果精排的 Rerank 模型。支持 VikingDB (火山引擎)、Cohere 和 OpenAI 兼容接口。+用于搜索结果精排的 Rerank 模型。支持 VikingDB(火山引擎)、Cohere、OpenAI+兼容接口、LiteLLM 和 Jev。**火山引擎 (VikingDB):**@@ -944,19 +945,65 @@ PDF 解析配置。支持三种策略:`local`(本地 pdfplumber)、`mineru}```+**Jev (TypeSafe System One) 提供方:**++```json+{+ "rerank": {+ "provider": "jev",+ "api_key": "your-typesafe-api-key",+ "model": "jev-latest",+ "timeout": 120,+ "log_payloads": false,+ "threshold": 0.1+ }+}+```++通过 Vercel AI Gateway 使用 Jev 时,把 `api_base` 指向 Vercel 的+[TypeSafe 兼容端点](https://vercel.com/docs/ai-gateway/sdks-and-apis/typesafe),+`model` 使用 Vercel 模型 ID。请求和响应格式与 TypeSafe 直连完全相同,适配器+不做任何区分:++```json+{+ "rerank": {+ "provider": "jev",+ "api_key": "your-vercel-ai-gateway-api-key",+ "api_base": "https://ai-gateway.vercel.sh/typesafe",+ "model": "typesafe-ai/jev",+ "threshold": 0.1+ }+}+```++走 Vercel 时注意:++- `api_key` 用 `vercel ai-gateway api-keys create` 生成的长期 AI Gateway API+ key,不要用 `vercel env pull` 拉取的 OIDC token,后者 12 小时过期。+- Vercel 团队须先在 AI Gateway 页面绑定信用卡,否则请求返回 403+ `customer_verification_required`。+- `api_base` 必须带 `/typesafe` 后缀;`https://ai-gateway.vercel.sh/v1` 是+ Vercel 自有的 evaluate 协议,适配器不支持。++Jev 适配器将 query 和候选文档作为结构化 System One `state`,并为每个候选+提出一个独立的 Noul 相关性问题。每个问题返回的 yes 概率就是该文档的 rerank+分数。所有问题在一次请求中并行计算,各文档分数互不竞争,也不要求总和为 1。+**参数**| 参数 | 类型 | 说明 ||------|------|------|-| `provider` | str | `"vikingdb"`、`"cohere"` 或 `"openai"`。省略时基于字段自动识别。 |+| `provider` | str | `"vikingdb"`、`"cohere"`、`"openai"`、`"litellm"` 或 `"jev"`。省略时基于字段自动识别。 || `ak` | str | VikingDB Access Key(仅 `vikingdb` 提供方使用) || `sk` | str | VikingDB Secret Key(仅 `vikingdb` 提供方使用) || `model_name` | str | 模型名称(仅 `vikingdb` 提供方使用,默认:`doubao-seed-rerank`) |-| `api_key` | str | API Key(用于 `openai` 或 `cohere` 提供方) |-| `api_base` | str | 接口地址(用于 `openai` 提供方) |-| `model` | str | 模型名称(用于 `openai` 提供方) |-| `timeout` | float | OpenAI 兼容 provider 的 HTTP 请求超时时间,单位为秒。对于较慢或冷启动的本地 rerank 服务可适当增大。默认:`30.0` |+| `api_key` | str | API Key(用于 `openai`、`cohere` 或 `jev` 提供方) |+| `api_base` | str | 接口地址(用于 `openai` 或 `jev`;Jev 默认为 `https://api.typesafe.ai`,Vercel 使用 `https://ai-gateway.vercel.sh/typesafe`) |+| `model` | str | 模型名称(用于 OpenAI 兼容、LiteLLM 或 `jev` 提供方) |+| `timeout` | float | HTTP Rerank provider(包括 Jev)的请求超时时间,单位为秒。默认:`30.0` || `max_input_tokens` | int | 每个 query-document 对发送给 reranker 的最大估算原始文本 token 数;超长输入会保留开头和结尾。`0` 表示不截断。默认:`0` |+| `log_payloads` | bool | 记录完整 rerank 请求和响应;日志可能包含 query 和文档内容。默认:`false` || `threshold` | float | 分数阈值,范围为 `0.0` 到 `1.0`。低于此值的结果会被过滤。默认:`0.1` || `extra_headers` | object | 自定义 HTTP 请求头(OpenAI 兼容 provider 可用,可选) |@@ -964,6 +1011,8 @@ PDF 解析配置。支持三种策略:`local`(本地 pdfplumber)、`mineru- `vikingdb`: 火山引擎 VikingDB Rerank API (使用 AK/SK)- `cohere`: Cohere Rerank API- `openai`: OpenAI 兼容的 Rerank 接口+- `litellm`: LiteLLM Rerank 接口+- `jev`: Jev (TypeSafe System One) 结构化判定接口,为每篇文档独立计算 Noul 相关性分数如果未配置 Rerank,搜索仅使用向量相似度。@@ -1935,7 +1984,7 @@ Task 记录文件位于所属账号的系统目录:"extra_request_body": {}},"rerank": {- "provider": "vikingdb|cohere|openai|litellm",+ "provider": "vikingdb|cohere|openai|litellm|jev","api_key": "string","model": "string","api_base": "string",diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex c91cb5396..a9194a273 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -226,6 +226,22 @@"model": "qwen3-rerank","threshold": 0.1,},+ "rerank_jev_example": {+ "_comment": "For direct Jev access through the TypeSafe System One API:",+ "provider": "jev",+ "api_key": "{your-typesafe-api-key}",+ "model": "jev-latest",+ "log_payloads": false,+ "threshold": 0.1,+ },+ "rerank_jev_vercel_example": {+ "_comment": "For Jev through Vercel AI Gateway (TypeSafe-compatible endpoint):",+ "provider": "jev",+ "api_key": "{your-vercel-ai-gateway-api-key}",+ "api_base": "https://ai-gateway.vercel.sh/typesafe",+ "model": "typesafe-ai/jev",+ "threshold": 0.1,+ },"retrieval": {"hotness_alpha": 0.0,"score_propagation_alpha": 1.0,diff --git a/openviking/models/rerank/__init__.py b/openviking/models/rerank/__init__.pyindex 2cf5ae3a3..1c85868d4 100644--- a/openviking/models/rerank/__init__.py+++ b/openviking/models/rerank/__init__.py@@ -8,10 +8,12 @@ Provides rerank functionality for hierarchical retrieval with multiple provider- cohere: Cohere Rerank v3.5 API- litellm: LiteLLM rerank (supports multiple providers)- openai: OpenAI-compatible rerank API+- jev: Jev (TypeSafe System One) rerank"""from openviking.models.rerank.base import RerankBasefrom openviking.models.rerank.cohere_rerank import CohereRerankClient+from openviking.models.rerank.jev_rerank import JevRerankClientfrom openviking.models.rerank.litellm_rerank import LiteLLMRerankClientfrom openviking.models.rerank.openai_rerank import OpenAIRerankClientfrom openviking.models.rerank.volcengine_rerank import RerankClient@@ -20,6 +22,7 @@ __all__ = ["RerankBase","RerankClient","CohereRerankClient",+ "JevRerankClient","LiteLLMRerankClient","OpenAIRerankClient",]diff --git a/openviking/models/rerank/jev_rerank.py b/openviking/models/rerank/jev_rerank.pynew file mode 100644index 000000000..9f73831a3--- /dev/null+++ b/openviking/models/rerank/jev_rerank.py@@ -0,0 +1,173 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""+Jev (TypeSafe System One) Rerank API Client.++TypeSafe has no native rerank endpoint; each document is evaluated by an+independent Noul question against the query. The returned yes probability is+used as the relevance score.++Speaks only the TypeSafe System One protocol. Vercel AI Gateway exposes a+TypeSafe-compatible endpoint (https://ai-gateway.vercel.sh/typesafe), so routing+through Vercel is just a different api_base and model id.++Same interface as the other rerank clients:+rerank_batch(query, documents) -> List[float]+"""++import json+import time+from typing import Dict, List, Optional++import httpx++from openviking.models.rerank.base import RerankBase+from openviking_cli.utils import get_logger++logger = get_logger(__name__)+++class JevRerankClient(RerankBase):+ """Jev rerank client — same interface as VikingDB RerankClient."""++ def __init__(+ self,+ api_key: str,+ model_name: str = "jev-latest",+ api_base: str = "https://api.typesafe.ai",+ timeout: float = 30.0,+ log_payloads: bool = False,+ ):+ super().__init__()+ self.api_key = api_key+ self.model_name = model_name+ self.api_base = api_base.rstrip("/")+ self.api_url = (+ self.api_base+ if self.api_base.endswith("/v1/systemone")+ else f"{self.api_base}/v1/systemone"+ )+ self.timeout = timeout+ self.log_payloads = log_payloads+ self.provider = "jev"+ self._client = httpx.Client(+ headers={+ "Authorization": f"Bearer {self.api_key}",+ "Content-Type": "application/json",+ },+ timeout=timeout,+ )++ def _build_questions(self, documents: List[str]) -> Dict[str, dict]:+ """Build one independent relevance question per document."""+ return {+ f"relevance_{index}": {+ "type": "noul",+ "instructions": {+ "candidate_index": index,+ "question": (+ "Does candidate_documents[candidate_index] answer or match "+ "the retrieval intent of query?"+ ),+ },+ "criteria": {+ "true": "The candidate directly answers or is relevant to the query",+ "false": "The candidate does not answer and is not relevant to the query",+ },+ }+ for index in range(len(documents))+ }++ def rerank_batch(self, query: str, documents: List[str]) -> Optional[List[float]]:+ """Rerank documents against a query using the Jev System One API.++ Returns relevance scores (0-1) in the same order as input documents,+ or None on failure so the caller falls back to vector scores.+ """+ if not documents:+ return []++ questions = self._build_questions(documents)+ body = {+ "model": self.model_name,+ "state": {"query": query, "candidate_documents": documents},+ "questions": questions,+ }++ try:+ if self.log_payloads:+ logger.warning(+ "[JevRerank] Request items=%s payload=%s",+ len(documents),+ json.dumps(body, ensure_ascii=False),+ )+ started = time.monotonic()+ resp = self._client.post(self.api_url, json=body)+ duration_seconds = time.monotonic() - started+ resp.raise_for_status()+ data = resp.json()+ if self.log_payloads:+ logger.warning(+ "[JevRerank] Response status=%s duration_ms=%.1f payload=%s",+ resp.status_code,+ duration_seconds * 1000,+ json.dumps(data, ensure_ascii=False),+ )++ answers = data.get("answers")+ if not isinstance(answers, dict):+ logger.warning("[JevRerank] Response has no answers object")+ return None++ scores = []+ for index in range(len(documents)):+ answer = answers.get(f"relevance_{index}")+ if not isinstance(answer, dict) or answer.get("type") != "noul":+ logger.warning("[JevRerank] Missing or malformed answer for item %s", index)+ return None+ score = answer.get("noul")+ if not isinstance(score, (int, float)) or not 0 <= score <= 1:+ logger.warning("[JevRerank] Invalid relevance score for item %s", index)+ return None+ scores.append(float(score))++ usage = data.get("usage") if isinstance(data.get("usage"), dict) else {}+ input_tokens = usage.get("input_tokens", 0)+ output_tokens = usage.get("output_tokens", 0)+ self.update_token_usage(+ model_name=data.get("model") or self.model_name,+ provider=self.provider,+ prompt_tokens=int(input_tokens or 0)+ or self._estimate_tokens(query)+ + sum(self._estimate_tokens(doc) for doc in documents),+ completion_tokens=int(output_tokens or 0),+ duration_seconds=duration_seconds,+ )++ logger.debug(f"[JevRerank] Reranked {len(documents)} documents")+ return scores++ except httpx.HTTPStatusError as e:+ logger.error(f"[JevRerank] API error: {e.response.status_code} {e.response.text}")+ return None+ except Exception as e:+ logger.error(f"[JevRerank] Rerank failed: {e}")+ return None++ def close(self):+ self._client.close()++ @classmethod+ def from_config(cls, config) -> Optional["JevRerankClient"]:+ """Create JevRerankClient from RerankConfig."""+ if not config or not config.is_available():+ return None+ api_base = config.api_base or "https://api.typesafe.ai"+ default_model = "typesafe-ai/jev" if "ai-gateway.vercel.sh" in api_base else "jev-latest"+ return cls(+ api_key=config.api_key,+ model_name=config.model or default_model,+ api_base=api_base,+ timeout=config.timeout,+ log_payloads=config.log_payloads,+ )diff --git a/openviking/models/rerank/volcengine_rerank.py b/openviking/models/rerank/volcengine_rerank.pyindex 92a5a55ab..5fec1679d 100644--- a/openviking/models/rerank/volcengine_rerank.py+++ b/openviking/models/rerank/volcengine_rerank.py@@ -219,6 +219,11 @@ class RerankClient(RerankBase):return OpenAIRerankClient.from_config(config)+ if provider == "jev":+ from openviking.models.rerank.jev_rerank import JevRerankClient++ return JevRerankClient.from_config(config)+return cls(ak=config.ak,sk=config.sk,diff --git a/openviking_cli/utils/config/rerank_config.py b/openviking_cli/utils/config/rerank_config.pyindex f4e87f73f..96454308c 100644--- a/openviking_cli/utils/config/rerank_config.py+++ b/openviking_cli/utils/config/rerank_config.py@@ -6,11 +6,11 @@ from pydantic import BaseModel, Field, model_validatorclass RerankConfig(BaseModel):- """Configuration for rerank API. Supports VikingDB, Cohere, OpenAI-compatible, and LiteLLM providers."""+ """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', or 'litellm'. Auto-detected from config if omitted.",+ description="Rerank provider: 'vikingdb', 'cohere', 'openai', 'litellm', or 'jev'. Auto-detected from config if omitted.",)# VikingDB fields@@ -22,13 +22,13 @@ class RerankConfig(BaseModel):model_name: str = Field(default="doubao-seed-rerank", description="Rerank model name")model_version: str = Field(default="251028", description="Rerank model version")- # Shared / OpenAI-compatible / Cohere fields+ # Shared provider fieldsapi_key: Optional[str] = Field(- default=None, description="API key (Cohere Bearer token or OpenAI-compatible providers)"+ 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 or LiteLLM providers"+ default=None, description="Model name for OpenAI-compatible, LiteLLM, or Jev providers")extra_headers: Optional[Dict[str, str]] = Field(@@ -38,8 +38,8 @@ class RerankConfig(BaseModel):timeout: float = Field(default=30.0,description=(- "HTTP request timeout in seconds for OpenAI-compatible rerank calls. "- "Increase for local LLM servers with model cold-start latency."+ "HTTP request timeout in seconds for rerank calls. Increase for local "+ "LLM servers with model cold-start latency."),)@@ -56,10 +56,20 @@ class RerankConfig(BaseModel):),)+ 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:@@ -74,9 +84,17 @@ class RerankConfig(BaseModel):raise ValueError("Rerank max_input_tokens must be 0 or at least 128")provider = self._effective_provider()- if provider and provider not in ["vikingdb", "cohere", "openai", "litellm"]:+ if provider and provider not in [+ "vikingdb",+ "cohere",+ "openai",+ "litellm",+ "jev",+ ]:raise ValueError(- f"Rerank provider must be one of ['vikingdb', 'cohere', 'openai', 'litellm'], got '{provider}'"+ "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:@@ -86,9 +104,10 @@ class RerankConfig(BaseModel):if provider == "litellm":if not self.model:raise ValueError("LiteLLM rerank provider requires 'model'")- if provider == "cohere":+ if provider in ("cohere", "jev"):if not self.api_key:- raise ValueError("Cohere rerank provider requires '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'")@@ -97,7 +116,7 @@ class RerankConfig(BaseModel):def is_available(self) -> bool:"""Check if rerank is configured."""p = self._effective_provider()- if p == "cohere":+ if p in ("cohere", "jev"):return self.api_key is not Noneif p == "openai":return self.api_key is not None and self.api_base is not Nonediff --git a/tests/unit/models/rerank/test_jev_rerank.py b/tests/unit/models/rerank/test_jev_rerank.pynew file mode 100644index 000000000..25df84a03--- /dev/null+++ b/tests/unit/models/rerank/test_jev_rerank.py@@ -0,0 +1,216 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for the Jev (TypeSafe System One) rerank client."""++from unittest.mock import MagicMock, patch++import httpx+import pytest++from openviking.models.rerank import JevRerankClient, RerankClient+from openviking_cli.utils.config.rerank_config import RerankConfig+++def _mock_response(payload: dict, status_error=None):+ response = MagicMock()+ response.json.return_value = payload+ response.raise_for_status = MagicMock(side_effect=status_error)+ response.status_code = 401 if status_error else 200+ response.text = "error" if status_error else ""+ return response+++def _systemone_payload(scores: list[float]) -> dict:+ answers = {+ f"relevance_{index}": {"type": "noul", "noul": score} for index, score in enumerate(scores)+ }+ return {+ "model": "jev-1.13.0",+ "answers": answers,+ "usage": {"input_tokens": 100, "output_tokens": 20},+ }+++class TestJevRerankClient:+ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_rerank_batch_basic(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([0.97, 0.04, 0.07]))++ client = JevRerankClient(api_key="test-key")+ scores = client.rerank_batch("What is UCW?", ["doc A", "doc B", "doc C"])++ assert scores == [0.97, 0.04, 0.07]+ body = mock_client.post.call_args[1]["json"]+ assert body["model"] == "jev-latest"+ assert body["state"] == {+ "query": "What is UCW?",+ "candidate_documents": ["doc A", "doc B", "doc C"],+ }+ assert len(body["questions"]) == 3+ assert body["questions"]["relevance_0"]["type"] == "noul"+ assert body["questions"]["relevance_2"]["instructions"]["candidate_index"] == 2+ mock_client.post.assert_called_once_with("https://api.typesafe.ai/v1/systemone", json=body)++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_vercel_gateway_uses_typesafe_compatible_endpoint(self, mock_client_class):+ """Vercel is just another api_base; the wire protocol stays TypeSafe System One."""+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([0.91, 0.08]))++ client = JevRerankClient(+ api_key="vercel-key",+ api_base="https://ai-gateway.vercel.sh/typesafe",+ model_name="typesafe-ai/jev",+ )+ assert client.rerank_batch("query", ["first", "second"]) == [0.91, 0.08]++ call = mock_client.post.call_args+ assert call.args == ("https://ai-gateway.vercel.sh/typesafe/v1/systemone",)+ assert call.kwargs["json"]["model"] == "typesafe-ai/jev"+ assert call.kwargs["json"]["questions"]["relevance_0"]["type"] == "noul"+ assert "headers" not in call.kwargs++ @patch("openviking.models.rerank.jev_rerank.logger.warning")+ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_logs_request_and_response_without_api_key(self, mock_client_class, mock_log):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([0.9]))++ client = JevRerankClient(api_key="secret-key", log_payloads=True)+ assert client.rerank_batch("query", ["document"]) == [0.9]++ messages = [str(call) for call in mock_log.call_args_list]+ assert any("[JevRerank] Request" in message for message in messages)+ assert any("[JevRerank] Response" in message for message in messages)+ assert all("secret-key" not in message for message in messages)++ @patch("openviking.models.rerank.jev_rerank.logger.warning")+ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_payload_logging_disabled_by_default(self, mock_client_class, mock_log):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([0.9]))++ client = JevRerankClient(api_key="secret-key")+ assert client.rerank_batch("query", ["document"]) == [0.9]+ mock_log.assert_not_called()++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_rerank_batch_empty(self, mock_client_class):+ client = JevRerankClient(api_key="test-key")+ assert client.rerank_batch("query", []) == []++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_rerank_batch_api_error_returns_none(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ error = httpx.HTTPStatusError("401", request=MagicMock(), response=MagicMock())+ mock_client.post.return_value = _mock_response({}, status_error=error)++ client = JevRerankClient(api_key="bad-key")+ assert client.rerank_batch("query", ["doc"]) is None++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_missing_answer_returns_none(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(+ {"answers": {}, "usage": {"input_tokens": 1, "output_tokens": 1}}+ )++ client = JevRerankClient(api_key="key")+ assert client.rerank_batch("q", ["doc"]) is None++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_each_document_gets_an_independent_question(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([0.2, 0.8, 0.4]))++ client = JevRerankClient(api_key="key")+ scores = client.rerank_batch("q", ["a", "b", "c"])++ assert scores == [0.2, 0.8, 0.4]+ questions = mock_client.post.call_args[1]["json"]["questions"]+ assert set(questions) == {"relevance_0", "relevance_1", "relevance_2"}++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_invalid_score_returns_none(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ mock_client.post.return_value = _mock_response(_systemone_payload([1.1]))++ client = JevRerankClient(api_key="key")+ assert client.rerank_batch("q", ["doc"]) is None++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_close(self, mock_client_class):+ mock_client = MagicMock()+ mock_client_class.return_value = mock_client+ client = JevRerankClient(api_key="key")+ client.close()+ mock_client.close.assert_called_once()+++class TestJevRerankConfig:+ def test_explicit_jev_provider(self):+ config = RerankConfig(provider="jev", api_key="key")+ assert config._effective_provider() == "jev"+ assert config.is_available() is True++ def test_jev_auto_detected_from_api_base(self):+ config = RerankConfig(api_key="key", api_base="https://api.typesafe.ai")+ assert config._effective_provider() == "jev"++ def test_jev_auto_detected_from_vercel_typesafe_base(self):+ config = RerankConfig(api_key="key", api_base="https://ai-gateway.vercel.sh/typesafe")+ assert config._effective_provider() == "jev"++ def test_plain_vercel_base_is_not_jev(self):+ config = RerankConfig(api_key="key", api_base="https://ai-gateway.vercel.sh/v1")+ assert config._effective_provider() == "openai"++ def test_jev_requires_api_key(self):+ with pytest.raises(ValueError, match="Jev"):+ RerankConfig(provider="jev")++ def test_unknown_provider_rejected(self):+ with pytest.raises(ValueError, match="Rerank provider"):+ RerankConfig(provider="nope", api_key="k")+++class TestJevDispatch:+ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_from_config_creates_jev_client(self, mock_client_class):+ config = RerankConfig(provider="jev", api_key="jev-key")+ client = RerankClient.from_config(config)+ assert isinstance(client, JevRerankClient)+ assert client.api_key == "jev-key"+ assert client.model_name == "jev-latest"++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_from_config_uses_custom_model(self, mock_client_class):+ config = RerankConfig(provider="jev", api_key="key", model="jev-1.13.0")+ client = RerankClient.from_config(config)+ assert client.model_name == "jev-1.13.0"++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_from_config_enables_payload_logging(self, mock_client_class):+ config = RerankConfig(provider="jev", api_key="key", log_payloads=True)+ client = RerankClient.from_config(config)+ assert client.log_payloads is True++ @patch("openviking.models.rerank.jev_rerank.httpx.Client")+ def test_from_config_uses_vercel_model_default(self, mock_client_class):+ config = RerankConfig(+ provider="jev",+ api_key="key",+ api_base="https://ai-gateway.vercel.sh/typesafe",+ )+ client = RerankClient.from_config(config)+ assert client.model_name == "typesafe-ai/jev"+ assert client.api_url == "https://ai-gateway.vercel.sh/typesafe/v1/systemone"