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
feat(search): add the keywords search type (#5456)
ByteDanceLiuYang0c650c3830af
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 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.rsindex 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.rsindex 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.rsindex 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.mdindex 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 0diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex 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 0diff --git a/openviking/core/retrieval_types.py b/openviking/core/retrieval_types.pynew file mode 100644index 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.pyindex 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, Tuplefrom openviking.core.namespace import AGENT_SKILLS_ROOT, canonical_user_rootfrom openviking.core.retrieval_targets import default_target_directories+from openviking.core.retrieval_types import SearchTypefrom 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.pyindex 686db2149..1372adc1d 100644--- a/openviking/retrieve/context_assembler/params.py+++ b/openviking/retrieve/context_assembler/params.py@@ -7,6 +7,8 @@ from __future__ import annotationsfrom dataclasses import dataclass, fieldfrom 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] = Nonelimit: int = DEFAULT_LIMITscore_threshold: Optional[float] = Nonediff --git a/openviking/retrieve/context_assembler/pipeline.py b/openviking/retrieve/context_assembler/pipeline.pyindex 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.pyindex 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, Optionalfrom openviking.core.context import ContextLevelfrom openviking.core.retrieval_targets import default_target_directories+from openviking.core.retrieval_types import SearchTypefrom openviking.models.embedder.base import EmbedResult, embed_compatfrom openviking.models.rerank import RerankClientfrom 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 callsquery_vector = Nonesparse_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 limitwith 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.pyindex 9dd3d4cd9..c69754f5c 100644--- a/openviking/retrieve/skill_package_retriever.py+++ b/openviking/retrieve/skill_package_retriever.py@@ -6,6 +6,7 @@ import mathimport timefrom typing import Optional+from openviking.core.retrieval_types import SearchTypefrom openviking.models.embedder.base import embed_compatfrom openviking.retrieve.hierarchical_retriever import HierarchicalRetrieverfrom 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.pyindex 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, Sendfrom openviking.core.path_variables import resolve_path_variablesfrom openviking.core.retrieval_targets import default_target_directories+from openviking.core.retrieval_types import SearchTypefrom 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 excservice = 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.pyindex 8f4a8a4bc..49d448f3a 100644--- a/openviking/server/routers/search.py+++ b/openviking/server/routers/search.py@@ -11,6 +11,7 @@ from fastapi import Response as FastAPIResponsefrom pydantic import BaseModel, ConfigDict, Field, model_validatorfrom openviking.core.path_variables import resolve_path_variables+from openviking.core.retrieval_types import SearchTypefrom openviking.core.uri_validation import validate_request_viking_urifrom openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundErrorfrom 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] = Nonetarget_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.pyindex 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 SearchTypefrom openviking.server.identity import RequestContextfrom openviking.storage.viking_fs import VikingFSfrom 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 Truereturn 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 CollectionSchemasschema = 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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__.pyindex 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_resolverself._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.pyindex 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 PermissionDeniedErrorfrom openviking_cli.utils.config.grep_config import GrepEngine_GREP_LS_PAGE_SIZE = 1000+_FULLTEXT_UNSUPPORTED_CACHE_TTL = 60.0def _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 = Noneif 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 resultexcept 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,+ )+ raiselogger.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.pyindex 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, Unionfrom openviking.core.context import ContextLevelfrom openviking.core.retrieval_targets import resolve_retrieval_targets+from openviking.core.retrieval_types import SearchTypefrom openviking.server.error_mapping import is_not_found_error, map_exceptionfrom openviking.server.identity import RequestContextfrom 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.pyindex 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 = Trueself._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_operationasync 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.pyindex 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.goindex 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.goindex 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 *SearchOptioreturn 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, errdiff --git a/sdk/go/types.go b/sdk/go/types.goindex 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 stringTargetURI anyImage stringSessionID string@@ -339,6 +340,7 @@ type SearchOptions struct {type SearchContextOptions struct {Image stringSessionID string+ SearchType stringLimit *intNodeLimit *intScoreThreshold *float64diff --git a/sdk/python/openviking_sdk/options.py b/sdk/python/openviking_sdk/options.pyindex 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: Anynode_limit: intscore_threshold: floatdiff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.pyindex 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"] == 0assert 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.asyncioasync 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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_querycaptured["ctx"] = ctx@@ -65,6 +66,7 @@ async def test_find_works_without_rerank_config(monkeypatch) -> None:captured["score_threshold"] = score_thresholdcaptured["scope_dsl"] = scope_dslcaptured["level"] = level+ captured["search_type"] = search_typereturn 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.2assert 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_querycaptured["mode"] = modediff --git a/tests/retrieve/test_hierarchical_retriever_keywords.py b/tests/retrieve/test_hierarchical_retriever_keywords.pynew file mode 100644index 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"] == 10diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.pyindex 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: strdiff --git a/tests/server/test_api_search_context.py b/tests/server/test_api_search_context.pyindex 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.pyindex 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.asyncioasync def test_context_mode_still_accepts_them():# The guard is list-mode only; reaching assemble_context (which this stub servicediff --git a/tests/storage/mock_backend.py b/tests/storage/mock_backend.pyindex 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.pyindex 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 EmbeddingMsgfrom openviking.storage.queuefs.process_result import ProcessOutcomefrom openviking.storage.vector_ids import vector_record_idfrom openviking.storage.vectordb import engine as vectordb_engine+from openviking.storage.vectordb.collection.collection import Collectionfrom openviking.storage.vectordb.collection.result import UpdateResult, UpsertDataResultfrom openviking.storage.vectordb.collection.vikingdb_clients import VikingDBClientfrom 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.pyindex 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.fixturedef 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.asyncioasync 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.pyindex 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.pyindex c67446115..f83a974b2 100644--- a/tests/storage/test_volcengine_clients.py+++ b/tests/storage/test_volcengine_clients.py@@ -2,6 +2,7 @@ import pytestimport requestsfrom volcengine.base.Request import Request+from openviking.storage.errors import ConnectionErrorfrom openviking.storage.vectordb.collection.collection import Collectionfrom openviking.storage.vectordb.collection.volcengine_clients import (ClientForConsoleApi,@@ -234,6 +235,29 @@ def test_volcengine_collection_get_meta_data_returns_empty_on_signature_error(moassert 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.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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