Skip to content

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

Feat/add resource processing mode (#3566)

Jiahui Zhou5d1ba45be49e
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index e2bd1ebb5..87ad102da 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -31,6 +31,9 @@ fn compact_request_body(body: &mut Value) {
return !map.is_empty();
}
}
+ if key == "processing_mode" {
+ return value != "semantic_and_vectors";
+ }
true
});
}
@@ -616,6 +619,7 @@ impl HttpClient {
exclude: Option<String>,
directly_upload_media: bool,
watch_interval: f64,
+ processing_mode: String,
resource_args: Option<Map<String, Value>>,
show_progress: bool,
verbose: bool,
@@ -678,6 +682,7 @@ impl HttpClient {
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
+ "processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
@@ -713,6 +718,7 @@ impl HttpClient {
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
+ "processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
@@ -736,6 +742,7 @@ impl HttpClient {
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
+ "processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
@@ -756,6 +763,7 @@ impl HttpClient {
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
+ "processing_mode": processing_mode.as_str(),
"args": args,
}));
@@ -1752,6 +1760,26 @@ mod tests {
assert!(body.as_object().unwrap().contains_key("args"));
}
+ #[test]
+ fn compact_request_body_drops_default_processing_mode_for_legacy_servers() {
+ let mut body = json!({
+ "path": "https://example.com/guide.md",
+ "processing_mode": "semantic_and_vectors",
+ });
+ super::compact_request_body(&mut body);
+ assert!(!body.as_object().unwrap().contains_key("processing_mode"));
+ }
+
+ #[test]
+ fn compact_request_body_keeps_non_default_processing_mode() {
+ let mut body = json!({
+ "path": "https://example.com/guide.md",
+ "processing_mode": "vectors_only",
+ });
+ super::compact_request_body(&mut body);
+ assert_eq!(body["processing_mode"], "vectors_only");
+ }
+
#[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 3520827a2..ccc777c0f 100644
--- a/crates/ov_cli/src/commands/resources.rs
+++ b/crates/ov_cli/src/commands/resources.rs
@@ -19,6 +19,7 @@ pub async fn add_resource(
exclude: Option<String>,
directly_upload_media: bool,
watch_interval: f64,
+ processing_mode: String,
resource_args: Option<Map<String, Value>>,
format: OutputFormat,
compact: bool,
@@ -41,6 +42,7 @@ pub async fn add_resource(
exclude,
directly_upload_media,
watch_interval,
+ processing_mode,
resource_args,
show_progress,
verbose,
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 8ff7447f0..2947d5e11 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -28,6 +28,7 @@ pub async fn handle_add_resource(
exclude: Option<String>,
no_directly_upload_media: bool,
watch_interval: f64,
+ processing_mode: String,
resource_args: Option<String>,
ctx: CliContext,
) -> Result<()> {
@@ -108,6 +109,7 @@ pub async fn handle_add_resource(
effective_exclude,
directly_upload_media,
watch_interval,
+ processing_mode,
add_resource_args,
ctx.output_format,
ctx.compact,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 7178d4801..43ad4adbd 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -349,6 +349,14 @@ enum Commands {
help_heading = "Advanced options"
)]
watch_interval: f64,
+ /// Resource processing mode
+ #[arg(
+ long = "processing-mode",
+ default_value = "semantic_and_vectors",
+ value_parser = ["semantic_and_vectors", "vectors_only"],
+ help_heading = "Advanced options"
+ )]
+ processing_mode: String,
/// Parser-specific import options, e.g. --args feishu_access_token:u-xxx
#[arg(long = "args")]
resource_args: Option<String>,
@@ -2766,6 +2774,7 @@ async fn main() {
exclude,
no_directly_upload_media,
watch_interval,
+ processing_mode,
resource_args,
upload_options,
} => {
@@ -2786,6 +2795,7 @@ async fn main() {
exclude,
no_directly_upload_media,
watch_interval,
+ processing_mode,
resource_args,
ctx,
)
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index 301b4fbc9..d0a2ccb64 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -138,16 +138,17 @@ Add a resource to the knowledge base. The SDK supports local files/directories,
#### 1. API Implementation Overview
-This endpoint is the core entry point for resource management, supporting adding resources from various sources with optional waiting for semantic processing completion.
+This endpoint is the core entry point for resource management, supporting adding resources from various sources with optional waiting for semantic processing and vectorization completion.
**Processing Flow**:
1. Identify and validate the resource source (URL or uploaded temporary file)
2. Resolve the target URI
3. Call the corresponding Parser to parse content
4. Build the directory tree and write to AGFS
-5. Wait for semantic processing completion when `wait=true`; with `wait=false`, return a `task_id` for queue tracking
-6. If `reason` is non-empty, append it to the fixed resource reason session and commit through the normal memory extraction pipeline so suitable user memories can reference the resource URI
-7. Set up scheduled update task if `watch_interval` is specified
+5. Run post-ingest processing according to `processing_mode`: `semantic_and_vectors` generates semantic artifacts and vectors; `vectors_only` skips semantic understanding and only enqueues file vectorization
+6. Wait for semantic processing/vectorization completion when `wait=true`; with `wait=false`, return a `task_id` for queue tracking
+7. If `reason` is non-empty, append it to the fixed resource reason session and commit through the normal memory extraction pipeline so suitable user memories can reference the resource URI
+8. Set up scheduled update task if `watch_interval` is specified
**Code Entry Points**:
- `openviking/client/local.py:LocalClient.add_resource` - SDK entry (embedded)
@@ -179,6 +180,7 @@ This endpoint is the core entry point for resource management, supporting adding
| preserve_structure | bool | No | None | Whether to preserve directory structure |
| args | object | No | `{}` | Parser-specific import options forwarded to the source parser/accessor. E.g. `args.site=true/false` forces/opts out of whole-site (sitemap/RSS) ingestion, `args.max_pages` etc. override the `webfeed` config; the recursive web crawler accepts `args.depth`, `args.max_pages`, `args.include_paths`, `args.exclude_paths`, `args.allow_external_links`, `args.skip_download_links`; Feishu user-token imports pass `args.feishu_access_token`. Core `add_resource` fields such as `path`, `to`, `watch_interval`, `include`, and `exclude` are not allowed inside `args` |
| watch_interval | float | No | 0 | Scheduled update interval (minutes). >0 creates a task for a re-readable URL/sitemap/RSS source; uploaded `temp_file_id` content is a one-time snapshot and must be re-added when it changes. <=0 cancels a task; explicit `to` wins, otherwise binds to the imported `root_uri` |
+| processing_mode | string | No | `semantic_and_vectors` | Post-ingest processing mode. `semantic_and_vectors` is the normal flow: generate semantic artifacts (`.abstract.md`, `.overview.md`) and vectors. `vectors_only` skips semantic understanding/VLM summarization and only vectorizes current resource files |
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
**Additional Notes**:
@@ -193,6 +195,8 @@ This endpoint is the core entry point for resource management, supporting adding
- Memory generated from `reason` is extracted through the same pipeline as `session.commit`. It uses `reason`, the resource URI, available source name, and available directory abstract; it does not inspect or expand the full resource content. OpenViking writes to existing memory types such as `entities`, `events`, or `preferences`, not a dedicated resource memory directory.
- When deleting a resource, OpenViking scans the self or peer memories targeted by the current context before deletion, removes the matching resource URI and content introduced by that `reason`, and refreshes the semantic index for the affected memories.
- Other sources with `wait=false` finish source parsing, target resolution, and AGFS writes before returning. Only semantic and embedding queues continue asynchronously.
+- `processing_mode=vectors_only` does not call the VLM semantic-understanding stage and does not generate or refresh `.abstract.md` / `.overview.md`. For existing targets, it preserves existing semantic artifacts and existing semantic vectors. It still updates the resource tree, vectorizes current non-hidden files when `build_index=true`, and removes detail vectors for files deleted during refresh.
+- `processing_mode` belongs to `add_resource`. The admin `reindex` API/CLI continues to use `mode` (`vectors_only`, `semantic_and_vectors`, `prune_orphans`) for maintenance operations on already-ingested data.
- When `watch_interval > 0`, the watch task binds to `to` if provided; otherwise it binds to the `root_uri` returned by this import. If no stable `root_uri` is available, the request fails and asks for an explicit `to`.
- Feishu/Lark app-token imports do not pass `args.feishu_access_token`. OpenViking keeps the existing app credential flow and the SDK obtains an app/tenant token from `app_id` and `app_secret`. This mode supports both one-time imports and `watch_interval > 0`.
- Feishu/Lark one-time user-token imports pass `args={"feishu_access_token": "u-..."}` with `watch_interval <= 0`. OpenViking uses that user token only for the current import and does not store it.
@@ -222,6 +226,17 @@ curl -X POST http://localhost:1933/api/v1/resources \
"wait": true
}'
+# Add a resource and only build vectors, without VLM semantic understanding
+curl -X POST http://localhost:1933/api/v1/resources \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "path": "https://example.com/guide.md",
+ "to": "viking://resources/guide",
+ "processing_mode": "vectors_only",
+ "wait": true
+ }'
+
# Recursively crawl a site: expand along same-host links; depth bounds
# how many levels, max_pages bounds how many pages are collected
curl -X POST http://localhost:1933/api/v1/resources \
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index b20ffc7e4..929d69b52 100644
--- a/docs/en/guides/06-mcp-integration.md
+++ b/docs/en/guides/06-mcp-integration.md
@@ -139,7 +139,7 @@ Once connected, OpenViking exposes 16 tools:
| `read` | Read one or more `viking://` URIs | `uris` (single string or array) |
| `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |
| `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |
-| `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, such as `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}` for Feishu user-token watches) |
+| `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `processing_mode` (optional: `semantic_and_vectors` default, or `vectors_only` to skip VLM semantic understanding and only vectorize current files), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, such as `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}` for Feishu user-token watches) |
| `list_watches` | List watch tasks (auto-refresh subscriptions) visible to the current agent. Each entry shows target URI, refresh interval (minutes), active/paused status, and next scheduled execution time | none |
| `cancel_watch` | Cancel (delete) a watch task by its target URI. To change the cadence or pause temporarily, cancel and re-add with a new `watch_interval` | `to_uri` (must match the watch task's `to` value, e.g. `viking://resources/...`) |
| `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string or array), `case_insensitive`, `node_limit` |
@@ -154,6 +154,8 @@ Once connected, OpenViking exposes 16 tools:
> Feishu/Lark imports without `args.feishu_access_token` keep the existing app/tenant-token behavior and can be watched. Feishu/Lark one-time user-token imports pass only `args.feishu_access_token`; Feishu/Lark user-token watches must also pass `args.feishu_refresh_token` and require the same Feishu app credentials configured on the OpenViking server.
+> `processing_mode=vectors_only` skips the VLM semantic-understanding stage. It does not generate or refresh `.abstract.md` / `.overview.md`; it only vectorizes current non-hidden resource files, preserving any older semantic artifacts that already exist.
+
### Adding local-file resources (single-step upload)
The `add_resource` tool accepts both **remote URLs** and **local file paths**, handled differently:
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index f3e0d8064..f2338a5e0 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -138,9 +138,10 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
2. 解析目标 URI
3. 调用对应 Parser 解析内容
4. 构建目录树并写入 AGFS
-5. `wait=true` 时等待语义处理完成;`wait=false` 时返回 `task_id` 用于队列跟踪
-6. 如果 `reason` 非空,将其追加到固定的资源 reason session 并 commit,复用常规记忆抽取链路,让合适的用户记忆引用该资源 URI
-7. 如指定 `--watch-interval`,设置定时更新任务
+5. 按 `processing_mode` 执行入库后的处理:`semantic_and_vectors` 生成语义产物和向量;`vectors_only` 跳过语义理解,只提交文件向量化
+6. `wait=true` 时等待语义处理/向量化完成;`wait=false` 时返回 `task_id` 用于队列跟踪
+7. 如果 `reason` 非空,将其追加到固定的资源 reason session 并 commit,复用常规记忆抽取链路,让合适的用户记忆引用该资源 URI
+8. 如指定 `--watch-interval`,设置定时更新任务
**代码入口**:
- `openviking/client/local.py:LocalClient.add_resource` - SDK 入口(嵌入式)
@@ -172,6 +173,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| preserve_structure | bool | 否 | None | 是否保留目录结构 |
| 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 总结,只对当前资源文件生成向量 |
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
**补充说明**:
@@ -184,6 +186,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
- `reason` 触发的记忆生成复用 `session.commit` 的抽取链路,只使用 `reason`、资源 URI、可用的资源名称和目录摘要,不会读取或展开完整资源正文;系统会写入 `entities`、`events`、`preferences` 等已有记忆类型,不创建独立的资源记忆目录。
- 删除资源时,系统会在删除前扫描本次上下文对应的 self 或 peer 记忆中的 `resource_refs`,清理对应资源 URI 和由该 `reason` 引入的内容,并重新刷新相关记忆的语义索引。
- 其他来源在 `wait=false` 时会在响应前完成来源解析、目标解析和 AGFS 写入,仅 semantic 与 embedding 队列继续异步处理。
+- `processing_mode=vectors_only` 不调用 VLM 语义理解阶段,也不会生成或刷新 `.abstract.md` / `.overview.md`。对已存在目标,它会保留旧的语义产物和旧的语义向量;仍会更新资源树,在 `build_index=true` 时向量化当前非隐藏文件,并清理由本次刷新删除的文件 detail 向量。
+- `processing_mode` 只属于 `add_resource`。管理员维护已有数据时,`reindex` API/CLI 仍使用 `mode`(`vectors_only`、`semantic_and_vectors`、`prune_orphans`)。
- `watch_interval > 0` 时,如果指定了 `to`,监控任务绑定该目标;如果未指定 `to`,监控任务绑定本次导入返回的 `root_uri`。如果无法得到稳定 `root_uri`,请求会报错并要求显式传 `to`。
- 飞书/Lark 应用 token 导入不传 `args.feishu_access_token`。OpenViking 保持原有应用凭证流程,由 SDK 使用 `app_id` 和 `app_secret` 自动获取 app/tenant token。该模式支持一次性导入和 `watch_interval > 0`。
- 飞书/Lark 一次性用户 token 导入通过 `args={"feishu_access_token": "u-..."}` 传入,且 `watch_interval <= 0`。OpenViking 只在本次导入使用该用户 token,不保存。
@@ -213,6 +217,17 @@ curl -X POST http://localhost:1933/api/v1/resources \
"wait": true
}'
+# 添加资源但只生成向量,不走 VLM 语义理解
+curl -X POST http://localhost:1933/api/v1/resources \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "path": "https://example.com/guide.md",
+ "to": "viking://resources/guide",
+ "processing_mode": "vectors_only",
+ "wait": true
+ }'
+
# 递归抓取网页:从入口页沿同域链接展开,depth 控制层数,max_pages 限制页数
curl -X POST http://localhost:1933/api/v1/resources \
-H "Content-Type: application/json" \
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index 2fad231da..0cf549f44 100644
--- a/docs/zh/guides/06-mcp-integration.md
+++ b/docs/zh/guides/06-mcp-integration.md
@@ -131,7 +131,7 @@ claude mcp add --transport http openviking \
| `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) |
| `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) |
| `remember` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |
-| `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,例如飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,飞书用户 token watch 使用 `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}`) |
+| `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `processing_mode`(可选:默认 `semantic_and_vectors`;传 `vectors_only` 时跳过 VLM 语义理解,只向量化当前文件), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,例如飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,飞书用户 token watch 使用 `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}`) |
| `list_watches` | 列出当前 Agent 可见的 watch 任务(自动刷新订阅),每行显示目标 URI、刷新间隔(分钟)、active/paused 状态以及下一次调度时间 | 无 |
| `cancel_watch` | 按目标 URI 取消(删除)watch 任务。若需调整刷新周期或临时暂停,请取消后使用新的 `watch_interval` 重新添加 | `to_uri`(必须匹配 watch 任务的 `to` 值,例如 `viking://resources/...`) |
| `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive`, `node_limit` |
@@ -146,6 +146,8 @@ claude mcp add --transport http openviking \
> 未传 `args.feishu_access_token` 的飞书/Lark 导入保持现有应用/tenant token 行为,也支持 watch。飞书/Lark 一次性用户 token 导入只传 `args.feishu_access_token`;飞书/Lark 用户 token watch 还必须传 `args.feishu_refresh_token`,并要求 OpenViking 服务端配置同一个飞书应用凭证。
+> `processing_mode=vectors_only` 会跳过 VLM 语义理解阶段,不生成或刷新 `.abstract.md` / `.overview.md`;它只向量化当前非隐藏资源文件,并保留已存在的旧语义产物。
+
### 添加本地文件资源(单步上传)
`add_resource` 工具同时接受**远程 URL** 和**本地文件路径**。两者的处理路径不同:
diff --git a/openviking/async_client.py b/openviking/async_client.py
index ae71027bd..19b75be32 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -329,6 +329,7 @@ class AsyncOpenViking:
watch_interval: float = 0,
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
+ processing_mode: str = "semantic_and_vectors",
**kwargs,
) -> Dict[str, Any]:
"""
@@ -345,6 +346,8 @@ class AsyncOpenViking:
parent: Target parent URI (must already exist).
build_index: Whether to build vector index immediately (default: True).
summarize: Whether to generate summary (default: False).
+ processing_mode: "semantic_and_vectors" for normal semantic processing,
+ or "vectors_only" to only build vector indexes.
watch_interval: Auto-refresh interval in minutes (>0 enables a watch).
On a sitemap/feed URL this keeps the whole site refreshed.
args: Parser/accessor-specific options (e.g. ``site``, ``max_pages``).
@@ -365,6 +368,7 @@ class AsyncOpenViking:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
telemetry=telemetry,
watch_interval=watch_interval,
args=args,
diff --git a/openviking/client/local.py b/openviking/client/local.py
index 0233b28d0..ae56c5c8e 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -138,6 +138,7 @@ class LocalClient(BaseClient):
telemetry: TelemetryRequest = False,
watch_interval: float = 0,
args: Optional[Dict[str, Any]] = None,
+ processing_mode: str = "semantic_and_vectors",
**kwargs,
) -> Dict[str, Any]:
"""Add resource to OpenViking."""
@@ -158,6 +159,7 @@ class LocalClient(BaseClient):
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
args=args,
**kwargs,
diff --git a/openviking/resource/processing_mode.py b/openviking/resource/processing_mode.py
new file mode 100644
index 000000000..b169bfb42
--- /dev/null
+++ b/openviking/resource/processing_mode.py
@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Resource post-ingest processing modes."""
+
+from typing import Literal
+
+SEMANTIC_AND_VECTORS = "semantic_and_vectors"
+VECTORS_ONLY = "vectors_only"
+
+ProcessingMode = Literal["semantic_and_vectors", "vectors_only"]
+DEFAULT_PROCESSING_MODE: ProcessingMode = SEMANTIC_AND_VECTORS
+SUPPORTED_PROCESSING_MODES = frozenset({SEMANTIC_AND_VECTORS, VECTORS_ONLY})
+
+
+def normalize_processing_mode(value: str | None) -> ProcessingMode:
+ mode = value or DEFAULT_PROCESSING_MODE
+ if mode not in SUPPORTED_PROCESSING_MODES:
+ supported = ", ".join(sorted(SUPPORTED_PROCESSING_MODES))
+ raise ValueError(f"Invalid processing_mode '{mode}'. Supported values: {supported}")
+ return mode # type: ignore[return-value]
diff --git a/openviking/resource/watch_manager.py b/openviking/resource/watch_manager.py
index de6a9b499..ec4a93db8 100644
--- a/openviking/resource/watch_manager.py
+++ b/openviking/resource/watch_manager.py
@@ -15,6 +15,7 @@ from typing import Any, Awaitable, Callable, Dict, List, Optional
from pydantic import BaseModel, Field
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.resource.watch_storage import (
WATCH_TASK_STORAGE_BAK_URI,
WATCH_TASK_STORAGE_TMP_URI,
@@ -67,6 +68,10 @@ class WatchTask(BaseModel):
watch_interval: float = Field(default=60.0, description="Monitoring interval in minutes")
build_index: bool = Field(default=True, description="Whether to build vector index")
summarize: bool = Field(default=False, description="Whether to generate summary")
+ processing_mode: ProcessingMode = Field(
+ default=DEFAULT_PROCESSING_MODE,
+ description="Post-ingest processing mode for scheduled add_resource runs",
+ )
processor_kwargs: Dict[str, Any] = Field(
default_factory=dict, description="Extra kwargs forwarded to processor"
)
@@ -97,6 +102,7 @@ class WatchTask(BaseModel):
"watch_interval": self.watch_interval,
"build_index": self.build_index,
"summarize": self.summarize,
+ "processing_mode": self.processing_mode,
"processor_kwargs": self.processor_kwargs,
"created_at": self.created_at.isoformat() if self.created_at else None,
"last_execution_time": self.last_execution_time.isoformat()
@@ -384,6 +390,7 @@ class WatchManager:
watch_interval: float = 60.0,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
processor_kwargs: Optional[Dict[str, Any]] = None,
auth_state: Optional[Dict[str, Any]] = None,
) -> WatchTask:
@@ -427,6 +434,7 @@ class WatchManager:
watch_interval=watch_interval,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=processor_kwargs or {},
auth_state=auth_state,
account_id=account_id,
@@ -461,6 +469,7 @@ class WatchManager:
watch_interval: Optional[float] = None,
build_index: Optional[bool] = None,
summarize: Optional[bool] = None,
+ processing_mode: Optional[ProcessingMode] = None,
processor_kwargs: Optional[Dict[str, Any]] = None,
auth_state: Any = _UNSET,
is_active: Optional[bool] = None,
@@ -531,6 +540,8 @@ class WatchManager:
task.build_index = build_index
if summarize is not None:
task.summarize = summarize
+ if processing_mode is not None:
+ task.processing_mode = processing_mode
if processor_kwargs is not None:
task.processor_kwargs = processor_kwargs
if auth_state is not _UNSET:
diff --git a/openviking/resource/watch_scheduler.py b/openviking/resource/watch_scheduler.py
index d3fa5e063..8e7e3aca5 100644
--- a/openviking/resource/watch_scheduler.py
+++ b/openviking/resource/watch_scheduler.py
@@ -291,6 +291,7 @@ class WatchScheduler:
instruction=task.instruction,
build_index=getattr(task, "build_index", True),
summarize=getattr(task, "summarize", False),
+ processing_mode=getattr(task, "processing_mode", "semantic_and_vectors"),
watch_interval=task.watch_interval,
**processor_kwargs,
)
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 88fb8a7d4..f9650f661 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -38,6 +38,7 @@ from openviking.parse.parsers.code.ast.code_tools import (
outline_file,
search_symbols,
)
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.retrieve.type_quota_recall import (
DEFAULT_MAX_CHARS,
DEFAULT_MIN_SCORE,
@@ -549,6 +550,7 @@ async def add_resource(
temp_file_id: str = "",
description: str = "",
watch_interval: float = 0,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
to: str = "",
parent: str = "",
args: Optional[dict[str, Any]] = None,
@@ -570,6 +572,8 @@ async def add_resource(
watch_interval: Auto-refresh cadence in minutes. 0 = no watch. Prefer >=1440 (24h)
unless the source changes faster — every refresh re-embeds the whole resource.
Only applies to remote-URL invocations.
+ processing_mode: "semantic_and_vectors" for normal semantic processing, or
+ "vectors_only" to skip semantic understanding and only build vector indexes.
to: Target URI under viking://resources/ (e.g. "viking://resources/volcengine/OpenViking").
Leave empty to derive a URI from the source.
parent: Parent URI under viking://resources/ for remote imports. Mutually exclusive
@@ -597,7 +601,13 @@ async def add_resource(
store = TempUploadStore.build(server_config)
try:
result = await ingest_temp_upload(
- store, temp_file_id, ctx, to=to, reason=description, args=args
+ store,
+ temp_file_id,
+ ctx,
+ to=to,
+ reason=description,
+ args=args,
+ processing_mode=processing_mode,
)
except (PermissionDeniedError, InvalidArgumentError) as exc:
return f"Error: {exc}"
@@ -642,6 +652,7 @@ async def add_resource(
reason=description,
wait=False,
watch_interval=watch_interval,
+ processing_mode=processing_mode,
enforce_public_remote_targets=True,
args=args,
)
@@ -684,6 +695,7 @@ async def add_resource(
to=to,
reason=description,
actor_peer_id=ctx.actor_peer_id or "",
+ processing_mode=processing_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 23f9760e2..267bfc0b1 100644
--- a/openviking/server/resource_ingest.py
+++ b/openviking/server/resource_ingest.py
@@ -12,6 +12,7 @@ from __future__ import annotations
from typing import Any, Optional
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.temp_upload_store import TempUploadStore
@@ -25,6 +26,7 @@ async def ingest_temp_upload(
to: str = "",
reason: str = "",
args: Optional[dict[str, Any]] = None,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
) -> dict[str, Any]:
"""Resolve a temp upload and ingest it as a resource; return the raw add_resource result.
@@ -47,6 +49,7 @@ async def ingest_temp_upload(
reason=reason,
source_name=resolved.original_filename,
wait=False,
+ processing_mode=processing_mode,
allow_local_path_resolution=True,
enforce_public_remote_targets=True,
args=args,
diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.py
index 75d21b55d..ed73f8fab 100644
--- a/openviking/server/routers/resources.py
+++ b/openviking/server/routers/resources.py
@@ -7,6 +7,7 @@ from typing import Any, Dict, Literal, Optional
from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
from pydantic import BaseModel, ConfigDict, Field, model_validator
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.server.auth import get_request_context, get_upload_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
@@ -85,6 +86,7 @@ class AddResourceRequest(BaseModel):
args: Dict[str, Any] = Field(default_factory=dict)
telemetry: TelemetryRequest = False
watch_interval: float = 0
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
@model_validator(mode="after")
def check_path_or_temp_file_id(self):
@@ -148,7 +150,12 @@ async def temp_upload(
if signed is None:
return {"temp_file_id": temp_file_id}
return await ingest_temp_upload(
- store, temp_file_id, _ctx, to=signed.to, reason=signed.reason
+ store,
+ temp_file_id,
+ _ctx,
+ to=signed.to,
+ reason=signed.reason,
+ processing_mode=signed.processing_mode,
)
try:
@@ -207,6 +214,7 @@ async def add_resource(
"exclude": request.exclude,
"directly_upload_media": request.directly_upload_media,
"watch_interval": request.watch_interval,
+ "processing_mode": request.processing_mode,
}
# Connector routing needs to distinguish an omitted create_parent from an
# explicit false. Standard imports still observe false when the field is
diff --git a/openviking/server/upload_token_store.py b/openviking/server/upload_token_store.py
index 7b9c765da..705170f9e 100644
--- a/openviking/server/upload_token_store.py
+++ b/openviking/server/upload_token_store.py
@@ -29,6 +29,8 @@ import time
from dataclasses import dataclass
from typing import Optional, Tuple
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
+
_TOKEN_ALPHABET = string.ascii_letters + string.digits # base62
_TOKEN_LENGTH = 6
@@ -44,6 +46,7 @@ class _TokenInfo:
to: str
reason: str
actor_peer_id: str
+ processing_mode: ProcessingMode
expires_at: float
@@ -56,6 +59,7 @@ class ConsumedUploadToken:
to: str
reason: str
actor_peer_id: str
+ processing_mode: ProcessingMode
class UploadTokenStore:
@@ -71,6 +75,7 @@ class UploadTokenStore:
to: str = "",
reason: str = "",
actor_peer_id: str = "",
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
) -> Tuple[str, float]:
"""Mint a fresh token bound to (account, user) plus ``to``/``reason``/``actor_peer_id``.
@@ -81,7 +86,15 @@ class UploadTokenStore:
"""
self._purge_expired()
expires_at = time.time() + max(1, ttl_seconds)
- info = _TokenInfo(account_id, user_id, to, reason, actor_peer_id, expires_at)
+ info = _TokenInfo(
+ account_id,
+ user_id,
+ to,
+ reason,
+ actor_peer_id,
+ processing_mode,
+ expires_at,
+ )
for _ in range(8):
token = "".join(secrets.choice(_TOKEN_ALPHABET) for _ in range(_TOKEN_LENGTH))
if token not in self._store:
@@ -99,7 +112,12 @@ class UploadTokenStore:
if info.expires_at < time.time():
raise UploadTokenError("upload token expired")
return ConsumedUploadToken(
- info.account_id, info.user_id, info.to, info.reason, info.actor_peer_id
+ info.account_id,
+ info.user_id,
+ info.to,
+ info.reason,
+ info.actor_peer_id,
+ info.processing_mode,
)
def peek(self, token: str) -> Optional[_TokenInfo]:
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 343181746..6c762168c 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -28,6 +28,12 @@ from openviking.resource.feishu_watch_auth import (
create_feishu_auth_state,
load_feishu_app_credentials,
)
+from openviking.resource.processing_mode import (
+ DEFAULT_PROCESSING_MODE,
+ VECTORS_ONLY,
+ ProcessingMode,
+ normalize_processing_mode,
+)
from openviking.server.identity import RequestContext
from openviking.server.local_input_guard import (
is_remote_resource_source,
@@ -84,6 +90,7 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset(
"timeout",
"build_index",
"summarize",
+ "processing_mode",
"watch_interval",
"skip_watch_management",
"allow_local_path_resolution",
@@ -202,6 +209,7 @@ class ResourceService:
instruction: str,
build_index: bool,
summarize: bool,
+ processing_mode: ProcessingMode,
processor_kwargs: Dict[str, Any],
watch_auth_state: Optional[Dict[str, Any]],
ctx: RequestContext,
@@ -252,6 +260,7 @@ class ResourceService:
watch_interval=watch_interval,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=sanitized,
auth_state=watch_auth_state,
ctx=ctx,
@@ -423,6 +432,7 @@ class ResourceService:
timeout=msg.timeout,
build_index=msg.build_index,
summarize=msg.summarize,
+ processing_mode=msg.processing_mode,
watch_interval=msg.watch_interval,
manage_watch=not msg.skip_watch_management,
allow_local_path_resolution=msg.allow_local_path_resolution,
@@ -454,6 +464,7 @@ class ResourceService:
resource_lock=resource_lock,
summarize=msg.summarize,
build_index=msg.build_index,
+ processing_mode=msg.processing_mode,
)
await request_wait_tracker.wait_for_request(
telemetry_id,
@@ -504,6 +515,7 @@ class ResourceService:
timeout: Optional[float] = None,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
allow_local_path_resolution: bool = True,
@@ -513,6 +525,7 @@ class ResourceService:
) -> Dict[str, Any]:
"""Start background ingestion for Git repositories while reserving the target URI."""
self._ensure_initialized()
+ processing_mode = normalize_processing_mode(processing_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
@@ -578,6 +591,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
skip_watch_management=not manage_watch,
allow_local_path_resolution=allow_local_path_resolution,
@@ -709,6 +723,7 @@ class ResourceService:
timeout: Optional[float] = None,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
@@ -733,6 +748,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=True,
allow_local_path_resolution=allow_local_path_resolution,
@@ -752,6 +768,7 @@ class ResourceService:
timeout: Optional[float] = None,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
@@ -769,6 +786,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=False,
allow_local_path_resolution=allow_local_path_resolution,
@@ -789,6 +807,7 @@ class ResourceService:
timeout: Optional[float] = None,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
allow_local_path_resolution: bool = True,
@@ -808,6 +827,7 @@ class ResourceService:
timeout: Wait timeout in seconds
build_index: Whether to build vector index immediately (default: True)
summarize: Whether to generate summary (default: False)
+ processing_mode: Post-ingest processing mode for semantic/vector work
watch_interval: Watch interval in minutes for automatic resource monitoring.
- watch_interval > 0: Creates or updates a watch task. The resource will be
automatically re-processed at the specified interval by the scheduler.
@@ -832,6 +852,7 @@ class ResourceService:
InvalidArgumentError: If the URI scope is not 'resources'
"""
self._ensure_initialized()
+ processing_mode = normalize_processing_mode(processing_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"):
@@ -867,6 +888,7 @@ class ResourceService:
instruction=instruction,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
connector_args=args or {},
kwargs=kwargs,
@@ -891,6 +913,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
allow_local_path_resolution=allow_local_path_resolution,
@@ -909,6 +932,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
allow_local_path_resolution=allow_local_path_resolution,
@@ -930,6 +954,7 @@ class ResourceService:
timeout: Optional[float] = None,
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
manage_watch: bool = True,
allow_local_path_resolution: bool = True,
@@ -1105,6 +1130,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
strict=bool(kwargs.get("strict", False)),
ignore_dirs=kwargs.get("ignore_dirs"),
include=kwargs.get("include"),
@@ -1149,6 +1175,7 @@ class ResourceService:
instruction=instruction,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=kwargs,
watch_auth_state=watch_auth_state,
ctx=ctx,
@@ -1171,6 +1198,7 @@ class ResourceService:
parent=target.parent,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
stage_callback=stage_callback,
allow_local_path_resolution=allow_local_path_resolution,
prepared_resource=prepared_resource,
@@ -1252,6 +1280,7 @@ class ResourceService:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
strict=bool(kwargs.get("strict", False)),
ignore_dirs=kwargs.get("ignore_dirs"),
include=kwargs.get("include"),
@@ -1283,6 +1312,7 @@ class ResourceService:
instruction=instruction,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=kwargs,
watch_auth_state=watch_auth_state,
ctx=ctx,
@@ -1394,6 +1424,7 @@ class ResourceService:
instruction: str = "",
build_index: bool = True,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
watch_interval: float = 0,
connector_args: Optional[Dict[str, Any]] = None,
kwargs: Optional[Dict[str, Any]] = None,
@@ -1479,6 +1510,7 @@ class ResourceService:
instruction=instruction,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
watch_interval=watch_interval,
connector_args=connector_args,
kwargs=kwargs or {},
@@ -1509,6 +1541,7 @@ class ResourceService:
instruction: str,
build_index: bool,
summarize: bool,
+ processing_mode: ProcessingMode,
watch_interval: float,
connector_args: Dict[str, Any],
kwargs: Dict[str, Any],
@@ -1541,6 +1574,8 @@ class ResourceService:
unsupported.append("build_index=false")
if summarize:
unsupported.append("summarize=true")
+ if processing_mode == VECTORS_ONLY:
+ unsupported.append("processing_mode=vectors_only")
if kwargs.get("strict"):
unsupported.append("strict=true (Connector imports fail per file, not all-or-nothing)")
for field in ("ignore_dirs", "include", "exclude"):
@@ -1860,6 +1895,7 @@ class ResourceService:
watch_interval: float,
build_index: bool,
summarize: bool,
+ processing_mode: ProcessingMode,
processor_kwargs: Dict[str, Any],
auth_state: Optional[Dict[str, Any]],
ctx: RequestContext,
@@ -1908,6 +1944,7 @@ class ResourceService:
watch_interval=watch_interval,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=processor_kwargs,
auth_state=auth_state,
is_active=True,
@@ -1928,6 +1965,7 @@ class ResourceService:
watch_interval=watch_interval,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
processor_kwargs=processor_kwargs,
auth_state=auth_state,
)
diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.py
index a2416ba7e..6db4e47cd 100644
--- a/openviking/storage/queuefs/add_resource_msg.py
+++ b/openviking/storage/queuefs/add_resource_msg.py
@@ -5,6 +5,8 @@
from dataclasses import asdict, dataclass, field
from typing import Any, Dict, Optional
+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
+
@dataclass(kw_only=True)
class AddResourceMsg:
@@ -39,6 +41,7 @@ class AddResourceMsg:
skip_watch_management: bool = True
defer_target_resolution: bool = False
understanding_response_id: Optional[str] = None
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
def to_dict(self) -> Dict[str, Any]:
data = asdict(self)
@@ -116,4 +119,5 @@ class AddResourceMsg:
if isinstance(data.get("understanding_response_id"), str)
else None
),
+ processing_mode=data.get("processing_mode", DEFAULT_PROCESSING_MODE),
)
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index 7c36ad3bf..974b89e7e 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -237,6 +237,7 @@ class SyncOpenViking:
summarize: bool = False,
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
+ processing_mode: str = "semantic_and_vectors",
**kwargs,
) -> Dict[str, Any]:
"""Add resource to OpenViking (resources scope only)
@@ -267,6 +268,7 @@ class SyncOpenViking:
timeout=timeout,
build_index=build_index,
summarize=summarize,
+ processing_mode=processing_mode,
args=args,
telemetry=telemetry,
**kwargs,
diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.py
index b4fc89b0c..e7d7e7d97 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -18,6 +18,7 @@ from openviking.server.identity import RequestContext
from openviking.storage.queuefs import get_queue_manager
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
+from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.utils.image_search import image_bytes_to_data_uri
from openviking.utils.time_utils import parse_iso_datetime
from openviking_cli.utils import VikingURI, get_logger
@@ -422,6 +423,7 @@ async def vectorize_file(
use_summary: bool = False,
preserve_existing_created_at: bool = False,
scalar_override: Optional[Dict[str, Any]] = None,
+ register_request_wait: bool = False,
) -> None:
"""
Vectorize a single file.
@@ -431,6 +433,7 @@ async def vectorize_file(
`use_summary` flag (code path override) or the embedding config.
"""
enqueued = False
+ registered_wait_root: Optional[tuple[str, str]] = None
try:
if not ctx:
@@ -541,12 +544,31 @@ async def vectorize_file(
_apply_scalar_overrides(embedding_msg, scalar_override)
embedding_msg.semantic_msg_id = semantic_msg_id
- await embedding_queue.enqueue(embedding_msg)
+ if register_request_wait:
+ get_request_wait_tracker().register_embedding_root(
+ embedding_msg.telemetry_id,
+ embedding_msg.id,
+ )
+ registered_wait_root = (embedding_msg.telemetry_id, embedding_msg.id)
+ enqueued_id = await embedding_queue.enqueue(embedding_msg)
+ if register_request_wait and not enqueued_id:
+ get_request_wait_tracker().mark_embedding_failed(
+ embedding_msg.telemetry_id,
+ embedding_msg.id,
+ f"Failed to enqueue file vector for {file_path}",
+ )
+ return
enqueued = True
logger.debug(f"Enqueued file for vectorization: {file_path}")
except Exception as e:
logger.error(f"Failed to vectorize file {file_path}: {e}", exc_info=True)
+ if registered_wait_root is not None:
+ get_request_wait_tracker().mark_embedding_failed(
+ registered_wait_root[0],
+ registered_wait_root[1],
+ f"Failed to enqueue file vector for {file_path}: {e}",
+ )
finally:
if not enqueued:
await _decrement_embedding_tracker(semantic_msg_id, 1)
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index cf42b59a2..5ded05951 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -12,11 +12,20 @@ import time
from collections.abc import Callable
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+from openviking.core.context import ContextLevel
+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
+from openviking.resource.processing_mode import (
+ DEFAULT_PROCESSING_MODE,
+ VECTORS_ONLY,
+ ProcessingMode,
+ normalize_processing_mode,
+)
from openviking.server.identity import RequestContext
from openviking.storage import VikingDBManager
from openviking.storage.errors import LockAcquisitionError
+from openviking.storage.expr import And, Eq, PathScope
from openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMES
from openviking.storage.transaction import (
LOCK_TIMEOUT_DEFAULT,
@@ -24,12 +33,13 @@ from openviking.storage.transaction import (
LockLease,
OwnedLockLease,
)
+from openviking.storage.queuefs.semantic_processor import SemanticProcessor
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry import get_current_telemetry
-from openviking.utils.embedding_utils import index_resource
+from openviking.utils.embedding_utils import index_resource, vectorize_file
from openviking.utils.summarizer import Summarizer
from openviking_cli.exceptions import OpenVikingError
-from openviking_cli.utils import get_logger
+from openviking_cli.utils import VikingURI, get_logger
from openviking_cli.utils.storage import StoragePath
if TYPE_CHECKING:
@@ -37,6 +47,7 @@ if TYPE_CHECKING:
from openviking.parse.vlm import VLMProcessor
logger = get_logger(__name__)
+VECTORDB_MAX_QUERY_LIMIT = 100_000
class ResourceProcessor:
@@ -427,6 +438,7 @@ class ResourceProcessor:
ctx: RequestContext,
resource_lock: LockLease = NO_LOCK,
summarize: bool = False,
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
**kwargs: Any,
) -> Dict[str, Any]:
"""Run the queue-producing phase for a resource already stored in VikingFS."""
@@ -438,7 +450,9 @@ class ResourceProcessor:
source_committed = bool(prepared.get("source_committed"))
target_preexisting = bool(prepared.get("target_preexisting"))
build_index = bool(kwargs.get("build_index", True))
- should_summarize = summarize or build_index
+ processing_mode = normalize_processing_mode(processing_mode)
+ vectors_only = processing_mode == VECTORS_ONLY
+ should_summarize = not vectors_only and (summarize or build_index)
result: Dict[str, Any] = {"status": "success", "root_uri": root_uri}
if should_summarize:
@@ -480,9 +494,21 @@ class ResourceProcessor:
if resource_lock.active:
try:
+ sync_deleted_files: list[str] = []
+ sync_deleted_dirs: list[str] = []
if not should_summarize and temp_uri and not source_committed:
viking_fs = get_viking_fs()
- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
+ if vectors_only and target_preexisting:
+ diff = await SemanticProcessor()._sync_topdown_recursive(
+ temp_uri,
+ root_uri,
+ ctx=ctx,
+ lock=resource_lock,
+ )
+ sync_deleted_files = list(getattr(diff, "deleted_files", []))
+ sync_deleted_dirs = list(getattr(diff, "deleted_dirs", []))
+ else:
+ await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
await rewrite_image_uris(
root_uri,
ctx=ctx,
@@ -490,10 +516,84 @@ class ResourceProcessor:
)
if temp_dir_path:
await viking_fs.delete_temp(temp_dir_path, ctx=ctx)
+ if vectors_only:
+ if sync_deleted_files or sync_deleted_dirs:
+ await self._delete_removed_resource_vectors(
+ files=sync_deleted_files,
+ dirs=sync_deleted_dirs,
+ ctx=ctx,
+ )
+ if vectors_only and build_index:
+ await self._vectorize_resource_files(root_uri, ctx=ctx)
finally:
await resource_lock.close()
+ elif vectors_only:
+ if not build_index:
+ return result
+ await self._vectorize_resource_files(root_uri, ctx=ctx)
return result
+ async def _delete_removed_resource_vectors(
+ self,
+ *,
+ files: list[str],
+ dirs: list[str],
+ ctx: RequestContext,
+ ) -> None:
+ for uri in dict.fromkeys(files):
+ records = await self.vikingdb.get_context_by_uri(
+ uri=uri,
+ level=int(ContextLevel.DETAIL),
+ limit=100,
+ ctx=ctx,
+ )
+ ids = [str(record["id"]) for record in records if record.get("id")]
+ if ids:
+ await self.vikingdb.delete(ids, ctx=ctx)
+ for uri in dict.fromkeys(dirs):
+ records = await self.vikingdb.filter(
+ filter=And(
+ [
+ PathScope("uri", uri, depth=-1),
+ Eq("level", int(ContextLevel.DETAIL)),
+ Eq("account_id", ctx.account_id),
+ ]
+ ),
+ limit=VECTORDB_MAX_QUERY_LIMIT,
+ output_fields=["id"],
+ ctx=ctx,
+ )
+ ids = [str(record["id"]) for record in records if record.get("id")]
+ if ids:
+ await self.vikingdb.delete(ids, ctx=ctx)
+
+ async def _vectorize_resource_files(self, root_uri: str, *, ctx: RequestContext) -> None:
+ viking_fs = get_viking_fs()
+ entries = await viking_fs.tree(
+ root_uri,
+ node_limit=None,
+ level_limit=None,
+ ctx=ctx,
+ )
+ for entry in entries:
+ entry_uri = entry.get("uri") if isinstance(entry, dict) else None
+ if not entry_uri or entry.get("isDir"):
+ continue
+ name = entry.get("name") or entry_uri.rsplit("/", 1)[-1]
+ if str(name).startswith("."):
+ continue
+ parent = VikingURI(entry_uri).parent
+ if parent is None:
+ continue
+ await vectorize_file(
+ file_path=entry_uri,
+ summary_dict={"name": name, "summary": ""},
+ parent_uri=parent.uri,
+ context_type=context_type_for_uri(entry_uri),
+ ctx=ctx,
+ register_request_wait=True,
+ )
+
async def reserve_unique_candidate(
self,
*,
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index f7f3efd1e..e1cdbfd60 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -43,6 +43,7 @@ class BaseClient(ABC):
wait: bool = False,
timeout: Optional[float] = None,
watch_interval: float = 0,
+ processing_mode: str = "semantic_and_vectors",
args: Optional[Dict[str, Any]] = None,
telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
diff --git a/sdk/python/README.md b/sdk/python/README.md
index c0292ae3c..5ebd617c1 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -166,6 +166,19 @@ result = client.add_resource(
print(result)
```
+To ingest content without VLM semantic understanding, pass `processing_mode="vectors_only"`.
+This writes/syncs the resource tree and vectorizes current files, but does not generate
+or refresh `.abstract.md` / `.overview.md`.
+
+```python
+result = client.add_resource(
+ "/path/to/notes.md",
+ to="viking://resources/demo-notes",
+ processing_mode="vectors_only",
+ wait=True,
+)
+```
+
### Filesystem Operations
```python
diff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.md
index b63bf82ab..b1b334018 100644
--- a/sdk/python/README_CN.md
+++ b/sdk/python/README_CN.md
@@ -166,6 +166,18 @@ result = client.add_resource(
print(result)
```
+如果只希望入库并生成向量、不走 VLM 语义理解,可以传 `processing_mode="vectors_only"`。
+该模式会写入/同步资源树并向量化当前文件,但不会生成或刷新 `.abstract.md` / `.overview.md`。
+
+```python
+result = client.add_resource(
+ "/path/to/notes.md",
+ to="viking://resources/demo-notes",
+ processing_mode="vectors_only",
+ wait=True,
+)
+```
+
### 文件系统操作
```python
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 0eb22a7e3..36ed96c48 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -641,6 +641,7 @@ class AsyncHTTPClient:
watch_interval: float = 0,
args: Optional[Dict[str, Any]] = None,
telemetry: Any = False,
+ processing_mode: Optional[str] = None,
) -> Dict[str, Any]:
if to and parent:
raise ValueError("Cannot specify both 'to' and 'parent' at the same time.")
@@ -661,6 +662,8 @@ class AsyncHTTPClient:
"args": args or {},
"telemetry": telemetry,
}
+ if processing_mode is not None:
+ request_data["processing_mode"] = processing_mode
if preserve_structure is not None:
request_data["preserve_structure"] = preserve_structure
@@ -1786,6 +1789,7 @@ class SyncHTTPClient:
watch_interval: float = 0,
args: Optional[Dict[str, Any]] = None,
telemetry: Any = False,
+ processing_mode: Optional[str] = None,
) -> Dict[str, Any]:
return run_async(
self._async_client.add_resource(
@@ -1803,6 +1807,7 @@ class SyncHTTPClient:
directly_upload_media=directly_upload_media,
preserve_structure=preserve_structure,
watch_interval=watch_interval,
+ processing_mode=processing_mode,
args=args,
telemetry=telemetry,
)
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index b45968af1..bef039399 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -453,6 +453,77 @@ async def test_add_resource_uploads_local_file_even_when_url_is_localhost(tmp_pa
assert "path" not in payload
+async def test_add_resource_forwards_processing_mode():
+ client = AsyncHTTPClient(url="http://127.0.0.1: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(
+ "https://example.com/demo.md",
+ processing_mode="vectors_only",
+ )
+
+ fake_http.post.assert_awaited_once()
+ payload = fake_http.post.await_args.kwargs["json"]
+ assert payload["processing_mode"] == "vectors_only"
+
+
+async def test_add_resource_omits_default_processing_mode_for_legacy_servers():
+ client = AsyncHTTPClient(url="http://127.0.0.1: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("https://example.com/demo.md")
+
+ fake_http.post.assert_awaited_once()
+ payload = fake_http.post.await_args.kwargs["json"]
+ assert "processing_mode" not in payload
+
+
+async def test_add_resource_preserves_positional_watch_args_for_legacy_callers():
+ client = AsyncHTTPClient(url="http://127.0.0.1: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(
+ "https://example.com/demo.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ False,
+ None,
+ None,
+ None,
+ True,
+ None,
+ 1440,
+ {"site": True},
+ False,
+ )
+
+ fake_http.post.assert_awaited_once()
+ payload = fake_http.post.await_args.kwargs["json"]
+ assert payload["watch_interval"] == 1440
+ assert payload["args"] == {"site": True}
+ assert payload["telemetry"] is False
+ assert "processing_mode" not in payload
+
+
@pytest.mark.asyncio
async def test_admin_create_paths_accept_initial_user_config():
client = AsyncHTTPClient(url="http://localhost:1933")
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 8b66df46d..22bc07715 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -24,6 +24,16 @@ The client follows the same HTTP API, identity headers, response envelope and er
Existing local file paths are uploaded automatically, and local directories are zipped before upload. Other strings are sent to the server as URLs or server-side paths.
+To ingest content without VLM semantic understanding, pass `processingMode: "vectors_only"` to `addResource`. This writes or syncs the resource tree and vectorizes current files, but does not generate or refresh `.abstract.md` / `.overview.md`.
+
+```ts
+await client.addResource("./docs/guide.md", {
+ to: "viking://resources/guide",
+ processingMode: "vectors_only",
+ wait: true,
+});
+```
+
Deployments using shared temporary storage can set `uploadMode: "shared"`; the server also accepts `"local"` (the default).
OVPack exports and backups follow the Python and Go SDK contract: they are streamed to a Node.js local file and return its final path.
diff --git a/sdk/typescript/README_CN.md b/sdk/typescript/README_CN.md
index 10a6b2802..c7fe75490 100644
--- a/sdk/typescript/README_CN.md
+++ b/sdk/typescript/README_CN.md
@@ -24,6 +24,16 @@ SDK 与 Python `openviking-sdk`、Go SDK 使用相同的 HTTP API、身份请求
Node.js 中存在的本地文件路径会自动上传,目录会先压缩后上传;其他字符串会作为 URL 或服务端路径发送。
+如果只希望入库并生成向量、不走 VLM 语义理解,可以给 `addResource` 传 `processingMode: "vectors_only"`。该模式会写入/同步资源树并向量化当前文件,但不会生成或刷新 `.abstract.md` / `.overview.md`。
+
+```ts
+await client.addResource("./docs/guide.md", {
+ to: "viking://resources/guide",
+ processingMode: "vectors_only",
+ wait: true,
+});
+```
+
使用共享临时存储的部署可设置 `uploadMode: "shared"`;服务端也接受 `"local"`(默认值)。
OVPack 导出和备份与 Python、Go SDK 契约一致:内容会流式写入 Node.js 本地文件,并返回最终文件路径。
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index 58d727424..f35c39213 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -119,6 +119,7 @@ export class OpenVikingClient {
directly_upload_media: options.directlyUploadMedia ?? true,
preserve_structure: options.preserveStructure,
watch_interval: options.watchInterval ?? 0,
+ processing_mode: options.processingMode,
args:
options.args && Object.keys(options.args).length
? options.args
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index d4b178fa2..455e6cb6b 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -7,6 +7,8 @@ export type ClientHeaders =
Headers | Record<string, string> | [string, string][];
/** Temporary upload storage mode supported by the OpenViking server. */
export type UploadMode = "local" | "shared";
+/** Resource post-ingest processing modes accepted by addResource. */
+export type ProcessingMode = "semantic_and_vectors" | "vectors_only";
/** Conflict policy accepted when importing an OVPack. */
export type PackConflictPolicy = "fail" | "overwrite" | "skip";
/** Vector handling strategy accepted when importing an OVPack. */
@@ -83,6 +85,7 @@ export interface AddResourceOptions extends WaitOptions {
directlyUploadMedia?: boolean;
preserveStructure?: boolean;
watchInterval?: number;
+ processingMode?: ProcessingMode;
args?: JsonObject;
}
/** Semantic retrieval options. */
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index e79268d60..b8194e4d3 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -88,6 +88,29 @@ describe("OpenVikingClient", () => {
});
});
+ it("sends processing_mode for addResource requests", async () => {
+ const fetcher = vi.fn<typeof fetch>().mockResolvedValue(ok({}));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ fetch: fetcher,
+ });
+
+ await client.addResource("https://example.com/guide.md", {
+ to: "viking://resources/guide",
+ processingMode: "vectors_only",
+ wait: true,
+ });
+
+ const [url, init] = fetcher.mock.calls[0]!;
+ expect(String(url)).toBe("https://example.com/api/v1/resources");
+ expect(JSON.parse(String(init?.body))).toMatchObject({
+ path: "https://example.com/guide.md",
+ to: "viking://resources/guide",
+ processing_mode: "vectors_only",
+ wait: true,
+ });
+ });
+
it("maps response envelopes to typed errors", async () => {
const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
new Response(
diff --git a/tests/api_test/api/client.py b/tests/api_test/api/client.py
index e0525feba..5b5b92241 100644
--- a/tests/api_test/api/client.py
+++ b/tests/api_test/api/client.py
@@ -277,6 +277,7 @@ class OpenVikingAPIClient:
parent: Optional[str] = None,
instruction: Optional[str] = None,
wait: bool = False,
+ processing_mode: Optional[str] = None,
) -> requests.Response:
endpoint = "/api/v1/resources"
url = self._build_url(self.server_url, endpoint)
@@ -299,6 +300,8 @@ class OpenVikingAPIClient:
payload["instruction"] = instruction
if wait:
payload["wait"] = wait
+ if processing_mode:
+ payload["processing_mode"] = processing_mode
try:
return self._request_with_retry("POST", url, json=payload)
finally:
diff --git a/tests/client/test_add_resource_signature_compat.py b/tests/client/test_add_resource_signature_compat.py
new file mode 100644
index 000000000..76185fe2c
--- /dev/null
+++ b/tests/client/test_add_resource_signature_compat.py
@@ -0,0 +1,126 @@
+import inspect
+
+from openviking import AsyncOpenViking, SyncOpenViking
+from openviking.client.local import LocalClient
+from openviking_sdk.client import AsyncHTTPClient, SyncHTTPClient
+
+
+def test_async_openviking_add_resource_preserves_positional_watch_args():
+ bound = inspect.signature(AsyncOpenViking.add_resource).bind_partial(
+ object(),
+ "doc.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ True,
+ False,
+ 1440,
+ {"site": True},
+ False,
+ )
+
+ assert bound.arguments["watch_interval"] == 1440
+ assert bound.arguments["args"] == {"site": True}
+ assert bound.arguments["telemetry"] is False
+ assert "processing_mode" not in bound.arguments
+
+
+def test_sync_openviking_add_resource_preserves_positional_args_and_telemetry():
+ bound = inspect.signature(SyncOpenViking.add_resource).bind_partial(
+ object(),
+ "doc.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ True,
+ False,
+ {"site": True},
+ False,
+ )
+
+ assert bound.arguments["args"] == {"site": True}
+ assert bound.arguments["telemetry"] is False
+ assert "processing_mode" not in bound.arguments
+
+
+def test_local_client_add_resource_preserves_positional_watch_args():
+ bound = inspect.signature(LocalClient.add_resource).bind_partial(
+ object(),
+ "doc.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ True,
+ False,
+ False,
+ 1440,
+ {"site": True},
+ )
+
+ assert bound.arguments["telemetry"] is False
+ assert bound.arguments["watch_interval"] == 1440
+ assert bound.arguments["args"] == {"site": True}
+ assert "processing_mode" not in bound.arguments
+
+
+def test_async_http_client_add_resource_preserves_positional_watch_args():
+ bound = inspect.signature(AsyncHTTPClient.add_resource).bind_partial(
+ object(),
+ "doc.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ False,
+ None,
+ None,
+ None,
+ True,
+ None,
+ 1440,
+ {"site": True},
+ False,
+ )
+
+ assert bound.arguments["watch_interval"] == 1440
+ assert bound.arguments["args"] == {"site": True}
+ assert bound.arguments["telemetry"] is False
+ assert "processing_mode" not in bound.arguments
+
+
+def test_sync_http_client_add_resource_preserves_positional_watch_args():
+ bound = inspect.signature(SyncHTTPClient.add_resource).bind_partial(
+ object(),
+ "doc.md",
+ None,
+ None,
+ "",
+ "",
+ False,
+ None,
+ False,
+ None,
+ None,
+ None,
+ True,
+ None,
+ 1440,
+ {"site": True},
+ False,
+ )
+
+ assert bound.arguments["watch_interval"] == 1440
+ assert bound.arguments["args"] == {"site": True}
+ assert bound.arguments["telemetry"] is False
+ assert "processing_mode" not in bound.arguments
diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.py
index 039b9b679..4dbbded75 100644
--- a/tests/parse/test_feishu_parser_api.py
+++ b/tests/parse/test_feishu_parser_api.py
@@ -390,6 +390,22 @@ def test_add_resource_message_round_trips_internal_fields():
assert restored.understanding_response_id == "response-1"
+def test_add_resource_message_round_trips_processing_mode():
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="https://example.com/demo.md",
+ root_uri="viking://resources/demo",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ processing_mode="vectors_only",
+ )
+
+ restored = AddResourceMsg.from_dict(msg.to_dict())
+
+ assert restored.processing_mode == "vectors_only"
+
+
@pytest.mark.asyncio
async def test_uat_producer_payload_reaches_worker_without_persisting_token(monkeypatch):
source = "https://example.larkoffice.com/docx/doxcnToken"
@@ -702,6 +718,7 @@ async def test_add_resource_job_expands_parser_args():
user_id="user-1",
role="user",
args={"custom_option": "forwarded"},
+ processing_mode="vectors_only",
)
ctx = RequestContext(
user=UserIdentifier("account-1", "user-1"),
@@ -719,6 +736,41 @@ async def test_add_resource_job_expands_parser_args():
assert call.kwargs["to"] == "viking://resources/doxcnToken"
assert call.kwargs["parent"] is None
assert call.kwargs["custom_option"] == "forwarded"
+ assert call.kwargs["processing_mode"] == "vectors_only"
+
+
+async def test_prepared_add_resource_job_forwards_processing_mode():
+ resource_processor = SimpleNamespace(
+ finish_prepared_resource=AsyncMock(
+ return_value={"status": "success", "root_uri": "viking://resources/demo"}
+ )
+ )
+ service = ResourceService(resource_processor=resource_processor)
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="/tmp/demo.md",
+ root_uri="viking://resources/demo",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ prepared={"root_uri": "viking://resources/demo"},
+ processing_mode="vectors_only",
+ )
+ ctx = RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+ await service.execute_add_resource_job(
+ msg,
+ ctx=ctx,
+ resource_lock=None,
+ stage_callback=AsyncMock(),
+ )
+
+ call = resource_processor.finish_prepared_resource.await_args
+ assert call.kwargs["processing_mode"] == "vectors_only"
@pytest.mark.asyncio
diff --git a/tests/resource/test_watch_manager.py b/tests/resource/test_watch_manager.py
index 39f5a0f38..3493b4032 100644
--- a/tests/resource/test_watch_manager.py
+++ b/tests/resource/test_watch_manager.py
@@ -80,6 +80,7 @@ class TestWatchTask:
assert task.created_at is not None
assert task.last_execution_time is None
assert task.next_execution_time is None
+ assert task.processing_mode == "semantic_and_vectors"
def test_create_task_with_all_fields(self):
"""Test creating a task with all fields specified."""
@@ -92,6 +93,7 @@ class TestWatchTask:
reason="Test reason",
instruction="Test instruction",
watch_interval=30.0,
+ processing_mode="vectors_only",
created_at=now,
last_execution_time=now,
next_execution_time=now + timedelta(minutes=30),
@@ -105,6 +107,7 @@ class TestWatchTask:
assert task.reason == "Test reason"
assert task.instruction == "Test instruction"
assert task.watch_interval == 30.0
+ assert task.processing_mode == "vectors_only"
assert task.is_active is False
assert task.created_at == now
assert task.last_execution_time == now
@@ -132,6 +135,7 @@ class TestWatchTask:
assert data["to_uri"] == "viking://test"
assert data["created_at"] == now.isoformat()
assert data["is_active"] is True
+ assert data["processing_mode"] == "semantic_and_vectors"
assert "auth_state" not in data
def test_from_dict(self):
@@ -145,6 +149,7 @@ class TestWatchTask:
"reason": "Test",
"instruction": "Instruction",
"watch_interval": 45.0,
+ "processing_mode": "vectors_only",
"created_at": now.isoformat(),
"last_execution_time": now.isoformat(),
"next_execution_time": (now + timedelta(minutes=45)).isoformat(),
@@ -157,10 +162,16 @@ class TestWatchTask:
assert task.path == "/test/path"
assert task.to_uri == "viking://test"
assert task.watch_interval == 45.0
+ assert task.processing_mode == "vectors_only"
assert task.is_active is False
assert task.created_at == now
assert task.last_execution_time == now
+ def test_from_dict_defaults_legacy_processing_mode(self):
+ task = WatchTask.from_dict({"path": "/test/path"})
+
+ assert task.processing_mode == "semantic_and_vectors"
+
def test_calculate_next_execution_time(self):
"""Test calculating next execution time."""
now = datetime.now()
diff --git a/tests/resource/test_watch_scheduler.py b/tests/resource/test_watch_scheduler.py
index 36557e4cc..43e5097d0 100644
--- a/tests/resource/test_watch_scheduler.py
+++ b/tests/resource/test_watch_scheduler.py
@@ -110,3 +110,34 @@ class TestWatchSchedulerResourceExistence:
assert updated.is_active is True
assert resource_service.calls and resource_service.calls[0]["to"] == task.to_uri
manager.update_execution_time.assert_awaited_once_with(task.task_id)
+
+ @pytest.mark.asyncio
+ async def test_execute_task_forwards_processing_mode(self, tmp_path):
+ class FakeResourceService(ResourceService):
+ def __init__(self):
+ super().__init__()
+ self.calls = []
+
+ async def refresh_resource(self, **kwargs):
+ self.calls.append(kwargs)
+ return {"root_uri": kwargs.get("to")}
+
+ source = tmp_path / "source.txt"
+ source.write_text("ok")
+ resource_service = FakeResourceService()
+ scheduler = WatchScheduler(resource_service=resource_service, check_interval=1)
+ manager = WatchManager(viking_fs=None)
+ await manager.initialize()
+ scheduler._watch_manager = manager
+ manager.update_execution_time = AsyncMock()
+ task = await manager.create_task(
+ path=str(source),
+ to_uri="viking://resources/codeask/wiki",
+ watch_interval=30.0,
+ processing_mode="vectors_only",
+ )
+
+ await scheduler._execute_task(task)
+
+ assert resource_service.calls
+ assert resource_service.calls[0]["processing_mode"] == "vectors_only"
diff --git a/tests/server/test_api_resources.py b/tests/server/test_api_resources.py
index 84a751244..d7ea3bcd6 100644
--- a/tests/server/test_api_resources.py
+++ b/tests/server/test_api_resources.py
@@ -9,9 +9,27 @@ from types import SimpleNamespace
import httpx
+from openviking.server.identity import RequestContext, Role
from openviking.server.routers import resources as resources_router
+from openviking.server.routers.resources import AddResourceRequest
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import get_current_telemetry
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def test_add_resource_request_accepts_processing_mode():
+ request = AddResourceRequest(
+ path="https://example.com/demo.md",
+ processing_mode="vectors_only",
+ )
+
+ assert request.processing_mode == "vectors_only"
+
+
+def test_add_resource_request_defaults_processing_mode():
+ request = AddResourceRequest(path="https://example.com/demo.md")
+
+ assert request.processing_mode == "semantic_and_vectors"
async def _wait_task_terminal(client: httpx.AsyncClient, task_id: str, timeout: float = 10.0):
@@ -99,6 +117,35 @@ async def test_add_resource_forwards_args_to_service(
assert seen["args"] == {"feishu_access_token": "u-test"}
+async def test_add_resource_forwards_processing_mode_to_service(monkeypatch):
+ seen = {}
+
+ async def fake_add_resource(**kwargs):
+ seen.update(kwargs)
+ return {
+ "status": "success",
+ "root_uri": "viking://resources/demo",
+ }
+
+ service = SimpleNamespace(resources=SimpleNamespace(add_resource=fake_add_resource))
+ monkeypatch.setattr(resources_router, "get_service", lambda: service)
+
+ response = await resources_router.add_resource(
+ SimpleNamespace(app=SimpleNamespace(state=SimpleNamespace(config=None))),
+ AddResourceRequest(
+ path="https://example.com/demo.md",
+ processing_mode="vectors_only",
+ ),
+ RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ ),
+ )
+
+ assert response["status"] == "ok"
+ assert seen["processing_mode"] == "vectors_only"
+
+
async def test_add_resource_preserves_create_parent_field_presence(
client: httpx.AsyncClient,
service,
diff --git a/tests/server/test_upload_token_store.py b/tests/server/test_upload_token_store.py
index 96395f37d..4cb6dced8 100644
--- a/tests/server/test_upload_token_store.py
+++ b/tests/server/test_upload_token_store.py
@@ -42,11 +42,13 @@ def test_consume_returns_bound_business_params(store):
to="viking://resources/team/proj",
reason="quarterly",
actor_peer_id="bot-a",
+ processing_mode="vectors_only",
)
consumed = store.consume(token)
assert consumed.to == "viking://resources/team/proj"
assert consumed.reason == "quarterly"
assert consumed.actor_peer_id == "bot-a"
+ assert consumed.processing_mode == "vectors_only"
def test_consume_burns_token(store):
diff --git a/tests/service/test_resource_service_watch.py b/tests/service/test_resource_service_watch.py
index 2bfe6c838..fba22225c 100644
--- a/tests/service/test_resource_service_watch.py
+++ b/tests/service/test_resource_service_watch.py
@@ -34,7 +34,16 @@ class MockResourceProcessor:
async def process_resource(self, **kwargs):
self.calls.append(kwargs)
- return {"root_uri": kwargs.get("to") or "viking://resources/test"}
+ root_uri = kwargs.get("to") or "viking://resources/test"
+ return {
+ "root_uri": root_uri,
+ "_post_process": {"root_uri": root_uri},
+ "_resource_lock": SimpleNamespace(
+ active=False,
+ to_handoff=MagicMock(return_value=None),
+ close=AsyncMock(),
+ ),
+ }
class MockSkillProcessor:
@@ -91,6 +100,13 @@ def isolate_service_dependencies(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(resource_service_module, "is_git_repo_url", lambda _path: False)
+@pytest_asyncio.fixture
+async def watch_manager() -> AsyncGenerator[WatchManager, None]:
+ manager = WatchManager(viking_fs=None)
+ await manager.initialize()
+ yield manager
+
+
@pytest_asyncio.fixture
async def resource_service(watch_manager: WatchManager) -> AsyncGenerator[ResourceService, None]:
"""Create ResourceService instance with watch support."""
@@ -103,6 +119,9 @@ async def resource_service(watch_manager: WatchManager) -> AsyncGenerator[Resour
skill_processor=MockSkillProcessor(),
watch_scheduler=scheduler,
)
+ service._enqueue_add_resource_job = AsyncMock(
+ return_value=SimpleNamespace(task_id="test-task")
+ )
yield service
@@ -199,6 +218,7 @@ class TestWatchTaskCreation:
watch_interval=30.0,
build_index=False,
summarize=True,
+ processing_mode="vectors_only",
custom_option="x",
)
@@ -206,7 +226,9 @@ class TestWatchTaskCreation:
assert task is not None
assert task.build_index is False
assert task.summarize is True
+ assert task.processing_mode == "vectors_only"
assert task.processor_kwargs.get("custom_option") == "x"
+ assert "processing_mode" not in task.processor_kwargs
@pytest.mark.asyncio
async def test_create_watch_task_with_default_interval(
diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.py
index f234bc07f..d3f139098 100644
--- a/tests/unit/test_vectorize_file_strategy.py
+++ b/tests/unit/test_vectorize_file_strategy.py
@@ -14,6 +14,18 @@ class DummyQueue:
self.items.append(msg)
+class DummyQueueWithId(DummyQueue):
+ async def enqueue(self, msg):
+ self.items.append(msg)
+ return "queue-message-id"
+
+
+class FailingQueue(DummyQueue):
+ async def enqueue(self, msg):
+ self.items.append(msg)
+ raise RuntimeError("queue unavailable")
+
+
class DummyQueueManager:
EMBEDDING = "embedding"
@@ -119,6 +131,83 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):
assert queue.items[0].get_vectorization_text() == "short summary"
+async def test_vectorize_file_registers_request_wait_with_embedding_msg_id(monkeypatch):
+ queue = DummyQueueWithId()
+ registered = []
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("hello"))
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_openviking_config",
+ lambda: types.SimpleNamespace(
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)
+ ),
+ )
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_request_wait_tracker",
+ lambda: types.SimpleNamespace(
+ register_embedding_root=lambda telemetry_id, root_id: registered.append(
+ (telemetry_id, root_id)
+ )
+ ),
+ )
+
+ await embedding_utils.vectorize_file(
+ file_path="viking://user/default/resources/test.md",
+ summary_dict={"name": "test.md", "summary": ""},
+ parent_uri="viking://user/default/resources",
+ ctx=DummyReq(),
+ register_request_wait=True,
+ )
+
+ assert len(queue.items) == 1
+ assert registered == [(queue.items[0].telemetry_id, queue.items[0].id)]
+ assert registered[0][1] != "queue-message-id"
+
+
+async def test_vectorize_file_marks_registered_wait_root_failed_when_enqueue_raises(monkeypatch):
+ queue = FailingQueue()
+ registered = []
+ failed = []
+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("hello"))
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_openviking_config",
+ lambda: types.SimpleNamespace(
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)
+ ),
+ )
+ monkeypatch.setattr(
+ embedding_utils,
+ "get_request_wait_tracker",
+ lambda: types.SimpleNamespace(
+ register_embedding_root=lambda telemetry_id, root_id: registered.append(
+ (telemetry_id, root_id)
+ ),
+ mark_embedding_failed=lambda telemetry_id, root_id, message: failed.append(
+ (telemetry_id, root_id, message)
+ ),
+ ),
+ )
+
+ await embedding_utils.vectorize_file(
+ file_path="viking://user/default/resources/test.md",
+ summary_dict={"name": "test.md", "summary": ""},
+ parent_uri="viking://user/default/resources",
+ ctx=DummyReq(),
+ register_request_wait=True,
+ )
+
+ assert len(queue.items) == 1
+ assert registered == [(queue.items[0].telemetry_id, queue.items[0].id)]
+ assert failed
+ assert failed[0][0:2] == registered[0]
+
+
@pytest.mark.asyncio
async def test_vectorize_unknown_text_file_embeds_summary_but_indexes_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
new file mode 100644
index 000000000..274f03aa4
--- /dev/null
+++ b/tests/utils/test_resource_processor_processing_mode.py
@@ -0,0 +1,289 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role
+from openviking.utils.resource_processor import ResourceProcessor
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class _FakeVikingDB:
+ def get_embedder(self):
+ return None
+
+
+class _RecordingVikingDB:
+ def __init__(self):
+ self.lookup_calls = []
+ self.filter_calls = []
+ self.delete_calls = []
+
+ def get_embedder(self):
+ return None
+
+ async def get_context_by_uri(self, *, uri, level, limit, ctx):
+ self.lookup_calls.append((uri, level, limit, ctx))
+ return [{"id": f"{uri}:{level}"}]
+
+ async def delete(self, ids, *, ctx):
+ self.delete_calls.append((ids, ctx))
+ return len(ids)
+
+ async def filter(self, *, filter, limit, output_fields, ctx):
+ self.filter_calls.append((filter, limit, output_fields, ctx))
+ return [{"id": "recursive-child-detail"}]
+
+
+def ctx() -> RequestContext:
+ return RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+
+async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch, ctx):
+ viking_fs = SimpleNamespace(
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ tree=AsyncMock(
+ return_value=[
+ {"uri": "viking://resources/demo/section", "isDir": True},
+ {
+ "uri": "viking://resources/demo/section/page.md",
+ "isDir": False,
+ "name": "page.md",
+ },
+ {
+ "uri": "viking://resources/demo/section/.abstract.md",
+ "isDir": False,
+ "name": ".abstract.md",
+ },
+ ]
+ ),
+ )
+ vectorize_file = AsyncMock()
+ rewrite_image_uris = AsyncMock()
+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)
+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", rewrite_image_uris)
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", vectorize_file)
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._get_summarizer = Mock(side_effect=AssertionError("summarizer should not run"))
+ processor._delete_resource_semantic_markers = AsyncMock()
+ processor._delete_resource_semantic_vectors = AsyncMock()
+ processor._delete_removed_resource_vectors = AsyncMock()
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+
+ result = await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/demo",
+ "temp_uri": "viking://temp/demo",
+ "temp_dir_path": "tmp/demo",
+ "source_committed": False,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=True,
+ processing_mode="vectors_only",
+ )
+
+ assert result == {"status": "success", "root_uri": "viking://resources/demo"}
+ viking_fs.persist_temp_tree.assert_awaited_once_with(
+ "viking://temp/demo", "viking://resources/demo", ctx=ctx
+ )
+ rewrite_image_uris.assert_awaited_once_with(
+ "viking://resources/demo",
+ ctx=ctx,
+ lock_handle="lock-1",
+ )
+ viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)
+ vectorize_file.assert_awaited_once()
+ assert vectorize_file.await_args.kwargs["file_path"] == (
+ "viking://resources/demo/section/page.md"
+ )
+ assert vectorize_file.await_args.kwargs["parent_uri"] == "viking://resources/demo/section"
+ assert vectorize_file.await_args.kwargs["summary_dict"] == {
+ "name": "page.md",
+ "summary": "",
+ }
+ 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()
+ lock.close.assert_awaited_once()
+
+
+async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypatch, ctx):
+ viking_fs = SimpleNamespace(
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ tree=AsyncMock(return_value=[]),
+ )
+ vectorize_file = AsyncMock()
+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)
+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", vectorize_file)
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._delete_resource_semantic_markers = AsyncMock()
+ processor._delete_resource_semantic_vectors = AsyncMock()
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+
+ await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/demo",
+ "temp_uri": "viking://temp/demo",
+ "source_committed": False,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=False,
+ processing_mode="vectors_only",
+ )
+
+ processor._delete_resource_semantic_markers.assert_not_awaited()
+ processor._delete_resource_semantic_vectors.assert_not_awaited()
+ vectorize_file.assert_not_awaited()
+
+
+async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypatch, ctx):
+ viking_fs = SimpleNamespace(
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ tree=AsyncMock(return_value=[]),
+ )
+ sync = AsyncMock()
+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)
+ monkeypatch.setattr("openviking.utils.resource_processor.SemanticProcessor", Mock())
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.SemanticProcessor.return_value._sync_topdown_recursive",
+ sync,
+ )
+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._delete_resource_semantic_vectors = AsyncMock()
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+
+ await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/demo",
+ "temp_uri": "viking://temp/demo",
+ "temp_dir_path": "viking://temp/demo",
+ "source_committed": False,
+ "target_preexisting": True,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=True,
+ processing_mode="vectors_only",
+ )
+
+ viking_fs.persist_temp_tree.assert_not_awaited()
+ sync.assert_awaited_once_with(
+ "viking://temp/demo",
+ "viking://resources/demo",
+ ctx=ctx,
+ lock=lock,
+ )
+
+
+async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypatch, ctx):
+ viking_fs = SimpleNamespace(
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ tree=AsyncMock(return_value=[]),
+ )
+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)
+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._delete_resource_semantic_vectors = AsyncMock()
+ processor._delete_removed_resource_vectors = AsyncMock()
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+
+ await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/demo",
+ "temp_uri": "viking://temp/demo",
+ "source_committed": False,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=True,
+ processing_mode="vectors_only",
+ )
+
+ processor._delete_resource_semantic_vectors.assert_not_awaited()
+
+
+async def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctx):
+ viking_fs = SimpleNamespace(
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ tree=AsyncMock(return_value=[]),
+ )
+ diff = SimpleNamespace(
+ deleted_files=["viking://resources/demo/old.md"],
+ deleted_dirs=["viking://resources/demo/old-dir"],
+ )
+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)
+ monkeypatch.setattr("openviking.utils.resource_processor.SemanticProcessor", Mock())
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.SemanticProcessor.return_value._sync_topdown_recursive",
+ AsyncMock(return_value=diff),
+ )
+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._delete_resource_semantic_vectors = AsyncMock()
+ processor._delete_removed_resource_vectors = AsyncMock()
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+
+ await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/demo",
+ "temp_uri": "viking://temp/demo",
+ "source_committed": False,
+ "target_preexisting": True,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=True,
+ processing_mode="vectors_only",
+ )
+
+ processor._delete_removed_resource_vectors.assert_awaited_once_with(
+ files=["viking://resources/demo/old.md"],
+ dirs=["viking://resources/demo/old-dir"],
+ ctx=ctx,
+ )
+
+
+async def test_delete_removed_resource_vectors_deletes_detail_records(ctx):
+ vikingdb = _RecordingVikingDB()
+ processor = ResourceProcessor(vikingdb)
+
+ await processor._delete_removed_resource_vectors(
+ files=["viking://resources/demo/old.md"],
+ dirs=["viking://resources/demo/old-dir"],
+ ctx=ctx,
+ )
+
+ assert vikingdb.lookup_calls == [
+ ("viking://resources/demo/old.md", 2, 100, ctx),
+ ]
+ assert len(vikingdb.filter_calls) == 1
+ assert vikingdb.filter_calls[0][1] == 100_000
+ assert vikingdb.delete_calls == [
+ (["viking://resources/demo/old.md:2"], ctx),
+ (["recursive-child-detail"], ctx),
+ ]