Skip to content

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

Feat/add resource tags (#3560)

Jiahui Zhou34b5a8897151
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 4b5c7cbea..fe5a58d9a 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -38,6 +38,17 @@ fn compact_request_body(body: &mut Value) {
});
}
+fn add_resource_tag_fields(body: &mut Value, tags: &[String], tag_mode: &str) {
+ if tags.is_empty() {
+ return;
+ }
+ let obj = body
+ .as_object_mut()
+ .expect("add_resource request body must be an object");
+ obj.insert("tags".to_string(), serde_json::json!(tags));
+ obj.insert("tag_mode".to_string(), serde_json::json!(tag_mode));
+}
+
fn normalize_image_input(image: Option<String>) -> Result<Option<String>> {
let Some(value) = image else {
return Ok(None);
@@ -696,6 +707,8 @@ impl HttpClient {
watch_interval: f64,
processing_mode: String,
resource_args: Option<Map<String, Value>>,
+ tags: Vec<String>,
+ tag_mode: String,
show_progress: bool,
verbose: bool,
) -> Result<serde_json::Value> {
@@ -715,6 +728,7 @@ impl HttpClient {
let build_body = |base: serde_json::Value| {
let mut body = base;
+ add_resource_tag_fields(&mut body, &tags, &tag_mode);
if create_parent {
body.as_object_mut()
.expect("add_resource request body must be an object")
@@ -1855,6 +1869,28 @@ mod tests {
assert_eq!(body["processing_mode"], "vectors_only");
}
+ #[test]
+ fn add_resource_tag_fields_adds_tags_and_tag_mode() {
+ let mut body = json!({"path": "https://example.com/demo.md"});
+ let tags = vec!["team=search".to_string(), "env=test".to_string()];
+
+ super::add_resource_tag_fields(&mut body, &tags, "append");
+
+ assert_eq!(body["tags"], json!(["team=search", "env=test"]));
+ assert_eq!(body["tag_mode"], json!("append"));
+ }
+
+ #[test]
+ fn add_resource_tag_fields_omits_empty_tags_for_compatibility() {
+ let mut body = json!({"path": "https://example.com/demo.md"});
+
+ super::add_resource_tag_fields(&mut body, &[], "replace");
+
+ let obj = body.as_object().unwrap();
+ assert!(!obj.contains_key("tags"));
+ assert!(!obj.contains_key("tag_mode"));
+ }
+
#[test]
fn timeout_config_calculation() {
let config = TimeoutConfig::new(60, 2.0);
diff --git a/crates/ov_cli/src/commands/resources.rs b/crates/ov_cli/src/commands/resources.rs
index ccc777c0f..415eca5ff 100644
--- a/crates/ov_cli/src/commands/resources.rs
+++ b/crates/ov_cli/src/commands/resources.rs
@@ -21,6 +21,8 @@ pub async fn add_resource(
watch_interval: f64,
processing_mode: String,
resource_args: Option<Map<String, Value>>,
+ tags: Vec<String>,
+ tag_mode: String,
format: OutputFormat,
compact: bool,
show_progress: bool,
@@ -44,6 +46,8 @@ pub async fn add_resource(
watch_interval,
processing_mode,
resource_args,
+ tags,
+ tag_mode,
show_progress,
verbose,
)
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 2947d5e11..3d483e3d2 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -30,6 +30,8 @@ pub async fn handle_add_resource(
watch_interval: f64,
processing_mode: String,
resource_args: Option<String>,
+ tags: Vec<String>,
+ tag_mode: String,
ctx: CliContext,
) -> Result<()> {
let is_url =
@@ -111,6 +113,8 @@ pub async fn handle_add_resource(
watch_interval,
processing_mode,
add_resource_args,
+ tags,
+ tag_mode,
ctx.output_format,
ctx.compact,
ctx.should_show_progress(),
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index bd0d32bb9..ea8b7cf43 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -360,6 +360,17 @@ enum Commands {
/// Parser-specific import options, e.g. --args feishu_access_token:u-xxx
#[arg(long = "args")]
resource_args: Option<String>,
+ /// Explicit k=v retrieval tag to apply after import. Can be repeated.
+ #[arg(long = "tag", value_name = "k=v", help_heading = "Common options")]
+ tags: Vec<String>,
+ /// Tag update mode when --tag is provided
+ #[arg(
+ long = "tag-mode",
+ default_value = "replace",
+ value_parser = ["replace", "append"],
+ help_heading = "Common options"
+ )]
+ tag_mode: String,
#[command(flatten)]
upload_options: UploadCliOptions,
},
@@ -2802,6 +2813,8 @@ async fn main() {
watch_interval,
processing_mode,
resource_args,
+ tags,
+ tag_mode,
upload_options,
} => {
let ctx =
@@ -2823,6 +2836,8 @@ async fn main() {
watch_interval,
processing_mode,
resource_args,
+ tags,
+ tag_mode,
ctx,
)
.await
@@ -3952,6 +3967,17 @@ mod tests {
assert!(help.contains("--verbose"));
}
+ #[test]
+ fn cli_add_resource_help_shows_tag_flags() {
+ let err = Cli::command()
+ .try_get_matches_from(["ov", "add-resource", "--help"])
+ .expect_err("help should exit through clap error");
+ let help = err.to_string();
+
+ assert!(help.contains("--tag"));
+ assert!(help.contains("--tag-mode"));
+ }
+
#[test]
fn cli_add_skill_help_shows_upload_flags() {
let err = Cli::command()
@@ -4010,6 +4036,30 @@ mod tests {
assert!(Cli::try_parse_from(["ov", "skills", "update", "--progress"]).is_err());
}
+ #[test]
+ fn cli_parses_add_resource_tags() {
+ let cli = Cli::try_parse_from([
+ "ov",
+ "add-resource",
+ "./README.md",
+ "--tag",
+ "team=search",
+ "--tag",
+ "env=test",
+ "--tag-mode",
+ "append",
+ ])
+ .expect("add-resource tag flags should parse");
+
+ match cli.command {
+ Commands::AddResource { tags, tag_mode, .. } => {
+ assert_eq!(tags, vec!["team=search", "env=test"]);
+ assert_eq!(tag_mode, "append");
+ }
+ _ => panic!("expected add-resource command"),
+ }
+ }
+
#[test]
fn cli_parses_skills_command_group() {
let list = Cli::try_parse_from(["ov", "skills", "list", "--limit", "25"])
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index f2338a5e0..e54daba18 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -174,6 +174,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| args | object | 否 | `{}` | 传给特定 parser/accessor 的导入参数。例如 `args.site=true/false` 强制/禁用整站(sitemap/RSS)导入,`args.max_pages` 等可覆盖 `webfeed` 配置;递归网页爬虫支持 `args.depth`、`args.max_pages`、`args.include_paths`、`args.exclude_paths`、`args.allow_external_links`、`args.skip_download_links`;飞书用户 token 导入传 `args.feishu_access_token`。`path`、`to`、`watch_interval`、`include`、`exclude` 等 `add_resource` 核心字段不能放入 `args` |
| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 为 URL/sitemap/RSS 等可重新读取的来源创建任务;通过 `temp_file_id` 上传的内容是一次性快照,变化后需重新添加。≤0 取消任务;显式 `to` 优先,否则绑定本次导入的 `root_uri` |
| processing_mode | string | 否 | `semantic_and_vectors` | 入库后的处理模式。`semantic_and_vectors` 是默认流程:生成语义产物(`.abstract.md`、`.overview.md`)并生成向量。`vectors_only` 跳过语义理解/VLM 总结,只对当前资源文件生成向量 |
+| tags | string[] | 否 | None | 导入时写入向量检索记录的显式检索标签,格式必须是 `k=v`,例如 `["team=search", "env=test"]`。搜索接口可用同名 `tags` 参数过滤召回 |
+| tag_mode | string | 否 | `"replace"` | `tags` 的写入模式,可选 `replace` 或 `append`。导入新资源时会随本次生成的每条向量记录写入;不会在完成后额外调用 `set_tags`,响应也不返回 `tags_result` |
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
**补充说明**:
@@ -182,6 +184,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
- 资源目标可以使用公共 `viking://resources/...`、当前用户短写 `viking://user/resources/...`、显式用户 `viking://user/{user_id}/resources/...`,或 peer 级 `viking://user/{user_id}/peers/{peer_id}/resources/...`。当前用户短写会按请求身份 canonicalize。
- `user_id` 和 `peer_id` 路径片段必须是安全的单段标识,例如 `alice` 或 `web-visitor-alice`。包含路径分隔符、`.`、`..`、`:` 或 `+` 的值会被拒绝。
- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
+- `tags` 会在资源解析后、向量记录写入时同步写入底层向量库。`add_resource(tags=...)` 不返回 `tags_result`;需要验证时,可在 `/api/v1/search/find` 或 `/api/v1/search/search` 中传相同 `tags` 过滤召回。
- 只有 Git 仓库来源在 `wait=false` 时使用完整后台导入;OpenViking 会先完成仓库 preflight 和目标规划,再返回 `task_id`。
- `reason` 触发的记忆生成复用 `session.commit` 的抽取链路,只使用 `reason`、资源 URI、可用的资源名称和目录摘要,不会读取或展开完整资源正文;系统会写入 `entities`、`events`、`preferences` 等已有记忆类型,不创建独立的资源记忆目录。
- 删除资源时,系统会在删除前扫描本次上下文对应的 self 或 peer 记忆中的 `resource_refs`,清理对应资源 URI 和由该 `reason` 引入的内容,并重新刷新相关记忆的语义索引。
@@ -266,6 +269,18 @@ curl -X POST http://localhost:1933/api/v1/resources \
\"create_parent\": true
}"
+# 导入时设置检索标签;标签随本次生成的向量记录写入,可用于 search/find 过滤
+curl -X POST http://localhost:1933/api/v1/resources \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d "{
+ \"temp_file_id\": \"$TEMP_FILE_ID\",
+ \"to\": \"viking://resources/tagged-guide.md\",
+ \"wait\": true,
+ \"tags\": [\"team=search\", \"env=test\"],
+ \"tag_mode\": \"replace\"
+ }"
+
# 使用一次性用户 access token 添加飞书文档
curl -X POST http://localhost:1933/api/v1/resources \
-H "Content-Type: application/json" \
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 19b75be32..f0c07d4d9 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -330,6 +330,8 @@ class AsyncOpenViking:
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
processing_mode: str = "semantic_and_vectors",
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
**kwargs,
) -> Dict[str, Any]:
"""
@@ -372,6 +374,8 @@ class AsyncOpenViking:
telemetry=telemetry,
watch_interval=watch_interval,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
**kwargs,
)
diff --git a/openviking/client/local.py b/openviking/client/local.py
index 2232fe9a2..abe51e488 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -139,6 +139,8 @@ class LocalClient(BaseClient):
watch_interval: float = 0,
args: Optional[Dict[str, Any]] = None,
processing_mode: str = "semantic_and_vectors",
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
**kwargs,
) -> Dict[str, Any]:
"""Add resource to OpenViking."""
@@ -162,6 +164,8 @@ class LocalClient(BaseClient):
processing_mode=processing_mode,
watch_interval=watch_interval,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
**kwargs,
),
)
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index f9650f661..147bde061 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -553,6 +553,8 @@ async def add_resource(
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
to: str = "",
parent: str = "",
+ tags: Optional[list[str]] = None,
+ tag_mode: str = "replace",
args: Optional[dict[str, Any]] = None,
) -> str:
"""Add a resource to OpenViking. Asynchronous — processing happens in the background.
@@ -578,6 +580,8 @@ async def add_resource(
Leave empty to derive a URI from the source.
parent: Parent URI under viking://resources/ for remote imports. Mutually exclusive
with ``to``.
+ tags: Optional explicit k=v retrieval tags to apply after ingestion.
+ tag_mode: Tag update mode, "replace" or "append". Defaults to "replace".
args: Parser-specific options, e.g. {"feishu_access_token": "..."} for Feishu imports,
or {"site": true} for whole-site ingestion.
"""
@@ -608,6 +612,8 @@ async def add_resource(
reason=description,
args=args,
processing_mode=processing_mode,
+ tags=tags,
+ tag_mode=tag_mode,
)
except (PermissionDeniedError, InvalidArgumentError) as exc:
return f"Error: {exc}"
@@ -655,6 +661,8 @@ async def add_resource(
processing_mode=processing_mode,
enforce_public_remote_targets=True,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
)
except Exception as exc:
return f"Error adding resource: {exc}"
@@ -696,6 +704,8 @@ async def add_resource(
reason=description,
actor_peer_id=ctx.actor_peer_id or "",
processing_mode=processing_mode,
+ tags=tags,
+ tag_mode=tag_mode,
)
base_url, url_source = _resolve_public_base_url()
upload_url = f"{base_url}/api/v1/resources/temp_upload?token={quote(token, safe='')}"
diff --git a/openviking/server/resource_ingest.py b/openviking/server/resource_ingest.py
index 267bfc0b1..a8b60e240 100644
--- a/openviking/server/resource_ingest.py
+++ b/openviking/server/resource_ingest.py
@@ -27,6 +27,8 @@ async def ingest_temp_upload(
reason: str = "",
args: Optional[dict[str, Any]] = None,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ tags: Optional[list[str]] = None,
+ tag_mode: str = "replace",
) -> dict[str, Any]:
"""Resolve a temp upload and ingest it as a resource; return the raw add_resource result.
@@ -53,6 +55,8 @@ async def ingest_temp_upload(
allow_local_path_resolution=True,
enforce_public_remote_targets=True,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
)
except Exception:
await store.mark_failed(resolved, ctx)
diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.py
index ed73f8fab..4376e113c 100644
--- a/openviking/server/routers/resources.py
+++ b/openviking/server/routers/resources.py
@@ -87,6 +87,8 @@ class AddResourceRequest(BaseModel):
telemetry: TelemetryRequest = False
watch_interval: float = 0
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
+ tags: Optional[list[str]] = None
+ tag_mode: str = "replace"
@model_validator(mode="after")
def check_path_or_temp_file_id(self):
@@ -156,6 +158,8 @@ async def temp_upload(
to=signed.to,
reason=signed.reason,
processing_mode=signed.processing_mode,
+ tags=signed.tags,
+ tag_mode=signed.tag_mode,
)
try:
@@ -191,6 +195,14 @@ async def add_resource(
resolved = None
store = None
if request.temp_file_id:
+ if request.watch_interval > 0:
+ raise InvalidArgumentError(
+ "watch_interval > 0 is not supported for uploaded content: an "
+ "upload is consumed as a one-time snapshot at ingest, so the "
+ "watch would re-process stale content forever. Watch a URL / "
+ "sitemap / RSS source instead, or re-add the resource when the "
+ "source changes."
+ )
store = TempUploadStore.build(http_request.app.state.config)
resolved = await store.resolve_for_consume(request.temp_file_id, _ctx)
path = resolved.local_path
@@ -221,7 +233,7 @@ async def add_resource(
# omitted because ResourceService reads it with kwargs.get(..., False).
if "create_parent" in request.model_fields_set:
kwargs["create_parent"] = request.create_parent
- if request.temp_file_id:
+ if request.temp_file_id and request.watch_interval <= 0:
kwargs["temp_file_id"] = request.temp_file_id
if request.preserve_structure is not None:
kwargs["preserve_structure"] = request.preserve_structure
@@ -237,6 +249,8 @@ async def add_resource(
instruction=request.instruction,
wait=request.wait,
timeout=request.timeout,
+ tags=request.tags,
+ tag_mode=request.tag_mode,
allow_local_path_resolution=allow_local_path_resolution,
enforce_public_remote_targets=True,
args=request.args,
diff --git a/openviking/server/upload_token_store.py b/openviking/server/upload_token_store.py
index 705170f9e..35d8f61c6 100644
--- a/openviking/server/upload_token_store.py
+++ b/openviking/server/upload_token_store.py
@@ -47,6 +47,8 @@ class _TokenInfo:
reason: str
actor_peer_id: str
processing_mode: ProcessingMode
+ tags: Optional[list[str]]
+ tag_mode: str
expires_at: float
@@ -60,6 +62,8 @@ class ConsumedUploadToken:
reason: str
actor_peer_id: str
processing_mode: ProcessingMode
+ tags: Optional[list[str]]
+ tag_mode: str
class UploadTokenStore:
@@ -76,6 +80,8 @@ class UploadTokenStore:
reason: str = "",
actor_peer_id: str = "",
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ tags: Optional[list[str]] = None,
+ tag_mode: str = "replace",
) -> Tuple[str, float]:
"""Mint a fresh token bound to (account, user) plus ``to``/``reason``/``actor_peer_id``.
@@ -93,6 +99,8 @@ class UploadTokenStore:
reason,
actor_peer_id,
processing_mode,
+ tags,
+ tag_mode,
expires_at,
)
for _ in range(8):
@@ -118,6 +126,8 @@ class UploadTokenStore:
info.reason,
info.actor_peer_id,
info.processing_mode,
+ info.tags,
+ info.tag_mode,
)
def peek(self, token: str) -> Optional[_TokenInfo]:
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index c26755020..c9676d9d1 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -21,6 +21,7 @@ import httpx
from openviking.connector.client import ConnectorClient
from openviking.core.content_targets import ContentTargetSpec
+from openviking.utils.ingest_options import IngestOptions
from openviking.core.uri_validation import validate_optional_content_target_uri
from openviking.parse.parsers.constants import MPEG_TS_EXTENSION_ALIAS
from openviking.resource.feishu_watch_auth import (
@@ -113,8 +114,11 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset(
"parser_backend",
"resolved_extension",
"defer_post_processing",
+ "tags",
+ "tag_mode",
}
)
+_ADD_RESOURCE_TAG_MODES = frozenset({"replace", "append"})
_INTERNAL_INGESTION_FIELDS = frozenset(
{
@@ -197,6 +201,40 @@ class ResourceService:
sanitized[key] = value
return sanitized
+ def _watch_processor_kwargs(
+ self,
+ processor_kwargs: Dict[str, Any],
+ tags: Optional[List[str]],
+ tag_mode: str,
+ ) -> Dict[str, Any]:
+ watch_kwargs = dict(processor_kwargs)
+ if tags is not None:
+ watch_kwargs["tags"] = tags
+ watch_kwargs["tag_mode"] = tag_mode
+ return watch_kwargs
+
+ def _processor_args_for_watch_run(self, processor_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+ return self._sanitize_watch_processor_kwargs(processor_kwargs)
+
+ def _validate_add_resource_tag_policy(
+ self,
+ *,
+ tags: Optional[List[str]],
+ tag_mode: str,
+ ) -> None:
+ if tags is not None and tag_mode not in _ADD_RESOURCE_TAG_MODES:
+ raise InvalidArgumentError(f"unsupported tag mode: {tag_mode}")
+
+ def _add_resource_ingest_tag_kwargs(
+ self,
+ *,
+ tags: Optional[List[str]],
+ tag_mode: str,
+ ) -> Dict[str, Any]:
+ if tags is None:
+ return {}
+ return {"ingest_options": IngestOptions.from_search_tags(tags, mode=tag_mode)}
+
async def _manage_watch_if_needed(
self,
*,
@@ -436,6 +474,8 @@ class ResourceService:
processing_mode=msg.processing_mode,
watch_interval=msg.watch_interval,
manage_watch=not msg.skip_watch_management,
+ tags=msg.tags,
+ tag_mode=msg.tag_mode,
allow_local_path_resolution=msg.allow_local_path_resolution,
enforce_public_remote_targets=msg.enforce_public_remote_targets,
resource_lock=resource_lock,
@@ -453,6 +493,10 @@ class ResourceService:
)
telemetry_id = get_current_telemetry().telemetry_id
+ ingest_tag_kwargs = self._add_resource_ingest_tag_kwargs(
+ tags=msg.tags,
+ tag_mode=msg.tag_mode,
+ )
request_wait_tracker = get_request_wait_tracker()
request_wait_tracker.register_request(telemetry_id)
try:
@@ -466,6 +510,7 @@ class ResourceService:
summarize=msg.summarize,
build_index=msg.build_index,
processing_mode=msg.processing_mode,
+ **ingest_tag_kwargs,
)
await request_wait_tracker.wait_for_request(
telemetry_id,
@@ -519,6 +564,8 @@ class ResourceService:
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
args: Optional[Dict[str, Any]] = None,
@@ -527,6 +574,7 @@ class ResourceService:
"""Start background ingestion for Git repositories while reserving the target URI."""
self._ensure_initialized()
processing_mode = normalize_processing_mode(processing_mode)
+ self._validate_add_resource_tag_policy(tags=tags, tag_mode=tag_mode)
normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)
kwargs.update(normalized_args.processor_kwargs)
from openviking.connector.routing import CONNECTOR_CREDENTIAL_ARGS
@@ -595,6 +643,8 @@ class ResourceService:
processing_mode=processing_mode,
watch_interval=watch_interval,
skip_watch_management=not manage_watch,
+ tags=tags,
+ tag_mode=tag_mode,
allow_local_path_resolution=allow_local_path_resolution,
enforce_public_remote_targets=enforce_public_remote_targets,
strict=bool(kwargs.get("strict", False)),
@@ -605,7 +655,7 @@ class ResourceService:
preserve_structure=kwargs.get("preserve_structure"),
create_parent=bool(kwargs.get("create_parent", False)),
source_name=source_name,
- args=self._sanitize_watch_processor_kwargs(processor_args),
+ args=self._processor_args_for_watch_run(processor_args),
)
task = await self._enqueue_add_resource_job(
msg,
@@ -726,6 +776,8 @@ class ResourceService:
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
args: Optional[Dict[str, Any]] = None,
@@ -752,6 +804,8 @@ class ResourceService:
processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=True,
+ tags=tags,
+ tag_mode=tag_mode,
allow_local_path_resolution=allow_local_path_resolution,
enforce_public_remote_targets=enforce_public_remote_targets,
args=args,
@@ -811,6 +865,8 @@ class ResourceService:
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
args: Optional[Dict[str, Any]] = None,
@@ -854,6 +910,7 @@ class ResourceService:
"""
self._ensure_initialized()
processing_mode = normalize_processing_mode(processing_mode)
+ self._validate_add_resource_tag_policy(tags=tags, tag_mode=tag_mode)
normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)
kwargs.update(normalized_args.processor_kwargs)
if watch_interval > 0 and kwargs.get("temp_file_id"):
@@ -893,6 +950,7 @@ class ResourceService:
watch_interval=watch_interval,
connector_args=args or {},
kwargs=kwargs,
+ tags=tags,
):
return await self._add_resource_via_connector(
path=path,
@@ -917,6 +975,8 @@ class ResourceService:
processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
+ tags=tags,
+ tag_mode=tag_mode,
allow_local_path_resolution=allow_local_path_resolution,
enforce_public_remote_targets=enforce_public_remote_targets,
**kwargs,
@@ -936,6 +996,8 @@ class ResourceService:
processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
+ tags=tags,
+ tag_mode=tag_mode,
allow_local_path_resolution=allow_local_path_resolution,
enforce_public_remote_targets=enforce_public_remote_targets,
watch_auth_state=normalized_args.watch_auth_state,
@@ -958,6 +1020,8 @@ class ResourceService:
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
watch_auth_state: Optional[Dict[str, Any]] = None,
@@ -974,6 +1038,10 @@ class ResourceService:
request_wait_tracker = get_request_wait_tracker()
job_enqueued = False
deferred_lock: LockLease = NO_LOCK
+ ingest_tag_kwargs = self._add_resource_ingest_tag_kwargs(
+ tags=tags,
+ tag_mode=tag_mode,
+ )
if telemetry_id:
request_wait_tracker.register_request(telemetry_id)
watch_manager = self._get_watch_manager()
@@ -1155,6 +1223,8 @@ class ResourceService:
skip_watch_management=True,
defer_target_resolution=defer_target_resolution,
understanding_response_id=understanding_response_id,
+ tags=tags,
+ tag_mode=tag_mode,
)
enqueue_started = True
task = await self._enqueue_add_resource_job(
@@ -1185,7 +1255,7 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
- processor_kwargs=kwargs,
+ processor_kwargs=self._watch_processor_kwargs(kwargs, tags, tag_mode),
watch_auth_state=watch_auth_state,
ctx=ctx,
)
@@ -1212,6 +1282,7 @@ class ResourceService:
allow_local_path_resolution=allow_local_path_resolution,
prepared_resource=prepared_resource,
defer_post_processing=not wait,
+ **ingest_tag_kwargs,
**kwargs,
)
prepared_resource = None
@@ -1301,6 +1372,8 @@ class ResourceService:
enforce_public_remote_targets=enforce_public_remote_targets,
source_name=kwargs.get("source_name"),
skip_watch_management=True,
+ tags=tags,
+ tag_mode=tag_mode,
)
task = await self._enqueue_add_resource_job(
msg,
@@ -1322,7 +1395,7 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
- processor_kwargs=kwargs,
+ processor_kwargs=self._watch_processor_kwargs(kwargs, tags, tag_mode),
watch_auth_state=watch_auth_state,
ctx=ctx,
)
@@ -1437,6 +1510,7 @@ class ResourceService:
watch_interval: float = 0,
connector_args: Optional[Dict[str, Any]] = None,
kwargs: Optional[Dict[str, Any]] = None,
+ tags: Optional[List[str]] = None,
) -> bool:
"""Decide whether a top-level resource path belongs to Connector.
@@ -1525,6 +1599,7 @@ class ResourceService:
kwargs=kwargs or {},
to=to,
parent=parent,
+ tags=tags,
)
if not unsupported:
return True
@@ -1556,6 +1631,7 @@ class ResourceService:
kwargs: Dict[str, Any],
to: Optional[str] = None,
parent: Optional[str] = None,
+ tags: Optional[List[str]] = None,
) -> List[str]:
"""add_resource params the Connector delegation cannot honor.
@@ -1598,6 +1674,8 @@ class ResourceService:
unsupported.append("directly_upload_media=false")
if kwargs.get("source_name"):
unsupported.append("source_name")
+ if tags is not None:
+ unsupported.append("tags (Connector imports cannot apply ingestion tags yet)")
supported_args = CONNECTOR_SUPPORTED_ARGS.get(
add_type, frozenset()
) | CONNECTOR_CREDENTIAL_ARGS.get(add_type, frozenset())
diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.py
index 29d617401..946dd2278 100644
--- a/openviking/storage/collection_schemas.py
+++ b/openviking/storage/collection_schemas.py
@@ -25,7 +25,10 @@ from openviking.storage.errors import (
)
from openviking.storage.queuefs.embedding_msg import EmbeddingMsg
from openviking.storage.queuefs.named_queue import DequeueHandlerBase
-from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
+from openviking.storage.viking_vector_index_backend import (
+ VikingVectorIndexBackend,
+ normalize_upsert_options,
+)
from openviking.telemetry import bind_telemetry, resolve_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.utils.circuit_breaker import (
@@ -746,6 +749,10 @@ class TextEmbeddingHandler(DequeueHandlerBase):
# Write to vector database
try:
+ raw_upsert_options = inserted_data.pop("_upsert_options", {})
+ upsert_options = normalize_upsert_options(
+ {**raw_upsert_options, "partial_update": True}
+ )
# Ensure vector DB has deterministic IDs per semantic layer.
uri = inserted_data.get("uri")
account_id = inserted_data.get("account_id", "default")
@@ -762,7 +769,7 @@ class TextEmbeddingHandler(DequeueHandlerBase):
result = await self._vikingdb.upsert(
inserted_data,
ctx=ctx,
- partial_update=True,
+ options=upsert_options,
)
record_id = result
if record_id:
diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.py
index 6db4e47cd..dbc485e8a 100644
--- a/openviking/storage/queuefs/add_resource_msg.py
+++ b/openviking/storage/queuefs/add_resource_msg.py
@@ -42,6 +42,8 @@ class AddResourceMsg:
defer_target_resolution: bool = False
understanding_response_id: Optional[str] = None
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
+ tags: Optional[list[str]] = None
+ tag_mode: str = "replace"
def to_dict(self) -> Dict[str, Any]:
data = asdict(self)
@@ -120,4 +122,10 @@ class AddResourceMsg:
else None
),
processing_mode=data.get("processing_mode", DEFAULT_PROCESSING_MODE),
+ tags=(
+ list(data["tags"])
+ if isinstance(data.get("tags"), list)
+ else None
+ ),
+ tag_mode=str(data.get("tag_mode") or "replace"),
)
diff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.py
index 2006d9875..5e2179918 100644
--- a/openviking/storage/queuefs/semantic_dag.py
+++ b/openviking/storage/queuefs/semantic_dag.py
@@ -8,6 +8,7 @@ from dataclasses import dataclass, field
from typing import ClassVar, Dict, List, Optional, Set
from weakref import WeakKeyDictionary
+from openviking.utils.ingest_options import IngestOptions
from openviking.server.identity import RequestContext
from openviking.storage.queuefs.semantic_sidecar import write_semantic_sidecars
from openviking.storage.transaction import NO_LOCK, LockLease
@@ -63,6 +64,7 @@ class VectorizeTask:
summary_dict: Optional[Dict[str, str]] = None
parent_uri: Optional[str] = None
use_summary: bool = False
+ ingest_options: IngestOptions = field(default_factory=IngestOptions)
# For directory tasks
abstract: Optional[str] = None
overview: Optional[str] = None
@@ -171,6 +173,7 @@ class SemanticDagExecutor:
is_code_repo: bool = False,
changes: Optional[Dict[str, List[str]]] = None,
skip_vectorization: bool = False,
+ ingest_options: IngestOptions | None = None,
coalesce_key: str = "",
coalesce_version: int = 0,
):
@@ -186,6 +189,7 @@ class SemanticDagExecutor:
self._is_code_repo = is_code_repo
self._changes = changes or {}
self._skip_vectorization = skip_vectorization
+ self._ingest_options = IngestOptions.from_value(ingest_options)
self._coalesce_key = coalesce_key
self._coalesce_version = coalesce_version
self._stale = False
@@ -406,6 +410,7 @@ class SemanticDagExecutor:
ctx=task.ctx,
semantic_msg_id=task.semantic_msg_id,
use_summary=task.use_summary,
+ ingest_options=task.ingest_options,
)
return
@@ -416,6 +421,7 @@ class SemanticDagExecutor:
task.overview,
ctx=task.ctx,
semantic_msg_id=task.semantic_msg_id,
+ ingest_options=task.ingest_options,
)
async def _dispatch_dir(self, dir_uri: str, parent_uri: Optional[str]) -> bool:
@@ -691,6 +697,7 @@ class SemanticDagExecutor:
summary_dict=summary_dict,
parent_uri=parent_uri,
use_summary=use_summary,
+ ingest_options=self._ingest_options,
)
await self._add_vectorize_task(task)
except Exception as e:
@@ -832,6 +839,7 @@ class SemanticDagExecutor:
semantic_msg_id=self._semantic_msg_id,
abstract=abstract,
overview=overview,
+ ingest_options=self._ingest_options,
)
await self._add_vectorize_task(task)
except Exception as e:
diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.py
index a71a77161..77ba29add 100644
--- a/openviking/storage/queuefs/semantic_msg.py
+++ b/openviking/storage/queuefs/semantic_msg.py
@@ -3,11 +3,12 @@
"""SemanticMsg: Semantic extraction queue message dataclass."""
import json
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
from datetime import datetime
from typing import Any, Dict, List, Optional
from uuid import uuid4
+from openviking.utils.ingest_options import IngestOptions
from openviking.storage.transaction import LockHandoffRef
@@ -55,6 +56,7 @@ class SemanticMsg:
lock_handoff: Optional[LockHandoffRef] = None
is_code_repo: bool = False
target_preexisting: Optional[bool] = None
+ ingest_options: IngestOptions = field(default_factory=IngestOptions)
coalesce_key: str = ""
coalesce_version: int = 0
changes: Optional[Dict[str, List[str]]] = (
@@ -76,6 +78,7 @@ class SemanticMsg:
lock_handoff: Optional[LockHandoffRef] = None,
is_code_repo: bool = False,
target_preexisting: Optional[bool] = None,
+ ingest_options: IngestOptions | Dict[str, Any] | None = None,
coalesce_key: str = "",
coalesce_version: int = 0,
changes: Optional[Dict[str, List[str]]] = None,
@@ -94,13 +97,16 @@ class SemanticMsg:
self.lock_handoff = lock_handoff
self.is_code_repo = is_code_repo
self.target_preexisting = target_preexisting
+ self.ingest_options = IngestOptions.from_value(ingest_options)
self.coalesce_key = coalesce_key
self.coalesce_version = coalesce_version
self.changes = changes
def to_dict(self) -> Dict[str, Any]:
"""Convert object to dictionary."""
- return asdict(self)
+ data = asdict(self)
+ data["ingest_options"] = self.ingest_options.to_dict()
+ return data
def to_json(self) -> str:
"""Convert object to JSON string."""
@@ -137,6 +143,13 @@ class SemanticMsg:
lock_handoff=LockHandoffRef.from_value(data.get("lock_handoff")),
is_code_repo=data.get("is_code_repo", False),
target_preexisting=data.get("target_preexisting"),
+ ingest_options=(
+ data.get("ingest_options")
+ or {
+ "search_tags": data.get("search_tags"),
+ "search_tag_mode": data.get("search_tag_mode", "replace"),
+ }
+ ),
coalesce_key=data.get("coalesce_key", ""),
coalesce_version=data.get("coalesce_version", 0),
changes=data.get("changes"),
diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.py
index 016a03e15..3a1b82556 100644
--- a/openviking/storage/queuefs/semantic_processor.py
+++ b/openviking/storage/queuefs/semantic_processor.py
@@ -31,6 +31,7 @@ from openviking.parse.parsers.media.utils import (
get_media_type,
)
from openviking.prompts import render_prompt
+from openviking.utils.ingest_options import IngestOptions
from openviking.server.identity import RequestContext, Role
from openviking.storage.errors import LockAcquisitionError
from openviking.storage.queuefs.named_queue import DequeueHandlerBase
@@ -440,6 +441,7 @@ class SemanticProcessor(DequeueHandlerBase):
is_code_repo=msg.is_code_repo,
changes=changes,
skip_vectorization=msg.skip_vectorization,
+ ingest_options=msg.ingest_options,
coalesce_key=msg.coalesce_key,
coalesce_version=msg.coalesce_version,
)
@@ -1539,6 +1541,7 @@ class SemanticProcessor(DequeueHandlerBase):
overview: str,
ctx: Optional[RequestContext] = None,
semantic_msg_id: Optional[str] = None,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""Create directory Context and enqueue to EmbeddingQueue."""
@@ -1552,6 +1555,7 @@ class SemanticProcessor(DequeueHandlerBase):
context_type=context_type,
ctx=active_ctx,
semantic_msg_id=semantic_msg_id,
+ ingest_options=ingest_options,
)
async def _vectorize_single_file(
@@ -1564,6 +1568,7 @@ class SemanticProcessor(DequeueHandlerBase):
semantic_msg_id: Optional[str] = None,
use_summary: bool = False,
preserve_existing_created_at: bool = False,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""Vectorize a single file using its content or summary."""
from openviking.utils.embedding_utils import vectorize_file
@@ -1578,4 +1583,5 @@ class SemanticProcessor(DequeueHandlerBase):
semantic_msg_id=semantic_msg_id,
use_summary=use_summary,
preserve_existing_created_at=preserve_existing_created_at,
+ ingest_options=ingest_options,
)
diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.py
index 5e7218b26..95f5e928f 100644
--- a/openviking/storage/viking_vector_index_backend.py
+++ b/openviking/storage/viking_vector_index_backend.py
@@ -7,7 +7,8 @@ from __future__ import annotations
import asyncio
import uuid
from contextlib import asynccontextmanager
-from typing import Any, AsyncIterator, Dict, List, Optional
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Dict, List, Mapping, Optional
from openviking.core.namespace import canonicalize_uri, uri_parts, visible_roots
from openviking.server.identity import RequestContext, Role
@@ -16,6 +17,7 @@ from openviking.storage.vectordb.collection.collection import Collection
from openviking.storage.vectordb.collection.result import UpdateResult
from openviking.storage.vectordb.utils.logging_init import init_cpp_logging
from openviking.storage.vectordb_adapters import create_collection_adapter
+from openviking.utils.tags import merge_search_tags
from openviking_cli.utils import get_logger
from openviking_cli.utils.config.vectordb_config import DEFAULT_INDEX_NAME, VectorDBBackendConfig
@@ -70,6 +72,25 @@ URI_REWRITE_OUTPUT_FIELDS = [
VIKINGDB_CONTENT_MAX_SIZE = 1024 * 1024
+@dataclass(frozen=True)
+class UpsertOptions:
+ partial_update: bool = False
+ search_tag_mode: str = "replace"
+
+
+def normalize_upsert_options(
+ options: UpsertOptions | Mapping[str, Any] | None = None,
+) -> UpsertOptions:
+ if options is None:
+ return UpsertOptions()
+ if isinstance(options, UpsertOptions):
+ return options
+ return UpsertOptions(
+ partial_update=bool(options.get("partial_update", False)),
+ search_tag_mode=str(options.get("search_tag_mode", "replace")),
+ )
+
+
async def _wait_for_task_completion_despite_cancellation(
task: asyncio.Task[Any],
) -> Optional[asyncio.CancelledError]:
@@ -310,14 +331,19 @@ class _SingleAccountBackend:
# Data Operations (with tenant enforcement)
# =========================================================================
- async def upsert(self, data: Dict[str, Any], partial_update: bool = False) -> str:
+ async def upsert(
+ self,
+ data: Dict[str, Any],
+ options: UpsertOptions | Mapping[str, Any] | None = None,
+ ) -> str:
+ options = normalize_upsert_options(options)
try:
payload = self._bind_upsert_payload(data)
except (PermissionError, ValueError) as exc:
logger.warning("Rejecting upsert: %s", exc)
return ""
- if partial_update:
+ if options.partial_update:
try:
existing_records = await self._async_adapter.call("get", [payload["id"]])
if self._bound_account_id:
@@ -332,6 +358,11 @@ class _SingleAccountBackend:
if existing_records:
existing = dict(existing_records[0])
+ if options.search_tag_mode == "append" and payload.get("search_tags") is not None:
+ payload["search_tags"] = merge_search_tags(
+ existing.get("search_tags"),
+ payload.get("search_tags"),
+ )
existing.update({k: v for k, v in payload.items() if v is not None})
payload = existing
@@ -839,20 +870,26 @@ class VikingVectorIndexBackend:
# =========================================================================
async def upsert(
- self, data: Dict[str, Any], *, ctx: RequestContext, partial_update: bool = False
+ self,
+ data: Dict[str, Any],
+ *,
+ ctx: RequestContext,
+ options: UpsertOptions | Mapping[str, Any] | None = None,
) -> str:
"""Main write entrypoint.
- With the default ``partial_update=False``, this preserves the legacy
- full-record upsert behavior. When ``partial_update=True``, the backend
+ With the default ``options.partial_update=False``, this preserves the legacy
+ full-record upsert behavior. When ``options.partial_update=True``, the backend
first reads the current record and preserves unspecified existing
fields before issuing the final upsert.
"""
+ options = normalize_upsert_options(options)
logger.debug(
"[VikingVectorIndexBackend.upsert] Called with ctx.account_id=%s, "
- "partial_update=%s, data=%s",
+ "partial_update=%s, search_tag_mode=%s, data=%s",
ctx.account_id,
- partial_update,
+ options.partial_update,
+ options.search_tag_mode,
data,
)
backend = self._get_backend_for_context(ctx)
@@ -860,10 +897,15 @@ class VikingVectorIndexBackend:
"[VikingVectorIndexBackend.upsert] Using backend for account_id=%s",
ctx.account_id,
)
- result = await backend.upsert(data, partial_update=partial_update)
+ result = await backend.upsert(
+ data,
+ options=options,
+ )
logger.debug(
- "[VikingVectorIndexBackend.upsert] Completed with partial_update=%s, result=%s",
- partial_update,
+ "[VikingVectorIndexBackend.upsert] Completed with partial_update=%s, "
+ "search_tag_mode=%s, result=%s",
+ options.partial_update,
+ options.search_tag_mode,
result,
)
return result
@@ -876,8 +918,9 @@ class VikingVectorIndexBackend:
All records are validated for the bound account before one adapter
invocation is made. Adapters may split that invocation into multiple
data-plane requests, so this API does not guarantee transaction
- atomicity. Use :meth:`upsert` with ``partial_update=True`` when omitted
- fields must be preserved from existing records.
+ atomicity. Use :meth:`upsert` with
+ ``options=UpsertOptions(partial_update=True)`` when omitted fields must
+ be preserved from existing records.
"""
logger.debug(
"[VikingVectorIndexBackend.upsert_many] Called with ctx.account_id=%s, count=%s",
diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.py
index f1b074bca..53f688bb6 100644
--- a/openviking/storage/vikingdb_manager.py
+++ b/openviking/storage/vikingdb_manager.py
@@ -5,14 +5,18 @@ VikingDB Manager class that extends VikingVectorIndexBackend with queue manageme
"""
from contextlib import asynccontextmanager
-from typing import Any, AsyncIterator, Dict, List, Optional, Tuple
+from typing import Any, AsyncIterator, Dict, List, Mapping, Optional, Tuple
from openviking.server.identity import RequestContext
from openviking.storage.expr import FilterExpr
from openviking.storage.queuefs.embedding_msg import EmbeddingMsg
from openviking.storage.queuefs.embedding_queue import EmbeddingQueue
from openviking.storage.queuefs.queue_manager import QueueManager
-from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
+from openviking.storage.viking_vector_index_backend import (
+ UpsertOptions,
+ VikingVectorIndexBackend,
+ normalize_upsert_options,
+)
from openviking_cli.utils import get_logger
from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
@@ -184,7 +188,7 @@ class VikingDBManagerProxy:
proxy = VikingDBManagerProxy(manager, ctx)
# 使用(无需传 ctx;仅在需要保留未显式传入字段时开启 partial_update)
- await proxy.upsert(data, partial_update=True)
+ await proxy.upsert(data, options=UpsertOptions(partial_update=True))
```
"""
@@ -286,14 +290,23 @@ class VikingDBManagerProxy:
# 数据操作 API(自动携带 ctx)
# =========================================================================
- async def upsert(self, data: Dict[str, Any], partial_update: bool = False):
+ async def upsert(
+ self,
+ data: Dict[str, Any],
+ options: UpsertOptions | Mapping[str, Any] | None = None,
+ ):
"""Bound write entrypoint.
- ``partial_update=False`` keeps the legacy full-record upsert semantics.
- ``partial_update=True`` reads the current record first and preserves
+ ``options.partial_update=False`` keeps the legacy full-record upsert semantics.
+ ``options.partial_update=True`` reads the current record first and preserves
fields that are omitted from ``data`` before writing.
"""
- return await self._manager.upsert(data, ctx=self._ctx, partial_update=partial_update)
+ options = normalize_upsert_options(options)
+ return await self._manager.upsert(
+ data,
+ ctx=self._ctx,
+ options=options,
+ )
async def upsert_many(self, data_list: List[Dict[str, Any]]) -> List[str]:
"""Bulk full-record upsert with the proxy's bound request context."""
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index 974b89e7e..f955fc89f 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -238,6 +238,8 @@ class SyncOpenViking:
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
processing_mode: str = "semantic_and_vectors",
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
**kwargs,
) -> Dict[str, Any]:
"""Add resource to OpenViking (resources scope only)
@@ -270,6 +272,8 @@ class SyncOpenViking:
summarize=summarize,
processing_mode=processing_mode,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
telemetry=telemetry,
**kwargs,
)
diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.py
index e7d7e7d97..0358a205e 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -13,7 +13,12 @@ from typing import Any, Dict, Optional
from charset_normalizer import from_bytes
from openviking.core.context import Context, ContextLevel, ResourceContentType, Vectorize
-from openviking.core.namespace import context_type_for_uri, is_session_uri, owner_space_for_uri
+from openviking.utils.ingest_options import IngestOptions
+from openviking.core.namespace import (
+ context_type_for_uri,
+ is_session_uri,
+ owner_space_for_uri,
+)
from openviking.server.identity import RequestContext
from openviking.storage.queuefs import get_queue_manager
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
@@ -64,6 +69,19 @@ def _apply_scalar_overrides(embedding_msg, overrides: Optional[Dict[str, Any]])
embedding_msg.context_data[field] = value
+def _apply_ingest_options(
+ embedding_msg,
+ ingest_options: IngestOptions | None,
+) -> None:
+ ingest_options = IngestOptions.from_value(ingest_options)
+ if not embedding_msg or ingest_options.search_tags is None:
+ return
+ embedding_msg.context_data["search_tags"] = list(ingest_options.search_tags or [])
+ embedding_msg.context_data["_upsert_options"] = {
+ "search_tag_mode": ingest_options.search_tag_mode
+ }
+
+
async def _decrement_embedding_tracker(semantic_msg_id: Optional[str], count: int) -> None:
if not semantic_msg_id or count <= 0:
return
@@ -312,6 +330,7 @@ async def vectorize_directory_meta(
semantic_msg_id: Optional[str] = None,
include_overview: bool = True,
scalar_overrides: Optional[Dict[int, Dict[str, Any]]] = None,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""
Vectorize directory metadata (.abstract.md and .overview.md).
@@ -332,7 +351,6 @@ async def vectorize_directory_meta(
owner_space = owner_space_for_uri(uri, ctx)
created_at, updated_at = await _resolve_context_timestamps(uri, ctx)
-
# Cap the abstract scalar below the bytes_row 65535-byte limit. #2774
# added this for the memory path; the resource indexing paths (here and
# index_resource, which feeds this function) were missed, so an
@@ -359,6 +377,7 @@ async def vectorize_directory_meta(
msg_abstract,
(scalar_overrides or {}).get(int(ContextLevel.ABSTRACT.value)),
)
+ _apply_ingest_options(msg_abstract, ingest_options)
if msg_abstract:
msg_abstract.semantic_msg_id = semantic_msg_id
try:
@@ -392,6 +411,7 @@ async def vectorize_directory_meta(
msg_overview,
(scalar_overrides or {}).get(int(ContextLevel.OVERVIEW.value)),
)
+ _apply_ingest_options(msg_overview, ingest_options)
if msg_overview:
msg_overview.semantic_msg_id = semantic_msg_id
try:
@@ -424,6 +444,7 @@ async def vectorize_file(
preserve_existing_created_at: bool = False,
scalar_override: Optional[Dict[str, Any]] = None,
register_request_wait: bool = False,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""
Vectorize a single file.
@@ -458,7 +479,6 @@ async def vectorize_file(
ctx,
preserve_existing_created_at=preserve_existing_created_at,
)
-
context = Context(
uri=file_path,
parent_uri=parent_uri,
@@ -543,6 +563,7 @@ async def vectorize_file(
return
_apply_scalar_overrides(embedding_msg, scalar_override)
+ _apply_ingest_options(embedding_msg, ingest_options)
embedding_msg.semantic_msg_id = semantic_msg_id
if register_request_wait:
get_request_wait_tracker().register_embedding_root(
@@ -577,6 +598,7 @@ async def vectorize_file(
async def index_resource(
uri: str,
ctx: RequestContext,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""
Build vector index for a resource directory.
@@ -611,7 +633,14 @@ async def index_resource(
overview = content.decode("utf-8") if isinstance(content, bytes) else content
if abstract or overview:
- await vectorize_directory_meta(uri, abstract, overview, context_type=context_type, ctx=ctx)
+ await vectorize_directory_meta(
+ uri,
+ abstract,
+ overview,
+ context_type=context_type,
+ ctx=ctx,
+ ingest_options=ingest_options,
+ )
# 2. Index Files
try:
@@ -637,6 +666,7 @@ async def index_resource(
parent_uri=uri,
context_type=context_type,
ctx=ctx,
+ ingest_options=ingest_options,
)
except Exception as e:
diff --git a/openviking/utils/ingest_options.py b/openviking/utils/ingest_options.py
new file mode 100644
index 000000000..fa1e1defe
--- /dev/null
+++ b/openviking/utils/ingest_options.py
@@ -0,0 +1,56 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Options carried with content as it enters downstream processing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping, Optional
+
+from openviking.utils.tags import normalize_search_tags
+
+
+@dataclass(frozen=True)
+class IngestOptions:
+ """Small, serializable options shared across processing stages.
+
+ This is not limited to resource imports. It may be used by any producer
+ that submits content into summarization, semantic indexing, or vector
+ writing pipelines. Do not put request identity, locks, telemetry collectors,
+ or large source payloads here.
+ """
+
+ search_tags: Optional[list[str]] = None
+ search_tag_mode: str = "replace"
+
+ @classmethod
+ def from_search_tags(
+ cls,
+ tags: Iterable[str] | None,
+ *,
+ mode: str = "replace",
+ ) -> "IngestOptions":
+ if tags is None:
+ return cls()
+ return cls(search_tags=normalize_search_tags(tags), search_tag_mode=mode)
+
+ @classmethod
+ def from_value(cls, value: "IngestOptions | Mapping[str, Any] | None") -> "IngestOptions":
+ if value is None:
+ return cls()
+ if isinstance(value, IngestOptions):
+ return value
+ return cls(
+ search_tags=(
+ list(value.get("search_tags") or [])
+ if value.get("search_tags") is not None
+ else None
+ ),
+ search_tag_mode=str(value.get("search_tag_mode", "replace")),
+ )
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "search_tags": list(self.search_tags) if self.search_tags is not None else None,
+ "search_tag_mode": self.search_tag_mode,
+ }
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index 5ded05951..553e42be7 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -13,6 +13,7 @@ from collections.abc import Callable
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
from openviking.core.context import ContextLevel
+from openviking.utils.ingest_options import IngestOptions
from openviking.core.namespace import context_type_for_uri
from openviking.parse.image_rewrite import rewrite_image_uris
from openviking.parse.tree_builder import TreeBuilder
@@ -136,8 +137,18 @@ class ResourceProcessor:
self, resource_uris: List[str], ctx: RequestContext, **kwargs
) -> Dict[str, Any]:
"""Expose index building as a standalone method."""
+ ingest_options = IngestOptions.from_value(kwargs.get("ingest_options"))
+ if ingest_options.search_tags is None and kwargs.get("search_tags") is not None:
+ ingest_options = IngestOptions.from_search_tags(
+ kwargs.get("search_tags"),
+ mode=kwargs.get("search_tag_mode", "replace"),
+ )
for uri in resource_uris:
- await index_resource(uri, ctx)
+ await index_resource(
+ uri,
+ ctx,
+ ingest_options=ingest_options,
+ )
return {"status": "success", "message": f"Indexed {len(resource_uris)} resources"}
async def summarize(
@@ -178,6 +189,7 @@ class ResourceProcessor:
}
defer_post_processing = bool(kwargs.pop("defer_post_processing", False))
preacquired_lock = kwargs.pop("resource_lock", NO_LOCK) or NO_LOCK
+ ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))
telemetry = get_current_telemetry()
async def _set_stage(stage: str) -> None:
@@ -420,6 +432,7 @@ class ResourceProcessor:
ctx=ctx,
resource_lock=resource_lock,
summarize=summarize,
+ ingest_options=ingest_options,
**kwargs,
)
if post_result.get("warnings"):
@@ -452,6 +465,7 @@ class ResourceProcessor:
build_index = bool(kwargs.get("build_index", True))
processing_mode = normalize_processing_mode(processing_mode)
vectors_only = processing_mode == VECTORS_ONLY
+ ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))
should_summarize = not vectors_only and (summarize or build_index)
result: Dict[str, Any] = {"status": "success", "root_uri": root_uri}
@@ -468,6 +482,7 @@ class ResourceProcessor:
temp_uris=[temp_uri],
is_code_repo=bool(prepared.get("is_code_repo")),
target_preexisting=target_preexisting,
+ ingest_options=ingest_options,
**kwargs,
)
if (
@@ -524,13 +539,21 @@ class ResourceProcessor:
ctx=ctx,
)
if vectors_only and build_index:
- await self._vectorize_resource_files(root_uri, ctx=ctx)
+ await self._vectorize_resource_files(
+ root_uri,
+ ctx=ctx,
+ ingest_options=ingest_options,
+ )
finally:
await resource_lock.close()
elif vectors_only:
if not build_index:
return result
- await self._vectorize_resource_files(root_uri, ctx=ctx)
+ await self._vectorize_resource_files(
+ root_uri,
+ ctx=ctx,
+ ingest_options=ingest_options,
+ )
return result
async def _delete_removed_resource_vectors(
@@ -567,7 +590,14 @@ class ResourceProcessor:
if ids:
await self.vikingdb.delete(ids, ctx=ctx)
- async def _vectorize_resource_files(self, root_uri: str, *, ctx: RequestContext) -> None:
+ async def _vectorize_resource_files(
+ self,
+ root_uri: str,
+ *,
+ ctx: RequestContext,
+ ingest_options: IngestOptions | None = None,
+ ) -> None:
+ ingest_options = IngestOptions.from_value(ingest_options)
viking_fs = get_viking_fs()
entries = await viking_fs.tree(
root_uri,
@@ -591,6 +621,7 @@ class ResourceProcessor:
parent_uri=parent.uri,
context_type=context_type_for_uri(entry_uri),
ctx=ctx,
+ ingest_options=ingest_options,
register_request_wait=True,
)
diff --git a/openviking/utils/summarizer.py b/openviking/utils/summarizer.py
index 50afe9e77..83f42092e 100644
--- a/openviking/utils/summarizer.py
+++ b/openviking/utils/summarizer.py
@@ -7,6 +7,7 @@ Handles summarization and key information extraction.
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+from openviking.utils.ingest_options import IngestOptions
from openviking.core.namespace import context_type_for_uri
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
from openviking.storage.transaction import NO_LOCK, LockLease
@@ -47,6 +48,7 @@ class Summarizer:
semantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC, allow_create=True)
temp_uris = kwargs.get("temp_uris", [])
+ ingest_options = IngestOptions.from_value(kwargs.get("ingest_options"))
if not temp_uris:
temp_uris = resource_uris
if len(temp_uris) != len(resource_uris):
@@ -125,6 +127,7 @@ class Summarizer:
lock_handoff=lock_handoff,
is_code_repo=kwargs.get("is_code_repo", False),
target_preexisting=resolve_target_preexisting(idx, target_uri),
+ ingest_options=ingest_options,
)
if msg.telemetry_id:
get_request_wait_tracker().register_semantic_root(msg.telemetry_id, msg.id)
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index e1cdbfd60..f016083cd 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -46,6 +46,8 @@ class BaseClient(ABC):
processing_mode: str = "semantic_and_vectors",
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
) -> Dict[str, Any]:
"""Add resource to OpenViking."""
...
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 383e9968a..8d024d36d 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -630,6 +630,31 @@ func TestAddResourceSendsArgsWhenProvided(t *testing.T) {
}
}
+func TestAddResourceSendsTagsAndTagMode(t *testing.T) {
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/api/v1/resources" {
+ t.Fatalf("unexpected path %s", r.URL.Path)
+ }
+ body := readJSONBody(t, r)
+ tags, ok := body["tags"].([]any)
+ if !ok || len(tags) != 1 || tags[0] != "team=search" {
+ t.Fatalf("tags = %#v", body["tags"])
+ }
+ if body["tag_mode"] != "append" {
+ t.Fatalf("tag_mode = %#v", body["tag_mode"])
+ }
+ writeOK(t, w, map[string]any{"uri": "viking://resources/demo.md"})
+ }))
+ defer closeServer()
+
+ if _, err := client.AddResource(context.Background(), "https://example.com/demo.md", &AddResourceOptions{
+ Tags: []string{"team=search"},
+ TagMode: "append",
+ }); err != nil {
+ t.Fatal(err)
+ }
+}
+
// An explicitly-provided but empty Args map is treated the same as no args: the
// key is omitted so the request stays compatible with pre-#2549 instances. The
// resources create route defaults args to {} server-side, so "absent" and
diff --git a/sdk/go/resources.go b/sdk/go/resources.go
index 3c61ab332..5a1890b1c 100644
--- a/sdk/go/resources.go
+++ b/sdk/go/resources.go
@@ -40,6 +40,12 @@ func (c *Client) AddResource(ctx context.Context, path string, opts *AddResource
if len(opts.Args) > 0 {
payload["args"] = opts.Args
}
+ if opts.Tags != nil {
+ payload["tags"] = opts.Tags
+ if opts.TagMode != "" {
+ payload["tag_mode"] = opts.TagMode
+ }
+ }
if err := c.addLocalUpload(ctx, payload, path, true); err != nil {
return nil, err
}
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 9cbe1a534..765ff967d 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -36,6 +36,8 @@ type AddResourceOptions struct {
PreserveStructure *bool
WatchInterval float64
Args map[string]any
+ Tags []string
+ TagMode string
Telemetry any
}
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 237150395..82f49b4e7 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -642,6 +642,8 @@ class AsyncHTTPClient:
args: Optional[Dict[str, Any]] = None,
telemetry: Any = False,
processing_mode: Optional[str] = None,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
) -> Dict[str, Any]:
if to and parent:
raise ValueError("Cannot specify both 'to' and 'parent' at the same time.")
@@ -664,6 +666,9 @@ class AsyncHTTPClient:
}
if processing_mode is not None:
request_data["processing_mode"] = processing_mode
+ if tags is not None:
+ request_data["tags"] = tags
+ request_data["tag_mode"] = tag_mode
if preserve_structure is not None:
request_data["preserve_structure"] = preserve_structure
@@ -1842,6 +1847,8 @@ class SyncHTTPClient:
args: Optional[Dict[str, Any]] = None,
telemetry: Any = False,
processing_mode: Optional[str] = None,
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
) -> Dict[str, Any]:
return run_async(
self._async_client.add_resource(
@@ -1861,6 +1868,8 @@ class SyncHTTPClient:
watch_interval=watch_interval,
processing_mode=processing_mode,
args=args,
+ tags=tags,
+ tag_mode=tag_mode,
telemetry=telemetry,
)
)
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index bef039399..fa76c484d 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -1,3 +1,4 @@
+import inspect
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import AsyncMock, Mock, patch
@@ -8,6 +9,13 @@ from openviking_sdk.client import Session, SyncSession
from openviking_sdk.errors import NotFoundError
+def test_add_resource_signatures_keep_telemetry_position():
+ for func in (AsyncHTTPClient.add_resource, SyncHTTPClient.add_resource):
+ params = list(inspect.signature(func).parameters)
+ assert params.index("telemetry") < params.index("tags")
+ assert params.index("telemetry") < params.index("tag_mode")
+
+
@pytest.mark.asyncio
async def test_async_http_client_initialize_forwards_event_hooks():
async def request_hook(_request):
@@ -602,6 +610,36 @@ async def test_import_ovpack_uploads_local_file_even_when_url_is_localhost(tmp_p
)
+async def test_add_resource_sends_tags_and_tag_mode():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))
+ client._http = fake_http
+ client._handle_response_data = lambda _response: {"result": {"root_uri": "viking://resources/demo"}}
+
+ await client.add_resource(
+ path="https://example.com/demo.md",
+ tags=["team=search"],
+ tag_mode="append",
+ )
+
+ fake_http.post.assert_awaited_once_with(
+ "/api/v1/resources",
+ json={
+ "path": "https://example.com/demo.md",
+ "reason": "",
+ "instruction": "",
+ "wait": False,
+ "strict": False,
+ "directly_upload_media": True,
+ "watch_interval": 0,
+ "telemetry": False,
+ "tags": ["team=search"],
+ "tag_mode": "append",
+ },
+ )
+
+
@pytest.mark.asyncio
async def test_find_uses_node_limit_as_http_limit_and_normalizes_target_uri_list():
client = AsyncHTTPClient(url="http://localhost:1933")
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index f35c39213..28ae1a6ac 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -124,6 +124,8 @@ export class OpenVikingClient {
options.args && Object.keys(options.args).length
? options.args
: undefined,
+ tags: options.tags,
+ tag_mode: options.tags ? options.tagMode : undefined,
telemetry: options.telemetry,
});
const local = await nodePathToBlob(source);
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 455e6cb6b..ea9ecf8a7 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -87,6 +87,8 @@ export interface AddResourceOptions extends WaitOptions {
watchInterval?: number;
processingMode?: ProcessingMode;
args?: JsonObject;
+ tags?: string[];
+ tagMode?: "replace" | "append";
}
/** Semantic retrieval options. */
export interface SearchOptions {
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index b8194e4d3..ca8d4ca39 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -166,6 +166,27 @@ describe("OpenVikingClient", () => {
expect(url.searchParams.get("sort_order")).toBe("desc");
});
+ it("sends addResource tags and tagMode to the server", async () => {
+ const fetcher = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(ok({ root_uri: "viking://resources/demo" }));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ fetch: fetcher,
+ });
+
+ await client.addResource("https://example.com/demo.md", {
+ tags: ["team=search"],
+ tagMode: "append",
+ });
+
+ expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toMatchObject({
+ path: "https://example.com/demo.md",
+ tags: ["team=search"],
+ tag_mode: "append",
+ });
+ });
+
it("converts an existing Node.js image path to a data URI", async () => {
const directory = await mkdtemp(join(tmpdir(), "openviking-sdk-image-"));
const path = join(directory, "photo.png");
diff --git a/tests/server/test_api_resources.py b/tests/server/test_api_resources.py
index d7ea3bcd6..5ac3312fa 100644
--- a/tests/server/test_api_resources.py
+++ b/tests/server/test_api_resources.py
@@ -8,6 +8,7 @@ import zipfile
from types import SimpleNamespace
import httpx
+import pytest
from openviking.server.identity import RequestContext, Role
from openviking.server.routers import resources as resources_router
@@ -146,6 +147,36 @@ async def test_add_resource_forwards_processing_mode_to_service(monkeypatch):
assert seen["processing_mode"] == "vectors_only"
+async def test_add_resource_forwards_tags_to_service(
+ client: httpx.AsyncClient,
+ service,
+ monkeypatch,
+):
+ seen = {}
+
+ async def fake_add_resource(**kwargs):
+ seen.update(kwargs)
+ return {
+ "status": "success",
+ "root_uri": "viking://resources/demo",
+ }
+
+ monkeypatch.setattr(service.resources, "add_resource", fake_add_resource)
+
+ resp = await client.post(
+ "/api/v1/resources",
+ json={
+ "path": "https://example.com/demo.md",
+ "tags": ["team=search"],
+ "tag_mode": "append",
+ },
+ )
+
+ assert resp.status_code == 200
+ assert seen["tags"] == ["team=search"]
+ assert seen["tag_mode"] == "append"
+
+
async def test_add_resource_preserves_create_parent_field_presence(
client: httpx.AsyncClient,
service,
@@ -615,9 +646,8 @@ async def test_wait_processed_after_add(
assert resp.json()["status"] == "ok"
-async def test_add_resource_with_watch_interval_auto_binds_root_uri(
+async def test_add_resource_rejects_temp_upload_with_watch_interval(
client: httpx.AsyncClient,
- service,
sample_markdown_file,
upload_temp_dir,
):
@@ -630,19 +660,9 @@ async def test_add_resource_with_watch_interval_auto_binds_root_uri(
"wait": True,
},
)
- assert resp.status_code == 200
- body = resp.json()
- assert body["status"] == "ok"
- root_uri = body["result"]["root_uri"]
- task = await service.watch_scheduler.watch_manager.get_task_by_uri(
- to_uri=root_uri,
- account_id="default",
- user_id="test_user",
- role="ROOT",
- )
- assert task is not None
- assert task.to_uri == root_uri
- assert task.watch_interval == 5.0
+ assert resp.status_code == 400
+ assert "uploaded content" in resp.text
+ assert not (upload_temp_dir / "watch_sources").exists()
async def test_add_resource_with_default_watch_interval(
@@ -786,6 +806,48 @@ async def test_shared_temp_upload_and_add_resource_deletes_upload_dir(
assert not await vfs.exists(upload_root)
[email protected]("upload_mode", ["local", "shared"])
+async def test_temp_upload_with_watch_and_tags_is_rejected_without_watch_source(
+ client: httpx.AsyncClient,
+ service,
+ upload_temp_dir,
+ upload_mode,
+):
+ data = {"upload_mode": upload_mode} if upload_mode == "shared" else None
+ upload_resp = await client.post(
+ "/api/v1/resources/temp_upload",
+ files={"file": ("watched.md", b"# watched upload\n", "text/markdown")},
+ data=data,
+ )
+ assert upload_resp.status_code == 200
+ temp_file_id = upload_resp.json()["result"]["temp_file_id"]
+ target_uri = f"viking://resources/watched-{upload_mode}-upload.md"
+
+ resp = await client.post(
+ "/api/v1/resources",
+ json={
+ "temp_file_id": temp_file_id,
+ "to": target_uri,
+ "reason": f"{upload_mode} upload watch",
+ "wait": True,
+ "watch_interval": 5.0,
+ "tags": ["team=watch", "env=test"],
+ "tag_mode": "replace",
+ },
+ )
+
+ assert resp.status_code == 400, resp.text
+ assert "uploaded content" in resp.text
+ task = await service.watch_scheduler.watch_manager.get_task_by_uri(
+ to_uri=target_uri,
+ account_id="default",
+ user_id="test_user",
+ role="ROOT",
+ )
+ assert task is None
+ assert not (upload_temp_dir / "watch_sources").exists()
+
+
async def test_shared_temp_upload_failed_consume_is_retryable(
client: httpx.AsyncClient,
app,
diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.py
index 94a91a8f5..abfb45730 100644
--- a/tests/server/test_mcp_endpoint.py
+++ b/tests/server/test_mcp_endpoint.py
@@ -643,6 +643,26 @@ async def test_add_resource_remote_parent_is_forwarded(service, monkeypatch):
assert captured["to"] is None
+async def test_add_resource_remote_tags_are_forwarded(service, monkeypatch):
+ captured = {}
+
+ async def fake_add_resource(*, path, ctx, **kwargs):
+ captured.update(kwargs)
+ return {"root_uri": "viking://resources/tagged"}
+
+ monkeypatch.setattr(service.resources, "add_resource", fake_add_resource)
+
+ result = await add_resource(
+ path="https://example.com/tagged.md",
+ tags=["team=search"],
+ tag_mode="append",
+ )
+
+ assert "Resource added" in result
+ assert captured["tags"] == ["team=search"]
+ assert captured["tag_mode"] == "append"
+
+
async def test_add_resource_temp_file_id_branch_resolves_and_ingests(
service, upload_temp_dir, monkeypatch
):
diff --git a/tests/server/test_resources_temp_upload_token.py b/tests/server/test_resources_temp_upload_token.py
index db967ffd8..64277d26b 100644
--- a/tests/server/test_resources_temp_upload_token.py
+++ b/tests/server/test_resources_temp_upload_token.py
@@ -32,9 +32,18 @@ def _issue(
to: str = "",
reason: str = "",
actor_peer_id: str = "",
+ tags: list[str] | None = None,
+ tag_mode: str = "replace",
):
token, _ = upload_token_store.issue(
- account_id, user_id, ttl_seconds=600, to=to, reason=reason, actor_peer_id=actor_peer_id
+ account_id,
+ user_id,
+ ttl_seconds=600,
+ to=to,
+ reason=reason,
+ actor_peer_id=actor_peer_id,
+ tags=tags,
+ tag_mode=tag_mode,
)
return token
@@ -49,6 +58,8 @@ def _stub_ingest(service, monkeypatch, root_uri: str = "viking://resources/uploa
captured["ctx"] = ctx
captured["to"] = kwargs.get("to")
captured["reason"] = kwargs.get("reason")
+ captured["tags"] = kwargs.get("tags")
+ captured["tag_mode"] = kwargs.get("tag_mode")
captured["allow_local_path_resolution"] = kwargs.get("allow_local_path_resolution")
return {"root_uri": root_uri}
@@ -91,6 +102,22 @@ async def test_token_upload_forwards_to_and_reason(
assert captured["reason"] == "quarterly report"
+async def test_token_upload_forwards_tags_and_tag_mode(
+ client: httpx.AsyncClient, service, upload_temp_dir: Path, monkeypatch
+):
+ captured = _stub_ingest(service, monkeypatch)
+ token = _issue(tags=["team=search"], tag_mode="append")
+ resp = await client.post(
+ "/api/v1/resources/temp_upload",
+ params={"token": token},
+ files={"file": ("r.md", b"data", "text/markdown")},
+ )
+
+ assert resp.status_code == 200, resp.text
+ assert captured["tags"] == ["team=search"]
+ assert captured["tag_mode"] == "append"
+
+
async def test_token_upload_uses_token_identity_ignoring_spoofed_headers(
client: httpx.AsyncClient, service, upload_temp_dir: Path, monkeypatch
):
diff --git a/tests/service/test_resource_service_connector.py b/tests/service/test_resource_service_connector.py
index 2b7ac9009..3fca0863c 100644
--- a/tests/service/test_resource_service_connector.py
+++ b/tests/service/test_resource_service_connector.py
@@ -936,6 +936,17 @@ async def test_tos_connector_rejects_wait(connector_config, ctx, service):
)
+async def test_tos_connector_rejects_tags_instead_of_dropping_them(connector_config, ctx, service):
+ with pytest.raises(InvalidArgumentError, match="tags"):
+ await service.add_resource(
+ path="tos://bucket/prefix",
+ ctx=ctx,
+ to="viking://resources/imports",
+ tags=["team=search"],
+ )
+
+
@pytest.mark.asyncio
async def test_monitor_links_reason_memory_on_success(
monkeypatch,
diff --git a/tests/service/test_resource_service_watch.py b/tests/service/test_resource_service_watch.py
index fba22225c..ea555d84c 100644
--- a/tests/service/test_resource_service_watch.py
+++ b/tests/service/test_resource_service_watch.py
@@ -9,10 +9,13 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
import pytest_asyncio
+from openviking.utils.ingest_options import IngestOptions
from openviking.resource.watch_manager import WatchManager
from openviking.server.identity import RequestContext, Role
from openviking.service import resource_service as resource_service_module
from openviking.service.resource_service import ResourceService
+from openviking.storage.content_write import ContentWriteCoordinator
+from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
from openviking_cli.exceptions import ConflictError, InvalidArgumentError
from openviking_cli.session.user_id import UserIdentifier
@@ -230,6 +233,157 @@ class TestWatchTaskCreation:
assert task.processor_kwargs.get("custom_option") == "x"
assert "processing_mode" not in task.processor_kwargs
+ @pytest.mark.asyncio
+ async def test_add_resource_forwards_tags_to_ingest_without_calling_set_tags(
+ self,
+ resource_service: ResourceService,
+ request_context: RequestContext,
+ monkeypatch: pytest.MonkeyPatch,
+ ):
+ async def fake_set_tags(self, **kwargs):
+ raise AssertionError("add_resource(tags=...) must write tags during ingest")
+
+ class FakeQueueManager:
+ async def wait_complete(self, timeout=None):
+ return {}
+
+ monkeypatch.setattr(ContentWriteCoordinator, "set_tags", fake_set_tags)
+ monkeypatch.setattr(resource_service_module, "get_queue_manager", lambda: FakeQueueManager())
+
+ result = await resource_service.add_resource(
+ path="/test/path",
+ ctx=request_context,
+ to="viking://resources/tagged_resource",
+ wait=True,
+ tags=["team=search"],
+ tag_mode="append",
+ )
+
+ assert "tags_result" not in result
+ assert resource_service._resource_processor.calls[-1]["ingest_options"] == IngestOptions(
+ search_tags=["team=search"],
+ search_tag_mode="append",
+ )
+
+ @pytest.mark.asyncio
+ async def test_add_resource_rejects_invalid_tag_mode_before_processing(
+ self,
+ resource_service: ResourceService,
+ request_context: RequestContext,
+ ):
+ with pytest.raises(InvalidArgumentError, match="unsupported tag mode"):
+ await resource_service.add_resource(
+ path="/test/path",
+ ctx=request_context,
+ tags=["team=search"],
+ tag_mode="create",
+ )
+
+ assert resource_service._resource_processor.calls == []
+
+ @pytest.mark.asyncio
+ async def test_watch_task_persists_tag_policy_for_refresh(
+ self,
+ resource_service: ResourceService,
+ request_context: RequestContext,
+ monkeypatch: pytest.MonkeyPatch,
+ ):
+ to_uri = "viking://resources/watch_tag_policy"
+
+ async def fake_set_tags(self, **kwargs):
+ return {"tags_updated": True}
+
+ class FakeQueueManager:
+ async def wait_complete(self, timeout=None):
+ return {}
+
+ monkeypatch.setattr(ContentWriteCoordinator, "set_tags", fake_set_tags)
+ monkeypatch.setattr(resource_service_module, "get_queue_manager", lambda: FakeQueueManager())
+
+ await resource_service.add_resource(
+ path="/test/path",
+ ctx=request_context,
+ to=to_uri,
+ wait=True,
+ watch_interval=30.0,
+ tags=["team=search"],
+ tag_mode="replace",
+ )
+
+ task = await get_task_by_uri(resource_service, to_uri, request_context)
+ assert task is not None
+ assert task.processor_kwargs["tags"] == ["team=search"]
+ assert task.processor_kwargs["tag_mode"] == "replace"
+
+ @pytest.mark.asyncio
+ async def test_execute_prepared_add_resource_job_forwards_tags_to_ingest(
+ self,
+ resource_service: ResourceService,
+ request_context: RequestContext,
+ monkeypatch: pytest.MonkeyPatch,
+ ):
+ finish_calls = []
+
+ async def fake_set_tags(self, **kwargs):
+ raise AssertionError("queued add_resource(tags=...) must write tags during ingest")
+
+ async def fake_finish_prepared_resource(*args, **kwargs):
+ finish_calls.append({"args": args, "kwargs": kwargs})
+ return {"root_uri": "viking://resources/queued"}
+
+ class FakeRequestWaitTracker:
+ def register_request(self, *_args, **_kwargs):
+ pass
+
+ async def wait_for_request(self, *_args, **_kwargs):
+ pass
+
+ def build_queue_status(self, *_args, **_kwargs):
+ return {}
+
+ def cleanup(self, *_args, **_kwargs):
+ pass
+
+ monkeypatch.setattr(ContentWriteCoordinator, "set_tags", fake_set_tags)
+ monkeypatch.setattr(
+ resource_service_module,
+ "get_request_wait_tracker",
+ lambda: FakeRequestWaitTracker(),
+ )
+ monkeypatch.setattr(
+ resource_service_module,
+ "unregister_wait_telemetry",
+ lambda *_args, **_kwargs: None,
+ )
+ resource_service._link_resource_reason_memory = AsyncMock()
+ resource_service._resource_processor.finish_prepared_resource = AsyncMock(
+ side_effect=fake_finish_prepared_resource
+ )
+
+ msg = AddResourceMsg(
+ task_id="task-1",
+ root_uri="viking://resources/queued",
+ account_id=request_context.account_id,
+ user_id=request_context.user.user_id,
+ role=str(request_context.role),
+ prepared={"path": "/test/path"},
+ tags=["team=search"],
+ tag_mode="append",
+ )
+
+ result = await resource_service.execute_add_resource_job(
+ msg,
+ ctx=request_context,
+ resource_lock=None,
+ stage_callback=lambda _stage: None,
+ )
+
+ assert "tags_result" not in result
+ assert finish_calls[-1]["kwargs"]["ingest_options"] == IngestOptions(
+ search_tags=["team=search"],
+ search_tag_mode="append",
+ )
+
@pytest.mark.asyncio
async def test_create_watch_task_with_default_interval(
self, resource_service: ResourceService, request_context: RequestContext
diff --git a/tests/storage/test_collection_schemas.py b/tests/storage/test_collection_schemas.py
index a56f68e81..56e897e82 100644
--- a/tests/storage/test_collection_schemas.py
+++ b/tests/storage/test_collection_schemas.py
@@ -34,6 +34,7 @@ from openviking.storage.vectordb_adapters.base import (
)
from openviking.storage.vectordb_adapters.local_adapter import LocalCollectionAdapter
from openviking.storage.viking_vector_index_backend import (
+ UpsertOptions,
VIKINGDB_CONTENT_MAX_SIZE,
VikingVectorIndexBackend,
_SingleAccountBackend,
@@ -391,8 +392,8 @@ async def test_embedding_handler_treats_shutdown_write_lock_as_success(monkeypat
self.is_closing = False
self.calls = 0
- async def upsert(self, _data, *, ctx, partial_update=False):
- assert partial_update is True
+ async def upsert(self, _data, *, ctx, options=UpsertOptions()):
+ assert options.partial_update is True
self.calls += 1
self.is_closing = True
raise RuntimeError("IO error: lock /tmp/LOCK: already held by process")
@@ -427,7 +428,7 @@ async def test_embedding_handler_propagates_account_id_on_success(monkeypatch):
class _DummyVikingDB:
is_closing = False
- async def upsert(self, _data, *, ctx):
+ async def upsert(self, _data, *, ctx, options=UpsertOptions()):
return None
captured: dict[str, object] = {}
@@ -489,7 +490,7 @@ async def test_embedding_handler_truncates_queue_input_before_embed(monkeypatch)
class _CapturingVikingDB:
is_closing = False
- async def upsert(self, _data, *, ctx):
+ async def upsert(self, _data, *, ctx, options=UpsertOptions()):
return "rec-1"
class _CapturingEmbedder(DenseEmbedderBase):
@@ -578,8 +579,8 @@ async def test_embedding_handler_preserves_parent_uri_for_backend_upsert_logic(m
is_closing = False
mode = "local"
- async def upsert(self, data, *, ctx, partial_update=False):
- assert partial_update is True
+ async def upsert(self, data, *, ctx, options=UpsertOptions()):
+ assert options.partial_update is True
captured["data"] = dict(data)
return "rec-1"
@@ -608,8 +609,8 @@ async def test_embedding_handler_marks_success_only_after_tracker_completion(mon
is_closing = False
mode = "local"
- async def upsert(self, _data, *, ctx, partial_update=False):
- assert partial_update is True
+ async def upsert(self, _data, *, ctx, options=UpsertOptions()):
+ assert options.partial_update is True
return "rec-1"
embedder = _DummyEmbedder()
@@ -1680,7 +1681,7 @@ async def test_single_account_backend_upsert_partial_update_reads_then_upserts_e
result = await backend.upsert(
{"id": "rec-1", "abstract": "patched"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "rec-1"
@@ -1698,6 +1699,76 @@ async def test_single_account_backend_upsert_partial_update_reads_then_upserts_e
]
+async def test_single_account_backend_upsert_partial_update_append_merges_search_tags_at_write():
+ calls = []
+
+ class _Collection:
+ def get_meta_data(self):
+ return {
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string"},
+ {"FieldName": "uri", "FieldType": "path"},
+ {"FieldName": "abstract", "FieldType": "string"},
+ {"FieldName": "search_tags", "FieldType": "list<string>"},
+ {"FieldName": "account_id", "FieldType": "string"},
+ ]
+ }
+
+ class _Adapter:
+ mode = "local"
+ USE_CONTENT_FIELD = False
+
+ def get_collection(self):
+ return _Collection()
+
+ def get(self, ids):
+ calls.append(("get", ids))
+ return [
+ {
+ "id": "rec-1",
+ "abstract": "before",
+ "account_id": "acc1",
+ "uri": "viking://resources/demo.md",
+ "search_tags": ["owner=alice", "env=dev"],
+ }
+ ]
+
+ def upsert(self, data):
+ calls.append(("upsert", data))
+ return ["rec-1"]
+
+ backend = _SingleAccountBackend(
+ config=VectorDBBackendConfig(backend="local", name="context", dimension=2),
+ bound_account_id="acc1",
+ shared_adapter=_Adapter(),
+ )
+
+ result = await backend.upsert(
+ {
+ "id": "rec-1",
+ "abstract": "patched",
+ "search_tags": ["env=prod", "team=search"],
+ },
+ options=UpsertOptions(partial_update=True, search_tag_mode="append"),
+ )
+
+ assert result == "rec-1"
+ assert calls == [
+ ("get", ["rec-1"]),
+ (
+ "upsert",
+ {
+ "id": "rec-1",
+ "abstract": "patched",
+ "account_id": "acc1",
+ "uri": "viking://resources/demo.md",
+ "search_tags": ["owner=alice", "env=prod", "team=search"],
+ },
+ ),
+ ]
+
+
@pytest.mark.asyncio
async def test_single_account_backend_upsert_partial_update_creates_when_record_does_not_exist():
calls = []
@@ -1744,7 +1815,7 @@ async def test_single_account_backend_upsert_partial_update_creates_when_record_
"abstract": "created",
"unknown": "ignored",
},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "rec-404"
@@ -1784,7 +1855,7 @@ async def test_single_account_backend_upsert_partial_update_returns_empty_when_g
result = await backend.upsert(
{"id": "rec-1", "abstract": "patched"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == ""
@@ -1823,8 +1894,8 @@ async def test_viking_vector_index_backend_upsert_partial_update_delegates_to_ac
calls = []
class _BoundBackend:
- async def upsert(self, data, partial_update=False):
- calls.append((data, partial_update))
+ async def upsert(self, data, options=UpsertOptions()):
+ calls.append((data, options))
return data["id"]
backend._get_backend_for_context = lambda _ctx: _BoundBackend()
@@ -1832,11 +1903,13 @@ async def test_viking_vector_index_backend_upsert_partial_update_delegates_to_ac
result = await backend.upsert(
{"id": "rec-1", "abstract": "patched"},
ctx=ctx,
- partial_update=True,
+ options=UpsertOptions(partial_update=True, search_tag_mode="append"),
)
assert result == "rec-1"
- assert calls == [({"id": "rec-1", "abstract": "patched"}, True)]
+ assert calls == [
+ ({"id": "rec-1", "abstract": "patched"}, UpsertOptions(True, "append"))
+ ]
@pytest.mark.asyncio
@@ -1852,10 +1925,10 @@ async def test_vikingdb_manager_proxy_upsert_partial_update_forwards_bound_conte
has_queue_manager = False
is_closing = False
- async def upsert(self, data, *, ctx, partial_update=False):
+ async def upsert(self, data, *, ctx, options=UpsertOptions()):
captured["data"] = data
captured["ctx"] = ctx
- captured["partial_update"] = partial_update
+ captured["options"] = options
return data["id"]
from openviking.storage.vikingdb_manager import VikingDBManagerProxy
@@ -1863,17 +1936,30 @@ async def test_vikingdb_manager_proxy_upsert_partial_update_forwards_bound_conte
proxy = VikingDBManagerProxy(_Manager(), ctx)
result = await proxy.upsert(
{"id": "rec-1", "abstract": "patched"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True, search_tag_mode="append"),
)
assert result == "rec-1"
assert captured == {
"data": {"id": "rec-1", "abstract": "patched"},
"ctx": ctx,
- "partial_update": True,
+ "options": UpsertOptions(True, "append"),
}
+def test_storage_upsert_signatures_use_options_instead_of_partial_update():
+ from openviking.storage.vikingdb_manager import VikingDBManagerProxy
+
+ for method in (
+ _SingleAccountBackend.upsert,
+ VikingVectorIndexBackend.upsert,
+ VikingDBManagerProxy.upsert,
+ ):
+ signature = inspect.signature(method)
+ assert "options" in signature.parameters
+ assert "partial_update" not in signature.parameters
+
+
@pytest.mark.asyncio
async def test_qdrant_backend_upsert_partial_update_reads_then_upserts_existing_record():
calls = []
@@ -1921,7 +2007,7 @@ async def test_qdrant_backend_upsert_partial_update_reads_then_upserts_existing_
result = await backend.upsert(
{"id": "doc-1", "uri": "viking://resources/qdrant", "abstract": "patched"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "doc-1"
@@ -1985,7 +2071,7 @@ async def test_qdrant_backend_upsert_partial_update_creates_when_record_does_not
result = await backend.upsert(
{"id": "doc-404", "uri": "viking://resources/qdrant/new", "abstract": "created"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "doc-404"
@@ -2051,7 +2137,7 @@ async def test_volcengine_backend_upsert_partial_update_reads_then_upserts_exist
result = await backend.upsert(
{"id": "doc-1", "uri": "viking://resources/volc", "abstract": "patched"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "doc-1"
@@ -2115,7 +2201,7 @@ async def test_volcengine_backend_upsert_partial_update_creates_when_record_does
result = await backend.upsert(
{"id": "doc-404", "uri": "viking://resources/volc/new", "abstract": "created"},
- partial_update=True,
+ options=UpsertOptions(partial_update=True),
)
assert result == "doc-404"
@@ -2150,8 +2236,8 @@ async def test_viking_vector_index_backend_update_search_tags_updates_exact_uri_
calls["get"].append((list(ids), ctx.account_id))
return [{"id": "root-id", "uri": resource_uri, "search_tags": ["old=root"]}]
- async def _fake_upsert(data, *, ctx, partial_update=False):
- del ctx, partial_update
+ async def _fake_upsert(data, *, ctx, options=UpsertOptions()):
+ del ctx, options
calls["upsert"].append(dict(data))
return data["id"]
@@ -2193,8 +2279,8 @@ async def test_update_search_tags_for_leaf_uri_queries_exact_uri_only(monkeypatc
calls["get"].append((list(ids), ctx.account_id))
return [{"id": "overview-id", "uri": overview_uri, "search_tags": ["existing=1"]}]
- async def _fake_upsert(data, *, ctx, partial_update=False):
- del ctx, partial_update
+ async def _fake_upsert(data, *, ctx, options=UpsertOptions()):
+ del ctx, options
calls["upsert"].append(dict(data))
return data["id"]
@@ -2241,8 +2327,8 @@ async def test_update_search_tags_with_levels_queries_directory_uri_only():
{"id": "dir-l1", "uri": directory_uri, "level": 1, "search_tags": ["old=1"]},
]
- async def _fake_upsert(data, *, ctx, partial_update=False):
- del ctx, partial_update
+ async def _fake_upsert(data, *, ctx, options=UpsertOptions()):
+ del ctx, options
calls["upsert"].append(dict(data))
return data["id"]
@@ -2307,8 +2393,8 @@ async def test_update_search_tags_with_levels_skips_records_without_id_and_priva
{"id": "r2", "uri": "viking://resources/demo/doc.md", "level": 2, "search_tags": None},
]
- async def _fake_upsert(data, *, ctx, partial_update=False):
- del ctx, partial_update
+ async def _fake_upsert(data, *, ctx, options=UpsertOptions()):
+ del ctx, options
calls["upsert"].append(dict(data))
return data["id"]
diff --git a/tests/storage/test_semantic_msg_ingest_options.py b/tests/storage/test_semantic_msg_ingest_options.py
new file mode 100644
index 000000000..a828c1469
--- /dev/null
+++ b/tests/storage/test_semantic_msg_ingest_options.py
@@ -0,0 +1,41 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from openviking.utils.ingest_options import IngestOptions
+from openviking.storage.queuefs.semantic_msg import SemanticMsg
+
+
+def test_semantic_msg_serializes_ingest_options():
+ msg = SemanticMsg(
+ uri="viking://resources/demo",
+ context_type="resource",
+ ingest_options=IngestOptions(search_tags=["team=search"], search_tag_mode="append"),
+ )
+
+ data = msg.to_dict()
+
+ assert data["ingest_options"] == {
+ "search_tags": ["team=search"],
+ "search_tag_mode": "append",
+ }
+ restored = SemanticMsg.from_dict(data)
+ assert restored.ingest_options == IngestOptions(
+ search_tags=["team=search"],
+ search_tag_mode="append",
+ )
+
+
+def test_semantic_msg_reads_legacy_search_tag_fields():
+ msg = SemanticMsg.from_dict(
+ {
+ "uri": "viking://resources/demo",
+ "context_type": "resource",
+ "search_tags": ["team=search"],
+ "search_tag_mode": "append",
+ }
+ )
+
+ assert msg.ingest_options == IngestOptions(
+ search_tags=["team=search"],
+ search_tag_mode="append",
+ )
diff --git a/tests/unit/test_add_resource_client_signatures.py b/tests/unit/test_add_resource_client_signatures.py
new file mode 100644
index 000000000..6835ce520
--- /dev/null
+++ b/tests/unit/test_add_resource_client_signatures.py
@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import inspect
+
+from openviking.async_client import AsyncOpenViking
+from openviking.client.local import LocalClient
+from openviking.sync_client import SyncOpenViking
+from openviking_cli.client.base import BaseClient
+
+
+def _assert_add_resource_keeps_telemetry_before_tags(func):
+ params = list(inspect.signature(func).parameters)
+ assert params.index("telemetry") < params.index("tags")
+ assert params.index("telemetry") < params.index("tag_mode")
+
+
+def test_top_level_add_resource_signatures_keep_telemetry_position():
+ _assert_add_resource_keeps_telemetry_before_tags(AsyncOpenViking.add_resource)
+ _assert_add_resource_keeps_telemetry_before_tags(SyncOpenViking.add_resource)
+ _assert_add_resource_keeps_telemetry_before_tags(LocalClient.add_resource)
+ _assert_add_resource_keeps_telemetry_before_tags(BaseClient.add_resource)
diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.py
index d3f139098..8367db427 100644
--- a/tests/unit/test_vectorize_file_strategy.py
+++ b/tests/unit/test_vectorize_file_strategy.py
@@ -2,6 +2,7 @@ import types
import pytest
+from openviking.utils.ingest_options import IngestOptions
from openviking.core.context import Context, ResourceContentType
from openviking.utils import embedding_utils
@@ -235,6 +236,144 @@ async def test_vectorize_unknown_text_file_embeds_summary_but_indexes_raw_conten
assert msg.context_data["content"] == raw_makefile
+async def test_vectorize_file_writes_search_tags_into_embedding_context(monkeypatch):
+ queue = DummyQueue()
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("deployment guide"))
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_openviking_config",
+ lambda: types.SimpleNamespace(
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)
+ ),
+ )
+
+ await embedding_utils.vectorize_file(
+ file_path="viking://user/default/resources/demo.md",
+ summary_dict={"name": "demo.md", "summary": "deployment summary"},
+ parent_uri="viking://user/default/resources",
+ ctx=DummyReq(),
+ ingest_options=IngestOptions.from_search_tags(["team=search", "env=test"]),
+ )
+
+ assert len(queue.items) == 1
+ msg = queue.items[0]
+ assert msg.context_data["search_tags"] == ["team=search", "env=test"]
+
+
+async def test_vectorize_file_appends_search_tags_to_existing_record_tags(monkeypatch):
+ queue = DummyQueue()
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("deployment guide"))
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_openviking_config",
+ lambda: types.SimpleNamespace(
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)
+ ),
+ )
+
+ await embedding_utils.vectorize_file(
+ file_path="viking://user/default/resources/demo.md",
+ summary_dict={"name": "demo.md", "summary": "deployment summary"},
+ parent_uri="viking://user/default/resources",
+ ctx=DummyReq(),
+ ingest_options=IngestOptions.from_search_tags(
+ ["env=prod", "team=search"],
+ mode="append",
+ ),
+ )
+
+ assert len(queue.items) == 1
+ msg = queue.items[0]
+ assert msg.context_data["search_tags"] == ["env=prod", "team=search"]
+ assert msg.context_data["_upsert_options"] == {"search_tag_mode": "append"}
+
+
+async def test_vectorize_file_append_does_not_read_existing_tags(monkeypatch):
+ queue = DummyQueue()
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("deployment guide"))
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_openviking_config",
+ lambda: types.SimpleNamespace(
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)
+ ),
+ )
+
+ class DummyVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("vectorize must not read existing tags")
+
+ monkeypatch.setattr(
+ "openviking.server.dependencies.get_service",
+ lambda: types.SimpleNamespace(vikingdb_manager=DummyVikingDB()),
+ )
+
+ await embedding_utils.vectorize_file(
+ file_path="viking://user/default/resources/demo.md",
+ summary_dict={"name": "demo.md", "summary": "deployment summary"},
+ parent_uri="viking://user/default/resources",
+ ctx=DummyReq(),
+ ingest_options=IngestOptions.from_search_tags(
+ ["env=prod", "team=search"],
+ mode="append",
+ ),
+ )
+
+ assert queue.items[0].context_data["search_tags"] == ["env=prod", "team=search"]
+ assert queue.items[0].context_data["_upsert_options"] == {"search_tag_mode": "append"}
+
+
+async def test_vectorize_directory_meta_writes_search_tags_into_embedding_context(monkeypatch):
+ queue = DummyQueue()
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("ignored"))
+
+ await embedding_utils.vectorize_directory_meta(
+ uri="viking://user/default/resources/demo",
+ abstract="demo abstract",
+ overview="demo overview",
+ ctx=DummyReq(),
+ ingest_options=IngestOptions.from_search_tags(["team=search", "env=test"]),
+ )
+
+ assert len(queue.items) == 2
+ for msg in queue.items:
+ assert msg.context_data["search_tags"] == ["team=search", "env=test"]
+
+
+async def test_vectorize_directory_meta_appends_search_tags_by_level(monkeypatch):
+ queue = DummyQueue()
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("ignored"))
+
+ await embedding_utils.vectorize_directory_meta(
+ uri="viking://user/default/resources/demo",
+ abstract="demo abstract",
+ overview="demo overview",
+ ctx=DummyReq(),
+ ingest_options=IngestOptions.from_search_tags(
+ ["env=prod", "team=search"],
+ mode="append",
+ ),
+ )
+
+ assert len(queue.items) == 2
+ assert queue.items[0].context_data["level"] == 0
+ assert queue.items[0].context_data["search_tags"] == ["env=prod", "team=search"]
+ assert queue.items[0].context_data["_upsert_options"] == {"search_tag_mode": "append"}
+ assert queue.items[1].context_data["level"] == 1
+ assert queue.items[1].context_data["search_tags"] == ["env=prod", "team=search"]
+ assert queue.items[1].context_data["_upsert_options"] == {"search_tag_mode": "append"}
+
+
@pytest.mark.asyncio
async def test_vectorize_unknown_text_file_sniffs_non_utf8_raw_content(monkeypatch):
queue = DummyQueue()
diff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.py
index 274f03aa4..d2b39836c 100644
--- a/tests/utils/test_resource_processor_processing_mode.py
+++ b/tests/utils/test_resource_processor_processing_mode.py
@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock, Mock
import pytest
+from openviking.utils.ingest_options import IngestOptions
from openviking.server.identity import RequestContext, Role
from openviking.utils.resource_processor import ResourceProcessor
from openviking_cli.session.user_id import UserIdentifier
@@ -90,6 +91,7 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,
resource_lock=lock,
build_index=True,
processing_mode="vectors_only",
+ ingest_options=IngestOptions.from_search_tags(["team=search"], mode="append"),
)
assert result == {"status": "success", "root_uri": "viking://resources/demo"}
@@ -111,6 +113,10 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,
"name": "page.md",
"summary": "",
}
+ assert vectorize_file.await_args.kwargs["ingest_options"] == IngestOptions(
+ search_tags=["team=search"],
+ search_tag_mode="append",
+ )
assert vectorize_file.await_args.kwargs["register_request_wait"] is True
processor._delete_resource_semantic_markers.assert_not_awaited()
processor._delete_resource_semantic_vectors.assert_not_awaited()