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
fix(retrieve): opt-in rerank for context mode and decouple rerank.threshold (#6605)
t0sakic7239e819eb7
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex 759033e26..f49b76652 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -9,10 +9,18 @@ OpenViking provides multiple retrieval methods, including simple vector similari| Intent Analysis | No | Requires session content and `retrieval.enable_intent=true` || Session Context | No | Optional || Query Expansion | No | When session content exists and intent analysis is enabled |-| Reranking | No | Used for text queries when a reranker is configured |+| Reranking | Never | `mode="list"`: text queries when a reranker is configured. `mode="context"`: only when `retrieval.apply_rerank_to_context` is on || Default Limit | 10 | 10 per planned query || Use Case | Simple queries | Conversational search |+Reranking applies per path:++- `find()` never reranks; it always uses vector scores.+- `search(mode="list")` reranks text queries when a usable `rerank` config exists.+- `search(mode="context")` reranks only when the server sets `retrieval.apply_rerank_to_context=true` (default `false`) and a usable `rerank` config exists. It reranks once per assembly, over the merged candidate pool before quotas and the token budget apply, for text queries only, and falls back to vector scores if the rerank call fails.++Score thresholds follow one rule: a request `score_threshold` overrides everything and filters whatever scores the path produces. Without it, `rerank.threshold` (default `0.1`) filters only scores the reranker produced; vector-only paths, including `find()` and a failed rerank fallback, default to `0`.+## Retrieval PipelineThe core retrieval pipeline is as follows:@@ -417,7 +425,7 @@ Semantic retrieval with optional session-aware query planning.`search()` uses the same target resolution and explicit tag filtering rules as `find()`, including the peer collection filter selected by `X-OpenViking-Actor-Peer` or SDK `actor_peer_id`. When `image_url` is provided, `search()` uses direct image retrieval and skips session query planning. `keywords` requires a non-empty text query, does not support images, and requires a remote VikingDB backend with a full-text index.-Event time decay applies to results tagged `memory_type=events` in semantic `find()` and both `search(mode="list")` and `search(mode="context")`. Memory extraction writes this tag on user/peer event L2 records; retrieval identifies events by the tag rather than inferring the type from a URI or level. Untagged/non-event results, query-less filter-only `find()`, `recall`, `grep`, and `glob` are unaffected. During event recall, the vector engine multiplies the original vector score by `time_score`. List responses expose this recall-stage vector score as `origin_score` and the factor as `time_score`; `score` is the final retrieval score, which may come from model rerank. Context mode uses that final score while assembling its candidates. The CLI labels list-result scores as semantic, time, and final scores. Inside the protection period `time_score` is 1, so the original score is unchanged. Time distance follows the VikingDB exponential decay operator, using the absolute difference from the request time. Time is read from the existing indexed `updated_at` field; no reindex or timestamp rewrite is required. Local fusion preserves the original score for missing or invalid timestamps; cloud fusion uses the indexed date-time field and the backend operator. The curve is owned by the server; callers only provide the per-request protection period. No `ov.conf` or `ovcli.conf` change is required.+Event time decay applies to results tagged `memory_type=events` in semantic `find()` and both `search(mode="list")` and `search(mode="context")`. Memory extraction writes this tag on user/peer event L2 records; retrieval identifies events by the tag rather than inferring the type from a URI or level. Untagged/non-event results, query-less filter-only `find()`, `recall`, `grep`, and `glob` are unaffected. During event recall, the vector engine multiplies the original vector score by `time_score`. List responses expose this recall-stage vector score as `origin_score` and the factor as `time_score`; `score` is the final retrieval score, which may come from model rerank. Context mode assembles its candidates with vector scores, or with the model score when `retrieval.apply_rerank_to_context` is on. The CLI labels list-result scores as semantic, time, and final scores. Inside the protection period `time_score` is 1, so the original score is unchanged. Time distance follows the VikingDB exponential decay operator, using the absolute difference from the request time. Time is read from the existing indexed `updated_at` field; no reindex or timestamp rewrite is required. Local fusion preserves the original score for missing or invalid timestamps; cloud fusion uses the indexed date-time field and the backend operator. The curve is owned by the server; callers only provide the per-request protection period. No `ov.conf` or `ovcli.conf` change is required.New and updated memories produced by memory extraction automatically receive a `memory_type=<type>` search tag. With decay enabled, both local and cloud backends recall records tagged `memory_type=events` separately and merge them with the complementary untagged/non-event branch; both branches preserve the original scope, permission and level filters, without requiring a peer ID. Existing data is not backfilled; untagged memories keep their original scores. Direct content refreshes and ordinary tag updates preserve the existing memory type without inferring it from the URI.@@ -659,7 +667,7 @@ Injecting context every turn used to mean searching per type, reading each hit b**Pipeline**:1. **L1 query understanding**: optional bounded intent expansion from the session's recent messages (at most 3 queries, timeout fuse, falls back to the original query)-2. **L0 retrieval**: bucketed per `quotas`, or a single whole-scope search when quotas are off+2. **L0 retrieval**: bucketed per `quotas`, or a single whole-scope search when quotas are off. Hits carry vector scores, as in `find()`; when the server enables `retrieval.apply_rerank_to_context` and has a usable `rerank` config, the merged candidates are reranked once against the original query and its expansions before quotas and the budget apply (see below)3. **L2 assembly**: tier filling inside the token budget (everyone at their category's default tier first, then leftover budget deepens in score order); an oversized tier falls back instead of being truncated4. **L3 rewrite**: optional digest with URI citations (timeout fuse; on failure the unrewritten `rendered` is still returned; an exact `NO_RELEVANT_MEMORY` result is reported as `stats.rewrite="no_relevant"` so Coding Agent clients inject nothing instead of falling back to `rendered`)@@ -673,6 +681,8 @@ Injecting context every turn used to mean searching per type, reading each hit b**L0 retrieval domain**: `query`, `image_url`, `context_type`, `limit`, `score_threshold`, `filter`, `tags`, `since`/`until`, and the optional `events_time_decay_protection` behave as in list mode. `limit` applies only to quota-free retrieval. Once `purpose` or explicit `quotas` enables bucketed retrieval, the sum of the per-category quotas is the candidate ceiling. `target_uri` is not supported in context mode yet (returns 400); `level` is ignored because `detail` governs tiers.+**Optional rerank**: with `retrieval.apply_rerank_to_context` on and a usable `rerank` config, text queries make one rerank call per request over the merged, deduplicated candidates, scored against the original `query` joined with its expanded queries, so a hit only an expansion recalled is judged on the topic that expansion named. Quota-free retrieval recalls `2 × limit` candidates for it; bucketed retrieval reranks up to `2 × quota` per bucket, giving room a short bucket leaves to the others. A Skill is scored on its package abstract. A reranked candidate's `score` becomes its rerank score, and `other_peer_penalty` still applies on top. `score_threshold` then filters the final scores instead of recall; without it, `rerank.threshold` filters only model scores. Candidates the model did not score (empty text, or a failed rerank call) keep their vector scores. Image queries skip rerank. `stats.rerank` reports `used`, `candidates` (sent to the model) and `capped` (left out by the per-bucket cap)+**L1 query understanding**| Parameter | Type | Default | Description |@@ -809,7 +819,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \| `entries[].text` | string | Body for that tier; empty at the `uri` tier || `rendered` | string | Flat XML context block, ready to inject; empty when rewrite reports `no_relevant` || `digest` | string | Digest when the rewrite succeeded, empty string on failure or when the compressor reports no relevant memory |-| `stats` | object | Budget usage, tier distribution, expansion and rewrite status (`off`, `ok`, `no_relevant`, `failed` or `timeout`), dedup ledger state; carries `retrieval_errors` when a retrieval scope failed, so a broken index is distinguishable from having no relevant memories |+| `stats` | object | Budget usage, tier distribution, expansion and rewrite status (`off`, `ok`, `no_relevant`, `failed` or `timeout`), dedup ledger state; carries `retrieval_errors` when a retrieval scope failed, so a broken index is distinguishable from having no relevant memories, and `rerank` when context rerank applied to the request |When `stats.rewrite` is `no_relevant`, the response keeps `entries` forinspection but returns both `digest` and `rendered` as empty strings. This makesdiff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.mdindex 38e9535ca..ddd442271 100644--- a/docs/en/concepts/07-retrieval.md+++ b/docs/en/concepts/07-retrieval.md@@ -89,7 +89,7 @@ class TypedQuery:| THINKING with a usable rerank configuration | `2 × limit` | One pass over the recalled candidates, returning at most `limit` results || THINKING without a usable rerank configuration | `limit` | Disabled |-`find()` uses QUICK. `search()` automatically selects THINKING when a reranker is configured, otherwise QUICK. This internal retrieval mode is separate from LLM reasoning parameters and session intent analysis. Queries generated by intent analysis continue to be retrieved and ranked separately, then aggregated as before.+`find()` uses QUICK. `search()` automatically selects THINKING when a reranker is configured, otherwise QUICK. This internal retrieval mode is separate from LLM reasoning parameters and session intent analysis. Queries generated by intent analysis continue to be retrieved and ranked separately, then aggregated as before. Context mode (`search(mode="context")`) recalls through `find()`, so it uses vector scores unless the server enables `retrieval.apply_rerank_to_context`; it then reranks its merged candidates once per request, against the original query and its session expansions, before quotas and the token budget apply.Image queries skip text reranking and recall `limit` candidates. They default to L2 unless `level` is specified.@@ -99,7 +99,7 @@ Rerank processes only the candidates from the completed global search; it never- Candidate index records supply the `abstract` text for reranking.- Scores and ranking use rerank scores when available, otherwise vector scores; access frequency, update time, and parent-directory scores do not affect them.-- Score thresholds apply after reranking, or to vector scores when reranking is disabled.+- Score thresholds apply after reranking. A request `score_threshold` filters any score; without one, `rerank.threshold` filters only model rerank scores; vector scores (reranking disabled or failed) only need to exceed `0`.- Failed requests or invalid rerank results retain the existing fallback to vector scores.- Directory priority queues, parent-to-child score propagation, and convergence rounds are removed.diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.mdindex fae2b678e..31f21f62c 100644--- a/docs/en/configuration/01-server.md+++ b/docs/en/configuration/01-server.md@@ -246,7 +246,7 @@ discard source restrictions. Empty does not mean unknown or inapplicable.| `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 || `mode` | `noul`, `choice`, or `null` | `noul` | Jev rerank mode; `null` also uses `noul` |-| `threshold` | number | `0.1` | Minimum score considered relevant |+| `threshold` | number | `0.1` | Minimum rerank score considered relevant; filters only model rerank scores, never vector scores, and a request `score_threshold` overrides it || `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 |@@ -259,7 +259,8 @@ Rerank has no separate `enabled` field. It becomes available when the required p```json{"retrieval": {- "enable_intent": true+ "enable_intent": true,+ "apply_rerank_to_context": false}}```@@ -269,8 +270,9 @@ Rerank has no separate `enabled` field. It becomes available when the required p| Field | Type / values | Default | Purpose ||---|---|---|---|| `enable_intent` | boolean | `true` | Run intent analysis/query planning when `session_id` is present |+| `apply_rerank_to_context` | boolean | `false` | Rerank `search(mode="context")` candidates with the configured `rerank` model |-Search and Find requests default to `limit: 10`; override the limit on each API or SDK request. `retrieval.enable_intent` controls LLM query planning for session-aware Search, while result reranking is enabled only when `rerank` has a usable provider configuration.+Search and Find requests default to `limit: 10`; override the limit on each API or SDK request. `retrieval.enable_intent` controls LLM query planning for session-aware Search, while result reranking is enabled only when `rerank` has a usable provider configuration. Context mode recalls with Find's vector scores; with `retrieval.apply_rerank_to_context` and a usable `rerank`, it also reranks its merged candidates once against the original query and its expansions before quotas and the token budget apply, which adds one rerank call per request.## Storage Settingsdiff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 5d397c0bf..42289d67b 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1202,7 +1202,7 @@ using Choice through MCP.| `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` |+| `threshold` | float | Rerank score threshold between `0.0` and `1.0`; reranked results below this are filtered out. It never filters vector scores (rerank not used, or failed), and a request `score_threshold` overrides it. Default: `0.1` || `extra_headers` | object | Custom HTTP headers (for OpenAI-compatible providers, optional) |**Supported providers:**@@ -1222,6 +1222,7 @@ Configuration for session intent analysis and context assembly timeouts.{"retrieval": {"enable_intent": true,+ "apply_rerank_to_context": false,"recall_intent_timeout_s": 5.0,"recall_rewrite_timeout_s": 30.0}@@ -1231,6 +1232,7 @@ Configuration for session intent analysis and context assembly timeouts.| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `enable_intent` | bool | Run intent analysis and query planning when `search()` receives a `session_id`. | `true` |+| `apply_rerank_to_context` | bool | Rerank `mode="context"` candidates with the configured [`rerank`](#rerank) model, once per request against the original query and its expansions, before quotas and the token budget apply. Needs a usable `rerank` config; image queries keep vector scores. | `false` |Session intent analysis in ordinary `search()` and query expansion in `mode="context"` share `recall_intent_timeout_s`. Context digest rewriting uses a separate timeout:diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex 41aaa8386..663b5c439 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -9,10 +9,18 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关| 意图分析 | 否 | 有会话内容且 `retrieval.enable_intent=true` 时执行 || 会话上下文 | 不使用 | 可选 || 查询扩展 | 否 | 意图分析启用且有会话内容时执行 |-| 重排序 | 不使用 | 配置了重排序模型时用于文本查询 |+| 重排序 | 从不使用 | `mode="list"`:配置了重排序模型时用于文本查询。`mode="context"`:仅在开启 `retrieval.apply_rerank_to_context` 时使用 || 默认结果数 | 10 | 每条规划查询最多 10 条 || 使用场景 | 简单查询 | 对话式搜索 |+各路径的 Rerank 情况:++- `find()` 从不执行 Rerank,始终使用向量分数。+- `search(mode="list")` 在配置了可用的 `rerank` 时对文本查询执行 Rerank。+- `search(mode="context")` 仅在服务端设置 `retrieval.apply_rerank_to_context=true`(默认 `false`)且 `rerank` 配置可用时执行 Rerank:每次组装在配额和 token 预算之前对合并后的候选统一重排一次,仅限文本查询,Rerank 调用失败时回退到向量分数。++分数阈值遵循同一规则:请求中的 `score_threshold` 优先,过滤该路径产出的任何分数;未指定时,`rerank.threshold`(默认 `0.1`)只过滤 Reranker 产出的分数,仅用向量分数的路径(包括 `find()` 和 Rerank 失败后的回退)默认阈值为 `0`。+## 检索流程检索的核心流程如下:@@ -417,7 +425,7 @@ ov find "红色海报风格" --image ./poster.png --uri "viking://resources/imag`search()` 使用和 `find()` 相同的目标解析和显式标签过滤规则,包括由 `X-OpenViking-Actor-Peer` 或 SDK `actor_peer_id` 选择的 peer 集合过滤。提供 `image_url` 时,`search()` 会直接执行图片检索并跳过会话 query planning。`keywords` 要求非空文本 query,不支持图片,且需要远程 VikingDB 配置全文索引。-事件时间衰减作用于语义 `find()`、`search(mode="list")` 和 `search(mode="context")` 中带 `memory_type=events` 标签的结果。记忆提取流程将该标签写入 user / peer 事件的 L2 记录;检索按标签判断,不从 URI 或层级推断事件类型。无事件标签的结果、无 query 的纯过滤 `find()`、`recall`、`grep` 和 `glob` 不受影响。事件召回阶段由向量引擎将原向量分乘以 `time_score`;响应中的 `score` 是最终检索分数,开启模型 rerank 时使用模型分。context 模式按最终分组装候选。保护期内 `time_score` 为 1,原分不变;时间距离与 VikingDB 指数衰减算子一致,取时间戳与请求时间的绝对差。list 响应中的 event 结果额外返回 `origin_score` 和 `time_score`,CLI 分别展示为 semantic、time 和 final 分。时间取自已有索引的 `updated_at` 字段,无需重新索引或改写时间戳;本地计算遇到缺失或非法时间时保持原分;云端使用索引中的日期时间字段和后处理算子。衰减曲线由服务端内部维护,调用方只需按请求传入保护期,无需修改 `ov.conf` 或 `ovcli.conf`。+事件时间衰减作用于语义 `find()`、`search(mode="list")` 和 `search(mode="context")` 中带 `memory_type=events` 标签的结果。记忆提取流程将该标签写入 user / peer 事件的 L2 记录;检索按标签判断,不从 URI 或层级推断事件类型。无事件标签的结果、无 query 的纯过滤 `find()`、`recall`、`grep` 和 `glob` 不受影响。事件召回阶段由向量引擎将原向量分乘以 `time_score`;响应中的 `score` 是最终检索分数,开启模型 rerank 时使用模型分。context 模式默认按向量分组装候选,开启 `retrieval.apply_rerank_to_context` 后按模型分组装。保护期内 `time_score` 为 1,原分不变;时间距离与 VikingDB 指数衰减算子一致,取时间戳与请求时间的绝对差。list 响应中的 event 结果额外返回 `origin_score` 和 `time_score`,CLI 分别展示为 semantic、time 和 final 分。时间取自已有索引的 `updated_at` 字段,无需重新索引或改写时间戳;本地计算遇到缺失或非法时间时保持原分;云端使用索引中的日期时间字段和后处理算子。衰减曲线由服务端内部维护,调用方只需按请求传入保护期,无需修改 `ov.conf` 或 `ovcli.conf`。由记忆提取流程新生成或更新的记忆会自动写入 `memory_type=<类型>` 检索标签。启用衰减时,本地和云端均将按是否带 `memory_type=events` 标签拆成互斥且完整覆盖原范围的两路,再合并排序;两路均保留原 scope 的权限、目录和 level 限制,无需指定 peer id。存量数据不补标签,无标签记忆保持原分。直接内容刷新和普通标签更新保留已有类型,不从 URI 推断或重设类型。@@ -659,7 +667,7 @@ Agent 插件每轮注入上下文时,过去需要按类型逐个检索、再**处理流程**:1. **L1 查询理解**:可选,结合 Session 最近消息做有界意图扩展(最多 3 条查询,超时熔断,失败回退原查询)-2. **L0 检索**:按 `quotas` 分桶独立检索,或不设配额时全域检索一次+2. **L0 检索**:按 `quotas` 分桶独立检索,或不设配额时全域检索一次。命中使用与 `find()` 相同的向量分数;服务端开启 `retrieval.apply_rerank_to_context` 且 `rerank` 配置可用时,合并后的候选会在配额和预算之前用原始查询及其扩展查询统一重排一次(见下文)3. **L2 组装**:token 预算内填充档位(全员先落到各自类别的默认档,再用剩余预算按分数序加深),超限退档不截断4. **L3 重写**:可选,把组装结果压成带 URI 引用的 digest(超时熔断,失败仍返回未重写的 `rendered`;精确返回 `NO_RELEVANT_MEMORY` 时记为 `stats.rewrite="no_relevant"`,Coding Agent 客户端不会再回退注入 `rendered`)@@ -673,6 +681,8 @@ Agent 插件每轮注入上下文时,过去需要按类型逐个检索、再**L0 检索域**:`query`、`image_url`、`context_type`、`limit`、`score_threshold`、`filter`、`tags`、`since`/`until` 以及可选的 `events_time_decay_protection` 与 list 模式一致。`limit` 只约束 quota-free 检索;一旦 `purpose` 或显式 `quotas` 启用分桶检索,各分类配额之和就是候选上限。`target_uri` 在 context 模式下暂不支持(返回 400);`level` 被忽略,档位由 `detail` 决定。+**可选 Rerank**:开启 `retrieval.apply_rerank_to_context` 且 `rerank` 配置可用时,文本查询每个请求对合并、去重后的候选执行一次 Rerank,以原始 `query` 与各条扩展查询拼接后的文本打分,只由扩展查询召回的命中也按该扩展点明的主题评判。不设配额时为此召回 `2 × limit` 条候选;分桶检索每桶最多重排 `2 × quota` 条,候选不足的桶留出的名额让给其他桶。Skill 以其包摘要参与打分。参与重排的候选 `score` 变为 Rerank 分数,`other_peer_penalty` 仍在其上生效。`score_threshold` 随之改为过滤最终分数而非召回;未指定时,`rerank.threshold` 只过滤模型分数。模型未打分的候选(文本为空或 Rerank 调用失败)保留向量分数。图像查询不执行 Rerank。`stats.rerank` 报告 `used`、`candidates`(送入模型的数量)和 `capped`(被每桶上限排除的数量)+**L1 查询理解**| 参数 | 类型 | 默认值 | 说明 |@@ -809,7 +819,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \| `entries[].text` | string | 该档位的正文;`uri` 档为空 || `rendered` | string | 扁平 XML 上下文块,可直接注入;重写返回 `no_relevant` 时为空 || `digest` | string | 重写成功时的摘要;失败或压缩器判定无相关记忆时为空字符串 |-| `stats` | object | 预算用量、档位分布、扩展与重写状态(`off`、`ok`、`no_relevant`、`failed` 或 `timeout`)、去重账本状态;某个检索域失败时附带 `retrieval_errors`,用于区分「检索坏了」和「确实没有相关记忆」 |+| `stats` | object | 预算用量、档位分布、扩展与重写状态(`off`、`ok`、`no_relevant`、`failed` 或 `timeout`)、去重账本状态;某个检索域失败时附带 `retrieval_errors`,用于区分「检索坏了」和「确实没有相关记忆」;请求应用了 context Rerank 时附带 `rerank` |当 `stats.rewrite` 为 `no_relevant` 时,响应仍保留 `entries` 供检查,但 `digest` 和`rendered` 都为空字符串。这样即使客户端尚未识别新状态,也不会回退注入原文。本轮diff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.mdindex a09c77f4b..e7aed0b51 100644--- a/docs/zh/concepts/07-retrieval.md+++ b/docs/zh/concepts/07-retrieval.md@@ -89,7 +89,7 @@ class TypedQuery:| THINKING,且配置了可用的 Rerank | `2 × limit` | 对召回候选统一执行一次,返回最多 `limit` 条 || THINKING,未配置可用的 Rerank | `limit` | 不执行 |-`find()` 使用 QUICK。`search()` 配置了可用的 Rerank 时自动使用 THINKING,否则使用 QUICK。这是内部检索模式,不是 LLM 的思考参数,也不控制会话意图分析。意图分析生成的多条查询仍分别检索和排序,再按现有方式汇总。+`find()` 使用 QUICK。`search()` 配置了可用的 Rerank 时自动使用 THINKING,否则使用 QUICK。这是内部检索模式,不是 LLM 的思考参数,也不控制会话意图分析。意图分析生成的多条查询仍分别检索和排序,再按现有方式汇总。Context 模式(`search(mode="context")`)通过 `find()` 召回,因此默认使用向量分数;服务端开启 `retrieval.apply_rerank_to_context` 后,会在配额和 token 预算之前,用原始查询及其会话扩展查询对合并后的候选每个请求统一重排一次。图像查询跳过文本 Rerank,候选数为 `limit`;未指定 `level` 时默认搜索 L2。@@ -99,7 +99,7 @@ Rerank 只处理本次全局召回的候选,不会触发下一轮检索。例- 使用候选索引记录的 `abstract` 字段作为 Rerank 文本。- 分数与排序使用 Rerank 分数,否则使用向量分数;访问频次、更新时间和父目录分数不参与加权。-- 分数阈值在 Rerank 后应用;未启用 Rerank 时使用向量分数。+- 分数阈值在 Rerank 后应用。请求中的 `score_threshold` 过滤所有分数;未指定时,`rerank.threshold` 只过滤模型产出的 Rerank 分数,向量分数(未启用 Rerank 或 Rerank 失败时)不受其过滤。- Rerank 请求失败或返回无效结果时,保留已有的向量分数回退行为。- 不再使用目录优先队列、父子分数传播或多轮收敛判断。diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.mdindex 98badb7b2..ac727ec8e 100644--- a/docs/zh/configuration/01-server.md+++ b/docs/zh/configuration/01-server.md@@ -238,7 +238,7 @@ Compiler 会优先忠实提炼原文中的对象、操作、前提和场景,| `provider` | `vikingdb`、`cohere`、`openai`、`litellm`、`jev` / `null` | `null` | Rerank 服务类型;省略时根据凭证字段推断 || `model` | string / `null` | `null` | OpenAI 兼容、LiteLLM 或 Jev Rerank 模型 || `mode` | `noul`、`choice` 或 `null` | `noul` | Jev Rerank 模式;`null` 同样使用 `noul` |-| `threshold` | number | `0.1` | 判定结果相关的最低分数 |+| `threshold` | number | `0.1` | 判定结果相关的最低 Rerank 分数;只过滤模型产出的 Rerank 分数,不过滤向量分数;请求中的 `score_threshold` 优先 || `max_input_tokens` | integer;`0` 或 `>= 128` | `0` | 每个 query-document pair 的最大估算 token;`0` 表示不截断 || `log_payloads` | boolean | `false` | 记录完整 rerank 请求和响应;日志可能包含 query 和文档内容 |@@ -251,7 +251,8 @@ Rerank 没有单独的 `enabled` 字段;配置了对应 provider 所需的凭```json{"retrieval": {- "enable_intent": true+ "enable_intent": true,+ "apply_rerank_to_context": false}}```@@ -261,8 +262,9 @@ Rerank 没有单独的 `enabled` 字段;配置了对应 provider 所需的凭| 字段 | 类型 / 可选值 | 默认值 | 作用 ||---|---|---|---|| `enable_intent` | boolean | `true` | 有 `session_id` 时是否进行意图分析和查询规划 |+| `apply_rerank_to_context` | boolean | `false` | 是否用已配置的 `rerank` 模型重排 `search(mode="context")` 的候选 |-Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK 请求中覆盖。`retrieval.enable_intent` 控制带 Session 的 Search 是否执行 LLM 查询规划;只有配置了可用的 `rerank` provider 时才会执行结果重排。+Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK 请求中覆盖。`retrieval.enable_intent` 控制带 Session 的 Search 是否执行 LLM 查询规划;只有配置了可用的 `rerank` provider 时才会执行结果重排。Context 模式使用 Find 的向量分数召回;开启 `retrieval.apply_rerank_to_context` 且 `rerank` 可用时,会在配额和 token 预算之前,用原始查询及其扩展查询对合并后的候选统一重排一次,每个请求多一次 Rerank 调用。## 存储配置diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex fc9b59001..8f424723d 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1190,7 +1190,7 @@ Jev 适配器将 query 和候选文档作为共享的 System One `state`,支| `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` |+| `threshold` | float | Rerank 分数阈值,范围为 `0.0` 到 `1.0`。Rerank 后低于此值的结果会被过滤;它不过滤向量分数(未使用 Rerank 或 Rerank 失败时),请求中的 `score_threshold` 优先。默认:`0.1` || `extra_headers` | object | 自定义 HTTP 请求头(OpenAI 兼容 provider 可用,可选) |**支持的提供方:**@@ -1210,6 +1210,7 @@ Jev 适配器将 query 和候选文档作为共享的 System One `state`,支{"retrieval": {"enable_intent": true,+ "apply_rerank_to_context": false,"recall_intent_timeout_s": 5.0,"recall_rewrite_timeout_s": 30.0}@@ -1219,6 +1220,7 @@ Jev 适配器将 query 和候选文档作为共享的 System One `state`,支| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `enable_intent` | bool | `search()` 收到 `session_id` 时是否执行意图分析和查询规划。 | `true` |+| `apply_rerank_to_context` | bool | 是否用已配置的 [`rerank`](#rerank) 模型重排 `mode="context"` 的候选:每个请求用原始查询及其扩展查询统一重排一次,在配额和 token 预算之前执行。需要可用的 `rerank` 配置;图像查询保持向量分数。 | `false` |普通 `search()` 的会话意图分析和 `mode="context"` 的查询扩展共用 `recall_intent_timeout_s`;上下文 digest 重写使用独立的超时配置:diff --git a/openviking/retrieve/context_assembler/gather.py b/openviking/retrieve/context_assembler/gather.pyindex ee5ca32ca..411ace209 100644--- a/openviking/retrieve/context_assembler/gather.py+++ b/openviking/retrieve/context_assembler/gather.py@@ -23,12 +23,17 @@ from openviking.retrieve.context_assembler.params import (OTHER_PEER_OVERFETCH,READ_CONCURRENCY,REPORTED_CATEGORY_KEYS,+ RERANK_CANDIDATE_MULTIPLIER,)+from openviking.retrieve.rerank_scoring import Reranker, RerankScoresfrom openviking.retrieve.skill_results import package_abstract, skill_root_urifrom openviking.server.identity import RequestContextfrom openviking.utils.search_filters import merge_context_type_filterfrom openviking_cli.exceptions import InvalidArgumentErrorfrom openviking_cli.retrieve import ContextType+from openviking_cli.utils.logger import get_logger++logger = get_logger(__name__)LEVEL_SUFFIXES = (".abstract.md", ".overview.md")@@ -218,8 +223,14 @@ async def gather_candidates(penalties: Optional[Mapping[str, float]] = None,excluded: Optional[Set[str]] = None,cooled: Optional[Set[str]] = None,+ reranker: Optional[Reranker] = None,+ rerank_query: str = "",) -> Tuple[List[Candidate], Dict[str, Any]]:- """Retrieve and rank candidates, returning ``(candidates, stats)``."""+ """Retrieve and rank candidates, returning ``(candidates, stats)``.++ With a ``reranker``, the merged candidate pool is rescored against+ ``rerank_query`` in one call before quotas, backfill and the flat cut run.+ """peer_scope = "actor" if peer_scope == "actor" else "all"user_root = canonical_user_root(ctx)open_ctx = replace(ctx, actor_peer_id=None)@@ -228,9 +239,13 @@ async def gather_candidates(cooled = cooled or set()planned = [q for q in queries if q] or [""]preset_dirs = preset_directory_uris(ctx)+ # A request threshold is meant for final scores, so with a reranker it+ # filters after reranking instead of pre-filtering vector recall.+ recall_threshold = score_threshold if reranker is None else Nonesearched: Dict[str, int] = {}retrieval_errors: List[str] = []+ rerank_stats: Dict[str, Any] = {}excluded_count = 0def _build(items: Sequence[Tuple[Any, Optional[str]]]) -> List[Candidate]:@@ -310,7 +325,7 @@ async def gather_candidates(ctx=find_ctx,target_uri=target_uri,limit=find_limit,- score_threshold=score_threshold,+ score_threshold=recall_threshold,filter=find_filter if find_filter is not None else filter,image_url=image_url,search_type=search_type,@@ -344,7 +359,7 @@ async def gather_candidates(ctx=ctx,target_uri=targets,limit=_overfetch(width),- score_threshold=score_threshold,+ score_threshold=recall_threshold,filter=bucket_filter,search_type=search_type,)@@ -405,12 +420,15 @@ async def gather_candidates(return candidatesasync def gather_flat() -> List[Candidate]:+ nonlocal rerank_stats+ # Rerank recalls past the cut, as search() does, so it can promote hits.+ width = limit * RERANK_CANDIDATE_MULTIPLIER if reranker is not None else limitsearches = [_find(query=query,find_ctx=ctx,target_uri="",- find_limit=_overfetch(limit),+ find_limit=_overfetch(width),)for query in planned]@@ -452,6 +470,14 @@ async def gather_candidates(candidates = [c for c in candidates if c.category != "skills"]candidates.extend(_dedupe_candidates(skills))candidates.sort(key=_rank_key, reverse=True)+ if reranker is not None:+ # Several planned queries and the peer scan can return more than+ # one search's worth; the vector-best `width` of them are reranked.+ capped = max(0, len(candidates) - width)+ [candidates], rerank_stats = await _rerank_groups(+ service, reranker, rerank_query, [candidates[:width]], score_threshold+ )+ rerank_stats["capped"] = cappedreturn candidates[: max(0, limit)]if quotas is None:@@ -459,7 +485,21 @@ async def gather_candidates(else:active = [(bucket, quota) for bucket, quota in quotas.items() if quota > 0]total = sum(quota for _, quota in active)- buckets = await asyncio.gather(*(gather_bucket(b, q, total) for b, q in active))++ def width(quota: int) -> int:+ # The quota total is already the over-fetch; a dominant bucket still+ # needs room past its own quota for rerank to promote hits.+ if reranker is None:+ return total+ return max(total, quota * RERANK_CANDIDATE_MULTIPLIER)++ buckets = await asyncio.gather(*(gather_bucket(b, q, width(q)) for b, q in active))+ if reranker is not None:+ pool, capped = _cap_rerank_pool(active, buckets)+ buckets, rerank_stats = await _rerank_groups(+ service, reranker, rerank_query, pool, score_threshold+ )+ rerank_stats["capped"] = capped# Each quota is a first-pass ceiling; slots a bucket leaves unused go to# the best remaining hits of the other buckets.first: List[Candidate] = []@@ -477,7 +517,8 @@ async def gather_candidates(candidates.append(candidate)candidates.sort(key=_rank_key, reverse=True)- candidates = await _fill_skill_abstracts(service, candidates)+ if reranker is None:+ candidates = await _fill_skill_abstracts(service, candidates)origins = dict.fromkeys(ORIGIN_ORDER, 0)for candidate in candidates:@@ -493,6 +534,8 @@ async def gather_candidates(}if retrieval_errors:stats["retrieval_errors"] = retrieval_errors[:5]+ if reranker is not None:+ stats["rerank"] = rerank_statsreturn candidates, stats@@ -521,6 +564,79 @@ async def _fill_skill_abstracts(service: Any, candidates: List[Candidate]) -> Lireturn candidates+def _cap_rerank_pool(+ active: Sequence[Tuple[str, int]], buckets: Sequence[List[Candidate]]+) -> Tuple[List[List[Candidate]], int]:+ """Bound rerank input to ``RERANK_CANDIDATE_MULTIPLIER`` x quota per bucket.++ Room a short bucket leaves goes to the vector-best remaining hits of the+ others, so the pool keeps the total width backfill could reach. Returns the+ capped buckets and how many candidates the cap left out.+ """+ kept = [+ found[: quota * RERANK_CANDIDATE_MULTIPLIER]+ for (_, quota), found in zip(active, buckets, strict=True)+ ]+ rest = sorted(+ (+ (index, candidate)+ for index, found in enumerate(buckets)+ for candidate in found[len(kept[index]) :]+ ),+ key=lambda pair: _rank_key(pair[1]),+ reverse=True,+ )+ room = sum(quota for _, quota in active) * RERANK_CANDIDATE_MULTIPLIER+ room = max(0, room - sum(len(found) for found in kept))+ for index, candidate in rest[:room]:+ kept[index].append(candidate)+ return kept, max(0, len(rest) - room)+++async def _rerank_groups(+ service: Any,+ reranker: Reranker,+ query: str,+ groups: Sequence[List[Candidate]],+ score_threshold: Optional[float],+) -> Tuple[List[List[Candidate]], Dict[str, Any]]:+ """Rescore every group with one rerank call over their distinct candidates.++ A model score replaces the candidate's score, keeping its other-peer+ penalty, and meets the request threshold, else ``rerank.threshold``. A+ candidate the model did not score keeps its vector score and meets only the+ request threshold, which recall left to this step. Each group comes back+ re-sorted, so quotas and the flat cut apply to the new order.+ """+ pool: Dict[str, Candidate] = {}+ for group in groups:+ for candidate in group:+ pool.setdefault(candidate.uri, candidate)+ # Skills are scored on their package abstract, so it is read here instead+ # of after the cut.+ unique = await _fill_skill_abstracts(service, list(pool.values()))+ fallback = [candidate.score for candidate in unique]+ try:+ result = await reranker.score(query, [c.abstract for c in unique], fallback)+ except Exception as exc:+ logger.warning("Context rerank failed, keeping vector scores: %s", exc)+ result = RerankScores(fallback, [False] * len(unique))++ kept: Dict[str, Candidate] = {}+ for candidate, score, from_model in zip(unique, result.scores, result.reranked, strict=True):+ threshold = score_threshold+ if threshold is None:+ threshold = reranker.threshold if from_model else 0.0+ if score > threshold:+ penalty = candidate.score - candidate.ranked_score+ kept[candidate.uri] = replace(candidate, score=score, ranked_score=score - penalty)+ rescored = [+ sorted((kept[c.uri] for c in group if c.uri in kept), key=_rank_key, reverse=True)+ for group in groups+ ]+ return rescored, {"used": result.model_used, "candidates": len(unique)}++def _rank_key(candidate: Candidate) -> Tuple[float, int]:origin_rank = {origin: index for index, origin in enumerate(ORIGIN_ORDER)}return (candidate.ranked_score, -origin_rank.get(candidate.origin, len(origin_rank)))diff --git a/openviking/retrieve/context_assembler/params.py b/openviking/retrieve/context_assembler/params.pyindex 3eb03fc30..45c0e7286 100644--- a/openviking/retrieve/context_assembler/params.py+++ b/openviking/retrieve/context_assembler/params.py@@ -37,6 +37,8 @@ MAX_EXCLUDE_URIS = 200MAX_PLANNED_QUERIES = 3READ_CONCURRENCY = 8OTHER_PEER_OVERFETCH = 4+# Candidates reranked per served slot, as HierarchicalRetriever.RERANK_CANDIDATE_MULTIPLIER.+RERANK_CANDIDATE_MULTIPLIER = 2ORIGIN_ORDER: Tuple[str, ...] = ("actor_peer", "self", "other_peer")diff --git a/openviking/retrieve/context_assembler/pipeline.py b/openviking/retrieve/context_assembler/pipeline.pyindex b091c4dee..c8ab36157 100644--- a/openviking/retrieve/context_assembler/pipeline.py+++ b/openviking/retrieve/context_assembler/pipeline.py@@ -31,6 +31,7 @@ from openviking.retrieve.context_assembler.params import (from openviking.retrieve.context_assembler.render import render_contextfrom openviking.retrieve.context_assembler.rewrite import rewrite_context, server_rewrite_enabledfrom openviking.retrieve.context_assembler.tiers import needs_content, prefetch_contents+from openviking.retrieve.rerank_scoring import Rerankerfrom openviking.server.identity import RequestContextfrom openviking.utils.time_decay import validate_event_time_decay_requestfrom openviking_cli.utils.logger import get_logger@@ -51,6 +52,24 @@ async def _load_session(service: Any, ctx: RequestContext, session_id: Optional[return None+def _context_reranker(service: Any, params: AssembleParams) -> Optional[Reranker]:+ """The server's opt-in context reranker, when it applies to this request.++ Reranking scores text against text, so an image query keeps its vector+ scores, as it does in search(); so does a filter-only one with no text.+ """+ if not params.query.strip() or params.image_url:+ return None+ factory = getattr(service.search, "context_reranker", None)+ if not callable(factory):+ return None+ try:+ return factory()+ except Exception as exc:+ logger.warning("Context rerank unavailable, keeping vector scores: %s", exc)+ return None++async def assemble_context(*,service: Any,@@ -107,6 +126,7 @@ async def assemble_context()cooled = ledger.cooled_uris() if ledger else set()excluded = normalize_exclude_uris(params.exclude_uris)+ reranker = _context_reranker(service, params)# The fan-out below embeds each planned query once per (query, target)# find, so wrap it in the request-scoped query embedding cache: sibling@@ -127,6 +147,10 @@ async def assemble_context(penalties=penalties,excluded=excluded,cooled=cooled,+ reranker=reranker,+ # An anaphoric query may only name its topic through a session+ # expansion, so the one rerank call scores against every planned query.+ rerank_query="\n".join(queries),)# Read only the candidates whose planned tier actually needs a body: withdiff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex ed25d9617..52fcee95c 100644--- a/openviking/retrieve/hierarchical_retriever.py+++ b/openviking/retrieve/hierarchical_retriever.py@@ -4,8 +4,6 @@Global vector retrieval with optional reranking of the recalled candidates."""-import asyncio-import mathimport timefrom datetime import datetime, timezonefrom typing import Any, Dict, List, Optional@@ -19,6 +17,7 @@ from openviking.models.embedder.base import (embedder_supports_multimodal,)from openviking.models.rerank import RerankClient+from openviking.retrieve.rerank_scoring import RerankScores, finite_score, rerank_scoresfrom openviking.retrieve.retrieval_stats import get_stats_collectorfrom openviking.server.identity import RequestContextfrom openviking.storage.abstract_overview import AbstractOverviewFormatError, body_for_preview@@ -27,10 +26,6 @@ from openviking.storage.vikingdb_manager import VikingDBManager, VikingDBManagerfrom openviking.telemetry import get_current_telemetryfrom openviking.utils.tags import normalize_search_tagsfrom openviking.utils.time_decay import parse_duration_ms-from openviking.utils.token_estimation import (- estimate_text_tokens,- truncate_text_to_token_budget,-)from openviking_cli.exceptions import InvalidArgumentErrorfrom openviking_cli.retrieve.types import (ContextType,@@ -90,21 +85,19 @@ class HierarchicalRetriever:self.rerank_config = rerank_configself.rerank_max_input_tokens = rerank_config.max_input_tokens if rerank_config else 0- # Use rerank threshold if available, otherwise use a default- self.threshold = rerank_config.threshold if rerank_config else 0+ # Applies only to scores the reranker produced, never to raw vector scores.+ self.rerank_threshold = rerank_config.threshold if rerank_config else 0# Initialize rerank client — all providers go through unified dispatchif rerank_config and rerank_config.is_available():self._rerank_client = RerankClient.from_config(rerank_config)provider = rerank_config._effective_provider()logger.info(- f"[HierarchicalRetriever] Rerank enabled (provider={provider}), threshold={self.threshold}"+ f"[HierarchicalRetriever] Rerank enabled (provider={provider}), threshold={self.rerank_threshold}")else:self._rerank_client = None- logger.info(- f"[HierarchicalRetriever] Rerank not configured, using vector search only with threshold={self.threshold}"- )+ logger.info("[HierarchicalRetriever] Rerank not configured, using vector search only")async def retrieve(self,@@ -128,7 +121,8 @@ class HierarchicalRetriever:ctx: Request context used for tenant and permission filteringmode: QUICK uses vector scores; THINKING optionally reranks the recalledcandidates. None selects THINKING when a reranker is configured.- score_threshold: Custom score threshold (overrides config)+ score_threshold: Custom score threshold. Without it, only rerank-produced+ scores are filtered, by the configured rerank threshold.score_gte: True uses >=, False uses >scope_dsl: Additional scope constraints passed from public find/search filterlevel: Optional result level filter (0=L0, 1=L1, 2=L2)@@ -136,7 +130,6 @@ class HierarchicalRetriever:"""t0 = time.monotonic()telemetry = get_current_telemetry()- effective_threshold = self._resolve_threshold(score_threshold)image_query = query.image_queryif mode is None:mode = RetrieverMode.THINKING if self._rerank_client else RetrieverMode.QUICK@@ -248,19 +241,23 @@ class HierarchicalRetriever:collected_by_uri.values(), key=lambda candidate: candidate["_score"], reverse=True)scores = [candidate["_score"] for candidate in candidates]+ reranked = [False] * len(candidates)rerank_used = use_rerank and bool(candidates)if rerank_used:- scores = await self._rerank_scores(+ rerank = await self._rerank_scores(query.query,[str(candidate.get("abstract", "")) for candidate in candidates],scores,)+ scores, reranked = rerank.scores, rerank.reranked# A low vector score can still rerank highly, so filter only after reranking.candidates = [{**candidate, "_final_score": score}- for candidate, score in zip(candidates, scores, strict=True)- if self._passes_threshold(score, effective_threshold, score_gte)+ for candidate, score, from_model in zip(candidates, scores, reranked, strict=True)+ if self._passes_threshold(+ score, self._resolve_threshold(score_threshold, from_model), score_gte+ )]telemetry.count("vector.passed", len(candidates))matched = await self._convert_to_matched_contexts(candidates, ctx=ctx)@@ -281,17 +278,15 @@ class HierarchicalRetriever:searched_directories=root_uris,)- def _resolve_threshold(self, threshold: Optional[float]) -> float:- resolved = threshold if threshold is not None else self.threshold- return resolved if resolved is not None else 0.0+ def _resolve_threshold(self, threshold: Optional[float], reranked: bool = False) -> float:+ """An explicit threshold applies to any score; the rerank one only to model scores."""+ if threshold is not None:+ return threshold+ if reranked and self.rerank_threshold is not None:+ return self.rerank_threshold+ return 0.0- @staticmethod- def _finite_score(value: Any, default: float = 0.0) -> float:- try:- score = float(value)- except (TypeError, ValueError):- return default- return score if math.isfinite(score) else default+ _finite_score = staticmethod(finite_score)@staticmethoddef _passes_threshold(score: float, threshold: float, score_gte: bool) -> bool:@@ -304,50 +299,15 @@ class HierarchicalRetriever:query: str,documents: List[str],fallback_scores: List[float],- ) -> List[float]:+ ) -> RerankScores:"""Return rerank scores or fall back to vector scores."""- if not self._rerank_client or not documents:- return fallback_scores-- rerank_query = query- rerank_documents = [- (index, document) for index, document in enumerate(documents) if document.strip()- ]- if not rerank_documents:- return fallback_scores-- if self.rerank_max_input_tokens > 0:- max_query_tokens = self.rerank_max_input_tokens * 3 // 4- if estimate_text_tokens(query) > max_query_tokens:- rerank_query = truncate_text_to_token_budget(query, max_query_tokens)- document_tokens = self.rerank_max_input_tokens - estimate_text_tokens(rerank_query)- rerank_documents = [- (index, truncate_text_to_token_budget(document, document_tokens))- for index, document in rerank_documents- ]-- try:- scores = await asyncio.to_thread(- self._rerank_client.rerank_batch,- rerank_query,- [document for _, document in rerank_documents],- )- except Exception as e:- logger.warning(- "[HierarchicalRetriever] Rerank failed, fallback to vector scores: %s", e- )- return fallback_scores-- if not scores or len(scores) != len(rerank_documents):- logger.warning(- "[HierarchicalRetriever] Invalid rerank result, fallback to vector scores"- )- return fallback_scores-- normalized_scores = list(fallback_scores)- for score, (index, _) in zip(scores, rerank_documents, strict=True):- normalized_scores[index] = self._finite_score(score, fallback_scores[index])- return normalized_scores+ return await rerank_scores(+ self._rerank_client,+ query,+ documents,+ fallback_scores,+ max_input_tokens=self.rerank_max_input_tokens,+ )async def _convert_to_matched_contexts(self,diff --git a/openviking/retrieve/rerank_scoring.py b/openviking/retrieve/rerank_scoring.pynew file mode 100644index 000000000..64eb3e587--- /dev/null+++ b/openviking/retrieve/rerank_scoring.py@@ -0,0 +1,110 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Score recalled documents with a rerank model, falling back to their vector scores."""++import asyncio+import math+from dataclasses import dataclass+from typing import Any, List, Optional++from openviking.models.rerank import RerankBase+from openviking.utils.token_estimation import (+ estimate_text_tokens,+ truncate_text_to_token_budget,+)+from openviking_cli.utils.logger import get_logger++logger = get_logger(__name__)+++@dataclass(frozen=True)+class RerankScores:+ """Per-document scores; ``reranked[i]`` is True when the model produced ``scores[i]``."""++ scores: List[float]+ reranked: List[bool]++ @property+ def model_used(self) -> bool:+ return any(self.reranked)+++@dataclass(frozen=True)+class Reranker:+ """A rerank client bound to the rerank config values its callers apply."""++ client: RerankBase+ threshold: float = 0.0+ max_input_tokens: int = 0++ async def score(+ self, query: str, documents: List[str], fallback_scores: List[float]+ ) -> RerankScores:+ return await rerank_scores(+ self.client,+ query,+ documents,+ fallback_scores,+ max_input_tokens=self.max_input_tokens,+ )+++def finite_score(value: Any, default: float = 0.0) -> float:+ try:+ score = float(value)+ except (TypeError, ValueError):+ return default+ return score if math.isfinite(score) else default+++async def rerank_scores(+ client: Optional[RerankBase],+ query: str,+ documents: List[str],+ fallback_scores: List[float],+ max_input_tokens: int = 0,+) -> RerankScores:+ """Return rerank scores, keeping the fallback score for every document the model skipped."""+ fallback = RerankScores(list(fallback_scores), [False] * len(fallback_scores))+ if not client or not documents:+ return fallback++ rerank_query = query+ rerank_documents = [+ (index, document) for index, document in enumerate(documents) if document.strip()+ ]+ if not rerank_documents:+ return fallback++ if max_input_tokens > 0:+ max_query_tokens = max_input_tokens * 3 // 4+ if estimate_text_tokens(query) > max_query_tokens:+ rerank_query = truncate_text_to_token_budget(query, max_query_tokens)+ document_tokens = max_input_tokens - estimate_text_tokens(rerank_query)+ rerank_documents = [+ (index, truncate_text_to_token_budget(document, document_tokens))+ for index, document in rerank_documents+ ]++ try:+ scores = await asyncio.to_thread(+ client.rerank_batch,+ rerank_query,+ [document for _, document in rerank_documents],+ )+ except Exception as e:+ logger.warning("[Rerank] Rerank failed, fallback to vector scores: %s", e)+ return fallback++ if not scores or len(scores) != len(rerank_documents):+ logger.warning("[Rerank] Invalid rerank result, fallback to vector scores")+ return fallback++ normalized_scores = list(fallback_scores)+ reranked = [False] * len(fallback_scores)+ for score, (index, _) in zip(scores, rerank_documents, strict=True):+ model_score = finite_score(score, default=math.nan)+ if math.isfinite(model_score):+ normalized_scores[index] = model_score+ reranked[index] = True+ return RerankScores(normalized_scores, reranked)diff --git a/openviking/retrieve/skill_package_retriever.py b/openviking/retrieve/skill_package_retriever.pyindex c69754f5c..9b8c54427 100644--- a/openviking/retrieve/skill_package_retriever.py+++ b/openviking/retrieve/skill_package_retriever.py@@ -42,6 +42,7 @@ class SkillPackageRetriever(HierarchicalRetriever):if limit <= 0 or not await proxy.collection_exists_bound():return QueryResult(query=query, matched_contexts=[], searched_directories=target_dirs)+ # Package search never reranks, so only an explicit threshold filters vector scores.threshold = self._resolve_threshold(score_threshold)query_vector = sparse_vector = Noneif search_type == "semantic" and self.embedder:diff --git a/openviking/service/search_service.py b/openviking/service/search_service.pyindex 5fa26c387..d41a7d95d 100644--- a/openviking/service/search_service.py+++ b/openviking/service/search_service.py@@ -10,6 +10,8 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Unionfrom openviking.core.namespace_policy import is_system_urifrom openviking.core.retrieval_types import SearchType+from openviking.models.rerank import RerankClient+from openviking.retrieve.rerank_scoring import Rerankerfrom openviking.server.identity import RequestContextfrom openviking.storage.viking_fs import VikingFSfrom openviking.utils.image_search import (@@ -86,6 +88,29 @@ class SearchService:return Truereturn bool(self._viking_fs.retrieval_config.enable_intent)+ def context_reranker(self) -> Optional[Reranker]:+ """The reranker context assembly applies to its merged candidates, if any.++ None unless ``retrieval.apply_rerank_to_context`` is on and ``rerank`` has+ a usable provider config. Off by default, so context mode keeps vector+ scores, as find() does.+ """+ if not self._viking_fs or self._viking_fs.retrieval_config is None:+ return None+ if not self._viking_fs.retrieval_config.apply_rerank_to_context:+ return None+ rerank_config = self._viking_fs.rerank_config+ if not rerank_config or not rerank_config.is_available():+ return None+ client = RerankClient.from_config(rerank_config)+ if client is None:+ return None+ return Reranker(+ client=client,+ threshold=rerank_config.threshold,+ max_input_tokens=rerank_config.max_input_tokens,+ )+async def ensure_keywords_search_supported(self, ctx: RequestContext) -> None:"""Validate keyword-search support at the top-level request boundary."""viking_fs = self._ensure_initialized()@@ -255,11 +280,7 @@ class SearchService:raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")if search_type == "semantic" and not embedder:raise RuntimeError("Embedder not configured.")- retriever = SkillPackageRetriever(- storage=storage,- embedder=embedder,- rerank_config=fs.rerank_config,- )+ retriever = SkillPackageRetriever(storage=storage, embedder=embedder)result = await retriever.retrieve_skills(TypedQuery(query, ContextType.SKILL, "", target_directories=targets),ctx,diff --git a/openviking_cli/utils/config/retrieval_config.py b/openviking_cli/utils/config/retrieval_config.pyindex e546538b5..accda46b8 100644--- a/openviking_cli/utils/config/retrieval_config.py+++ b/openviking_cli/utils/config/retrieval_config.py@@ -26,3 +26,11 @@ class RetrievalConfig(BaseModel):"(same path as no-session search)."),)+ apply_rerank_to_context: bool = Field(+ default=False,+ description=(+ "Whether search(mode='context') reranks its merged candidates with the configured "+ "rerank model before quota allocation and budgeting. Needs a usable rerank "+ "config; false keeps context mode on vector scores."+ ),+ )diff --git a/tests/misc/test_retrieval_context_rerank.py b/tests/misc/test_retrieval_context_rerank.pynew file mode 100644index 000000000..af471b4d3--- /dev/null+++ b/tests/misc/test_retrieval_context_rerank.py@@ -0,0 +1,55 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++from types import SimpleNamespace++from openviking.models.rerank import CohereRerankClient+from openviking.retrieve.rerank_scoring import Reranker+from openviking.service.search_service import SearchService+from openviking_cli.utils.config.open_viking_config import OpenVikingConfig+from openviking_cli.utils.config.rerank_config import RerankConfig+from openviking_cli.utils.config.retrieval_config import RetrievalConfig++COHERE = RerankConfig(provider="cohere", api_key="key", threshold=0.3, max_input_tokens=512)+++def _service(*, apply_rerank_to_context, rerank_config=COHERE):+ fs = SimpleNamespace(+ retrieval_config=RetrievalConfig(apply_rerank_to_context=apply_rerank_to_context),+ rerank_config=rerank_config,+ )+ return SearchService(fs)+++def test_apply_rerank_to_context_defaults_off():+ assert RetrievalConfig().apply_rerank_to_context is False+ assert OpenVikingConfig.from_dict({}).retrieval.apply_rerank_to_context is False+++def test_apply_rerank_to_context_loads_from_config():+ config = OpenVikingConfig.from_dict({"retrieval": {"apply_rerank_to_context": True}})++ assert config.retrieval.apply_rerank_to_context is True+++def test_context_reranker_is_off_without_the_flag():+ assert _service(apply_rerank_to_context=False).context_reranker() is None+ assert SearchService().context_reranker() is None+ assert SearchService(SimpleNamespace(retrieval_config=None)).context_reranker() is None+++def test_context_reranker_needs_a_usable_rerank_config():+ assert _service(apply_rerank_to_context=True, rerank_config=None).context_reranker() is None+ assert (+ _service(apply_rerank_to_context=True, rerank_config=RerankConfig()).context_reranker()+ is None+ )+++def test_context_reranker_carries_the_rerank_config():+ reranker = _service(apply_rerank_to_context=True).context_reranker()++ assert isinstance(reranker, Reranker)+ assert isinstance(reranker.client, CohereRerankClient)+ assert reranker.threshold == 0.3+ assert reranker.max_input_tokens == 512diff --git a/tests/retrieve/test_context_assembler_pipeline.py b/tests/retrieve/test_context_assembler_pipeline.pyindex 7f740a54c..4b76d20d9 100644--- a/tests/retrieve/test_context_assembler_pipeline.py+++ b/tests/retrieve/test_context_assembler_pipeline.py@@ -24,6 +24,7 @@ from openviking.retrieve.context_assembler.params import (from openviking.retrieve.context_assembler.pipeline import assemble_contextfrom openviking.retrieve.context_assembler.render import render_entryfrom openviking.retrieve.context_assembler.tiers import tier_window+from openviking.retrieve.rerank_scoring import Rerankerfrom openviking.server.identity import RequestContext, Rolefrom openviking_cli.session.user_id import UserIdentifier@@ -1149,3 +1150,348 @@ async def test_full_buckets_keep_their_quotas_when_one_bucket_scores_highest():)assert Counter(entry.category for entry in result.entries) == quotas+++class _FakeRerankClient:+ """Scores each document by its text; unknown text scores 0."""++ def __init__(self, scores, *, error=None, result=None):+ self.scores = scores+ self.error = error+ self.result = result+ self.calls = []++ def rerank_batch(self, query, documents):+ self.calls.append((query, list(documents)))+ if self.error is not None:+ raise self.error+ if self.result is not None:+ return self.result+ return [self.scores.get(document, 0.0) for document in documents]+++def _rerank_service(service, client, *, threshold=0.1):+ service.search.context_reranker = lambda: Reranker(client=client, threshold=threshold)+ return service+++def _flat_service(hits, finds=None):+ """Answers every flat find from ``hits``, honouring the requested limit."""++ async def fake_find(**kwargs):+ if finds is not None:+ finds.append(kwargs)+ return _FakeFindResult(memories=list(hits[: kwargs["limit"]]))++ return SimpleNamespace(+ search=SimpleNamespace(find=fake_find),+ fs=SimpleNamespace(read=None),+ sessions=SimpleNamespace(),+ viking_fs=None,+ )+++PREFERENCES = f"{USER_ROOT}/memories/preferences"+FLAT_HITS = [+ _hit(f"{PREFERENCES}/{name}.md", score, f"text {name}")+ for name, score in (("a", 0.9), ("b", 0.8), ("c", 0.7), ("d", 0.6))+]+++async def _assemble_flat(service, **overrides):+ params = {"query": "q", "limit": 2, "peer_scope": "actor", "max_tokens": 8000}+ params.update(overrides)+ return await assemble_context(service=service, ctx=_ctx(), params=AssembleParams(**params))+++def _scored(result):+ return [(entry.uri.rsplit("/", 1)[-1], entry.score) for entry in result.entries]+++async def test_context_rerank_off_leaves_the_assembly_unchanged():+ plain_finds, off_finds = [], []+ plain = await _assemble_flat(_flat_service(FLAT_HITS, plain_finds))+ off_service = _flat_service(FLAT_HITS, off_finds)+ off_service.search.context_reranker = lambda: None+ off = await _assemble_flat(off_service)++ assert _scored(plain) == _scored(off) == [("a.md", 0.9), ("b.md", 0.8)]+ assert plain.stats == off.stats+ assert "rerank" not in off.stats+ assert [call["limit"] for call in off_finds] == [call["limit"] for call in plain_finds] == [2]+++async def test_flat_context_rerank_widens_recall_and_reorders_the_cut():+ finds = []+ client = _FakeRerankClient({"text a": 0.3, "text b": 0.2, "text c": 0.5, "text d": 0.95})+ service = _rerank_service(_flat_service(FLAT_HITS, finds), client)++ result = await _assemble_flat(service)++ assert [call["limit"] for call in finds] == [4]+ assert client.calls == [("q", ["text a", "text b", "text c", "text d"])]+ # d sat outside the vector cut of 2; its rerank score now reports as its score.+ assert _scored(result) == [("d.md", 0.95), ("c.md", 0.5)]+ assert result.stats["rerank"] == {"used": True, "candidates": 4, "capped": 0}+++async def test_context_rerank_scores_against_the_expanded_queries_once(monkeypatch):+ async def fake_expand(*, query, session, mode, **kwargs):+ del session, mode, kwargs+ return [query, "fix for Redis OOM incident"], "used"++ redis = _hit(f"{PREFERENCES}/redis.md", 0.6, "redis oom fix")+ finds = []++ async def fake_find(**kwargs):+ finds.append(kwargs)+ # Only the expansion names the topic, so only it recalls the memory.+ if "Redis" in kwargs["query"]:+ return _FakeFindResult(memories=[redis])+ return _FakeFindResult(memories=[_hit(f"{PREFERENCES}/a.md", 0.5, "text a")])++ class _QueryAwareClient(_FakeRerankClient):+ def rerank_batch(self, query, documents):+ self.calls.append((query, list(documents)))+ return [0.9 if "redis" in d and "Redis" in query else 0.03 for d in documents]++ monkeypatch.setattr(pipeline_module, "expand_queries", fake_expand)+ client = _QueryAwareClient({})+ service = SimpleNamespace(+ search=SimpleNamespace(find=fake_find),+ fs=SimpleNamespace(read=None),+ sessions=SimpleNamespace(get=lambda *args, **kwargs: _async_value(_fake_session())),+ viking_fs=None,+ vlm_resolver=_DEFAULT_VLM_RESOLVER,+ )++ result = await _assemble_flat(+ _rerank_service(service, client), query="how did we fix it?", session_id="s1"+ )++ assert [call["query"] for call in finds] == ["how did we fix it?", "fix for Redis OOM incident"]+ assert [query for query, _ in client.calls] == [+ "how did we fix it?\nfix for Redis OOM incident"+ ]+ # Scored against the raw query alone, it would fall under rerank.threshold.+ assert _scored(result) == [("redis.md", 0.9)]+++async def _async_value(value):+ return value+++async def test_bucketed_context_rerank_runs_before_quotas():+ events = f"{USER_ROOT}/memories/events"+ entities = f"{USER_ROOT}/memories/entities"+ finds = []+ service = _bucket_service(+ {+ events: [_hit(f"{events}/e0.md", 0.9, "e0"), _hit(f"{events}/e1.md", 0.5, "e1")],+ entities: [_hit(f"{entities}/n0.md", 0.8, "n0")],+ },+ finds=finds,+ )+ params = {"quotas": {"events": 1, "entities": 1}}++ before = await _assemble_flat(service, **params)+ client = _FakeRerankClient({"e0": 0.2, "e1": 0.95, "n0": 0.6})+ after = await _assemble_flat(_rerank_service(service, client), **params)++ assert _scored(before) == [("e0.md", 0.9), ("n0.md", 0.8)]+ # e1 was beyond the events quota on vector scores; reranked, it takes the slot.+ assert _scored(after) == [("e1.md", 0.95), ("n0.md", 0.6)]+ assert len(client.calls) == 1+ assert sorted(client.calls[0][1]) == ["e0", "e1", "n0"]+++async def test_a_lone_bucket_recalls_past_its_quota_for_rerank():+ events = f"{USER_ROOT}/memories/events"+ hits = [_hit(f"{events}/{i}.md", 0.9 - i * 0.1, f"e{i}") for i in range(4)]+ plain_finds, finds = [], []++ await _assemble_flat(_bucket_service({events: hits}, finds=plain_finds), quotas={"events": 2})+ client = _FakeRerankClient({"e3": 0.9, "e2": 0.8})+ result = await _assemble_flat(+ _rerank_service(_bucket_service({events: hits}, finds=finds), client),+ quotas={"events": 2},+ )++ assert {call["limit"] for call in plain_finds} == {2}+ assert {call["limit"] for call in finds} == {4}+ assert [entry.uri.rsplit("/", 1)[-1] for entry in result.entries] == ["3.md", "2.md"]+++async def test_bucketed_rerank_pool_is_capped_per_quota_and_reports_it():+ events = f"{USER_ROOT}/memories/events"++ async def fake_find(**kwargs):+ if kwargs["target_uri"] != events:+ return _FakeFindResult()+ # Ignores the limit, as overfetch for cooled URIs can return more.+ return _FakeFindResult(+ memories=[_hit(f"{events}/{i}.md", 0.9 - i * 0.1, f"e{i}") for i in range(5)]+ )++ service = SimpleNamespace(+ search=SimpleNamespace(find=fake_find),+ fs=SimpleNamespace(read=lambda uri, **kwargs: _async_value(f"# Summary\n{uri}")),+ sessions=SimpleNamespace(),+ viking_fs=None,+ )+ client = _FakeRerankClient({"e3": 0.9})++ result = await _assemble_flat(+ _rerank_service(service, client), quotas={"events": 1, "entities": 1}+ )++ # 2 x quota per bucket, and the empty entities bucket's room goes to events.+ assert client.calls == [("q", ["e0", "e1", "e2", "e3"])]+ assert result.stats["rerank"] == {"used": True, "candidates": 4, "capped": 1}+ assert [entry.uri.rsplit("/", 1)[-1] for entry in result.entries][0] == "3.md"+++async def test_context_rerank_scores_skills_on_their_package_abstract():+ reads = []+ service = _skill_service(+ [+ _skill_hit(f"{DEPLOY}/scripts/run.py", 0.4, "run script"),+ _skill_hit(f"{REVIEW}/SKILL.md", 0.7, "review file abstract"),+ ],+ {DEPLOY: "name: deploy"},+ reads=reads,+ )+ client = _FakeRerankClient({"name: deploy": 0.9})++ result = await _assemble_skills(_rerank_service(service, client))++ # The package without an abstract is not sent and keeps its vector score.+ assert client.calls == [("how do I deploy", ["name: deploy"])]+ assert [(entry.uri, entry.score, entry.text) for entry in result.entries] == [+ (f"{DEPLOY}/SKILL.md", 0.9, "name: deploy"),+ (f"{REVIEW}/SKILL.md", 0.7, ""),+ ]+ assert sorted(reads) == [DEPLOY, REVIEW]+++async def test_image_query_skips_context_rerank():+ finds = []+ client = _FakeRerankClient({"text d": 0.95})+ service = _rerank_service(_flat_service(FLAT_HITS, finds), client)++ result = await _assemble_flat(service, image_url="https://example.com/shot.png")++ assert client.calls == []+ assert [call["limit"] for call in finds] == [2]+ assert _scored(result) == [("a.md", 0.9), ("b.md", 0.8)]+ assert "rerank" not in result.stats+++async def test_filter_only_query_skips_context_rerank():+ finds = []+ client = _FakeRerankClient({"text d": 0.95})+ service = _rerank_service(_flat_service(FLAT_HITS, finds), client)++ result = await _assemble_flat(+ service, query="", filter={"op": "must", "field": "tags", "conds": ["ops"]}+ )++ assert client.calls == []+ assert [call["limit"] for call in finds] == [2]+ assert "rerank" not in result.stats+++async def test_an_unavailable_context_reranker_keeps_vector_order():+ def broken_factory():+ raise RuntimeError("bad rerank provider config")++ service = _flat_service(FLAT_HITS)+ service.search.context_reranker = broken_factory++ result = await _assemble_flat(service)++ assert _scored(result) == [("a.md", 0.9), ("b.md", 0.8)]+ assert "rerank" not in result.stats+++async def test_context_rerank_failure_keeps_vector_order():+ for client in (+ _FakeRerankClient({}, error=RuntimeError("rerank down")),+ _FakeRerankClient({}, result=[0.9]),+ ):+ result = await _assemble_flat(_rerank_service(_flat_service(FLAT_HITS), client))++ assert len(client.calls) == 1+ assert _scored(result) == [("a.md", 0.9), ("b.md", 0.8)]+ assert result.stats["rerank"] == {"used": False, "candidates": 4, "capped": 0}+++async def test_a_reranker_that_raises_does_not_fail_the_assembly():+ class BrokenReranker:+ threshold = 0.1++ async def score(self, query, documents, fallback_scores):+ raise RuntimeError("unexpected")++ service = _flat_service(FLAT_HITS)+ service.search.context_reranker = BrokenReranker++ result = await _assemble_flat(service)++ assert _scored(result) == [("a.md", 0.9), ("b.md", 0.8)]+ assert result.stats["rerank"]["used"] is False+++async def test_context_rerank_moves_the_score_threshold_after_reranking():+ hits = [+ _hit(f"{PREFERENCES}/low.md", 0.9, "low"),+ _hit(f"{PREFERENCES}/high.md", 0.2, "high"),+ _hit(f"{PREFERENCES}/mid.md", 0.8, "mid"),+ {"uri": f"{PREFERENCES}/blank.md", "score": 0.05, "abstract": "", "level": 2},+ ]+ scores = {"low": 0.05, "high": 0.9, "mid": 0.4}++ finds = []+ service = _rerank_service(_flat_service(hits, finds), _FakeRerankClient(scores))+ default = await _assemble_flat(service, limit=4)+ # rerank.threshold (0.1) filters model scores only; the blank candidate was+ # not reranked, so its 0.05 vector score stays.+ assert _scored(default) == [("high.md", 0.9), ("mid.md", 0.4), ("blank.md", 0.05)]++ explicit = await _assemble_flat(service, limit=4, score_threshold=0.3)+ # A request threshold filters every final score, and never pre-filters recall.+ assert _scored(explicit) == [("high.md", 0.9), ("mid.md", 0.4)]+ assert {call["score_threshold"] for call in finds} == {None}++ failing = _rerank_service(+ _flat_service(hits), _FakeRerankClient({}, error=RuntimeError("down"))+ )+ fallback = await _assemble_flat(failing, limit=4, score_threshold=0.3)+ assert _scored(fallback) == [("low.md", 0.9), ("mid.md", 0.8)]+++async def test_context_rerank_keeps_the_other_peer_penalty():+ own = f"{PREFERENCES}/own.md"+ other = f"{USER_ROOT}/peers/other/memories/preferences/theirs.md"++ async def fake_find(**kwargs):+ if kwargs["target_uri"] == f"{USER_ROOT}/peers":+ return _FakeFindResult(memories=[_hit(other, 0.5, "theirs")])+ return _FakeFindResult(memories=[_hit(own, 0.6, "own")])++ service = SimpleNamespace(+ search=SimpleNamespace(find=fake_find),+ fs=SimpleNamespace(read=None),+ sessions=SimpleNamespace(),+ viking_fs=None,+ )+ client = _FakeRerankClient({"own": 0.85, "theirs": 0.9})++ result = await _assemble_flat(+ _rerank_service(service, client),+ limit=1,+ peer_scope="all",+ other_peer_penalty={"preferences": 0.1},+ )++ assert [(entry.uri, entry.score) for entry in result.entries] == [(own, 0.85)]diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex 561bc9028..948731922 100644--- a/tests/retrieve/test_hierarchical_retriever_rerank.py+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -177,13 +177,14 @@ async def test_rerank_scores_preserves_fallbacks_for_empty_documents(monkeypatchrerank_config=_config(),)- scores = await retriever._rerank_scores(+ rerank = await retriever._rerank_scores("hello",["root A", "", " ", "root D"],[0.2, 0.8, 0.7, 0.4],)- assert scores == [0.95, 0.8, 0.7, 0.05]+ assert rerank.scores == [0.95, 0.8, 0.7, 0.05]+ assert rerank.reranked == [True, False, False, True]assert fake_client.calls == [("hello", ["root A", "root D"])]@@ -231,9 +232,9 @@ async def test_rerank_scores_bounds_oversized_documents_and_preserves_tail(rerank_config=RerankConfig(ak="ak", sk="sk", max_input_tokens=128),)- scores = await retriever._rerank_scores("query", [oversized_document], [0.2])+ rerank = await retriever._rerank_scores("query", [oversized_document], [0.2])- assert scores == [0.95]+ assert rerank.scores == [0.95]rerank_query, rerank_documents = fake_client.calls[0]bounded_document = rerank_documents[0]assert estimate_text_tokens(rerank_query) + estimate_text_tokens(bounded_document) <= 128@@ -288,6 +289,96 @@ async def test_retrieve_falls_back_to_vector_scores_when_rerank_fails(monkeypatcassert fake_client.calls == [("hello", ["deep B", "deep A", "deep C"])][email protected]("failure", [None, [0.9], RuntimeError("provider unavailable")])+async def test_rerank_failure_fallback_does_not_apply_rerank_threshold(monkeypatch, failure):+ class FailedRerankClient(FakeRerankClient):+ def rerank_batch(self, query, documents):+ if isinstance(failure, Exception):+ raise failure+ return failure++ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: FailedRerankClient([]),+ )+ storage = DummyStorage(+ [+ _result("viking://resources/high", 0.8, abstract="high"),+ _result("viking://resources/low", 0.05, abstract="low"),+ ]+ )+ retriever = HierarchicalRetriever(storage, DummyEmbedder(), rerank_config=_config())++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=5)+ explicit = await retriever.retrieve(_query(), ctx=_ctx(), limit=5, score_threshold=0.5)++ # Vector scores are not on the reranker's scale, so rerank.threshold must not filter them.+ assert [ctx.score for ctx in result.matched_contexts] == [0.8, 0.05]+ assert [ctx.score for ctx in explicit.matched_contexts] == [0.8]+++async def test_rerank_threshold_filters_only_model_scores(monkeypatch):+ fake_client = FakeRerankClient([0.05, 0.9, 0.95])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )+ storage = DummyStorage(+ [+ _result("viking://resources/demoted", 0.9, abstract="demoted"),+ _result("viking://resources/relevant", 0.8, abstract="relevant"),+ _result("viking://resources/no-abstract", 0.05, abstract=""),+ _result("viking://resources/promoted", 0.01, abstract="promoted"),+ ]+ )+ retriever = HierarchicalRetriever(storage, DummyEmbedder(), rerank_config=_config())++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=5)++ assert fake_client.calls == [("hello", ["demoted", "relevant", "promoted"])]+ # The empty abstract was never reranked, so its vector score skips rerank.threshold.+ assert [(ctx.uri, ctx.score) for ctx in result.matched_contexts] == [+ ("viking://resources/promoted", 0.95),+ ("viking://resources/relevant", 0.9),+ ("viking://resources/no-abstract", 0.05),+ ]+++ "rerank_config, mode",+ [+ (RerankConfig(), None),+ (_config(), RetrieverMode.QUICK),+ (RerankConfig(ak="ak", sk="sk", threshold=0.8), RetrieverMode.QUICK),+ ],+)+async def test_quick_path_does_not_apply_rerank_threshold(monkeypatch, rerank_config, mode):+ fake_client = FakeRerankClient([])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )+ storage = DummyStorage(+ [+ _result("viking://resources/high", 0.9, abstract="high"),+ _result("viking://resources/low", 0.05, abstract="low"),+ ]+ )+ retriever = HierarchicalRetriever(storage, DummyEmbedder(), rerank_config=rerank_config)++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=5, mode=mode)+ explicit = await retriever.retrieve(+ _query(), ctx=_ctx(), limit=5, mode=mode, score_threshold=0.5+ )++ assert fake_client.calls == []+ assert [ctx.score for ctx in result.matched_contexts] == [0.9, 0.05]+ assert [ctx.score for ctx in explicit.matched_contexts] == [0.9]++@pytest.mark.asyncioasync def test_rerank_scores_runs_blocking_client_off_event_loop():class SlowRerankClient:@@ -315,7 +406,7 @@ async def test_rerank_scores_runs_blocking_client_off_event_loop():await asyncio.sleep(0.01)ticks += 1- assert await rerank_task == [0.9]+ assert (await rerank_task).scores == [0.9]assert fake_client.thread_id != threading.get_ident()assert ticks >= 3diff --git a/tests/retrieve/test_skill_package_results.py b/tests/retrieve/test_skill_package_results.pyindex 88c761329..68ae825d8 100644--- a/tests/retrieve/test_skill_package_results.py+++ b/tests/retrieve/test_skill_package_results.py@@ -17,6 +17,7 @@ from openviking_cli.retrieve.types import (TypedQuery,)from openviking_cli.session.user_id import UserIdentifier+from openviking_cli.utils.config import RerankConfigSKILLS = "viking://agent/skills"@@ -216,3 +217,24 @@ async def test_package_abstract_reports_only_a_generated_abstract(answer, expectassert await package_abstract(fs, request_ctx, f"{SKILLS}/demo") == expectedassert fs.calls == [(f"{SKILLS}/demo", request_ctx)]+++async def test_rerank_threshold_does_not_filter_package_vector_scores():+ """Package search never reranks; only an explicit threshold filters its vector scores."""+ store = PagedStore([row(f"{SKILLS}/a/SKILL.md", 0.9), row(f"{SKILLS}/b/SKILL.md", 0.05)])+ retriever = SkillPackageRetriever(store, None, rerank_config=RerankConfig(threshold=0.8))++ result = await retriever.retrieve_skills(+ query(), ctx(), limit=5, skill_resolver=SkillResultResolver(Files(), ctx())+ )+ explicit = await retriever.retrieve_skills(+ query(),+ ctx(),+ limit=5,+ score_threshold=0.5,+ skill_resolver=SkillResultResolver(Files(), ctx()),+ )++ assert [item.score for item in result.matched_contexts] == [0.9, 0.05]+ assert [item.score for item in explicit.matched_contexts] == [0.9]diff --git a/tests/unit/test_find_skills_entrypoint.py b/tests/unit/test_find_skills_entrypoint.pyindex 6fc57ff8d..72c3e2f2e 100644--- a/tests/unit/test_find_skills_entrypoint.py+++ b/tests/unit/test_find_skills_entrypoint.py@@ -50,13 +50,14 @@ def _service(rerank_config):return SearchService(fs)-async def test_find_skills_applies_the_configured_rerank_threshold(seen):- """Without the rerank config the package floor is 0 while general find sits at 0.1."""+async def test_find_skills_does_not_apply_the_rerank_threshold(seen):+ """Package search never reranks, so rerank.threshold must not filter its vector scores."""rerank_config = SimpleNamespace(threshold=0.1)await _service(rerank_config).find_skills(query="deploy", ctx=_ctx(), target_uri=SKILLS)- assert seen["init"]["rerank_config"] is rerank_config+ assert seen["init"].get("rerank_config") is None+ assert seen["retrieve"]["score_threshold"] is Noneasync def test_find_skills_forwards_the_filter_as_the_retrieval_scope(seen):