Skip to content

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

retrieval: add Jev rerank provider (#5247)

chenjwec13c5b113bb
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index 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 Settings
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 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 score
If 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.md
index 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.md
index 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.example
index 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__.py
index 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 RerankBase
from openviking.models.rerank.cohere_rerank import CohereRerankClient
+from openviking.models.rerank.jev_rerank import JevRerankClient
from openviking.models.rerank.litellm_rerank import LiteLLMRerankClient
from openviking.models.rerank.openai_rerank import OpenAIRerankClient
from 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.py
new file mode 100644
index 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.py
index 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.py
index 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_validator
class 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 fields
api_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 None
if p == "openai":
return self.api_key is not None and self.api_base is not None
diff --git a/tests/unit/models/rerank/test_jev_rerank.py b/tests/unit/models/rerank/test_jev_rerank.py
new file mode 100644
index 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"