Skip to content

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

feat(search): add the keywords search type (#5456)

ByteDanceLiuYang0c650c3830af
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index b6b3ca9ae..0057c5e2d 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -34,6 +34,9 @@ fn compact_request_body(body: &mut Value) {
if key == "processing_mode" {
return value != "semantic_and_vectors";
}
+ if key == "search_type" {
+ return value != "semantic";
+ }
true
});
}
@@ -776,6 +779,7 @@ impl HttpClient {
query: String,
uri: String,
image: Option<String>,
+ search_type: String,
session_id: Option<String>,
node_limit: i32,
threshold: Option<f64>,
@@ -792,6 +796,7 @@ impl HttpClient {
let mut body = serde_json::json!({
"query": query,
"image_url": image_url,
+ "search_type": search_type,
"target_uri": uri,
"session_id": session_id,
"limit": node_limit,
@@ -2149,6 +2154,20 @@ mod tests {
assert_eq!(body["processing_mode"], "vectors_only");
}
+ #[test]
+ fn compact_request_body_drops_default_search_type_for_legacy_servers() {
+ let mut body = json!({"query": "OAuth token", "search_type": "semantic"});
+ super::compact_request_body(&mut body);
+ assert!(!body.as_object().unwrap().contains_key("search_type"));
+ }
+
+ #[test]
+ fn compact_request_body_keeps_keywords_search_type() {
+ let mut body = json!({"query": "OAuth token", "search_type": "keywords"});
+ super::compact_request_body(&mut body);
+ assert_eq!(body["search_type"], "keywords");
+ }
+
#[test]
fn add_resource_tag_fields_adds_tags_and_tag_mode() {
let mut body = json!({"path": "https://example.com/demo.md"});
diff --git a/crates/ov_cli/src/commands/search.rs b/crates/ov_cli/src/commands/search.rs
index 5037172d8..32ea04f3b 100644
--- a/crates/ov_cli/src/commands/search.rs
+++ b/crates/ov_cli/src/commands/search.rs
@@ -165,6 +165,7 @@ pub async fn search(
query: &str,
uri: &str,
image: Option<String>,
+ search_type: &str,
session_id: Option<String>,
node_limit: i32,
threshold: Option<f64>,
@@ -184,6 +185,7 @@ pub async fn search(
query.to_string(),
uri.to_string(),
image,
+ search_type.to_string(),
session_id,
node_limit,
threshold,
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 718cc18f8..cf78fcca5 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -1560,6 +1560,7 @@ pub async fn handle_search(
query: Option<String>,
uri: String,
image: Option<String>,
+ search_type: String,
session_id: Option<String>,
node_limit: i32,
threshold: Option<f64>,
@@ -1578,7 +1579,15 @@ pub async fn handle_search(
"Search query or --image must not be empty.".to_string(),
));
}
+ if search_type == "keywords" && image.is_some() {
+ return Err(Error::Client(
+ "--image is not supported with --search-type keywords.".to_string(),
+ ));
+ }
let mut params = vec![format!("--uri={}", uri), format!("-n {}", node_limit)];
+ if search_type != "semantic" {
+ params.push(format!("--search-type {}", search_type));
+ }
if let Some(ref img) = image {
params.push(format!("--image {}", img));
}
@@ -1618,6 +1627,7 @@ pub async fn handle_search(
&query,
&uri,
image,
+ &search_type,
session_id,
node_limit,
threshold,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index de44518d1..17cdca3aa 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -972,6 +972,14 @@ enum Commands {
help_heading = "Common options"
)]
image: Option<String>,
+ /// Retrieval type
+ #[arg(
+ long,
+ default_value = "semantic",
+ value_parser = ["semantic", "keywords"],
+ help_heading = "Common options"
+ )]
+ search_type: String,
/// Target URI
#[arg(
short,
@@ -3919,6 +3927,7 @@ async fn main() {
Commands::Search {
query,
image,
+ search_type,
uri,
session_id,
node_limit,
@@ -3935,6 +3944,7 @@ async fn main() {
query,
uri,
image,
+ search_type,
session_id,
node_limit,
threshold,
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
index 8625137a4..9577e8931 100644
--- a/docs/en/api/06-retrieval.md
+++ b/docs/en/api/06-retrieval.md
@@ -1,6 +1,6 @@
# Retrieval
-OpenViking provides multiple retrieval methods, including simple vector similarity search, intelligent retrieval with session context, regex pattern matching, and file pattern matching.
+OpenViking provides multiple retrieval methods, including simple vector similarity search, keyword search, intelligent retrieval with session context, regex pattern matching, and file pattern matching.
## find vs search
@@ -390,6 +390,7 @@ The `search()` method adds session context understanding and intent analysis cap
|-----------|------|----------|---------|-------------|
| query | str | No | "" | Search query string. Required unless `image_url` is provided |
| image_url | str | No | None | Image query as a `data:image/...;base64,...`, `http(s)://`, or `viking://` URI. Requires a multimodal embedding model |
+| search_type | `"semantic"` \| `"keywords"` | No | `"semantic"` | Retrieval type. `semantic` uses embeddings and vector recall; `keywords` uses BM25 keyword recall |
| target_uri | str \| List[str] | No | "" | Limit search to specific URI prefix |
| session | Session | No | None | Session for context-aware search (SDK) |
| session_id | str | No | None | Session ID for context-aware search (HTTP) |
@@ -407,7 +408,7 @@ The `search()` method adds session context understanding and intent analysis cap
| read_content | bool | No | False | Read each final matched URI with the visible-content read semantics and inline the result as `content`. Individual read failures leave the hit unchanged. Only supported by `mode="list"`. |
| telemetry | bool \| object | No | False | Attach telemetry data to response |
-`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.
+`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.
@@ -453,6 +454,19 @@ curl -X POST http://localhost:1933/api/v1/search/search \
}'
```
+**Keyword Search**
+```bash
+curl -X POST http://localhost:1933/api/v1/search/search \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "query": "hnsw",
+ "search_type": "keywords",
+ "target_uri": "viking://resources/docs",
+ "limit": 10
+ }'
+```
+
**Image Search**
```bash
@@ -562,6 +576,9 @@ openviking search "recent decisions" --context-type memory --level 2 \
# Search without session (still performs intent analysis)
openviking search "how to implement OAuth 2.0 authorization code flow"
+# BM25 keyword retrieval
+openviking search "SearchByKeywords" --search-type keywords --uri "viking://resources/docs"
+
# Limit to specific level(s) (L0 only)
openviking search "best practices" --level 0
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
index 30b46c1e8..564bff9f4 100644
--- a/docs/zh/api/06-retrieval.md
+++ b/docs/zh/api/06-retrieval.md
@@ -1,6 +1,6 @@
# 检索
-OpenViking 提供多种检索方法,包括简单的向量相似度搜索、带会话上下文的智能检索、正则表达式匹配搜索和文件模式匹配。
+OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关键词搜索、带会话上下文的智能检索、正则表达式匹配搜索和文件模式匹配。
## find 与 search 对比
@@ -391,6 +391,7 @@ openviking find "红色海报风格" --image ./poster.png --uri "viking://resour
|------|------|------|--------|------|
| query | str | 否 | "" | 搜索查询字符串;未提供 `image_url` 时必填 |
| image_url | str | 否 | None | 图片查询,支持 `data:image/...;base64,...`、`http(s)://` 或 `viking://` URI;需要 multimodal embedding 模型 |
+| search_type | `"semantic"` \| `"keywords"` | 否 | `"semantic"` | 检索类型。`semantic` 使用 Embedding 和向量召回;`keywords` 使用 BM25 关键词召回 |
| target_uri | str \| List[str] | 否 | "" | 限制搜索范围到指定的 URI 前缀 |
| session | Session | 否 | None | 用于上下文感知搜索的会话(SDK)|
| session_id | str | 否 | None | 用于上下文感知搜索的会话 ID(HTTP)|
@@ -409,7 +410,7 @@ openviking find "红色海报风格" --image ./poster.png --uri "viking://resour
| read_content | bool | 否 | False | 按可见内容 read 语义读取每个最终命中的 URI,并以内联 `content` 返回。单个读取失败时保留原命中,不附加内容;仅支持 `mode="list"`。 |
| telemetry | bool \| object | 否 | False | 在响应中附带遥测数据 |
-`search()` 使用和 `find()` 相同的目标解析和显式标签过滤规则,包括由 `X-OpenViking-Actor-Peer` 或 SDK `actor_peer_id` 选择的 peer 集合过滤。提供 `image_url` 时,`search()` 会直接执行图片检索并跳过会话 query planning。
+`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`。
@@ -455,6 +456,19 @@ curl -X POST http://localhost:1933/api/v1/search/search \
}'
```
+**关键词检索**
+```bash
+curl -X POST http://localhost:1933/api/v1/search/search \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "query": "hnsw",
+ "search_type": "keywords",
+ "target_uri": "viking://resources/docs",
+ "limit": 10
+ }'
+```
+
**图片搜索**
```bash
@@ -564,6 +578,9 @@ openviking search "recent decisions" --context-type memory --level 2 \
# 不带会话的搜索(仍进行意图分析)
openviking search "how to implement OAuth 2.0 authorization code flow"
+# BM25 关键词检索
+openviking search "SearchByKeywords" --search-type keywords --uri "viking://resources/docs"
+
# 限定层级范围(仅 L0)
openviking search "best practices" --level 0
diff --git a/openviking/core/retrieval_types.py b/openviking/core/retrieval_types.py
new file mode 100644
index 000000000..9b0d81ef5
--- /dev/null
+++ b/openviking/core/retrieval_types.py
@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Shared retrieval types without runtime dependencies."""
+
+from typing import Literal
+
+SearchType = Literal["semantic", "keywords"]
diff --git a/openviking/retrieve/context_assembler/gather.py b/openviking/retrieve/context_assembler/gather.py
index dd4ae12e7..bf5917f76 100644
--- a/openviking/retrieve/context_assembler/gather.py
+++ b/openviking/retrieve/context_assembler/gather.py
@@ -14,6 +14,7 @@ from typing import Any, Dict, List, Mapping, Optional, Sequence, Set, Tuple
from openviking.core.namespace import AGENT_SKILLS_ROOT, canonical_user_root
from openviking.core.retrieval_targets import default_target_directories
+from openviking.core.retrieval_types import SearchType
from openviking.retrieve.context_assembler.params import (
MEMORY_CATEGORIES,
ORIGIN_ORDER,
@@ -211,6 +212,7 @@ async def gather_candidates(
filter: Optional[Dict[str, Any]] = None,
image_url: Optional[str] = None,
events_time_decay_protection: Optional[str] = None,
+ search_type: SearchType = "semantic",
peer_scope: str = "all",
penalties: Optional[Mapping[str, float]] = None,
excluded: Optional[Set[str]] = None,
@@ -301,6 +303,7 @@ async def gather_candidates(
score_threshold=score_threshold,
filter=find_filter if find_filter is not None else filter,
image_url=image_url,
+ search_type=search_type,
level=None,
events_time_decay_protection=events_time_decay_protection,
)
@@ -333,6 +336,7 @@ async def gather_candidates(
limit=_overfetch(quota),
score_threshold=score_threshold,
filter=bucket_filter,
+ search_type=search_type,
)
)
elif filter:
diff --git a/openviking/retrieve/context_assembler/params.py b/openviking/retrieve/context_assembler/params.py
index 686db2149..1372adc1d 100644
--- a/openviking/retrieve/context_assembler/params.py
+++ b/openviking/retrieve/context_assembler/params.py
@@ -7,6 +7,8 @@ from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Dict, Literal, Mapping, Optional, Sequence, Tuple, Union
+from openviking.core.retrieval_types import SearchType
+
Detail = Literal["abstract", "overview", "full"]
# "auto" no longer selects a strategy; it is accepted as a synonym for "unset".
DetailRequest = Union[Literal["auto", "abstract", "overview", "full"], Dict[str, Detail]]
@@ -120,6 +122,7 @@ class AssembleParams:
"""Resolved request contract for one context assembly run."""
query: str = ""
+ search_type: SearchType = "semantic"
image_url: Optional[str] = None
limit: int = DEFAULT_LIMIT
score_threshold: Optional[float] = None
diff --git a/openviking/retrieve/context_assembler/pipeline.py b/openviking/retrieve/context_assembler/pipeline.py
index 5a669af0e..2a71a06e0 100644
--- a/openviking/retrieve/context_assembler/pipeline.py
+++ b/openviking/retrieve/context_assembler/pipeline.py
@@ -59,6 +59,12 @@ async def assemble_context(
) -> AssembleResult:
"""Run the full assembly pipeline for one request."""
validate_event_time_decay_request(params.events_time_decay_protection)
+ if params.search_type == "keywords":
+ if params.image_url:
+ from openviking_cli.exceptions import InvalidArgumentError
+
+ raise InvalidArgumentError("image_url is not supported when search_type='keywords'")
+ await service.search.ensure_keywords_search_supported(ctx)
quotas = normalize_quotas(params.quotas, params.purpose)
penalties = normalize_penalties(params.other_peer_penalty)
@@ -116,6 +122,7 @@ async def assemble_context(
filter=params.filter,
image_url=params.image_url,
events_time_decay_protection=params.events_time_decay_protection,
+ search_type=params.search_type,
peer_scope=params.peer_scope,
penalties=penalties,
excluded=excluded,
diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.py
index a69c2ddba..e2abb16db 100644
--- a/openviking/retrieve/hierarchical_retriever.py
+++ b/openviking/retrieve/hierarchical_retriever.py
@@ -12,6 +12,7 @@ from typing import Any, Dict, List, Optional
from openviking.core.context import ContextLevel
from openviking.core.retrieval_targets import default_target_directories
+from openviking.core.retrieval_types import SearchType
from openviking.models.embedder.base import EmbedResult, embed_compat
from openviking.models.rerank import RerankClient
from openviking.retrieve.retrieval_stats import get_stats_collector
@@ -96,6 +97,7 @@ class HierarchicalRetriever:
level: Optional[List[int]] = None,
events_time_decay_protection: Optional[str] = None,
request_now: Optional[datetime] = None,
+ search_type: SearchType = "semantic",
) -> QueryResult:
"""
Run one global vector search, then optionally rerank its candidates.
@@ -149,7 +151,7 @@ class HierarchicalRetriever:
# Generate query vectors once to avoid duplicate embedding calls
query_vector = None
sparse_query_vector = None
- if self.embedder:
+ if search_type == "semantic" and self.embedder:
if image_query and not getattr(self.embedder, "supports_multimodal", False):
raise InvalidArgumentError("Image search requires a multimodal embedding model.")
with telemetry.measure("search.embed_query"):
@@ -174,16 +176,26 @@ class HierarchicalRetriever:
search_limit = limit * self.RERANK_CANDIDATE_MULTIPLIER if use_rerank else limit
with telemetry.measure("search.vector_retrieval"):
- vector_results = await vector_proxy.search_in_tenant(
- query_vector=query_vector,
- sparse_query_vector=sparse_query_vector,
- context_type=context_type,
- target_directories=target_dirs,
- extra_filter=scope_dsl,
- level=level,
- limit=search_limit,
- **decay_kwargs,
- )
+ if search_type == "keywords":
+ vector_results = await vector_proxy.search_by_keywords_in_tenant(
+ query=query.query,
+ context_type=context_type,
+ target_directories=target_dirs,
+ extra_filter=scope_dsl,
+ level=level,
+ limit=search_limit,
+ )
+ else:
+ vector_results = await vector_proxy.search_in_tenant(
+ query_vector=query_vector,
+ sparse_query_vector=sparse_query_vector,
+ context_type=context_type,
+ target_directories=target_dirs,
+ extra_filter=scope_dsl,
+ level=level,
+ limit=search_limit,
+ **decay_kwargs,
+ )
telemetry.count("vector.searches", 1)
telemetry.count("vector.scored", len(vector_results))
telemetry.count("vector.scanned", len(vector_results))
diff --git a/openviking/retrieve/skill_package_retriever.py b/openviking/retrieve/skill_package_retriever.py
index 9dd3d4cd9..c69754f5c 100644
--- a/openviking/retrieve/skill_package_retriever.py
+++ b/openviking/retrieve/skill_package_retriever.py
@@ -6,6 +6,7 @@ import math
import time
from typing import Optional
+from openviking.core.retrieval_types import SearchType
from openviking.models.embedder.base import embed_compat
from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever
from openviking.retrieve.retrieval_stats import get_stats_collector
@@ -32,6 +33,7 @@ class SkillPackageRetriever(HierarchicalRetriever):
score_gte: bool = False,
level: Optional[list[int]] = None,
scope_dsl=None,
+ search_type: SearchType = "semantic",
) -> QueryResult:
started = time.monotonic()
telemetry = get_current_telemetry()
@@ -42,7 +44,7 @@ class SkillPackageRetriever(HierarchicalRetriever):
threshold = self._resolve_threshold(score_threshold)
query_vector = sparse_vector = None
- if self.embedder:
+ if search_type == "semantic" and self.embedder:
with telemetry.measure("search.embed_query"):
embedded = await embed_compat(self.embedder, query.query, is_query=True)
query_vector, sparse_vector = embedded.dense_vector, embedded.sparse_vector
@@ -54,16 +56,27 @@ class SkillPackageRetriever(HierarchicalRetriever):
matches = []
while True:
with telemetry.measure("search.vector_retrieval"):
- page = await proxy.search_in_tenant(
- query_vector=query_vector,
- sparse_query_vector=sparse_vector,
- context_type="skill",
- target_directories=target_dirs,
- extra_filter=scope_dsl,
- level=level,
- limit=page_size,
- offset=offset,
- )
+ if search_type == "keywords":
+ page = await proxy.search_by_keywords_in_tenant(
+ query=query.query,
+ context_type="skill",
+ target_directories=target_dirs,
+ extra_filter=scope_dsl,
+ level=level,
+ limit=page_size,
+ offset=offset,
+ )
+ else:
+ page = await proxy.search_in_tenant(
+ query_vector=query_vector,
+ sparse_query_vector=sparse_vector,
+ context_type="skill",
+ target_directories=target_dirs,
+ extra_filter=scope_dsl,
+ level=level,
+ limit=page_size,
+ offset=offset,
+ )
telemetry.count("vector.searches", 1)
telemetry.count("vector.scored", len(page))
telemetry.count("vector.scanned", len(page))
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 25ee1c0b8..948a83cec 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -43,6 +43,7 @@ from starlette.types import ASGIApp, Receive, Scope, Send
from openviking.core.path_variables import resolve_path_variables
from openviking.core.retrieval_targets import default_target_directories
+from openviking.core.retrieval_types import SearchType
from openviking.core.uri_validation import (
validate_content_target_uri,
validate_request_viking_uri,
@@ -399,6 +400,7 @@ _MCP_CONTEXT_ONLY_ALIASES = {
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def search(
query: str,
+ search_type: SearchType = "semantic",
target_uri: str = "",
session_id: Optional[str] = None,
limit: int = 10,
@@ -422,7 +424,7 @@ async def search(
read_content: bool = False,
events_time_decay_protection: Optional[str] = None,
) -> str:
- """Deep semantic retrieval with optional session context and intent analysis.
+ """Retrieval with optional session context and intent analysis.
``mode="list"`` returns ranked memories, resources, and skills with URI,
abstract, and score. ``mode="context"`` returns an injection-ready,
@@ -436,6 +438,8 @@ async def search(
raise InvalidArgumentError(str(exc)) from exc
service = get_service()
ctx = _get_ctx()
+ if search_type == "keywords" and not query.strip():
+ raise InvalidArgumentError("query must not be empty when search_type='keywords'")
context_filter = _resolve_context_type_filter(context_type)
if mode == "context":
if read_content:
@@ -460,6 +464,7 @@ async def search(
ctx=ctx,
params=AssembleParams(
query=query,
+ search_type=search_type,
limit=limit,
score_threshold=min_score,
filter=context_filter,
@@ -528,6 +533,7 @@ async def search(
await session.load()
result = await service.search.search(
query=query,
+ search_type=search_type,
ctx=ctx,
target_uri=target_uri,
session=session,
diff --git a/openviking/server/routers/search.py b/openviking/server/routers/search.py
index 8f4a8a4bc..49d448f3a 100644
--- a/openviking/server/routers/search.py
+++ b/openviking/server/routers/search.py
@@ -11,6 +11,7 @@ from fastapi import Response as FastAPIResponse
from pydantic import BaseModel, ConfigDict, Field, model_validator
from openviking.core.path_variables import resolve_path_variables
+from openviking.core.retrieval_types import SearchType
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.retrieve.context_assembler import (
@@ -216,6 +217,7 @@ class SearchRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
query: str = ""
+ search_type: SearchType = "semantic"
image_url: Optional[str] = None
target_uri: Union[str, List[str]] = ""
context_type: Optional[Union[str, List[str]]] = None
@@ -252,6 +254,11 @@ class SearchRequest(BaseModel):
@model_validator(mode="after")
def _validate_mode(self) -> "SearchRequest":
validate_event_time_decay_request(self.events_time_decay_protection)
+ if self.search_type == "keywords":
+ if not self.query.strip():
+ raise ValueError("query must not be empty when search_type='keywords'")
+ if self.image_url:
+ raise ValueError("image_url is not supported when search_type='keywords'")
if self.mode == "list":
error = context_only_fields_error(self.model_fields_set)
if error:
@@ -429,6 +436,7 @@ async def _search_context(
"""Assemble an injection-ready context block for one request."""
params = AssembleParams(
query=request.query,
+ search_type=request.search_type,
image_url=_resolve_image_url(request.image_url, ctx),
limit=actual_limit,
score_threshold=request.score_threshold,
@@ -501,6 +509,7 @@ async def search(
await session.load()
return await service.search.search(
query=request.query,
+ search_type=request.search_type,
ctx=_ctx,
target_uri=resolved_target_uri,
session=session,
diff --git a/openviking/service/search_service.py b/openviking/service/search_service.py
index 5bdd30039..1d8acb96f 100644
--- a/openviking/service/search_service.py
+++ b/openviking/service/search_service.py
@@ -3,11 +3,12 @@
"""
Search Service for OpenViking.
-Provides semantic search operations: search, find.
+Provides search operations: search, find.
"""
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+from openviking.core.retrieval_types import SearchType
from openviking.server.identity import RequestContext
from openviking.storage.viking_fs import VikingFS
from openviking.utils.image_search import (
@@ -45,7 +46,7 @@ def _ensure_non_empty_query(
class SearchService:
- """Semantic search service."""
+ """Search service."""
def __init__(self, viking_fs: Optional[VikingFS] = None):
self._viking_fs = viking_fs
@@ -71,6 +72,21 @@ class SearchService:
return True
return bool(self._viking_fs.retrieval_config.enable_intent)
+ 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()
+ vector_store = viking_fs._get_vector_store()
+ if not vector_store or not await viking_fs._collection_has_fulltext(
+ vector_store,
+ ctx,
+ supported_modes=("volcengine", "vikingdb"),
+ raise_on_error=True,
+ ):
+ raise InvalidArgumentError(
+ "Keyword search is not supported by the configured vector backend, or full-text "
+ "indexing is not enabled for the content field."
+ )
+
async def _resolve_image_url(
self,
image_url: Optional[str],
@@ -100,8 +116,9 @@ class SearchService:
level: Optional[List[int]] = None,
image_url: Optional[str] = None,
events_time_decay_protection: Optional[str] = None,
+ search_type: SearchType = "semantic",
) -> Any:
- """Complex search with session context.
+ """Search with session context.
Args:
query: Query string
@@ -115,8 +132,12 @@ class SearchService:
Returns:
FindResult
"""
+ if search_type == "keywords" and image_url:
+ raise InvalidArgumentError("image_url is not supported when search_type='keywords'")
resolved_image_url = await self._resolve_image_url(image_url, ctx)
_ensure_non_empty_query(query, resolved_image_url)
+ if search_type == "keywords":
+ await self.ensure_keywords_search_supported(ctx)
viking_fs = self._ensure_initialized()
session_info = None
@@ -135,6 +156,7 @@ class SearchService:
level=level,
image_url=resolved_image_url,
events_time_decay_protection=events_time_decay_protection,
+ search_type=search_type,
)
return result
@@ -149,8 +171,9 @@ class SearchService:
level: Optional[List[int]] = None,
image_url: Optional[str] = None,
events_time_decay_protection: Optional[str] = None,
+ search_type: SearchType = "semantic",
) -> Any:
- """Semantic search without session context.
+ """Search without session context.
Args:
query: Query string
@@ -163,6 +186,8 @@ class SearchService:
Returns:
FindResult
"""
+ if search_type == "keywords" and image_url:
+ raise InvalidArgumentError("image_url is not supported when search_type='keywords'")
resolved_image_url = await self._resolve_image_url(image_url, ctx)
_ensure_non_empty_query(query, resolved_image_url, filter)
viking_fs = self._ensure_initialized()
@@ -176,6 +201,7 @@ class SearchService:
level=level,
image_url=resolved_image_url,
events_time_decay_protection=events_time_decay_protection,
+ search_type=search_type,
)
return result
@@ -188,6 +214,7 @@ class SearchService:
score_threshold: Optional[float] = None,
level: Optional[List[int]] = None,
filter: Optional[Dict] = None,
+ search_type: SearchType = "semantic",
) -> Any:
"""Find distinct packages; general find/search stay item-based."""
from openviking.core.retrieval_targets import resolve_retrieval_targets
@@ -203,7 +230,7 @@ class SearchService:
storage, embedder = fs._get_vector_store(), fs._get_embedder(ctx)
if not storage:
raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")
- if not embedder:
+ if search_type == "semantic" and not embedder:
raise RuntimeError("Embedder not configured.")
retriever = SkillPackageRetriever(
storage=storage,
@@ -218,5 +245,6 @@ class SearchService:
score_threshold=score_threshold,
level=level,
scope_dsl=filter,
+ search_type=search_type,
)
return FindResult(memories=[], resources=[], skills=result.matched_contexts)
diff --git a/openviking/storage/vectordb/collection/collection.py b/openviking/storage/vectordb/collection/collection.py
index 177648fd5..8840736ef 100644
--- a/openviking/storage/vectordb/collection/collection.py
+++ b/openviking/storage/vectordb/collection/collection.py
@@ -81,6 +81,8 @@ class ICollection(ABC):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
raise NotImplementedError
@@ -269,7 +271,7 @@ class Collection:
raise RuntimeError("Collection is closed")
self.__collection.end_bulk_ingest()
- def get_meta_data(self) -> Dict[str, Any]:
+ def get_meta_data(self, *, raise_on_error: bool = False) -> Dict[str, Any]:
"""
Retrieve the full metadata of the collection.
@@ -279,6 +281,8 @@ class Collection:
"""
if self.__collection is None:
raise RuntimeError("Collection is closed")
+ if raise_on_error:
+ return self.__collection.get_meta_data(raise_on_error=True)
return self.__collection.get_meta_data()
def get_meta(self) -> Dict[str, Any]:
@@ -391,6 +395,8 @@ class Collection:
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
):
"""Search by keywords or query string using vectorization.
@@ -414,7 +420,15 @@ class Collection:
if self.__collection is None:
raise RuntimeError("Collection is closed")
return self.__collection.search_by_keywords(
- index_name, keywords, query, limit, offset, filters, output_fields
+ index_name=index_name,
+ keywords=keywords,
+ query=query,
+ mode=mode,
+ fields=fields,
+ limit=limit,
+ offset=offset,
+ filters=filters,
+ output_fields=output_fields,
)
def search_by_id(
diff --git a/openviking/storage/vectordb/collection/http_collection.py b/openviking/storage/vectordb/collection/http_collection.py
index f99983380..c461c8eff 100644
--- a/openviking/storage/vectordb/collection/http_collection.py
+++ b/openviking/storage/vectordb/collection/http_collection.py
@@ -565,6 +565,8 @@ class HttpCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
url = self.url_prefix + "api/vikingdb/data/search/keywords"
payload = {
@@ -573,6 +575,8 @@ class HttpCollection(ICollection):
"index_name": index_name,
"keywords": json.dumps(keywords) if keywords else None,
"query": query,
+ "mode": mode,
+ "fields": json.dumps(fields) if fields else None,
"filter": json.dumps(filters) if filters else None,
"output_fields": json.dumps(output_fields) if output_fields else None,
"limit": limit,
diff --git a/openviking/storage/vectordb/collection/local_collection.py b/openviking/storage/vectordb/collection/local_collection.py
index 4854303c1..be235d26f 100644
--- a/openviking/storage/vectordb/collection/local_collection.py
+++ b/openviking/storage/vectordb/collection/local_collection.py
@@ -740,6 +740,8 @@ class LocalCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
"""Local backend does not generate vectors from keywords.
diff --git a/openviking/storage/vectordb/collection/vikingdb_collection.py b/openviking/storage/vectordb/collection/vikingdb_collection.py
index 9f7091c7a..68a2f07c6 100644
--- a/openviking/storage/vectordb/collection/vikingdb_collection.py
+++ b/openviking/storage/vectordb/collection/vikingdb_collection.py
@@ -86,7 +86,13 @@ class VikingDBCollection(ICollection):
except json.JSONDecodeError:
return {}
- def _console_get(self, params: Optional[Dict[str, Any]], action: str):
+ def _console_get(
+ self,
+ params: Optional[Dict[str, Any]],
+ action: str,
+ *,
+ raise_on_error: bool = False,
+ ):
if params is None:
params = {}
path, method = VIKINGDB_APIS[action]
@@ -94,12 +100,16 @@ class VikingDBCollection(ICollection):
response = self.client.do_req(method, path=path, req_body=params)
if response.status_code != 200:
+ if raise_on_error:
+ raise self._build_response_error(response, action)
logger.error(f"Request to {action} failed: {response.text}")
return {}
try:
result = response.json()
return result.get("Result", {})
except json.JSONDecodeError:
+ if raise_on_error:
+ raise self._build_response_error(response, action)
return {}
def _data_post(self, path: str, data: Dict[str, Any]):
@@ -136,12 +146,16 @@ class VikingDBCollection(ICollection):
return self._console_post(data, action="UpdateVikingdbCollection")
- def get_meta_data(self):
+ def get_meta_data(self, *, raise_on_error: bool = False):
params = {
"ProjectName": self.project_name,
"CollectionName": self.collection_name,
}
- return self._console_get(params, action="GetVikingdbCollection")
+ return self._console_get(
+ params,
+ action="GetVikingdbCollection",
+ raise_on_error=raise_on_error,
+ )
def close(self):
pass
@@ -373,6 +387,8 @@ class VikingDBCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
path = "/api/vikingdb/data/search/keywords"
data = {
@@ -381,6 +397,8 @@ class VikingDBCollection(ICollection):
"index_name": index_name,
"keywords": keywords,
"query": query,
+ "mode": mode,
+ "fields": fields,
"filter": filters,
"output_fields": output_fields,
"limit": limit,
diff --git a/openviking/storage/vectordb/collection/volcengine_api_key_collection.py b/openviking/storage/vectordb/collection/volcengine_api_key_collection.py
index 66491c3ec..44a3991fd 100644
--- a/openviking/storage/vectordb/collection/volcengine_api_key_collection.py
+++ b/openviking/storage/vectordb/collection/volcengine_api_key_collection.py
@@ -245,7 +245,7 @@ class VolcengineApiKeyCollection(ICollection):
"volcengine api_key mode is data-plane only; update is not supported"
)
- def get_meta_data(self):
+ def get_meta_data(self, *, raise_on_error: bool = False):
from openviking.storage.collection_schemas import CollectionSchemas
schema = CollectionSchemas.context_collection(
@@ -395,12 +395,16 @@ class VolcengineApiKeyCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
path = "/api/vikingdb/data/search/keywords"
data = {
**self._base_data_payload(index_name=index_name),
"keywords": keywords,
"query": query,
+ "mode": mode,
+ "fields": fields,
"filter": filters,
"output_fields": output_fields,
"limit": limit,
diff --git a/openviking/storage/vectordb/collection/volcengine_collection.py b/openviking/storage/vectordb/collection/volcengine_collection.py
index 32f2d24c2..a7fdbf929 100644
--- a/openviking/storage/vectordb/collection/volcengine_collection.py
+++ b/openviking/storage/vectordb/collection/volcengine_collection.py
@@ -136,7 +136,13 @@ class VolcengineCollection(ICollection):
except json.JSONDecodeError:
return {}
- def _console_get(self, params: Optional[Dict[str, Any]], action: str):
+ def _console_get(
+ self,
+ params: Optional[Dict[str, Any]],
+ action: str,
+ *,
+ raise_on_error: bool = False,
+ ):
if params is None:
params = {}
req_params = {"Action": action, "Version": VIKING_DB_VERSION}
@@ -144,12 +150,16 @@ class VolcengineCollection(ICollection):
response = self.console_client.do_req("POST", req_params=req_params, req_body=req_body)
if response.status_code != 200:
+ if raise_on_error:
+ raise self._build_response_error(response, action)
logger.error(str(self._build_response_error(response, action)))
return {}
try:
result = response.json()
return result.get("Result", {})
except json.JSONDecodeError:
+ if raise_on_error:
+ raise self._build_response_error(response, action)
return {}
@staticmethod
@@ -317,12 +327,16 @@ class VolcengineCollection(ICollection):
return self._console_post(data, action="UpdateVikingdbCollection")
- def get_meta_data(self):
+ def get_meta_data(self, *, raise_on_error: bool = False):
params = {
"ProjectName": self.project_name,
"CollectionName": self.collection_name,
}
- return self._console_get(params, action="GetVikingdbCollection")
+ return self._console_get(
+ params,
+ action="GetVikingdbCollection",
+ raise_on_error=raise_on_error,
+ )
def close(self):
pass
@@ -588,6 +602,8 @@ class VolcengineCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
path = "/api/vikingdb/data/search/keywords"
data = {
@@ -596,6 +612,8 @@ class VolcengineCollection(ICollection):
"index_name": index_name,
"keywords": keywords,
"query": query,
+ "mode": mode,
+ "fields": fields,
"filter": filters,
"output_fields": output_fields,
"limit": limit,
diff --git a/openviking/storage/vectordb/service/api_fastapi.py b/openviking/storage/vectordb/service/api_fastapi.py
index 30f36d519..3cf4dc5ac 100644
--- a/openviking/storage/vectordb/service/api_fastapi.py
+++ b/openviking/storage/vectordb/service/api_fastapi.py
@@ -659,6 +659,12 @@ async def search_by_keywords(request: SearchByKeywordsRequest, req: Request):
index_name=index_name,
keywords=keywords,
query=query,
+ mode=request.mode,
+ fields=(
+ data_utils.convert_dict(request.fields)
+ if request.fields is not None
+ else None
+ ),
limit=limit,
offset=offset,
filters=filters,
diff --git a/openviking/storage/vectordb/service/app_models.py b/openviking/storage/vectordb/service/app_models.py
index 18b240920..e4d8c3e84 100644
--- a/openviking/storage/vectordb/service/app_models.py
+++ b/openviking/storage/vectordb/service/app_models.py
@@ -165,6 +165,8 @@ class SearchByKeywordsRequest(BaseModel):
project: Optional[str] = Field("default", description="Project name")
keywords: Optional[Any] = Field(None, description="Keywords list")
query: Optional[str] = Field(None, description="Query string")
+ mode: Optional[str] = Field(None, description="Keyword ranking mode")
+ fields: Optional[Any] = Field(None, description="Fields used for keyword matching")
filter: Optional[Any] = Field(None, description="Filter conditions")
output_fields: Optional[Any] = Field(None, description="Output fields")
limit: Optional[int] = Field(10, description="Result limit")
diff --git a/openviking/storage/vectordb_adapters/base.py b/openviking/storage/vectordb_adapters/base.py
index c45f00354..7563e8bc3 100644
--- a/openviking/storage/vectordb_adapters/base.py
+++ b/openviking/storage/vectordb_adapters/base.py
@@ -703,6 +703,8 @@ class CollectionAdapter(ABC):
offset: int = 0,
filter: Optional[Dict[str, Any] | FilterExpr] = None,
output_fields: Optional[list[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[list[str]] = None,
) -> list[Dict[str, Any]]:
coll = self.get_collection()
compiled_filter = self._compile_filter(filter)
@@ -719,6 +721,8 @@ class CollectionAdapter(ABC):
index_name=self._index_name,
keywords=keywords,
query=query,
+ mode=mode,
+ fields=fields,
limit=limit,
offset=offset,
filters=compiled_filter,
diff --git a/openviking/storage/vectordb_adapters/opengauss/collection.py b/openviking/storage/vectordb_adapters/opengauss/collection.py
index a093563aa..ed3d05e13 100644
--- a/openviking/storage/vectordb_adapters/opengauss/collection.py
+++ b/openviking/storage/vectordb_adapters/opengauss/collection.py
@@ -1242,6 +1242,8 @@ class OpenGaussCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
raise NotImplementedError(
"openGauss backend does not provide OpenViking keyword/full-text search"
diff --git a/openviking/storage/viking_fs/__init__.py b/openviking/storage/viking_fs/__init__.py
index cb2321cd5..4af01d28e 100644
--- a/openviking/storage/viking_fs/__init__.py
+++ b/openviking/storage/viking_fs/__init__.py
@@ -156,7 +156,7 @@ class VikingFS(
self._vector_config_resolver = vector_config_resolver
self._count_cache: Dict[str, tuple] = {} # cache_key → (count, timestamp)
self._count_cache_max_size = 1024
- self._fulltext_available: Dict[tuple[str, str, str, str], bool] = {}
+ self._fulltext_available: Dict[tuple[str, str, str, str], tuple[bool, Optional[float]]] = {}
self._bound_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar(
"vikingfs_bound_ctx", default=None
)
diff --git a/openviking/storage/viking_fs/_grep.py b/openviking/storage/viking_fs/_grep.py
index f9c31f3dc..ad8f79331 100644
--- a/openviking/storage/viking_fs/_grep.py
+++ b/openviking/storage/viking_fs/_grep.py
@@ -17,6 +17,7 @@ from openviking_cli.exceptions import PermissionDeniedError
from openviking_cli.utils.config.grep_config import GrepEngine
_GREP_LS_PAGE_SIZE = 1000
+_FULLTEXT_UNSUPPORTED_CACHE_TTL = 60.0
def _pkg():
@@ -185,7 +186,9 @@ class _GrepMixin:
return "vikingdb_then_fs"
- async def _collection_has_fulltext(self, vector_store, ctx) -> bool:
+ async def _collection_has_fulltext(
+ self, vector_store, ctx, supported_modes=None, raise_on_error: bool = False
+ ) -> bool:
"""Check if collection has content field and FullText config.
The cache is scoped by Account and collection identity because one
@@ -203,15 +206,23 @@ class _GrepMixin:
str(getattr(backend, "collection_name", getattr(backend, "_collection_name", ""))),
str(getattr(backend, "index_name", getattr(backend, "_index_name", ""))),
)
- if cache_key in self._fulltext_available:
- return self._fulltext_available[cache_key]
+ if supported_modes is not None and getattr(backend, "_mode", None) not in supported_modes:
+ return False
+ cached = self._fulltext_available.get(cache_key)
+ if cached is not None:
+ supported, expires_at = cached
+ if expires_at is None or time.monotonic() < expires_at:
+ return supported
+ del self._fulltext_available[cache_key]
try:
meta = None
if hasattr(vector_store, "get_collection_meta"):
- meta = await vector_store.get_collection_meta(ctx=ctx)
- if not meta:
- self._fulltext_available[cache_key] = False
- return False
+ meta = await vector_store.get_collection_meta(
+ ctx=ctx,
+ raise_on_error=raise_on_error,
+ )
+ if not isinstance(meta, dict) or not isinstance(meta.get("Fields"), list):
+ raise RuntimeError("Vector backend returned invalid collection metadata")
fields = meta.get("Fields", [])
has_content = any(
f.get("FieldName") == "content" and f.get("FieldType") == "text" for f in fields
@@ -219,9 +230,21 @@ class _GrepMixin:
fulltext = meta.get("FullText") or []
has_content_fulltext = any(ft.get("Field") == "content" for ft in fulltext)
result = has_content and has_content_fulltext
- self._fulltext_available[cache_key] = result
+ expires_at = None if result else time.monotonic() + _FULLTEXT_UNSUPPORTED_CACHE_TTL
+ self._fulltext_available[cache_key] = (result, expires_at)
return result
except Exception:
+ if raise_on_error:
+ logger.error(
+ "Failed to check collection fulltext config: "
+ "account_id=%s backend=%s collection=%s index=%s",
+ account_id,
+ cache_key[1],
+ cache_key[2],
+ cache_key[3],
+ exc_info=True,
+ )
+ raise
logger.debug(
"Failed to check collection fulltext config, assuming no fulltext", exc_info=True
)
diff --git a/openviking/storage/viking_fs/_semantic.py b/openviking/storage/viking_fs/_semantic.py
index 6a65e80e6..77a97cde7 100644
--- a/openviking/storage/viking_fs/_semantic.py
+++ b/openviking/storage/viking_fs/_semantic.py
@@ -8,6 +8,7 @@ from typing import Any, Dict, List, Optional, Union
from openviking.core.context import ContextLevel
from openviking.core.retrieval_targets import resolve_retrieval_targets
+from openviking.core.retrieval_types import SearchType
from openviking.server.error_mapping import is_not_found_error, map_exception
from openviking.server.identity import RequestContext
from openviking.storage.abstract_overview import (
@@ -202,6 +203,7 @@ class _SemanticMixin:
level: Optional[List[int]] = None,
image_url: Optional[str] = None,
events_time_decay_protection: Optional[str] = None,
+ search_type: SearchType = "semantic",
):
"""Semantic search.
@@ -271,7 +273,7 @@ class _SemanticMixin:
raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")
embedder = self._get_embedder(real_ctx)
- if not embedder:
+ if search_type == "semantic" and not embedder:
raise RuntimeError("Embedder not configured.")
retriever = HierarchicalRetriever(
@@ -306,6 +308,7 @@ class _SemanticMixin:
level=level,
events_time_decay_protection=events_time_decay_protection,
request_now=request_now,
+ search_type=search_type,
)
# Convert QueryResult to FindResult
@@ -398,6 +401,7 @@ class _SemanticMixin:
level: Optional[List[int]] = None,
image_url: Optional[str] = None,
events_time_decay_protection: Optional[str] = None,
+ search_type: SearchType = "semantic",
):
"""Complex search with session context.
@@ -525,6 +529,7 @@ class _SemanticMixin:
level=level,
events_time_decay_protection=events_time_decay_protection,
request_now=request_now,
+ search_type=search_type,
)
query_results = await asyncio.gather(*[_execute(tq) for tq in typed_queries])
diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.py
index 330cf6d08..42fcca685 100644
--- a/openviking/storage/viking_vector_index_backend.py
+++ b/openviking/storage/viking_vector_index_backend.py
@@ -225,10 +225,16 @@ class _AsyncVectorAdapter:
self._closed = True
self._adapter.close()
- async def collection_meta(self, index_name: str) -> Dict[str, Any]:
+ async def collection_meta(
+ self, index_name: str, *, raise_on_error: bool = False
+ ) -> Dict[str, Any]:
def _get() -> Dict[str, Any]:
collection = self._adapter.get_collection()
- meta = collection.get_meta_data() or {}
+ meta = (
+ collection.get_meta_data(raise_on_error=True)
+ if raise_on_error
+ else collection.get_meta_data()
+ ) or {}
if self._adapter.mode in {"local", "cuvs"}:
index_meta = collection.get_index_meta_data(index_name) or {}
if "ScalarIndex" in index_meta:
@@ -513,10 +519,15 @@ class _SingleAccountBackend:
}
@_backend_operation
- async def get_collection_meta(self) -> Optional[Dict[str, Any]]:
+ async def get_collection_meta(
+ self, *, raise_on_error: bool = False
+ ) -> Optional[Dict[str, Any]]:
if not await self.collection_exists():
return None
- return await self._async_adapter.collection_meta(self._index_name)
+ return await self._async_adapter.collection_meta(
+ self._index_name,
+ raise_on_error=raise_on_error,
+ )
@_backend_operation
async def update_collection_description(self, description: str) -> bool:
@@ -1010,6 +1021,8 @@ class _SingleAccountBackend:
offset: int = 0,
filter: Optional[Dict[str, Any] | FilterExpr] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> List[Dict[str, Any]]:
try:
if self._bound_account_id:
@@ -1025,6 +1038,8 @@ class _SingleAccountBackend:
self._adapter.search_by_keywords,
keywords=keywords,
query=query,
+ mode=mode,
+ fields=fields,
limit=limit,
offset=offset,
filter=filter,
@@ -1250,12 +1265,13 @@ class VikingVectorIndexBackend:
self,
*,
ctx: Optional[RequestContext] = None,
+ raise_on_error: bool = False,
) -> Optional[Dict[str, Any]]:
if ctx:
backend = await self._get_backend_for_context(ctx)
else:
backend = self._get_default_backend()
- return await backend.get_collection_meta()
+ return await backend.get_collection_meta(raise_on_error=raise_on_error)
async def update_collection_description(self, description: str) -> bool:
return await self._get_default_backend().update_collection_description(description)
@@ -1787,6 +1803,8 @@ class VikingVectorIndexBackend:
output_fields: Optional[List[str]] = None,
*,
ctx: Optional[RequestContext] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> List[Dict[str, Any]]:
if ctx:
backend = await self._get_backend_for_context(ctx)
@@ -1800,6 +1818,8 @@ class VikingVectorIndexBackend:
return await backend.search_by_keywords(
keywords=keywords,
query=query,
+ mode=mode,
+ fields=fields,
limit=limit,
offset=offset,
filter=filter,
@@ -1925,6 +1945,37 @@ class VikingVectorIndexBackend:
request_now=request_now,
)
+ async def search_by_keywords_in_tenant(
+ self,
+ ctx: RequestContext,
+ query: str,
+ context_type: Optional[str] = None,
+ target_directories: Optional[List[str]] = None,
+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,
+ level: Optional[List[int]] = None,
+ limit: int = 10,
+ offset: int = 0,
+ ) -> List[Dict[str, Any]]:
+ acl_enabled = await self._acl_enabled(ctx)
+ scope_filter = self._build_scope_filter(
+ ctx=ctx,
+ context_type=context_type,
+ target_directories=target_directories,
+ extra_filter=extra_filter,
+ level=level,
+ acl_enabled=acl_enabled,
+ )
+ backend = await self._get_backend_for_context(ctx)
+ return await backend.search_by_keywords(
+ query=query,
+ mode="bm25",
+ fields=["content"],
+ filter=scope_filter,
+ limit=limit,
+ offset=offset,
+ output_fields=RETRIEVAL_OUTPUT_FIELDS,
+ )
+
async def filter_in_tenant(
self,
ctx: RequestContext,
diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.py
index 6a3ffbd1a..202474ada 100644
--- a/openviking/storage/vikingdb_manager.py
+++ b/openviking/storage/vikingdb_manager.py
@@ -453,6 +453,27 @@ class VikingDBManagerProxy:
)
return await self._manager.search_in_tenant(self._ctx, **kwargs)
+ async def search_by_keywords_in_tenant(
+ self,
+ query: str,
+ context_type: Optional[str] = None,
+ target_directories: Optional[List[str]] = None,
+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,
+ level: Optional[List[int]] = None,
+ limit: int = 10,
+ offset: int = 0,
+ ) -> List[Dict[str, Any]]:
+ return await self._manager.search_by_keywords_in_tenant(
+ self._ctx,
+ query=query,
+ context_type=context_type,
+ target_directories=target_directories,
+ extra_filter=extra_filter,
+ level=level,
+ limit=limit,
+ offset=offset,
+ )
+
async def filter_in_tenant(
self,
context_type: Optional[str] = None,
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 037347127..39b6ce82a 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -177,7 +177,7 @@ func TestFindOmitsSearchFiltersWhenUnset(t *testing.T) {
t.Fatalf("path = %s", r.URL.Path)
}
body := readJSONBody(t, r)
- requireBodyKeysAbsent(t, body, "since", "until", "time_field", "level", "tags", "agent_id", "agent_uri")
+ requireBodyKeysAbsent(t, body, "search_type", "since", "until", "time_field", "level", "tags", "agent_id", "agent_uri")
writeOK(t, w, map[string]any{"resources": []any{}})
}))
defer closeServer()
@@ -662,6 +662,9 @@ func TestSearchSendsSessionAndSearchFilters(t *testing.T) {
if got := body["session_id"]; got != "session-1" {
t.Fatalf("session_id = %#v", got)
}
+ if got := body["search_type"]; got != "keywords" {
+ t.Fatalf("search_type = %#v", got)
+ }
if got := body["target_uri"]; got != "viking://resources/docs" {
t.Fatalf("target_uri = %#v", got)
}
@@ -689,6 +692,7 @@ func TestSearchSendsSessionAndSearchFilters(t *testing.T) {
if _, err := client.Search(context.Background(), "auth", &SearchOptions{
TargetURI: "resources/docs",
SessionID: "session-1",
+ SearchType: "keywords",
Since: "1d",
Until: "2026-06-18",
TimeField: "updated_at",
@@ -727,6 +731,9 @@ func TestSearchContextSendsContextOptionsAndRejectsModeOverride(t *testing.T) {
if body["session_id"] != "session-1" || body["purpose"] != "coding" {
t.Fatalf("context fields = %#v", body)
}
+ if body["search_type"] != "keywords" {
+ t.Fatalf("search_type = %#v", body["search_type"])
+ }
if body["max_tokens"] != float64(3000) || body["dedup_turns"] != float64(5) {
t.Fatalf("budget fields = %#v", body)
}
@@ -743,6 +750,7 @@ func TestSearchContextSendsContextOptionsAndRejectsModeOverride(t *testing.T) {
result, err := client.SearchContext(context.Background(), "continue refactor", &SearchContextOptions{
SessionID: "session-1",
+ SearchType: "keywords",
Purpose: "coding",
MaxTokens: Int(3000),
DedupTurns: Int(5),
diff --git a/sdk/go/retrieval.go b/sdk/go/retrieval.go
index d6ef3fe6e..6249c8712 100644
--- a/sdk/go/retrieval.go
+++ b/sdk/go/retrieval.go
@@ -71,6 +71,7 @@ func (c *Client) Search(ctx context.Context, queryText string, opts *SearchOptio
return nil, err
}
payload := map[string]any{"query": queryText}
+ setString(payload, "search_type", opts.SearchType)
if opts.TargetURI != nil {
payload["target_uri"] = normalizeTarget(opts.TargetURI)
}
@@ -110,6 +111,7 @@ func (c *Client) SearchContext(ctx context.Context, query string, opts *SearchCo
"query": query,
"mode": "context",
}
+ setString(payload, "search_type", opts.SearchType)
imageURL, err := normalizeImageInput(opts.Image)
if err != nil {
return nil, err
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 4552c4cdd..2425d6f3d 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -316,6 +316,7 @@ type FindOptions struct {
// SearchOptions controls Search.
type SearchOptions struct {
EventsTimeDecayProtection string
+ SearchType string
TargetURI any
Image string
SessionID string
@@ -339,6 +340,7 @@ type SearchOptions struct {
type SearchContextOptions struct {
Image string
SessionID string
+ SearchType string
Limit *int
NodeLimit *int
ScoreThreshold *float64
diff --git a/sdk/python/openviking_sdk/options.py b/sdk/python/openviking_sdk/options.py
index 3c0c12106..e09cfc966 100644
--- a/sdk/python/openviking_sdk/options.py
+++ b/sdk/python/openviking_sdk/options.py
@@ -34,10 +34,11 @@ class FindOptions(_ExtraOptions, total=False):
class SearchOptions(FindOptions, total=False):
- pass
+ search_type: Literal["semantic", "keywords"]
class SearchContextOptions(_ExtraOptions, total=False):
+ search_type: Literal["semantic", "keywords"]
image: Any
node_limit: int
score_threshold: float
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index 791f99af2..b012cb569 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -910,10 +910,25 @@ async def test_search_forwards_level_zero_and_omits_unset_time_filters():
assert payload["level"] == 0
assert payload["session_id"] == "s1"
assert payload["events_time_decay_protection"] == "0"
- for key in ("since", "until", "time_field"):
+ for key in ("search_type", "since", "until", "time_field"):
assert key not in payload
+async def test_search_and_search_context_forward_search_type():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ client._request = AsyncMock(return_value=object())
+ client._handle_response_data = lambda _response: {"result": {}}
+
+ await client.search("OAuth token", options={"search_type": "keywords"})
+ search_payload = client._request.await_args.kwargs["json"]
+ assert search_payload["search_type"] == "keywords"
+
+ await client.search_context("OAuth token", options={"search_type": "keywords"})
+ context_payload = client._request.await_args.kwargs["json"]
+ assert context_payload["search_type"] == "keywords"
+
+
@pytest.mark.asyncio
async def test_find_extra_forwards_unknown_fields_to_payload():
client = AsyncHTTPClient(url="http://localhost:1933")
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index d114cde5d..a7d7c11e0 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -394,6 +394,8 @@ export class OpenVikingClient {
session_id:
kind === "search" ? (options as SearchOptions).sessionId : undefined,
events_time_decay_protection: options.eventsTimeDecayProtection,
+ search_type:
+ kind === "search" ? (options as SearchOptions).searchType : undefined,
limit: options.limit,
node_limit: options.nodeLimit,
score_threshold: options.scoreThreshold,
@@ -423,6 +425,7 @@ export class OpenVikingClient {
const body = compact({
query,
mode: "context",
+ search_type: options.searchType,
image_url: imageUrl,
session_id: options.sessionId,
limit: options.limit,
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 3d65b8162..aaa332ad3 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -166,12 +166,14 @@ export interface FindOptions {
eventsTimeDecayProtection?: string | null;
extra?: JsonObject;
}
-/** Session-aware semantic retrieval options. */
+/** Session-aware retrieval options. */
export interface SearchOptions extends FindOptions {
sessionId?: string;
+ searchType?: "semantic" | "keywords";
}
/** Server-side context assembly options. */
export interface SearchContextOptions {
+ searchType?: "semantic" | "keywords";
image?: string;
sessionId?: string;
limit?: number;
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index b4ef2abeb..f224b40a8 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -109,6 +109,7 @@ describe("OpenVikingClient", () => {
await expect(
client.searchContext("continue refactor", {
sessionId: "session-1",
+ searchType: "keywords",
purpose: "coding",
maxTokens: 3000,
dedupTurns: 5,
@@ -119,6 +120,7 @@ describe("OpenVikingClient", () => {
expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toEqual({
query: "continue refactor",
mode: "context",
+ search_type: "keywords",
session_id: "session-1",
purpose: "coding",
max_tokens: 3000,
@@ -289,6 +291,23 @@ describe("OpenVikingClient", () => {
});
});
+ it("forwards the search type", async () => {
+ const fetcher = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(ok({ resources: [] }));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ fetch: fetcher,
+ });
+
+ await client.search("OAuth token", { searchType: "keywords" });
+
+ expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toEqual({
+ query: "OAuth token",
+ search_type: "keywords",
+ });
+ });
+
it("preserves explicit zero and empty retrieval options", async () => {
const fetcher = vi
.fn<typeof fetch>()
diff --git a/tests/misc/test_vikingfs_find_without_rerank.py b/tests/misc/test_vikingfs_find_without_rerank.py
index 711b4d484..448ad43b5 100644
--- a/tests/misc/test_vikingfs_find_without_rerank.py
+++ b/tests/misc/test_vikingfs_find_without_rerank.py
@@ -57,6 +57,7 @@ async def test_find_works_without_rerank_config(monkeypatch) -> None:
level,
events_time_decay_protection=None,
request_now=None,
+ search_type="semantic",
):
captured["typed_query"] = typed_query
captured["ctx"] = ctx
@@ -65,6 +66,7 @@ async def test_find_works_without_rerank_config(monkeypatch) -> None:
captured["score_threshold"] = score_threshold
captured["scope_dsl"] = scope_dsl
captured["level"] = level
+ captured["search_type"] = search_type
return QueryResult(
query=typed_query,
matched_contexts=[
@@ -105,6 +107,7 @@ async def test_find_works_without_rerank_config(monkeypatch) -> None:
assert captured["score_threshold"] == 0.2
assert captured["scope_dsl"] == {"category": "doc"}
assert captured["level"] is None
+ assert captured["search_type"] == "semantic"
fs._ensure_access.assert_called_once_with("viking://resources/docs", request_ctx)
@@ -128,6 +131,7 @@ async def test_find_accepts_image_url_without_text_query(monkeypatch) -> None:
level,
events_time_decay_protection=None,
request_now=None,
+ search_type="semantic",
):
captured["typed_query"] = typed_query
captured["mode"] = mode
diff --git a/tests/retrieve/test_hierarchical_retriever_keywords.py b/tests/retrieve/test_hierarchical_retriever_keywords.py
new file mode 100644
index 000000000..f37760f6e
--- /dev/null
+++ b/tests/retrieve/test_hierarchical_retriever_keywords.py
@@ -0,0 +1,81 @@
+import pytest
+
+from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever, RetrieverMode
+from openviking.server.identity import RequestContext, Role
+from openviking_cli.retrieve.types import TypedQuery
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class FailingEmbedder:
+ async def embed_async(self, *_args, **_kwargs):
+ raise AssertionError("keywords search must not call the embedder")
+
+
+class FixedReranker:
+ def rerank_batch(self, _query, documents):
+ return [0.9] * len(documents)
+
+
+class KeywordStorage:
+ def __init__(self):
+ self.calls = []
+
+ async def get_account_backend(self, _account_id):
+ return self
+
+ async def collection_exists(self):
+ return True
+
+ async def search_by_keywords_in_tenant(self, ctx, **kwargs):
+ self.calls.append({"ctx": ctx, **kwargs})
+ return [
+ {
+ "uri": "viking://resources/oauth.md",
+ "context_type": "resource",
+ "level": 2,
+ "abstract": "OAuth token",
+ "_score": 3.5,
+ }
+ ]
+
+
+def _ctx():
+ return RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+
+
+async def test_keywords_quick_search_skips_embedding_and_uses_keyword_recall():
+ storage = KeywordStorage()
+ retriever = HierarchicalRetriever(storage=storage, embedder=FailingEmbedder())
+
+ result = await retriever.retrieve(
+ TypedQuery("OAuth token", None, ""),
+ ctx=_ctx(),
+ limit=5,
+ mode=RetrieverMode.QUICK,
+ search_type="keywords",
+ )
+
+ assert [item.uri for item in result.matched_contexts] == ["viking://resources/oauth.md"]
+ assert storage.calls[0]["query"] == "OAuth token"
+ assert storage.calls[0]["limit"] == 5
+
+
+async def test_keywords_thinking_search_uses_global_keyword_recall_and_rerank():
+ storage = KeywordStorage()
+ retriever = HierarchicalRetriever(storage=storage, embedder=FailingEmbedder())
+ retriever._rerank_client = FixedReranker()
+
+ result = await retriever.retrieve(
+ TypedQuery("OAuth token", None, ""),
+ ctx=_ctx(),
+ limit=5,
+ mode=RetrieverMode.THINKING,
+ search_type="keywords",
+ )
+
+ assert [item.uri for item in result.matched_contexts] == ["viking://resources/oauth.md"]
+ assert len(storage.calls) == 1
+ assert storage.calls[0]["query"] == "OAuth token"
+ assert storage.calls[0]["limit"] == 10
diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.py
index be0a11cb5..36ac50d6c 100644
--- a/tests/server/test_api_search.py
+++ b/tests/server/test_api_search.py
@@ -58,6 +58,44 @@ async def test_find_basic(client_with_resource):
assert "telemetry" not in body
+async def test_search_forwards_keywords_search_type(
+ client: httpx.AsyncClient, service, monkeypatch
+):
+ captured = {}
+
+ async def fake_search(**kwargs):
+ captured.update(kwargs)
+ return FindResult(memories=[], resources=[], skills=[])
+
+ monkeypatch.setattr(service.search, "search", fake_search)
+
+ response = await client.post(
+ "/api/v1/search/search",
+ json={"query": "OAuth token", "search_type": "keywords"},
+ )
+
+ assert response.status_code == 200
+ assert captured["search_type"] == "keywords"
+
+
+ "payload",
+ [
+ {"query": "", "search_type": "keywords"},
+ {
+ "query": "OAuth token",
+ "image_url": "https://example.com/image.png",
+ "search_type": "keywords",
+ },
+ ],
+)
+async def test_search_rejects_invalid_keywords_inputs(client: httpx.AsyncClient, payload):
+ response = await client.post("/api/v1/search/search", json=payload)
+
+ assert response.status_code == 400
+ assert response.json()["error"]["code"] == "INVALID_ARGUMENT"
+
+
@pytest.mark.parametrize("endpoint", ["/api/v1/search/find", "/api/v1/search/search"])
async def test_search_endpoints_inline_visible_content_when_requested(
client: httpx.AsyncClient, service, monkeypatch, endpoint: str
diff --git a/tests/server/test_api_search_context.py b/tests/server/test_api_search_context.py
index e5f7670fa..3cfeb0f05 100644
--- a/tests/server/test_api_search_context.py
+++ b/tests/server/test_api_search_context.py
@@ -95,6 +95,51 @@ async def test_context_mode_quotas_use_category_ownership_roots(
assert skill_targets == [["viking://user/default/skills", "viking://agent/skills"]]
+async def test_context_mode_forwards_keywords_to_every_internal_search(
+ client: httpx.AsyncClient,
+ service,
+ monkeypatch,
+):
+ search_types = []
+ capability_checks = []
+
+ async def fake_ensure_keywords_search_supported(ctx):
+ capability_checks.append(ctx)
+
+ async def fake_find(**kwargs):
+ search_types.append(("find", kwargs["search_type"]))
+ return _FakeFindResult()
+
+ async def fake_find_skills(**kwargs):
+ search_types.append(("find_skills", kwargs["search_type"]))
+ return _FakeFindResult()
+
+ monkeypatch.setattr(service.search, "find", fake_find)
+ monkeypatch.setattr(service.search, "find_skills", fake_find_skills)
+ monkeypatch.setattr(
+ service.search,
+ "ensure_keywords_search_supported",
+ fake_ensure_keywords_search_supported,
+ )
+
+ response = await client.post(
+ "/api/v1/search/search",
+ json={
+ "query": "OAuth token",
+ "search_type": "keywords",
+ "mode": "context",
+ "purpose": "coding",
+ "peer_scope": "actor",
+ },
+ )
+
+ assert response.status_code == 200
+ assert search_types
+ assert {search_type for _, search_type in search_types} == {"keywords"}
+ assert {method for method, _ in search_types} == {"find", "find_skills"}
+ assert len(capability_checks) == 1
+
+
async def test_coding_purpose_searches_all_domains_and_actor_resource(
client: httpx.AsyncClient,
service,
diff --git a/tests/server/test_mcp_search_modes.py b/tests/server/test_mcp_search_modes.py
index 38c847d2d..6b47fc1fd 100644
--- a/tests/server/test_mcp_search_modes.py
+++ b/tests/server/test_mcp_search_modes.py
@@ -102,6 +102,14 @@ async def test_list_mode_is_unchanged_without_context_only_arguments():
assert not set(forwarded) & set(CONTEXT_ONLY_ARGS)
+async def test_list_mode_forwards_keywords_search_type():
+ with pytest.raises(_SearchCalled) as excinfo:
+ await mcp_endpoint.search(query="anything", search_type="keywords")
+
+ assert excinfo.value.kwargs["search_type"] == "keywords"
+
+
@pytest.mark.asyncio
async def test_context_mode_still_accepts_them():
# The guard is list-mode only; reaching assemble_context (which this stub service
diff --git a/tests/storage/mock_backend.py b/tests/storage/mock_backend.py
index 07e28d50f..7dd67d919 100644
--- a/tests/storage/mock_backend.py
+++ b/tests/storage/mock_backend.py
@@ -110,6 +110,8 @@ class MockCollection(ICollection):
offset: int = 0,
filters: Optional[Dict[str, Any]] = None,
output_fields: Optional[List[str]] = None,
+ mode: Optional[str] = None,
+ fields: Optional[List[str]] = None,
) -> SearchResult:
raise NotImplementedError("MockCollection.search_by_keywords is not supported")
diff --git a/tests/storage/test_collection_schemas.py b/tests/storage/test_collection_schemas.py
index 78ef455fb..7a6a1291f 100644
--- a/tests/storage/test_collection_schemas.py
+++ b/tests/storage/test_collection_schemas.py
@@ -34,6 +34,7 @@ from openviking.storage.queuefs.embedding_msg import EmbeddingMsg
from openviking.storage.queuefs.process_result import ProcessOutcome
from openviking.storage.vector_ids import vector_record_id
from openviking.storage.vectordb import engine as vectordb_engine
+from openviking.storage.vectordb.collection.collection import Collection
from openviking.storage.vectordb.collection.result import UpdateResult, UpsertDataResult
from openviking.storage.vectordb.collection.vikingdb_clients import VikingDBClient
from openviking.storage.vectordb.collection.vikingdb_collection import VikingDBCollection
@@ -1470,6 +1471,27 @@ def test_private_vikingdb_collection_raises_on_data_api_error(monkeypatch):
assert exc_info.value.action == "/api/vikingdb/data/upsert"
+def test_private_vikingdb_collection_get_meta_data_raises_in_strict_mode(monkeypatch):
+ class _Response:
+ status_code = 503
+ text = '{"code":"InternalError","message":"service unavailable"}'
+
+ def json(self):
+ return {"code": "InternalError", "message": "service unavailable"}
+
+ collection = VikingDBCollection(
+ host="https://vikingdb.example.com",
+ meta_data={"ProjectName": "default", "CollectionName": "context"},
+ )
+ monkeypatch.setattr(collection.client, "do_req", lambda *args, **kwargs: _Response())
+
+ with pytest.raises(VikingDBException) as exc_info:
+ Collection(collection).get_meta_data(raise_on_error=True)
+
+ assert exc_info.value.status_code == 503
+ assert exc_info.value.retryable is True
+
+
def test_private_vikingdb_collection_marks_server_error_retryable(monkeypatch):
class _Response:
status_code = 503
@@ -1535,7 +1557,7 @@ def _exercise_fetch_and_search_apis(collection):
collection.search_by_id("default", "rec-1")
collection.search_by_multimodal("default", text="hello")
collection.search_by_random("default")
- collection.search_by_keywords("default", query="hello")
+ collection.search_by_keywords("default", query="hello", mode="bm25", fields=["content"])
collection.search_by_scalar("default", field="updated_at")
@@ -1564,6 +1586,10 @@ def test_volcengine_api_key_collection_ignores_unknown_fields_on_fetch_and_searc
"/api/vikingdb/data/search/keywords",
"/api/vikingdb/data/search/scalar",
]
+ keyword_payload = next(data for path, data in calls if path.endswith("/keywords"))
+ assert keyword_payload["query"] == "hello"
+ assert keyword_payload["mode"] == "bm25"
+ assert keyword_payload["fields"] == ["content"]
assert all(data["ignore_unknown_fields"] is True for _, data in calls)
diff --git a/tests/storage/test_viking_fs_grep.py b/tests/storage/test_viking_fs_grep.py
index ef754a367..c57ed0d1f 100644
--- a/tests/storage/test_viking_fs_grep.py
+++ b/tests/storage/test_viking_fs_grep.py
@@ -49,6 +49,56 @@ class _KeywordFailingButTagFilterWorkingStore:
return [{"uri": "viking://resources/tagged.md"}]
+class _FulltextMetaFailureStore:
+ def __init__(self):
+ self.calls = 0
+ self.backend = type(
+ "Backend",
+ (),
+ {
+ "_mode": "vikingdb",
+ "collection_name": "context",
+ "index_name": "default",
+ },
+ )()
+
+ async def get_account_backend(self, _account_id):
+ return self.backend
+
+ async def get_collection_meta(self, **_kwargs):
+ self.calls += 1
+ raise RuntimeError("metadata unavailable")
+
+
+class _SequencedFulltextMetaStore:
+ def __init__(self, metadata):
+ self.backend = type(
+ "Backend",
+ (),
+ {
+ "_mode": "vikingdb",
+ "collection_name": "context",
+ "index_name": "default",
+ },
+ )()
+ self.metadata = iter(metadata)
+ self.calls = 0
+
+ async def get_account_backend(self, _account_id):
+ return self.backend
+
+ async def get_collection_meta(self, **_kwargs):
+ self.calls += 1
+ return next(self.metadata)
+
+
+def _fulltext_meta(enabled):
+ return {
+ "Fields": [{"FieldName": "content", "FieldType": "text"}],
+ "FullText": [{"Field": "content"}] if enabled else [],
+ }
+
+
@pytest.fixture
def fs(monkeypatch):
viking_fs = VikingFS(agfs=_DummyAgfs())
@@ -289,6 +339,70 @@ def test_grep_config_default_switch_to_remote_threshold_is_10000():
assert GrepConfig().switch_to_remote_threshold == 10000
+async def test_fulltext_probe_keeps_grep_fallback_on_metadata_failure():
+ fs = VikingFS(agfs=_DummyAgfs())
+ ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+ store = _FulltextMetaFailureStore()
+
+ assert await fs._collection_has_fulltext(store, ctx) is False
+ assert await fs._collection_has_fulltext(store, ctx) is False
+ assert store.calls == 2
+
+
+async def test_fulltext_probe_propagates_metadata_failure_for_strict_callers():
+ fs = VikingFS(agfs=_DummyAgfs())
+ ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+
+ with pytest.raises(RuntimeError, match="metadata unavailable"):
+ await fs._collection_has_fulltext(
+ _FulltextMetaFailureStore(),
+ ctx,
+ supported_modes=("vikingdb",),
+ raise_on_error=True,
+ )
+
+
+async def test_fulltext_probe_caches_supported_collection_without_expiry(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+ ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+ store = _SequencedFulltextMetaStore([_fulltext_meta(True), _fulltext_meta(False)])
+ monkeypatch.setattr(grep_module.time, "monotonic", lambda: 10_000_000)
+
+ assert await fs._collection_has_fulltext(store, ctx) is True
+ assert await fs._collection_has_fulltext(store, ctx) is True
+ assert store.calls == 1
+
+
+async def test_fulltext_probe_rechecks_unsupported_collection_after_one_minute(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+ ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+ store = _SequencedFulltextMetaStore([_fulltext_meta(False), _fulltext_meta(True)])
+ now = 1000.0
+ monkeypatch.setattr(grep_module.time, "monotonic", lambda: now)
+
+ assert await fs._collection_has_fulltext(store, ctx) is False
+ now = 1059.0
+ assert await fs._collection_has_fulltext(store, ctx) is False
+ now = 1060.0
+ assert await fs._collection_has_fulltext(store, ctx) is True
+ assert store.calls == 2
+
+
+async def test_fulltext_probe_does_not_cache_inconclusive_metadata():
+ fs = VikingFS(agfs=_DummyAgfs())
+ ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+ store = _SequencedFulltextMetaStore([{}, _fulltext_meta(True)])
+
+ assert await fs._collection_has_fulltext(store, ctx) is False
+ assert await fs._collection_has_fulltext(store, ctx) is True
+ assert store.calls == 2
+
+
@pytest.mark.asyncio
async def test_grep_without_config_uses_documented_remote_threshold(monkeypatch):
fs = VikingFS(agfs=_DummyAgfs())
diff --git a/tests/storage/test_viking_vector_scope_filter.py b/tests/storage/test_viking_vector_scope_filter.py
index aa551e4f5..e3fd9e40a 100644
--- a/tests/storage/test_viking_vector_scope_filter.py
+++ b/tests/storage/test_viking_vector_scope_filter.py
@@ -178,6 +178,41 @@ def test_mixed_visible_and_outside_targets_keep_original_tenant_filter():
)
[email protected]("acl_enabled", [False, True])
+async def test_keywords_tenant_search_reuses_scope_filter_and_sets_bm25_fields(acl_enabled):
+ ctx = _ctx()
+ backend = object.__new__(VikingVectorIndexBackend)
+ backend.acl_manager = None
+ backend._acl_enabled = AsyncMock(return_value=acl_enabled)
+ tenant_backend = SimpleNamespace(search_by_keywords=AsyncMock(return_value=[]))
+ backend._get_backend_for_context = AsyncMock(return_value=tenant_backend)
+
+ await backend.search_by_keywords_in_tenant(
+ ctx=ctx,
+ query="OAuth token",
+ context_type="resource",
+ target_directories=["viking://resources/docs"],
+ extra_filter=Eq("status", "ready"),
+ level=[2],
+ limit=5,
+ )
+
+ kwargs = tenant_backend.search_by_keywords.await_args.kwargs
+ assert kwargs["query"] == "OAuth token"
+ assert kwargs["mode"] == "bm25"
+ assert kwargs["fields"] == ["content"]
+ assert kwargs["filter"] == _build(
+ ctx,
+ ["viking://resources/docs"],
+ extra_filter=Eq("status", "ready"),
+ level=[2],
+ acl_enabled=acl_enabled,
+ )
+ backend._acl_enabled.assert_awaited_once_with(ctx)
+ backend._get_backend_for_context.assert_awaited_once_with(ctx)
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("legacy_mode", [{}, {"acl_mode": None}, {"acl_mode": "none"}])
async def test_tenant_search_enforces_visible_roots_and_shared_acl(
diff --git a/tests/storage/test_volcengine_clients.py b/tests/storage/test_volcengine_clients.py
index c67446115..f83a974b2 100644
--- a/tests/storage/test_volcengine_clients.py
+++ b/tests/storage/test_volcengine_clients.py
@@ -2,6 +2,7 @@ import pytest
import requests
from volcengine.base.Request import Request
+from openviking.storage.errors import ConnectionError
from openviking.storage.vectordb.collection.collection import Collection
from openviking.storage.vectordb.collection.volcengine_clients import (
ClientForConsoleApi,
@@ -234,6 +235,29 @@ def test_volcengine_collection_get_meta_data_returns_empty_on_signature_error(mo
assert collection.get_meta_data() == {}
+def test_volcengine_collection_get_meta_data_raises_in_strict_mode(monkeypatch):
+ from openviking.storage.vectordb.collection.collection import Collection
+
+ class _Response:
+ status_code = 503
+ text = "service unavailable"
+
+ @staticmethod
+ def json():
+ return {"ResponseMetadata": {"Error": {"Code": "InternalError"}}}
+
+ collection = VolcengineCollection(
+ ak="test-ak",
+ sk="test-sk",
+ region="cn-beijing",
+ meta_data={"ProjectName": "default", "CollectionName": "context"},
+ )
+ monkeypatch.setattr(collection.console_client, "do_req", lambda *args, **kwargs: _Response())
+
+ with pytest.raises(ConnectionError, match="service unavailable"):
+ Collection(collection).get_meta_data(raise_on_error=True)
+
+
def test_volcengine_collection_get_meta_data_returns_empty_on_collection_not_found(
monkeypatch,
):
diff --git a/tests/unit/test_find_skills_entrypoint.py b/tests/unit/test_find_skills_entrypoint.py
index bc7936106..b327db006 100644
--- a/tests/unit/test_find_skills_entrypoint.py
+++ b/tests/unit/test_find_skills_entrypoint.py
@@ -43,7 +43,7 @@ def _service(rerank_config):
fs = SimpleNamespace(
_ensure_retrieval_scope=ensure_scope,
_get_vector_store=lambda: object(),
- _get_embedder=lambda: object(),
+ _get_embedder=lambda _ctx: object(),
rerank_config=rerank_config,
retrieval_config=None,
)
@@ -67,6 +67,17 @@ async def test_find_skills_forwards_the_filter_as_the_retrieval_scope(seen):
assert seen["retrieve"]["scope_dsl"] == TAG_FILTER
+async def test_find_skills_forwards_keywords_search_type(seen):
+ await _service(None).find_skills(
+ query="deploy",
+ ctx=_ctx(),
+ target_uri=SKILLS,
+ search_type="keywords",
+ )
+
+ assert seen["retrieve"]["search_type"] == "keywords"
+
+
@pytest.mark.parametrize("query", ["", " "])
async def test_find_skills_needs_a_query_even_with_a_filter(seen, query):
"""It embeds the query, so a filter cannot stand in the way it can on find."""
diff --git a/tests/unit/test_search_service_keywords.py b/tests/unit/test_search_service_keywords.py
new file mode 100644
index 000000000..97a63ecdc
--- /dev/null
+++ b/tests/unit/test_search_service_keywords.py
@@ -0,0 +1,33 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role
+from openviking.service.search_service import SearchService
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx():
+ return RequestContext(user=UserIdentifier("account", "user"), role=Role.USER)
+
+
+async def test_keywords_capability_check_propagates_metadata_failures():
+ error = RuntimeError("metadata unavailable")
+ check = AsyncMock(side_effect=error)
+ vector_store = object()
+ fs = SimpleNamespace(
+ _get_vector_store=lambda: vector_store,
+ _collection_has_fulltext=check,
+ )
+
+ with pytest.raises(RuntimeError, match="metadata unavailable"):
+ await SearchService(fs).ensure_keywords_search_supported(_ctx())
+
+ check.assert_awaited_once_with(
+ vector_store,
+ _ctx(),
+ supported_modes=("volcengine", "vikingdb"),
+ raise_on_error=True,
+ )
diff --git a/tests/unit/test_search_type_import_boundary.py b/tests/unit/test_search_type_import_boundary.py
new file mode 100644
index 000000000..99db0ebfd
--- /dev/null
+++ b/tests/unit/test_search_type_import_boundary.py
@@ -0,0 +1,18 @@
+import os
+import subprocess
+import sys
+
+
+def test_viking_fs_imports_in_fresh_process(tmp_path):
+ env = os.environ.copy()
+ env["OPENVIKING_CONFIG_FILE"] = str(tmp_path / "missing-ov.conf")
+
+ result = subprocess.run(
+ [sys.executable, "-c", "from openviking.storage.viking_fs import VikingFS"],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ env=env,
+ )
+
+ assert result.returncode == 0, result.stderr