Skip to content

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

feat(tags): support tagged write and filesystem filtering (#4457)

Jiahui Zhou4f9840eca756
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.md
index ce42a041a..61b180dbe 100644
--- a/crates/ov_cli/README.md
+++ b/crates/ov_cli/README.md
@@ -266,6 +266,13 @@ ov find "authentication" --uri viking://resources/project --level 0,1
# Recursive list
ov ls viking://resources --recursive
+# Write caller-provided tags, then filter or project them
+ov write viking://resources/docs/api.md --content "# API" \
+ --tags team=search,env=prod
+ov ls viking://resources/docs --tags team=search,env=prod --fields tags
+ov grep "TODO" --uri viking://resources/docs --tags team=search,env=prod
+ov glob "**/*.md" --uri viking://resources/docs --tags team=search,env=prod
+
# Temporarily override identity from CLI flags
ov --account acme --user alice ls viking://
@@ -276,6 +283,7 @@ ov admin regenerate-key acme bob --seed bob-new-seed
# Glob search
ov glob "**/*.md" --uri viking://resources
+ov glob "**/*.md" --uri viking://resources -f tags
# Session workflow
SESSION=$(ov -o json session new | jq -r '.result.session_id')
diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.md
index 1313c8f50..fc8e1be67 100644
--- a/crates/ov_cli/README_CN.md
+++ b/crates/ov_cli/README_CN.md
@@ -265,6 +265,13 @@ ov find "authentication" --uri viking://resources/project --level 0,1
# 递归列目录
ov ls viking://resources --recursive
+# 写入调用方提供的 tags,再按 tags 过滤或回显
+ov write viking://resources/docs/api.md --content "# API" \
+ --tags team=search,env=prod
+ov ls viking://resources/docs --tags team=search,env=prod --fields tags
+ov grep "TODO" --uri viking://resources/docs --tags team=search,env=prod
+ov glob "**/*.md" --uri viking://resources/docs --tags team=search,env=prod
+
# 临时通过 CLI 参数覆盖身份
ov --account acme --user alice ls viking://
@@ -275,6 +282,7 @@ ov admin regenerate-key acme bob --seed bob-new-seed
# Glob 搜索
ov glob "**/*.md" --uri viking://resources
+ov glob "**/*.md" --uri viking://resources -f tags
# Session 工作流
SESSION=$(ov -o json session new | jq -r '.result.session_id')
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 8049e3bf3..8d07e5a9d 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -412,8 +412,11 @@ impl HttpClient {
wait: bool,
timeout: Option<f64>,
processing_mode: &str,
+ tags: Vec<String>,
+ tag_mode: &str,
) -> Result<serde_json::Value> {
- let body = Self::build_write_body(uri, content, mode, wait, timeout, processing_mode);
+ let mut body = Self::build_write_body(uri, content, mode, wait, timeout, processing_mode);
+ add_resource_tag_fields(&mut body, &tags, tag_mode);
self.post("/api/v1/content/write", &body).await
}
@@ -585,6 +588,8 @@ impl HttpClient {
show_all_hidden: bool,
node_limit: i32,
extra_fields: &[String],
+ tags: &[String],
+ include_tags: bool,
) -> Result<serde_json::Value> {
let mut params = vec![
("uri".to_string(), uri.to_string()),
@@ -598,6 +603,12 @@ impl HttpClient {
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
+ for tag in tags {
+ params.push(("tags".to_string(), tag.clone()));
+ }
+ if include_tags {
+ params.push(("include_tags".to_string(), "true".to_string()));
+ }
self.get("/api/v1/fs/ls", &params).await
}
@@ -610,6 +621,8 @@ impl HttpClient {
node_limit: i32,
level_limit: i32,
extra_fields: &[String],
+ tags: &[String],
+ include_tags: bool,
) -> Result<serde_json::Value> {
let mut params = vec![
("uri".to_string(), uri.to_string()),
@@ -622,6 +635,12 @@ impl HttpClient {
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
+ for tag in tags {
+ params.push(("tags".to_string(), tag.clone()));
+ }
+ if include_tags {
+ params.push(("include_tags".to_string(), "true".to_string()));
+ }
self.get("/api/v1/fs/tree", &params).await
}
@@ -749,15 +768,20 @@ impl HttpClient {
ignore_case: bool,
node_limit: i32,
level_limit: i32,
+ tags: &[String],
+ include_tags: bool,
) -> Result<serde_json::Value> {
- let body = serde_json::json!({
+ let mut body = serde_json::json!({
"uri": uri,
"exclude_uri": exclude_uri,
"pattern": pattern,
"case_insensitive": ignore_case,
"node_limit": node_limit,
"level_limit": level_limit,
+ "tags": (!tags.is_empty()).then(|| tags),
+ "include_tags": include_tags.then_some(true),
});
+ compact_request_body(&mut body);
self.post("/api/v1/search/grep", &body).await
}
@@ -767,15 +791,20 @@ impl HttpClient {
uri: &str,
node_limit: i32,
extra_fields: Option<&[String]>,
+ tags: &[String],
+ include_tags: bool,
) -> Result<serde_json::Value> {
let mut body = serde_json::json!({
"pattern": pattern,
"uri": uri,
"node_limit": node_limit,
+ "tags": (!tags.is_empty()).then(|| tags),
+ "include_tags": include_tags.then_some(true),
});
if let Some(fields) = extra_fields {
body["extra_fields"] = serde_json::json!(fields);
}
+ compact_request_body(&mut body);
self.post("/api/v1/search/glob", &body).await
}
@@ -2258,7 +2287,7 @@ mod tests {
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
- .ls("viking://resources", false, false, "agent", 256, false, 1, &[])
+ .ls("viking://resources", false, false, "agent", 256, false, 1, &[], &[], false)
.await
.expect("ls request should succeed");
@@ -2384,7 +2413,7 @@ mod tests {
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
- .tree("viking://resources", "agent", 256, false, 1, 3, &[])
+ .tree("viking://resources", "agent", 256, false, 1, 3, &[], &[], false)
.await
.expect("tree request should succeed");
@@ -2394,6 +2423,92 @@ mod tests {
assert!(!request.contains("include_mod_time_iso="));
}
+ #[tokio::test]
+ async fn grep_omits_optional_tags_fields_when_not_requested() {
+ let (base_url, request_rx) = spawn_request_capture_server().await;
+ let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
+
+ client
+ .grep(
+ "viking://resources",
+ None,
+ "needle",
+ false,
+ 10,
+ 3,
+ &[],
+ false,
+ )
+ .await
+ .expect("plain grep request should succeed");
+
+ let request = request_rx.await.expect("request should be captured");
+ assert!(request.starts_with("POST /api/v1/search/grep "));
+ assert!(!request.contains(r#""tags""#));
+ assert!(!request.contains(r#""include_tags""#));
+ }
+
+ #[tokio::test]
+ async fn grep_sends_include_tags_only_when_requested() {
+ let (base_url, request_rx) = spawn_request_capture_server().await;
+ let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
+
+ client
+ .grep(
+ "viking://resources",
+ None,
+ "needle",
+ false,
+ 10,
+ 3,
+ &[],
+ true,
+ )
+ .await
+ .expect("grep tags projection request should succeed");
+
+ let request = request_rx.await.expect("request should be captured");
+ assert!(request.contains(r#""include_tags":true"#));
+ }
+
+ #[tokio::test]
+ async fn glob_omits_tags_when_not_requested() {
+ let (base_url, request_rx) = spawn_request_capture_server().await;
+ let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
+
+ client
+ .glob("**/*.md", "viking://resources", 10, None, &[], false)
+ .await
+ .expect("plain glob request should succeed");
+
+ let request = request_rx.await.expect("request should be captured");
+ assert!(request.starts_with("POST /api/v1/search/glob "));
+ assert!(!request.contains(r#""tags"#));
+ assert!(!request.contains(r#""include_tags"#));
+ }
+
+ #[tokio::test]
+ async fn glob_sends_tags_and_projection_when_requested() {
+ let (base_url, request_rx) = spawn_request_capture_server().await;
+ let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
+
+ client
+ .glob(
+ "**/*.md",
+ "viking://resources",
+ 10,
+ Some(&["tags".to_string()]),
+ &["team=search".to_string(), "env=prod".to_string()],
+ true,
+ )
+ .await
+ .expect("tagged glob request should succeed");
+
+ let request = request_rx.await.expect("request should be captured");
+ assert!(request.contains(r#""tags":["team=search","env=prod"]"#));
+ assert!(request.contains(r#""include_tags":true"#));
+ }
+
#[tokio::test]
async fn compile_create_deserializes_http_202_body() {
let listener = TcpListener::bind("127.0.0.1:0")
diff --git a/crates/ov_cli/src/commands/content.rs b/crates/ov_cli/src/commands/content.rs
index f78b0d534..a687876bc 100644
--- a/crates/ov_cli/src/commands/content.rs
+++ b/crates/ov_cli/src/commands/content.rs
@@ -44,11 +44,22 @@ pub async fn write(
wait: bool,
timeout: Option<f64>,
processing_mode: &str,
+ tags: Vec<String>,
+ tag_mode: &str,
output_format: OutputFormat,
compact: bool,
) -> Result<()> {
let result = client
- .write(uri, content, mode, wait, timeout, processing_mode)
+ .write(
+ uri,
+ content,
+ mode,
+ wait,
+ timeout,
+ processing_mode,
+ tags,
+ tag_mode,
+ )
.await?;
crate::output::output_success(result, output_format, compact);
Ok(())
diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rs
index d9d15f45f..40739e4dc 100644
--- a/crates/ov_cli/src/commands/filesystem.rs
+++ b/crates/ov_cli/src/commands/filesystem.rs
@@ -43,6 +43,7 @@ static ALL_FIELDS: &[FieldDef] = &[
FieldDef { name: "locked", header: "LOCKED", alignment: FieldAlignment::Left },
FieldDef { name: "id", header: "ID", alignment: FieldAlignment::Left },
FieldDef { name: "count", header: "COUNT", alignment: FieldAlignment::Right },
+ FieldDef { name: "tags", header: "TAGS", alignment: FieldAlignment::Left },
FieldDef { name: "abstract", header: "ABSTRACT", alignment: FieldAlignment::Left },
];
@@ -133,6 +134,12 @@ fn field_value(entry: &Value, field: &FieldDef) -> String {
.and_then(Value::as_u64)
.map(|c| c.to_string())
.unwrap_or_else(|| "-".to_string()),
+ "tags" => obj
+ .and_then(|o| o.get("tags"))
+ .and_then(Value::as_array)
+ .map(|tags| tags.iter().filter_map(Value::as_str).collect::<Vec<_>>().join(","))
+ .filter(|tags| !tags.is_empty())
+ .unwrap_or_else(|| "-".to_string()),
"abstract" => entry_string(obj, "abstract")
.map(|s| {
if is_directory_abstract_placeholder(s) {
@@ -167,6 +174,7 @@ pub async fn ls(
output_format: OutputFormat,
compact: bool,
fields: Option<Vec<String>>,
+ tags: &[String],
) -> Result<()> {
let extra = extra_fields_from(&fields);
// When fields are requested we need entry objects (not URI strings) regardless of --simple.
@@ -181,6 +189,8 @@ pub async fn ls(
show_all_hidden,
node_limit,
&extra,
+ tags,
+ fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),
)
.await?;
output_filesystem_entries(&result, output_format, compact, false, simple, fields.as_deref());
@@ -199,6 +209,7 @@ pub async fn tree(
compact: bool,
simple: bool,
fields: Option<Vec<String>>,
+ tags: &[String],
) -> Result<()> {
let extra = extra_fields_from(&fields);
let result = client
@@ -210,6 +221,8 @@ pub async fn tree(
node_limit,
level_limit,
&extra,
+ tags,
+ fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),
)
.await?;
output_filesystem_entries(&result, output_format, compact, true, simple, fields.as_deref());
diff --git a/crates/ov_cli/src/commands/search.rs b/crates/ov_cli/src/commands/search.rs
index 4ee848981..b20b0add1 100644
--- a/crates/ov_cli/src/commands/search.rs
+++ b/crates/ov_cli/src/commands/search.rs
@@ -637,6 +637,8 @@ pub async fn grep(
ignore_case: bool,
node_limit: i32,
level_limit: i32,
+ tags: &[String],
+ show_tags: bool,
output_format: OutputFormat,
compact: bool,
) -> Result<()> {
@@ -648,21 +650,38 @@ pub async fn grep(
ignore_case,
node_limit,
level_limit,
+ tags,
+ show_tags || !tags.is_empty(),
)
.await?;
- output_grep_results(&result, output_format, compact);
+ output_grep_results(&result, output_format, compact, show_tags);
Ok(())
}
-fn output_grep_results(result: &Value, output_format: OutputFormat, compact: bool) {
- if let Some(rendered) = render_grep_output_for_table(result, output_format) {
+fn output_grep_results(
+ result: &Value,
+ output_format: OutputFormat,
+ compact: bool,
+ show_tags: bool,
+) {
+ if let Some(rendered) = render_grep_output_for_table_with_tags(result, output_format, show_tags)
+ {
println!("{rendered}");
} else {
output_success(result, output_format, compact);
}
}
+#[cfg(test)]
fn render_grep_output_for_table(value: &Value, output_format: OutputFormat) -> Option<String> {
+ render_grep_output_for_table_with_tags(value, output_format, false)
+}
+
+fn render_grep_output_for_table_with_tags(
+ value: &Value,
+ output_format: OutputFormat,
+ show_tags: bool,
+) -> Option<String> {
if matches!(output_format, OutputFormat::Json) {
return None;
}
@@ -700,14 +719,20 @@ fn render_grep_output_for_table(value: &Value, output_format: OutputFormat) -> O
for (index, item) in matches.iter().enumerate() {
lines.push(String::new());
- render_grep_match_card(index + 1, item, text_width, &mut lines);
+ render_grep_match_card(index + 1, item, text_width, show_tags, &mut lines);
}
append_profile_lines(profile, &mut lines);
Some(lines.join("\n"))
}
-fn render_grep_match_card(rank: usize, item: &Value, text_width: usize, lines: &mut Vec<String>) {
+fn render_grep_match_card(
+ rank: usize,
+ item: &Value,
+ text_width: usize,
+ show_tags: bool,
+ lines: &mut Vec<String>,
+) {
let object = item.as_object();
let line_number = object
.and_then(|object| object.get("line"))
@@ -743,6 +768,24 @@ fn render_grep_match_card(rank: usize, item: &Value, text_width: usize, lines: &
lines.push(format!("{SEARCH_INDENT}{}", theme::body(line)));
}
}
+ if show_tags {
+ let tags = object
+ .and_then(|object| object.get("tags"))
+ .and_then(Value::as_array)
+ .map(|items| {
+ items
+ .iter()
+ .filter_map(Value::as_str)
+ .collect::<Vec<_>>()
+ .join(", ")
+ })
+ .filter(|tags| !tags.is_empty())
+ .unwrap_or_else(|| "-".to_string());
+ lines.push(format!(
+ "{SEARCH_INDENT}{}",
+ theme::muted(format!("tags: {tags}"))
+ ));
+ }
}
fn pluralize<'a>(count: u64, singular: &'a str, plural: &'a str) -> &'a str {
@@ -758,6 +801,7 @@ pub async fn glob(
compact: bool,
simple: bool,
fields: Option<Vec<String>>,
+ tags: &[String],
) -> Result<()> {
let has_fields = fields.is_some();
let extra: Option<&[String]> = if has_fields {
@@ -765,8 +809,12 @@ pub async fn glob(
} else {
None
};
- let result = client.glob(pattern, uri, node_limit, extra).await?;
- if simple && !has_fields {
+ let include_tags = fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags"))
+ || !tags.is_empty();
+ let result = client
+ .glob(pattern, uri, node_limit, extra, tags, include_tags)
+ .await?;
+ if simple && !has_fields && tags.is_empty() {
super::filesystem::print_uri_blob_per_line(&result);
return Ok(());
}
@@ -856,7 +904,10 @@ mod tests {
assert!(rendered.contains("Deployment summary."));
for line in ["# Deploy", "Step one.", "Step two.", "Step three."] {
- assert!(rendered.contains(line), "missing inlined content line: {line}");
+ assert!(
+ rendered.contains(line),
+ "missing inlined content line: {line}"
+ );
}
}
@@ -1123,6 +1174,28 @@ mod tests {
}
}
+ #[test]
+ fn grep_table_output_shows_requested_tags() {
+ let result = json!({
+ "matches": [{
+ "line": 1,
+ "uri": "viking://resources/a.md",
+ "content": "needle",
+ "tags": ["env=prod", "team=search"]
+ }],
+ "count": 1,
+ "match_count": 1,
+ "files_scanned": 1
+ });
+
+ let rendered = strip_ansi(
+ &render_grep_output_for_table_with_tags(&result, OutputFormat::Table, true)
+ .expect("grep"),
+ );
+
+ assert!(rendered.contains("tags: env=prod, team=search"));
+ }
+
#[test]
fn grep_table_output_handles_empty_matches() {
let result = json!({
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index dee9e1112..0a3b32ef9 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -1392,6 +1392,8 @@ pub async fn handle_write(
wait: bool,
timeout: Option<f64>,
processing_mode: String,
+ tags: Vec<String>,
+ tag_mode: String,
ctx: CliContext,
) -> Result<()> {
let client = ctx.get_client();
@@ -1413,6 +1415,8 @@ pub async fn handle_write(
wait,
timeout,
&processing_mode,
+ tags,
+ &tag_mode,
ctx.output_format,
ctx.compact,
)
@@ -1641,6 +1645,7 @@ pub async fn handle_ls(
show_all_hidden: bool,
node_limit: i32,
fields: Option<Vec<String>>,
+ tags: Vec<String>,
ctx: CliContext,
) -> Result<()> {
let mut params = vec![
@@ -1657,6 +1662,9 @@ pub async fn handle_ls(
if show_all_hidden {
params.push("-a".to_string());
}
+ if !tags.is_empty() {
+ params.push(format!("--tags {}", tags.join(",")));
+ }
if let Some(fields) = &fields {
params.push(format!("-f {}", fields.join(",")));
}
@@ -1680,6 +1688,7 @@ pub async fn handle_ls(
ctx.output_format,
ctx.compact,
fields,
+ &tags,
)
.await
}
@@ -1692,6 +1701,7 @@ pub async fn handle_tree(
level_limit: i32,
simple: bool,
fields: Option<Vec<String>>,
+ tags: Vec<String>,
ctx: CliContext,
) -> Result<()> {
let mut params = vec![
@@ -1706,6 +1716,9 @@ pub async fn handle_tree(
if simple {
params.push("-s".to_string());
}
+ if !tags.is_empty() {
+ params.push(format!("--tags {}", tags.join(",")));
+ }
if let Some(fields) = &fields {
params.push(format!("-f {}", fields.join(",")));
}
@@ -1729,6 +1742,7 @@ pub async fn handle_tree(
ctx.compact,
simple,
fields,
+ &tags,
)
.await
}
@@ -1827,6 +1841,8 @@ pub async fn handle_grep(
ignore_case: bool,
node_limit: i32,
level_limit: i32,
+ tags: Vec<String>,
+ fields: Option<Vec<String>>,
ctx: CliContext,
) -> Result<()> {
// Prevent grep from root directory to avoid excessive server load and timeouts
@@ -1847,6 +1863,12 @@ pub async fn handle_grep(
if ignore_case {
params.push("-i".to_string());
}
+ if !tags.is_empty() {
+ params.push(format!("--tags {}", tags.join(",")));
+ }
+ if let Some(fields) = &fields {
+ params.push(format!("-f {}", fields.join(",")));
+ }
params.push(format!("\"{}\"", pattern));
print_command_echo("ov grep", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
@@ -1858,6 +1880,8 @@ pub async fn handle_grep(
ignore_case,
node_limit,
level_limit,
+ &tags,
+ fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")),
ctx.output_format,
ctx.compact,
)
@@ -1870,6 +1894,7 @@ pub async fn handle_glob(
node_limit: i32,
simple: bool,
fields: Option<Vec<String>>,
+ tags: Vec<String>,
ctx: CliContext,
) -> Result<()> {
let mut params = vec![
@@ -1880,6 +1905,9 @@ pub async fn handle_glob(
if simple {
params.push("-s".to_string());
}
+ if !tags.is_empty() {
+ params.push(format!("--tags {}", tags.join(",")));
+ }
if let Some(fields) = &fields {
params.push(format!("-f {}", fields.join(",")));
}
@@ -1894,6 +1922,7 @@ pub async fn handle_glob(
ctx.compact,
simple,
fields,
+ &tags,
)
.await
}
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 2e38a3006..511ca9d3d 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -530,9 +530,12 @@ enum Commands {
help_heading = "Common options"
)]
node_limit: i32,
- /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,abstract)
+ /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,tags,abstract)
#[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]
fields: Option<Vec<String>>,
+ /// Comma-separated k=v retrieval tags; all tags must match
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
+ tags: Vec<String>,
},
/// [Data] Get directory tree
Tree {
@@ -574,9 +577,12 @@ enum Commands {
/// Simple path output (just paths, no tree formatting)
#[arg(short, long, help_heading = "Common options")]
simple: bool,
- /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count)
+ /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,tags)
#[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]
fields: Option<Vec<String>>,
+ /// Comma-separated k=v retrieval tags; all tags must match
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
+ tags: Vec<String>,
},
/// [Data] Create directory
Mkdir {
@@ -703,6 +709,12 @@ enum Commands {
help_heading = "Common options"
)]
timeout: Option<f64>,
+ /// Comma-separated k=v retrieval tags to write with the content
+ #[arg(long = "tags", value_delimiter = ',')]
+ tags: Vec<String>,
+ /// Tag update mode when --tags is provided
+ #[arg(long = "tag-mode", default_value = "replace", value_parser = ["replace", "append"])]
+ tag_mode: String,
},
/// [Data] Update explicit retrieval tags metadata for a file or directory
#[command(hide = true)]
@@ -914,6 +926,12 @@ enum Commands {
help_heading = "Advanced options"
)]
level_limit: i32,
+ /// Comma-separated k=v retrieval tags; all tags must match
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
+ tags: Vec<String>,
+ /// Fields to include in output (currently: tags)
+ #[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]
+ fields: Option<Vec<String>>,
},
/// [Data] Run file glob pattern search
Glob {
@@ -943,7 +961,10 @@ enum Commands {
/// Simple output (one entry per line)
#[arg(short, long, help_heading = "Common options")]
simple: bool,
- /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id)
+ /// Comma-separated k=v retrieval tags; all tags must match
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
+ tags: Vec<String>,
+ /// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,tags)
#[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]
fields: Option<Vec<String>>,
},
@@ -3165,6 +3186,8 @@ async fn main() {
instruction,
wait,
timeout,
+ tags,
+ tag_mode,
strict_mode,
ignore_dirs,
include,
@@ -3173,8 +3196,6 @@ async fn main() {
watch_interval,
processing_mode,
resource_args,
- tags,
- tag_mode,
upload_options,
} => {
let ctx =
@@ -3486,7 +3507,8 @@ async fn main() {
all,
node_limit,
fields,
- } => handlers::handle_ls(uri, simple, recursive, abs_limit, all, node_limit, fields, ctx).await,
+ tags,
+ } => handlers::handle_ls(uri, simple, recursive, abs_limit, all, node_limit, fields, tags, ctx).await,
Commands::Tree {
uri,
abs_limit,
@@ -3495,7 +3517,8 @@ async fn main() {
level_limit,
simple,
fields,
- } => handlers::handle_tree(uri, abs_limit, all, node_limit, level_limit, simple, fields, ctx).await,
+ tags,
+ } => handlers::handle_tree(uri, abs_limit, all, node_limit, level_limit, simple, fields, tags, ctx).await,
Commands::Mkdir { uri, description } => handlers::handle_mkdir(uri, description, ctx).await,
Commands::Rm {
uri,
@@ -3612,6 +3635,8 @@ async fn main() {
wait,
processing_mode,
timeout,
+ tags,
+ tag_mode,
} => {
let effective_mode = if let Some(m) = mode {
m
@@ -3628,6 +3653,8 @@ async fn main() {
wait,
timeout,
processing_mode,
+ tags,
+ tag_mode,
ctx,
)
.await
@@ -3717,6 +3744,8 @@ async fn main() {
ignore_case,
node_limit,
level_limit,
+ tags,
+ fields,
} => {
handlers::handle_grep(
uri,
@@ -3725,6 +3754,8 @@ async fn main() {
ignore_case,
node_limit,
level_limit,
+ tags,
+ fields,
ctx,
)
.await
@@ -3736,7 +3767,8 @@ async fn main() {
node_limit,
simple,
fields,
- } => handlers::handle_glob(pattern, uri, node_limit, simple, fields, ctx).await,
+ tags,
+ } => handlers::handle_glob(pattern, uri, node_limit, simple, fields, tags, ctx).await,
};
if let Err(e) = result {
diff --git a/crates/ov_cli/src/tui/tree.rs b/crates/ov_cli/src/tui/tree.rs
index 78ac443ee..3f88e50a7 100644
--- a/crates/ov_cli/src/tui/tree.rs
+++ b/crates/ov_cli/src/tui/tree.rs
@@ -139,7 +139,7 @@ impl TreeState {
async fn fetch_children(client: &HttpClient, uri: &str) -> Result<Vec<TreeNode>, String> {
let result = client
- .ls(uri, false, false, "original", 256, false, 1000, &[])
+ .ls(uri, false, false, "original", 256, false, 1000, &[], &[], false)
.await
.map_err(|e| e.to_string())?;
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 48c3f43ac..1f5794cee 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -26,6 +26,9 @@ List directory contents.
| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before applying `node_limit`; directories remain first |
| sort_order | str | No | `asc` | Sort direction: `asc` or `desc` |
| extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |
+| tags | string[] | No | Unset | Return only entries matching every supplied `k=v` retrieval tag |
+
+`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
**Entry Structure**
@@ -98,7 +101,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}
+GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}
```
```bash
@@ -118,12 +121,12 @@ curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&recursiv
**CLI**
```bash
-openviking ls viking://resources/ [--simple] [--recursive] [-f FIELDS]
-openviking tree viking://resources/my-project/ [--simple] [-f FIELDS]
-openviking glob "**/*.md" [--uri viking://resources/] [--simple] [-f FIELDS]
+openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f FIELDS]
+openviking tree viking://resources/my-project/ [--simple] [--tags team=search,env=prod] [-f FIELDS]
+openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f FIELDS]
```
-`-f`/`--fields` accepts a comma-separated list of columns to display (ps `-o` style), producing a column-aligned table with a header row. Available fields: `name`, `uri`, `path`, `type`, `size`, `mode`, `mtime`, `locked`, `id`, `count`, `abstract`. Combining `--simple` with `-f` outputs comma-separated values (no header, no tree indentation), one entry per line — suitable for scripting pipelines. When `--simple` is used without `-f`, the previous behavior (bare URI per line) is preserved.
+`-f`/`--fields` accepts a comma-separated list of columns to display (ps `-o` style), producing a column-aligned table with a header row. Available fields: `name`, `uri`, `path`, `type`, `size`, `mode`, `mtime`, `locked`, `id`, `count`, `abstract`, `tags`. Combining `--simple` with `-f` outputs comma-separated values (no header, no tree indentation), one entry per line — suitable for scripting pipelines. When `--simple` is used without `-f`, the previous behavior (bare URI per line) is preserved.
**Response**
@@ -162,6 +165,9 @@ Get directory tree structure.
| node_limit | int | No | 1000 | Maximum number of results |
| level_limit | int | No | 3 | Maximum directory depth to traverse |
| extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |
+| tags | string[] | No | Unset | Retain only nodes matching every supplied `k=v` retrieval tag |
+
+`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
**Python HTTP SDK**
@@ -195,7 +201,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/tree?uri={uri}
+GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}
```
```bash
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
index bab95f993..bd0b01ebf 100644
--- a/docs/en/api/06-retrieval.md
+++ b/docs/en/api/06-retrieval.md
@@ -808,6 +808,12 @@ The `grep()` method performs regex pattern matching search in the file system, u
| exclude_uri | str | No | None | URI prefix to exclude from search |
| node_limit | int | No | 256 | Maximum number of results. Omitted requests default to 256; pass a larger integer when you need more results |
| level_limit | int | No | Python SDK: 5; HTTP API / CLI / Go SDK: 10 | Maximum directory depth to traverse. The Go SDK currently uses the HTTP API default. |
+| tags | string[] | No | Unset | Search only files matching every supplied `k=v` retrieval tag |
+| include_tags | bool | No | `false` | Include each matched file's retrieval tags without filtering |
+
+`tags` uses AND semantics and filters candidate files before content matching and `node_limit` truncation. For example, `["team=search", "env=prod"]` matches only files carrying both tags.
+
+Entries in `matches` include `tags` when `tags` filtering is used or `include_tags=true` is requested; files without retrieval tags then return an empty array (`[]`). Plain grep omits `tags` to avoid an unnecessary VectorDB read.
#### 3. Usage Examples
@@ -824,7 +830,8 @@ curl -X POST http://localhost:1933/api/v1/search/grep \
-d '{
"uri": "viking://resources",
"pattern": "authentication",
- "case_insensitive": true
+ "case_insensitive": true,
+ "tags": ["team=search", "env=prod"]
}'
```
@@ -841,6 +848,7 @@ results = client.grep(
pattern="authentication",
case_insensitive=True,
node_limit=1024,
+ tags=["team=search", "env=prod"],
)
print(f"Found {results['count']} matches")
@@ -852,7 +860,9 @@ for match in results['matches']:
**TypeScript SDK**
```typescript
-console.log(await client.grep("viking://resources/docs/", "authentication"));
+console.log(await client.grep("viking://resources/docs/", "authentication", {
+ tags: ["team=search", "env=prod"],
+}));
```
**Go SDK**
@@ -862,6 +872,7 @@ nodeLimit := 1024
result, err := client.Grep(ctx, "viking://resources", "authentication", &openviking.GrepOptions{
CaseInsensitive: true,
NodeLimit: &nodeLimit,
+ Tags: []string{"team=search", "env=prod"},
})
if err != nil {
return err
@@ -880,8 +891,16 @@ openviking grep "authentication" --uri viking://resources --ignore-case
# Specify depth limit
openviking grep "TODO" --uri viking://resources --level-limit 3
+
+# Search only files carrying every tag
+openviking grep "TODO" --uri viking://resources --tags team=search,env=prod
+
+# Include tags in human-readable results without filtering
+openviking grep "TODO" --uri viking://resources --fields tags
```
+For HTTP `POST /api/v1/search/grep`, set `include_tags: true` to include tags without filtering. A request with `tags` always returns tags for the matched files.
+
**Response Example**
```json
@@ -892,7 +911,8 @@ openviking grep "TODO" --uri viking://resources --level-limit 3
{
"uri": "viking://resources/docs/auth.md",
"line": 15,
- "content": "User authentication is handled by..."
+ "content": "User authentication is handled by...",
+ "tags": ["team=search", "env=prod"]
}
],
"count": 1
@@ -932,6 +952,10 @@ The `glob()` method uses file wildcard pattern matching URIs, similar to Unix sh
| uri | str | No | "viking://" | Starting URI |
| node_limit | int | No | 256 | Maximum number of matches to return. Omitted requests default to 256; pass a larger integer when you need more results |
| extra_fields | list[str] | No | None | Extra fields to include per match. Recognized names: `name`, `uri`, `path`, `type`, `size`, `mode`, `mtime`, `locked`, `id`. When omitted, the response contains URI strings only; when provided, `result.matches` becomes a list of entry objects |
+| tags | string[] | No | Unset | Retain only matches that have every supplied `k=v` retrieval tag |
+| include_tags | bool | No | `false` | Return retrieval tags for each match without filtering |
+
+`tags` uses AND semantics and is applied before `node_limit`. A tagged or `include_tags=true` request returns entry objects with a `tags` array; ordinary glob requests retain URI-string results and do not read tags from VectorDB.
#### 3. Usage Examples
@@ -948,7 +972,8 @@ curl -X POST http://localhost:1933/api/v1/search/glob \
-d '{
"pattern": "**/*.md",
"uri": "viking://resources",
- "extra_fields": ["name", "size", "mtime"]
+ "tags": ["team=search", "env=prod"],
+ "include_tags": true
}'
```
@@ -968,20 +993,21 @@ for uri in results['matches']:
# Find all Python files with extra stat fields
results = client.glob(
- pattern="**/*.py",
+ pattern="**/*.md",
uri="viking://resources",
- node_limit=1024,
- extra_fields=["name", "size", "mtime", "mode"],
+ tags=["team=search", "env=prod"],
)
-print(f"Found {results['count']} Python files")
+print(f"Found {results['count']} tagged markdown files")
for entry in results['matches']:
- print(f" {entry['name']} {entry['size']} {entry['mtime']}")
+ print(f" {entry['uri']} {entry['tags']}")
```
**TypeScript SDK**
```typescript
-console.log(await client.glob("**/*.md", "viking://resources/docs/"));
+console.log(await client.glob("**/*.md", "viking://resources/docs/", {
+ tags: ["team=search", "env=prod"],
+}));
```
**Go SDK**
@@ -989,6 +1015,7 @@ console.log(await client.glob("**/*.md", "viking://resources/docs/"));
```go
result, err := client.Glob(ctx, "**/*.md", "viking://resources", &openviking.GlobOptions{
NodeLimit: openviking.Int(1024),
+ Tags: []string{"team=search", "env=prod"},
})
if err != nil {
return err
@@ -1005,6 +1032,10 @@ openviking glob "**/*.md" --uri viking://resources
# Find all Python files
openviking glob "**/*.py"
+# Filter by all tags, or project tags without filtering
+openviking glob "**/*.md" --tags team=search,env=prod
+openviking glob "**/*.md" -f tags
+
# Table output with extra fields (ps -o style -f)
openviking glob "**/*.py" -f name,size,mtime,mode
diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.md
index e0783b5b0..c2ea88e34 100644
--- a/docs/en/api/12-content.md
+++ b/docs/en/api/12-content.md
@@ -222,6 +222,8 @@ Write a file and automatically refresh related semantics and vectors.
| mode | str | No | `replace` | `replace` overwrites an existing file or creates a missing file; `append` appends to an existing file or creates a missing file; `create` creates only a missing file and returns `409 Conflict` if it already exists |
| wait | bool | No | `false` | Wait for background semantic/vector refresh |
| timeout | float | No | `null` | Timeout in seconds when `wait=true` |
+| tags | string[] | No | Unset | Explicit retrieval tags for the written file, for example `["team=search", "env=prod"]` |
+| tag_mode | string | No | `replace` | Tag update mode when `tags` is supplied: `replace` overwrites tags; `append` merges tags by key |
**Notes**
@@ -230,6 +232,7 @@ Write a file and automatically refresh related semantics and vectors.
- Existing `.abstract.md` and `.overview.md` bodies may be updated, but public APIs cannot create them. A body-only request preserves stored OKF metadata; a full-OKF request must match the stored metadata. Unknown metadata fields are silently dropped. A sidecar body write rebuilds only the directory's existing L0/L1 vectors and does not regenerate semantics.
- File content is updated before the API returns. `wait` only controls whether the call waits for semantic/vector refresh to finish.
- The public API no longer accepts `regenerate_semantics` or `revectorize`; write always refreshes related semantics and vectors.
+- When `tags` is supplied, tags are included in the file's first vector upsert rather than updated after processing. Omitting `tags` preserves existing tags; explicit `tags: []` with `tag_mode: "replace"` clears them.
**Python SDK**
@@ -240,6 +243,7 @@ result = client.write(
content="# Updated API\n\nFresh content.",
mode="replace",
wait=True,
+ options={"tags": ["team=search", "env=prod"], "tag_mode": "replace"},
)
print(result["root_uri"])
```
@@ -247,7 +251,11 @@ print(result["root_uri"])
**TypeScript SDK**
```typescript
-await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
+await client.write("viking://resources/docs/new.md", "# New document\n", {
+ wait: true,
+ tags: ["team=search", "env=prod"],
+ tagMode: "replace",
+});
```
**Go SDK**
@@ -260,6 +268,8 @@ result, err := client.Write(
&openviking.WriteOptions{
Mode: "replace",
Wait: true,
+ Tags: []string{"team=search", "env=prod"},
+ TagMode: "replace",
},
)
if err != nil {
@@ -282,7 +292,9 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \
"uri": "viking://resources/docs/api.md",
"content": "# Updated API\n\nFresh content.",
"mode": "replace",
- "wait": true
+ "wait": true,
+ "tags": ["team=search", "env=prod"],
+ "tag_mode": "replace"
}'
```
@@ -291,6 +303,8 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \
```bash
openviking write viking://resources/docs/api.md \
--content "# Updated API\n\nFresh content." \
+ --tags team=search,env=prod \
+ --tag-mode replace \
--wait
```
@@ -726,10 +740,10 @@ curl -X POST http://localhost:1933/api/v1/content/reindex \
```bash
openviking reindex viking://resources --mode vectors_only \
- --tag team=search --tag env=prod --tag-mode replace
+ --tags team=search,env=prod --tag-mode replace
```
-The CLI sends tag fields only when at least one `--tag` is provided. Use HTTP or an SDK to clear tags with `tags: []`.
+The CLI sends tag fields only when non-empty `--tags` is provided. Use HTTP or an SDK to clear tags with `tags: []`.
```bash
openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index e3713367a..ef2c414e3 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -26,6 +26,9 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
| limit | int | 否 | None | `node_limit` 的别名 |
| sort_by | str | 否 | None | 在应用 `node_limit` 前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 |
| sort_order | str | 否 | `asc` | 排序方向:`asc` 或 `desc` |
+| tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |
+
+`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。
**条目结构**
@@ -37,7 +40,8 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
"modTime": "2024-01-01T00:00:00Z", # ISO 时间戳
"isDir": True, # 如果是目录则为 True
"uri": "viking://resources/docs/", # Viking URI
- "meta": {} # 可选元数据
+ "meta": {}, # 可选元数据
+ "tags": ["team=search"] # 显式检索标签;未设置时为空数组
}
```
@@ -67,6 +71,7 @@ entries = client.ls(
node_limit=200,
sort_by="mtime",
sort_order="desc",
+ tags=["team=search", "env=prod"],
)
for entry in entries:
type_str = "dir" if entry['isDir'] else "file"
@@ -76,14 +81,18 @@ for entry in entries:
**TypeScript SDK**
```typescript
-const entries = await client.list("viking://resources/docs/", { simple: true });
+const entries = await client.list("viking://resources/docs/", {
+ tags: ["team=search", "env=prod"],
+});
console.log(entries);
```
**Go SDK**
```go
-entries, err := client.List(ctx, "viking://resources/", nil)
+entries, err := client.List(ctx, "viking://resources/", &openviking.ListOptions{
+ Tags: []string{"team=search", "env=prod"},
+})
if err != nil {
return err
}
@@ -95,7 +104,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}
+GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}
```
```bash
@@ -110,12 +119,29 @@ curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&simple=t
# 递归列表
curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&recursive=true" \
-H "X-API-Key: your-key"
+
+# 按全部 tags 过滤(重复 query 参数)
+curl -G "http://localhost:1933/api/v1/fs/ls" \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "uri=viking://resources/" \
+ --data-urlencode "tags=team=search" \
+ --data-urlencode "tags=env=prod"
+
+# 不过滤、但在结果中携带 tags
+curl -G "http://localhost:1933/api/v1/fs/ls" \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "uri=viking://resources/" \
+ --data-urlencode "include_tags=true"
```
**CLI**
```bash
-openviking ls viking://resources/ [--simple] [--recursive]
+openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f tags]
+openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f tags]
+
+# 在人类可读列表中显示 tags;不能与 --simple 一起使用
+openviking ls viking://resources/ --fields tags
```
@@ -131,7 +157,8 @@ openviking ls viking://resources/ [--simple] [--recursive]
"mode": 16877,
"modTime": "2024-01-01T00:00:00Z",
"isDir": true,
- "uri": "viking://resources/docs/"
+ "uri": "viking://resources/docs/",
+ "tags": ["team=search"]
}
],
"time": 0.1
@@ -154,12 +181,15 @@ openviking ls viking://resources/ [--simple] [--recursive]
| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |
| node_limit | int | 否 | 1000 | 最大返回节点数 |
| level_limit | int | 否 | 3 | 最大目录遍历深度 |
+| tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的节点 |
+
+`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。
**Python HTTP SDK**
```python
-entries = client.tree(uri="viking://resources/")
+entries = client.tree(uri="viking://resources/", tags=["team=search", "env=prod"])
for entry in entries:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['rel_path']} - {type_str}")
@@ -168,14 +198,19 @@ for entry in entries:
**TypeScript SDK**
```typescript
-const tree = await client.tree("viking://resources/docs/", { nodeLimit: 100 });
+const tree = await client.tree("viking://resources/docs/", {
+ nodeLimit: 100,
+ tags: ["team=search", "env=prod"],
+});
console.log(tree);
```
**Go SDK**
```go
-entries, err := client.Tree(ctx, "viking://resources/", nil)
+entries, err := client.Tree(ctx, "viking://resources/", &openviking.TreeOptions{
+ Tags: []string{"team=search", "env=prod"},
+})
if err != nil {
return err
}
@@ -187,18 +222,25 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/tree?uri={uri}
+GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}
```
```bash
curl -X GET "http://localhost:1933/api/v1/fs/tree?uri=viking://resources/" \
-H "X-API-Key: your-key"
+
+# 仅返回同时包含 team=search 和 env=prod 的节点
+curl -G "http://localhost:1933/api/v1/fs/tree" \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "uri=viking://resources/" \
+ --data-urlencode "tags=team=search" \
+ --data-urlencode "tags=env=prod"
```
**CLI**
```bash
-openviking tree viking://resources/my-project/
+openviking tree viking://resources/my-project/ --fields tags
```
@@ -213,14 +255,16 @@ openviking tree viking://resources/my-project/
"size": 4096,
"isDir": true,
"rel_path": "docs/",
- "uri": "viking://resources/docs/"
+ "uri": "viking://resources/docs/",
+ "tags": ["team=search"]
},
{
"name": "api.md",
"size": 1024,
"isDir": false,
"rel_path": "docs/api.md",
- "uri": "viking://resources/docs/api.md"
+ "uri": "viking://resources/docs/api.md",
+ "tags": ["team=search", "env=prod"]
}
],
"time": 0.1
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
index 9ab0a68bf..169aa01b9 100644
--- a/docs/zh/api/06-retrieval.md
+++ b/docs/zh/api/06-retrieval.md
@@ -809,6 +809,12 @@ curl -X POST http://localhost:1933/api/v1/search/search \
| node_limit | int | 否 | 256 | 最大返回节点数。省略时默认使用 256;如需更多结果,请显式传入更大的整数 |
| exclude_uri | str | 否 | None | 要排除在搜索之外的 URI 前缀 |
| level_limit | int | 否 | Python SDK: 5;HTTP API / CLI / Go SDK: 10 | 最大目录遍历深度。Go SDK 当前使用 HTTP API 默认值。 |
+| tags | string[] | 否 | 未设置 | 仅搜索同时匹配全部 `k=v` 检索标签的文件 |
+| include_tags | bool | 否 | `false` | 不过滤时也在每条命中中返回检索标签 |
+
+`tags` 使用 AND 语义,并在内容匹配与 `node_limit` 截断之前过滤候选文件。例如 `["team=search", "env=prod"]` 只匹配同时具有两个标签的文件。
+
+使用 `tags` 过滤或传 `include_tags=true` 时,`matches` 中的命中会返回文件的 `tags`;没有检索标签的文件返回空数组 `[]`。普通 grep 会省略 `tags`,避免不必要的 VectorDB 读取。
#### 3. 使用示例
@@ -825,7 +831,8 @@ curl -X POST http://localhost:1933/api/v1/search/grep \
-d '{
"uri": "viking://resources",
"pattern": "authentication",
- "case_insensitive": true
+ "case_insensitive": true,
+ "tags": ["team=search", "env=prod"]
}'
```
@@ -842,6 +849,7 @@ results = client.grep(
pattern="authentication",
case_insensitive=True,
node_limit=1024,
+ tags=["team=search", "env=prod"],
)
print(f"Found {results['count']} matches")
@@ -853,7 +861,9 @@ for match in results['matches']:
**TypeScript SDK**
```typescript
-console.log(await client.grep("viking://resources/docs/", "authentication"));
+console.log(await client.grep("viking://resources/docs/", "authentication", {
+ tags: ["team=search", "env=prod"],
+}));
```
**Go SDK**
@@ -863,6 +873,7 @@ nodeLimit := 1024
result, err := client.Grep(ctx, "viking://resources", "authentication", &openviking.GrepOptions{
CaseInsensitive: true,
NodeLimit: &nodeLimit,
+ Tags: []string{"team=search", "env=prod"},
})
if err != nil {
return err
@@ -881,8 +892,16 @@ openviking grep "authentication" --uri viking://resources --ignore-case
# 指定深度限制
openviking grep "TODO" --uri viking://resources --level-limit 3
+
+# 只搜索同时匹配所有 tags 的文件
+openviking grep "TODO" --uri viking://resources --tags team=search,env=prod
+
+# 不过滤、但在人类可读结果中显示 tags
+openviking grep "TODO" --uri viking://resources --fields tags
```
+HTTP `POST /api/v1/search/grep` 在不做过滤时可传 `include_tags: true` 返回 tags;传入 `tags` 过滤时会始终返回命中文件的 tags。
+
**响应示例**
```json
@@ -893,7 +912,8 @@ openviking grep "TODO" --uri viking://resources --level-limit 3
{
"uri": "viking://resources/docs/auth.md",
"line": 15,
- "content": "User authentication is handled by..."
+ "content": "User authentication is handled by...",
+ "tags": ["team=search", "env=prod"]
}
],
"count": 1
@@ -932,6 +952,11 @@ openviking grep "TODO" --uri viking://resources --level-limit 3
| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`)|
| uri | str | 否 | "viking://" | 起始 URI |
| node_limit | int | 否 | 256 | 最大返回匹配数。省略时默认使用 256;如需更多结果,请显式传入更大的整数 |
+| extra_fields | list[str] | 否 | None | 每条命中的额外字段。省略时返回 URI 字符串;提供后 `result.matches` 返回条目对象 |
+| tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的结果 |
+| include_tags | bool | 否 | `false` | 不过滤时也在每条命中中返回检索标签 |
+
+`tags` 使用 AND 语义,并在 `node_limit` 截断前应用。传入 `tags` 或 `include_tags=true` 时,响应返回带 `tags` 数组的条目对象;普通 glob 继续返回 URI 字符串,且不会为了 tags 读取 VectorDB。
#### 3. 使用示例
@@ -947,7 +972,9 @@ curl -X POST http://localhost:1933/api/v1/search/glob \
-H "X-API-Key: your-key" \
-d '{
"pattern": "**/*.md",
- "uri": "viking://resources"
+ "uri": "viking://resources",
+ "tags": ["team=search", "env=prod"],
+ "include_tags": true
}'
```
@@ -965,19 +992,21 @@ print(f"Found {results['count']} markdown files:")
for uri in results['matches']:
print(f" {uri}")
-# 查找所有 Python 文件,并显式放宽返回上限
+# 查找同时匹配全部 tags 的 Markdown 文件
results = client.glob(
- pattern="**/*.py",
+ pattern="**/*.md",
uri="viking://resources",
- node_limit=1024,
+ tags=["team=search", "env=prod"],
)
-print(f"Found {results['count']} Python files")
+print(f"Found {results['count']} tagged markdown files")
```
**TypeScript SDK**
```typescript
-console.log(await client.glob("**/*.md", "viking://resources/docs/"));
+console.log(await client.glob("**/*.md", "viking://resources/docs/", {
+ tags: ["team=search", "env=prod"],
+}));
```
**Go SDK**
@@ -985,6 +1014,7 @@ console.log(await client.glob("**/*.md", "viking://resources/docs/"));
```go
result, err := client.Glob(ctx, "**/*.md", "viking://resources", &openviking.GlobOptions{
NodeLimit: openviking.Int(1024),
+ Tags: []string{"team=search", "env=prod"},
})
if err != nil {
return err
@@ -1000,6 +1030,10 @@ openviking glob "**/*.md" --uri viking://resources
# 查找所有 Python 文件
openviking glob "**/*.py"
+
+# 按全部 tags 过滤,或只返回 tags
+openviking glob "**/*.md" --tags team=search,env=prod
+openviking glob "**/*.md" -f tags
```
**响应示例**
diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.md
index 736113f65..fe2febb93 100644
--- a/docs/zh/api/12-content.md
+++ b/docs/zh/api/12-content.md
@@ -222,6 +222,8 @@ openviking read viking://resources/docs/api.md
| mode | str | 否 | `replace` | `replace` 覆盖已有文件、缺失时创建;`append` 追加已有文件、缺失时创建;`create` 仅创建缺失文件,目标已存在时返回 `409 Conflict` |
| wait | bool | 否 | `false` | 是否等待后台语义/向量刷新完成 |
| timeout | float | 否 | `null` | 当 `wait=true` 时的超时时间(秒) |
+| tags | string[] | 否 | 未设置 | 写入文件的显式检索标签,例如 `["team=search", "env=prod"]` |
+| tag_mode | string | 否 | `replace` | 提供 `tags` 时的更新方式:`replace` 覆盖标签,`append` 按 key 合并标签 |
**说明**
@@ -230,6 +232,7 @@ openviking read viking://resources/docs/api.md
- 已存在的 `.abstract.md` / `.overview.md` 可以修改正文,但不能通过公共 API 创建;只提交正文时会保留现有 OKF metadata,提交完整 OKF 时 metadata 必须与存量值一致。未知 metadata 字段会静默丢弃。sidecar 正文写入只重建该目录实际存在的 L0/L1 向量,不触发语义重新生成。
- 文件内容会在 API 返回前完成更新;`wait` 只控制是否等待语义/向量刷新完成。
- 公共 API 已不再接受 `regenerate_semantics` 或 `revectorize`;写入后一定会自动刷新相关语义与向量。
+- 提供 `tags` 时,标签会在该文件首次向量 upsert 时写入,而非在处理完成后再单独更新。省略 `tags` 不改变已有标签;显式 `tags: []` 配合 `tag_mode: "replace"` 可清空标签。
**Python SDK**
@@ -240,6 +243,7 @@ result = client.write(
content="# Updated API\n\nFresh content.",
mode="replace",
wait=True,
+ options={"tags": ["team=search", "env=prod"], "tag_mode": "replace"},
)
print(result["root_uri"])
```
@@ -247,7 +251,11 @@ print(result["root_uri"])
**TypeScript SDK**
```typescript
-await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
+await client.write("viking://resources/docs/new.md", "# New document\n", {
+ wait: true,
+ tags: ["team=search", "env=prod"],
+ tagMode: "replace",
+});
```
**Go SDK**
@@ -260,6 +268,8 @@ result, err := client.Write(
&openviking.WriteOptions{
Mode: "replace",
Wait: true,
+ Tags: []string{"team=search", "env=prod"},
+ TagMode: "replace",
},
)
if err != nil {
@@ -282,7 +292,9 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \
"uri": "viking://resources/docs/api.md",
"content": "# Updated API\n\nFresh content.",
"mode": "replace",
- "wait": true
+ "wait": true,
+ "tags": ["team=search", "env=prod"],
+ "tag_mode": "replace"
}'
```
@@ -291,6 +303,8 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \
```bash
openviking write viking://resources/docs/api.md \
--content "# Updated API\n\nFresh content." \
+ --tags team=search,env=prod \
+ --tag-mode replace \
--wait
```
@@ -726,10 +740,10 @@ curl -X POST http://localhost:1933/api/v1/content/reindex \
```bash
openviking reindex viking://resources --mode vectors_only \
- --tag team=search --tag env=prod --tag-mode replace
+ --tags team=search,env=prod --tag-mode replace
```
-CLI 仅在至少传入一个 `--tag` 时发送标签字段;如需用 `tags: []` 清空标签,请使用 HTTP 或 SDK。
+CLI 仅在 `--tags` 非空时发送标签字段;如需用 `tags: []` 清空标签,请使用 HTTP 或 SDK。
```bash
openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
diff --git a/openviking/server/routers/content.py b/openviking/server/routers/content.py
index b349a04b1..2a098eb5d 100644
--- a/openviking/server/routers/content.py
+++ b/openviking/server/routers/content.py
@@ -47,6 +47,8 @@ class WriteContentRequest(BaseModel):
timeout: float | None = None
telemetry: TelemetryRequest = False
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
+ tags: list[str] | None = None
+ tag_mode: Literal["replace", "append"] = "replace"
class BatchWriteOperation(BaseModel):
@@ -245,6 +247,8 @@ async def write(
wait=request.wait,
timeout=request.timeout,
processing_mode=request.processing_mode,
+ tags=request.tags,
+ tag_mode=request.tag_mode,
),
)
return Response(
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 2b74754c5..6495691f3 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -39,9 +39,7 @@ def _clean_memory_attrs(raw: str) -> dict[str, Any]:
return attrs
-async def _tags_attr(
- service: Any, uri: str, ctx: RequestContext, *, is_dir: bool
-) -> list[str]:
+async def _tags_attr(service: Any, uri: str, ctx: RequestContext, *, is_dir: bool) -> list[str]:
vikingdb_manager = getattr(service, "vikingdb_manager", None)
if not vikingdb_manager:
return []
@@ -85,6 +83,8 @@ async def ls(
extra_fields: Optional[list[str]] = Query(
None, description="Extra fields to include: locked, id, count"
),
+ tags: list[str] | None = Query(None, description="Only include entries matching all k=v tags"),
+ include_tags: bool = Query(False, description="Include tags in each entry"),
_ctx: RequestContext = Depends(get_request_context),
):
"""List directory contents."""
@@ -105,6 +105,8 @@ async def ls(
sort_by=sort_by,
sort_order=sort_order,
extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
@@ -128,6 +130,8 @@ async def tree(
extra_fields: Optional[list[str]] = Query(
None, description="Extra fields to include: locked, id, count"
),
+ tags: list[str] | None = Query(None, description="Only include entries matching all k=v tags"),
+ include_tags: bool = Query(False, description="Include tags in each entry"),
_ctx: RequestContext = Depends(get_request_context),
):
"""Get directory tree."""
@@ -145,6 +149,8 @@ async def tree(
node_limit=actual_node_limit,
level_limit=level_limit,
extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
@@ -209,9 +215,7 @@ async def attrs(
},
}
if result["context_type"] == "memory" and not stat_result.get("isDir", False):
- result["attrs"]["memory"] = _clean_memory_attrs(
- await service.fs.read(uri, ctx=_ctx)
- )
+ result["attrs"]["memory"] = _clean_memory_attrs(await service.fs.read(uri, ctx=_ctx))
return Response(status="ok", result=result)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
diff --git a/openviking/server/routers/search.py b/openviking/server/routers/search.py
index c9341303a..309e050ba 100644
--- a/openviking/server/routers/search.py
+++ b/openviking/server/routers/search.py
@@ -95,9 +95,7 @@ def _resolve_search_filter(
raise InvalidArgumentError(str(exc)) from exc
-def _resolve_uri_or_uris(
- uri: Union[str, List[str]], ctx: RequestContext
-) -> Union[str, List[str]]:
+def _resolve_uri_or_uris(uri: Union[str, List[str]], ctx: RequestContext) -> Union[str, List[str]]:
"""Resolve path variables in a single URI or list of URIs."""
if isinstance(uri, list):
return [validate_request_viking_uri(resolve_path_variables(u), ctx) for u in uri]
@@ -310,6 +308,8 @@ class GrepRequest(BaseModel):
case_insensitive: bool = False
node_limit: Optional[int] = 256
level_limit: int = 10
+ tags: Optional[List[str]] = None
+ include_tags: bool = False
class GlobRequest(BaseModel):
@@ -319,6 +319,8 @@ class GlobRequest(BaseModel):
uri: str = "viking://"
node_limit: Optional[int] = 256
extra_fields: Optional[list[str]] = None
+ tags: Optional[List[str]] = None
+ include_tags: bool = False
@router.post("/find")
@@ -534,6 +536,8 @@ async def grep(
case_insensitive=request.case_insensitive,
node_limit=request.node_limit,
level_limit=request.level_limit,
+ tags=request.tags,
+ include_tags=request.include_tags,
)
except AGFSNotFoundError:
raise NotFoundError(resolved_uri, "file")
@@ -565,6 +569,8 @@ async def glob(
uri=resolved_uri,
node_limit=request.node_limit,
extra_fields=request.extra_fields,
+ tags=request.tags,
+ include_tags=request.include_tags,
)
except AGFSNotFoundError:
raise NotFoundError(resolved_uri or request.pattern, "file")
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index f2a6ce374..aa13cc4ba 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -27,15 +27,18 @@ from openviking.storage.abstract_overview import (
)
from openviking.storage.acl import CreatorAclGrant
from openviking.storage.content_write import ContentWriteCoordinator
+from openviking.storage.expr import And, Eq, In, Or
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
from openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key
from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessAction
from openviking.storage.vector_ids import is_vector_record_id
from openviking.storage.viking_fs import VikingFS
+from openviking.storage.vikingdb_manager import VikingDBManagerProxy
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.telemetry.resource_summary import build_queue_status_payload
from openviking.utils.embedding_utils import vectorize_directory_meta
+from openviking.utils.tags import normalize_search_tags
from openviking_cli.exceptions import DeadlineExceededError, NotInitializedError
from openviking_cli.utils import VikingURI, get_logger
from openviking_cli.utils.config import get_openviking_config
@@ -123,6 +126,56 @@ class FSService:
return None
return self._watch_scheduler.watch_manager
+ async def _attach_and_filter_tags(
+ self,
+ entries: List[Dict[str, Any]],
+ ctx: RequestContext,
+ tags: Optional[List[str]],
+ include_tags: bool,
+ ) -> List[Dict[str, Any]]:
+ normalized_tags = normalize_search_tags(tags, discard_invalid=True)
+ if not entries or (not normalized_tags and not include_tags):
+ return entries
+ tags_by_uri: Dict[str, List[str]] = {}
+ if self._vikingdb:
+ uris = list(
+ dict.fromkeys(str(entry.get("uri") or "") for entry in entries if entry.get("uri"))
+ )
+ if uris:
+ records = await VikingDBManagerProxy(self._vikingdb, ctx).filter(
+ filter=And(
+ [Or([Eq("uri", item_uri) for item_uri in uris]), In("level", [0, 1, 2])]
+ ),
+ limit=max(len(uris) * 3, 1),
+ output_fields=["uri", "level", "search_tags"],
+ )
+ records_by_uri: Dict[str, List[Dict[str, Any]]] = {}
+ for record in records:
+ records_by_uri.setdefault(str(record.get("uri") or ""), []).append(record)
+ for entry in entries:
+ uri = str(entry.get("uri") or "")
+ levels = {0, 1} if entry.get("isDir", False) else {2}
+ found: List[str] = []
+ for record in sorted(
+ records_by_uri.get(uri, []), key=lambda item: item.get("level", 99)
+ ):
+ if record.get("level") in levels:
+ for tag in normalize_search_tags(
+ record.get("search_tags"), discard_invalid=True
+ ):
+ if tag not in found:
+ found.append(tag)
+ tags_by_uri[uri] = found
+ result_entries: List[Dict[str, Any]] = []
+ for entry in entries:
+ entry_tags = tags_by_uri.get(str(entry.get("uri") or ""), [])
+ if normalized_tags and not set(normalized_tags).issubset(entry_tags):
+ continue
+ if include_tags:
+ entry = {**entry, "tags": entry_tags}
+ result_entries.append(entry)
+ return result_entries
+
async def ls(
self,
uri: str,
@@ -137,6 +190,8 @@ class FSService:
sort_by: Optional[str] = None,
sort_order: str = "asc",
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Any]:
"""List directory contents.
@@ -165,7 +220,7 @@ class FSService:
ctx=ctx,
output="original",
show_all_hidden=show_all_hidden,
- node_limit=node_limit,
+ node_limit=None if tags else node_limit,
level_limit=level_limit,
)
else:
@@ -174,10 +229,13 @@ class FSService:
ctx=ctx,
output="original",
show_all_hidden=show_all_hidden,
- node_limit=node_limit,
+ node_limit=None if tags else node_limit,
sort_by=sort_by,
sort_order=sort_order,
)
+ entries = await self._attach_and_filter_tags(entries, ctx, tags, include_tags=False)
+ if tags and node_limit > 0:
+ entries = entries[:node_limit]
return [e.get("uri", "") for e in entries]
if recursive:
@@ -187,7 +245,7 @@ class FSService:
output=output,
abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
- node_limit=node_limit,
+ node_limit=None if tags else node_limit,
level_limit=level_limit,
extra_fields=extra_fields,
)
@@ -198,11 +256,16 @@ class FSService:
output=output,
abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
- node_limit=node_limit,
+ node_limit=None if tags else node_limit,
sort_by=sort_by,
sort_order=sort_order,
extra_fields=extra_fields,
)
+ entries = await self._attach_and_filter_tags(
+ entries, ctx, tags, include_tags or bool(tags) or "tags" in extra_fields
+ )
+ if tags and node_limit > 0:
+ entries = entries[:node_limit]
return entries
async def mkdir(
@@ -588,19 +651,27 @@ class FSService:
node_limit: int = 1000,
level_limit: int = 3,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Dict[str, Any]]:
"""Get directory tree."""
viking_fs = self._ensure_initialized()
- return await viking_fs.tree(
+ result = await viking_fs.tree(
uri,
ctx=ctx,
output=output,
abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
- node_limit=node_limit,
+ node_limit=None if tags else node_limit,
level_limit=level_limit,
extra_fields=extra_fields,
)
+ result = await self._attach_and_filter_tags(
+ result, ctx, tags, include_tags or bool(tags) or "tags" in (extra_fields or [])
+ )
+ if tags and node_limit > 0:
+ result = result[:node_limit]
+ return result
async def stat(self, uri: str, ctx: RequestContext) -> Dict[str, Any]:
"""Get resource status."""
@@ -678,19 +749,35 @@ class FSService:
case_insensitive: bool = False,
node_limit: Optional[int] = None,
level_limit: int = 10,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict:
"""Content search."""
viking_fs = self._ensure_initialized()
+ normalized_tags = normalize_search_tags(tags, discard_invalid=True)
+ tag_filter = None
+ if normalized_tags:
+ from openviking.utils.tags import build_search_tags_filter
+
+ tag_filter = build_search_tags_filter(normalized_tags)
kwargs = {
"exclude_uri": exclude_uri,
"case_insensitive": case_insensitive,
"node_limit": node_limit,
"level_limit": level_limit,
"ctx": ctx,
+ "tag_filter": tag_filter,
+ "include_tags": include_tags or bool(normalized_tags),
}
if _may_include_memory_content(uri):
kwargs["content_transform"] = _visible_grep_content
- return await viking_fs.grep(uri, pattern, **kwargs)
+ result = dict(await viking_fs.grep(uri, pattern, **kwargs))
+ matches = result.get("matches", [])
+ if include_tags and not normalized_tags and any("tags" not in match for match in matches):
+ matches = await self._attach_and_filter_tags(matches, ctx, None, include_tags=True)
+ result["matches"] = matches
+ result["count"] = len(matches)
+ return result
async def glob(
self,
@@ -699,12 +786,33 @@ class FSService:
uri: str = "viking://",
node_limit: Optional[int] = None,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict:
"""File pattern matching."""
viking_fs = self._ensure_initialized()
- return await viking_fs.glob(
- pattern, uri=uri, node_limit=node_limit, ctx=ctx, extra_fields=extra_fields
+ normalized_tags = normalize_search_tags(tags, discard_invalid=True)
+ project_tags = bool(normalized_tags) or include_tags
+ result = dict(
+ await viking_fs.glob(
+ pattern,
+ uri=uri,
+ node_limit=None if normalized_tags else node_limit,
+ ctx=ctx,
+ extra_fields=extra_fields if extra_fields is not None else ([] if project_tags else None),
+ )
)
+ if not project_tags:
+ return result
+
+ matches = await self._attach_and_filter_tags(
+ result.get("matches", []), ctx, normalized_tags, include_tags=True
+ )
+ if node_limit is not None and node_limit > 0:
+ matches = matches[:node_limit]
+ result["matches"] = matches
+ result["count"] = len(matches)
+ return result
async def read_file_bytes(self, uri: str, ctx: RequestContext) -> bytes:
"""Read file as raw bytes."""
@@ -720,6 +828,8 @@ class FSService:
wait: bool = False,
timeout: Optional[float] = None,
processing_mode: str = "semantic_and_vectors",
+ tags: Optional[List[str]] = None,
+ tag_mode: str = "replace",
) -> Dict[str, Any]:
"""Write to an existing file and refresh semantics/vectors."""
viking_fs = self._ensure_initialized()
@@ -732,6 +842,8 @@ class FSService:
wait=wait,
timeout=timeout,
processing_mode=processing_mode,
+ tags=tags,
+ tag_mode=tag_mode,
)
async def batch_write(
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 769c8b4c6..41522f996 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -815,6 +815,7 @@ class MemoryUpdater:
memory_type: Optional[str],
ctx: RequestContext,
strict: bool = False,
+ ingest_options=None,
) -> bool:
if not vikingdb or not bool(getattr(vikingdb, "has_queue_manager", False)):
return False
@@ -829,6 +830,7 @@ class MemoryUpdater:
result,
ctx,
uri_memory_type_map={uri: memory_type} if memory_type else {},
+ ingest_options=ingest_options,
)
return attempted > 0
except Exception:
@@ -1388,6 +1390,7 @@ class MemoryUpdater:
extract_context: Any = None,
uri_memory_type_map: Dict[str, str] = None,
search_tags_by_uri: Dict[str, List[str]] = None,
+ ingest_options: Any = None,
) -> int:
"""Vectorize written and edited memory files.
@@ -1397,6 +1400,7 @@ class MemoryUpdater:
extract_context: Extract context for embedding template rendering
uri_memory_type_map: Mapping from URI to memory_type
search_tags_by_uri: Transient search tags to attach while indexing each URI
+ ingest_options: Write options for a single-file content write.
"""
if not self._vikingdb:
logger.debug("VikingDB not available, skipping vectorization")
@@ -1484,12 +1488,18 @@ class MemoryUpdater:
# Convert to embedding msg and enqueue
embedding_msg = EmbeddingMsgConverter.from_context(memory_context)
if embedding_msg:
- transient_tags = search_tags_by_uri.get(uri)
- if transient_tags:
- embedding_msg.context_data["search_tags"] = list(transient_tags)
+ if getattr(ingest_options, "search_tags", None) is not None:
+ embedding_msg.context_data["search_tags"] = list(ingest_options.search_tags)
embedding_msg.context_data["_upsert_options"] = {
- "search_tag_mode": "append"
+ "search_tag_mode": ingest_options.search_tag_mode
}
+ else:
+ transient_tags = search_tags_by_uri.get(uri)
+ if transient_tags:
+ embedding_msg.context_data["search_tags"] = list(transient_tags)
+ embedding_msg.context_data["_upsert_options"] = {
+ "search_tag_mode": "append"
+ }
if embedding_msg.telemetry_id:
request_wait_tracker.register_embedding_root(
embedding_msg.telemetry_id, embedding_msg.id
diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.py
index f446e74be..c8335b9f9 100644
--- a/openviking/storage/content_write.py
+++ b/openviking/storage/content_write.py
@@ -47,6 +47,7 @@ from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.telemetry.resource_summary import build_queue_status_payload
from openviking.utils.embedding_utils import vectorize_directory_meta, vectorize_file
+from openviking.utils.ingest_options import IngestOptions
from openviking.utils.path_safety import validate_safe_viking_uri_path
from openviking.utils.tags import normalize_search_tags
from openviking_cli.exceptions import (
@@ -125,12 +126,15 @@ class ContentWriteCoordinator:
wait: bool = False,
timeout: Optional[float] = None,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ tags: list[str] | None = None,
+ tag_mode: str = "replace",
) -> Dict[str, Any]:
self._validate_mode(mode)
processing_mode = normalize_processing_mode(processing_mode)
normalized_uri = self._validate_uri_path(uri, field_name="uri")
self._ensure_content_write_policy(normalized_uri)
await self._viking_fs._ensure_access(normalized_uri, ctx, action=AclAction.WRITE)
+ ingest_options = IngestOptions.from_search_tags(tags, mode=tag_mode)
if mode == "create":
return await self._create_and_write(
@@ -140,6 +144,7 @@ class ContentWriteCoordinator:
wait=wait,
timeout=timeout,
processing_mode=processing_mode,
+ ingest_options=ingest_options,
)
stat = await self._safe_stat(normalized_uri, ctx=ctx, allow_not_found=True)
@@ -155,6 +160,7 @@ class ContentWriteCoordinator:
processing_mode=processing_mode,
result_mode=mode,
validate_extension=False,
+ ingest_options=ingest_options,
)
if stat.get("isDir"):
raise InvalidArgumentError(
@@ -180,6 +186,7 @@ class ContentWriteCoordinator:
written_bytes=written_bytes,
telemetry_id=telemetry_id,
processing_mode=processing_mode,
+ ingest_options=ingest_options,
)
return await self._write_direct_with_refresh(
@@ -194,6 +201,7 @@ class ContentWriteCoordinator:
written_bytes=written_bytes,
telemetry_id=telemetry_id,
processing_mode=processing_mode,
+ ingest_options=ingest_options,
)
async def batch_write(
@@ -576,6 +584,7 @@ class ContentWriteCoordinator:
target_uri: str = "",
recursive: bool = False,
force_refresh: bool = False,
+ ingest_options: IngestOptions | None = None,
) -> FreshnessAction:
changed_entries = len({uri for values in changes.values() for uri in values})
semantic_config = get_openviking_config().semantic
@@ -606,6 +615,7 @@ class ContentWriteCoordinator:
role=str(ctx.role),
skip_vectorization=False,
telemetry_id=telemetry.telemetry_id,
+ ingest_options=ingest_options,
coalesce_key=(
build_semantic_coalesce_key(
context_type=context_type,
@@ -775,6 +785,7 @@ class ContentWriteCoordinator:
written_bytes: int,
telemetry_id: str,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ ingest_options: IngestOptions | None = None,
) -> Dict[str, Any]:
lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
try:
@@ -810,7 +821,9 @@ class ContentWriteCoordinator:
)
content_written = True
if is_abstract_overview_uri(uri):
- vector_enqueued = await self._vectorize_abstract_overview(uri=uri, ctx=ctx)
+ vector_enqueued = await self._vectorize_abstract_overview(
+ uri=uri, ctx=ctx, ingest_options=ingest_options
+ )
post_process_started = True
elif processing_mode == VECTORS_ONLY:
vector_enqueued = await self._vectorize_written_file(
@@ -818,6 +831,7 @@ class ContentWriteCoordinator:
context_type=context_type,
ctx=ctx,
creator_acl_grant=(CreatorAclGrant.DIRECT if mode == "create" else None),
+ ingest_options=ingest_options,
)
post_process_started = True
else:
@@ -828,6 +842,7 @@ class ContentWriteCoordinator:
ctx=ctx,
change_type="added" if mode == "create" else "modified",
force_refresh=wait,
+ ingest_options=ingest_options,
)
post_process_started = True
await self._viking_fs._async_agfs.pathlock_release(lease)
@@ -926,6 +941,7 @@ class ContentWriteCoordinator:
context_type: str,
ctx: RequestContext,
creator_acl_grant: CreatorAclGrant | None = None,
+ ingest_options: IngestOptions | None = None,
) -> bool:
parent = VikingURI(uri).parent
if parent is None:
@@ -938,19 +954,32 @@ class ContentWriteCoordinator:
context_type=context_type,
ctx=ctx,
creator_acl_grant=creator_acl_grant,
+ ingest_options=ingest_options,
)
- async def _vectorize_abstract_overview(self, *, uri: str, ctx: RequestContext) -> bool:
+ async def _vectorize_abstract_overview(
+ self,
+ *,
+ uri: str,
+ ctx: RequestContext,
+ ingest_options: IngestOptions | None = None,
+ ) -> bool:
"""Re-index a manually edited L0/L1 body without regenerating it."""
parent = VikingURI(uri).parent
if parent is None:
return False
- await self._vectorize_semantic_directory(directory_uri=parent.uri, ctx=ctx)
+ await self._vectorize_semantic_directory(
+ directory_uri=parent.uri, ctx=ctx, ingest_options=ingest_options
+ )
return True
async def _vectorize_semantic_directory(
- self, *, directory_uri: str, ctx: RequestContext
+ self,
+ *,
+ directory_uri: str,
+ ctx: RequestContext,
+ ingest_options: IngestOptions | None = None,
) -> None:
"""Re-index the semantic levels that exist for one directory."""
@@ -974,6 +1003,7 @@ class ContentWriteCoordinator:
ctx=ctx,
include_abstract=abstract is not None,
include_overview=overview is not None,
+ ingest_options=ingest_options,
)
def _validate_mode(self, mode: str) -> None:
@@ -1035,6 +1065,7 @@ class ContentWriteCoordinator:
wait: bool,
timeout: Optional[float],
processing_mode: ProcessingMode,
+ ingest_options: IngestOptions | None = None,
result_mode: str = "create",
validate_extension: bool = True,
) -> Dict[str, Any]:
@@ -1067,6 +1098,7 @@ class ContentWriteCoordinator:
written_bytes=written_bytes,
telemetry_id=telemetry_id,
processing_mode=processing_mode,
+ ingest_options=ingest_options,
)
return await self._write_direct_with_refresh(
@@ -1082,6 +1114,7 @@ class ContentWriteCoordinator:
written_bytes=written_bytes,
telemetry_id=telemetry_id,
processing_mode=processing_mode,
+ ingest_options=ingest_options,
)
async def _write_in_place(
@@ -1161,6 +1194,7 @@ class ContentWriteCoordinator:
target_uri: str = "",
recursive: bool = False,
force_refresh: bool = False,
+ ingest_options: IngestOptions | None = None,
) -> FreshnessAction:
return await self._enqueue_semantic_refresh_changes(
root_uri=root_uri,
@@ -1170,6 +1204,7 @@ class ContentWriteCoordinator:
target_uri=target_uri,
recursive=recursive,
force_refresh=force_refresh,
+ ingest_options=ingest_options,
)
async def _wait_for_queues(self, *, timeout: Optional[float]) -> Dict[str, Any]:
@@ -1209,6 +1244,7 @@ class ContentWriteCoordinator:
written_bytes: int,
telemetry_id: str,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ ingest_options: IngestOptions | None = None,
) -> Dict[str, Any]:
del processing_mode
@@ -1241,6 +1277,7 @@ class ContentWriteCoordinator:
uri=uri,
memory_type=MemoryUpdater.memory_type_from_uri(root_uri),
ctx=ctx,
+ ingest_options=ingest_options,
)
queue_status = None
if embedding_requested and wait:
diff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.py
index 0fa381e87..fa1b2f624 100644
--- a/openviking/storage/queuefs/semantic_dag.py
+++ b/openviking/storage/queuefs/semantic_dag.py
@@ -519,6 +519,19 @@ class SemanticDagExecutor:
prefix = uri.rstrip("/") + "/"
return any(path.startswith(prefix) for path in self._changed_paths)
+ def _ingest_options_for_file(self, file_path: str) -> IngestOptions:
+ if (
+ self._generation_trigger == "content_write"
+ and file_path not in self._changed_paths
+ ):
+ return IngestOptions()
+ return self._ingest_options
+
+ def _ingest_options_for_directory(self) -> IngestOptions:
+ if self._generation_trigger == "content_write":
+ return IngestOptions()
+ return self._ingest_options
+
async def _check_file_content_changed(self, file_path: str) -> bool:
if self._is_direct_incremental_update():
return file_path in self._changed_paths
@@ -712,7 +725,7 @@ class SemanticDagExecutor:
summary_dict=summary_dict,
ctx=self._ctx,
use_summary=use_summary,
- ingest_options=self._ingest_options,
+ ingest_options=self._ingest_options_for_file(file_path),
creator_acl_grant=self._creator_acl_grant(file_path),
)
except Exception as e:
@@ -968,7 +981,7 @@ class SemanticDagExecutor:
abstract=abstract,
overview=overview,
ctx=self._ctx,
- ingest_options=self._ingest_options,
+ ingest_options=self._ingest_options_for_directory(),
creator_acl_grant=self._creator_acl_grant(dir_uri),
)
except Exception as e:
diff --git a/openviking/storage/viking_fs/_grep.py b/openviking/storage/viking_fs/_grep.py
index 8451249f1..f0e048e65 100644
--- a/openviking/storage/viking_fs/_grep.py
+++ b/openviking/storage/viking_fs/_grep.py
@@ -6,7 +6,7 @@ import asyncio
import re
import sys
import time
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Set
from openviking.pyagfs.exceptions import AGFSNotSupportedError
from openviking.server.identity import RequestContext
@@ -32,6 +32,9 @@ class _GrepMixin:
level_limit: int = 10,
ctx: Optional[RequestContext] = None,
content_transform: Optional[Callable[[str, str], str]] = None,
+ allowed_uris: Optional[Set[str]] = None,
+ tag_filter: Optional[Dict[str, Any]] = None,
+ include_tags: bool = False,
) -> Dict:
"""Content search by pattern or keywords.
@@ -75,9 +78,33 @@ class _GrepMixin:
if content_transform is not None
else await self._resolve_grep_engine(engine, uri, ctx, switch_to_remote_threshold)
)
+ tags_by_uri: Dict[str, List[str]] = {}
+ if tag_filter is not None and resolved_engine == "fs":
+ vector_store = self._get_vector_store()
+ if vector_store is None:
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+ records = await vector_store.filter(
+ filter=And(
+ [
+ PathScope("uri", uri, depth=level_limit),
+ RawDSL(tag_filter),
+ ]
+ ),
+ limit=100000,
+ output_fields=["uri", "search_tags"],
+ ctx=ctx,
+ )
+ allowed_uris = {str(record["uri"]) for record in records if record.get("uri")}
+ if not allowed_uris:
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+ tags_by_uri = {
+ str(record["uri"]): list(record.get("search_tags") or [])
+ for record in records
+ if record.get("uri")
+ }
if resolved_engine == "fs":
- return await self._grep_fs(
+ result = await self._grep_fs(
uri=uri,
pattern=pattern,
exclude_uri=exclude_uri,
@@ -86,9 +113,10 @@ class _GrepMixin:
level_limit=level_limit,
ctx=ctx,
content_transform=content_transform,
+ allowed_uris=allowed_uris,
)
else: # "vikingdb_then_fs"
- return await self._grep_vikingdb_then_fs(
+ result = await self._grep_vikingdb_then_fs(
uri=uri,
pattern=pattern,
exclude_uri=exclude_uri,
@@ -96,7 +124,11 @@ class _GrepMixin:
node_limit=node_limit,
level_limit=level_limit,
ctx=ctx,
+ allowed_uris=allowed_uris,
+ tag_filter=tag_filter,
+ include_tags=include_tags,
)
+ return self._attach_grep_tags(result, tags_by_uri)
async def _resolve_grep_engine(
self, engine: GrepEngine, uri: str, ctx, switch_to_remote_threshold: int = 10000
@@ -200,9 +232,10 @@ class _GrepMixin:
level_limit,
ctx,
content_transform=None,
+ allowed_uris=None,
):
"""Filesystem grep path: prefer native agfs grep and fall back if unavailable."""
- if content_transform is None:
+ if content_transform is None and allowed_uris is None:
try:
return await self._grep_with_agfs(
uri=uri,
@@ -225,6 +258,7 @@ class _GrepMixin:
level_limit=level_limit,
ctx=ctx,
content_transform=content_transform,
+ allowed_uris=allowed_uris,
)
async def _grep_vikingdb_then_fs(
@@ -236,9 +270,14 @@ class _GrepMixin:
node_limit,
level_limit,
ctx,
+ allowed_uris=None,
+ tag_filter=None,
+ include_tags=False,
):
"""VikingDB bm25 recall + local fs precise matching."""
vector_store = self._get_vector_store()
+ tags_by_uri: Dict[str, List[str]] = {}
+ output_fields = ["uri", "search_tags"] if tag_filter is not None or include_tags else ["uri"]
# Split regex alternation (e.g. "error|warning|fail") and join as a
# single query string for bm25 search. VikingDB's standard tokenizer
@@ -249,15 +288,21 @@ class _GrepMixin:
if exclude_uri:
excluded_prefix = exclude_uri.rstrip("/")
await self._ensure_access(excluded_prefix, ctx)
- filter_expr = And([
- filter_expr,
- RawDSL({
- "op": "must_not",
- "field": "uri",
- "conds": [excluded_prefix],
- "para": "-d=-1",
- }),
- ])
+ filter_expr = And(
+ [
+ filter_expr,
+ RawDSL(
+ {
+ "op": "must_not",
+ "field": "uri",
+ "conds": [excluded_prefix],
+ "para": "-d=-1",
+ }
+ ),
+ ]
+ )
+ if tag_filter is not None:
+ filter_expr = And([filter_expr, RawDSL(tag_filter)])
# Auto-adapt bm25 recall limit: recall up to 5x requested matches
# while capping at VikingDB's max limit. If node_limit is unset,
@@ -272,28 +317,62 @@ class _GrepMixin:
query,
remote_return_limit,
filter_expr,
- ["uri"],
+ output_fields,
)
result = await vector_store.search_by_keywords(
query=query,
limit=remote_return_limit,
filter=filter_expr,
- output_fields=["uri"],
+ output_fields=output_fields,
ctx=ctx,
)
except Exception as e:
logger.warning(f"grep vikingdb step failed, falling back to fs: {e}")
- return await self._grep_fs(
- uri=uri,
- pattern=pattern,
- exclude_uri=exclude_uri,
- case_insensitive=case_insensitive,
- node_limit=node_limit,
- level_limit=level_limit,
- ctx=ctx,
- )
+ if tag_filter is not None and allowed_uris is None:
+ try:
+ records = await vector_store.filter(
+ filter=And(
+ [
+ PathScope("uri", uri, depth=level_limit),
+ RawDSL(tag_filter),
+ ]
+ ),
+ limit=100000,
+ output_fields=["uri", "search_tags"],
+ ctx=ctx,
+ )
+ except Exception as filter_error:
+ logger.warning(
+ "grep tag-filter fallback failed; returning no results: %s",
+ filter_error,
+ )
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+ allowed_uris = {str(record["uri"]) for record in records if record.get("uri")}
+ if not allowed_uris:
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+ tags_by_uri = {
+ str(record["uri"]): list(record.get("search_tags") or [])
+ for record in records
+ if record.get("uri")
+ }
+ fallback_kwargs = {
+ "uri": uri,
+ "pattern": pattern,
+ "exclude_uri": exclude_uri,
+ "case_insensitive": case_insensitive,
+ "node_limit": node_limit,
+ "level_limit": level_limit,
+ "ctx": ctx,
+ }
+ if allowed_uris is not None:
+ fallback_kwargs["allowed_uris"] = allowed_uris
+ return self._attach_grep_tags(await self._grep_fs(**fallback_kwargs), tags_by_uri)
candidate_uris = [r["uri"] for r in result if r.get("uri")]
+ if allowed_uris is not None:
+ candidate_uris = [
+ candidate_uri for candidate_uri in candidate_uris if candidate_uri in allowed_uris
+ ]
if excluded_prefix:
candidate_uris = [
u
@@ -305,13 +384,34 @@ class _GrepMixin:
return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
# Step 2: local fs precise matching on candidate files
- return await self._grep_in_files(
+ grep_result = await self._grep_in_files(
candidate_uris,
pattern,
case_insensitive,
node_limit,
ctx,
)
+ if tag_filter is None and not include_tags:
+ return grep_result
+ return self._attach_grep_tags(
+ grep_result,
+ {
+ str(record["uri"]): list(record.get("search_tags") or [])
+ for record in result
+ if record.get("uri")
+ },
+ )
+
+ @staticmethod
+ def _attach_grep_tags(result: Dict, tags_by_uri: Dict[str, List[str]]) -> Dict:
+ if not tags_by_uri:
+ return result
+ result = dict(result)
+ result["matches"] = [
+ {**match, "tags": tags_by_uri.get(str(match.get("uri") or ""), [])}
+ for match in result.get("matches", [])
+ ]
+ return result
async def _grep_in_files(
self,
@@ -427,11 +527,13 @@ class _GrepMixin:
files_scanned_set.add(file_uri)
- results.append({
- "line": match.get("line", match.get("line_number", 0)),
- "uri": file_uri,
- "content": match.get("content", ""),
- })
+ results.append(
+ {
+ "line": match.get("line", match.get("line_number", 0)),
+ "uri": file_uri,
+ "content": match.get("content", ""),
+ }
+ )
if node_limit and len(results) >= node_limit:
break
@@ -463,6 +565,7 @@ class _GrepMixin:
level_limit: int = 10,
ctx: Optional[RequestContext] = None,
content_transform: Optional[Callable[[str, str], str]] = None,
+ allowed_uris: Optional[Set[str]] = None,
) -> Dict:
"""Grep implementation for encrypted files.
@@ -492,6 +595,7 @@ class _GrepMixin:
excluded_prefix=excluded_prefix,
level_limit=level_limit,
ctx=ctx,
+ allowed_uris=allowed_uris,
)
results, files_scanned = await self._grep_files_parallel(
file_uris,
@@ -514,6 +618,7 @@ class _GrepMixin:
excluded_prefix: Optional[str],
level_limit: int,
ctx: Optional[RequestContext] = None,
+ allowed_uris: Optional[Set[str]] = None,
) -> List[str]:
file_uris: List[str] = []
@@ -544,7 +649,7 @@ class _GrepMixin:
if entry.get("isDir"):
await search_recursive(entry_uri, current_depth + 1)
- else:
+ elif allowed_uris is None or entry_uri in allowed_uris:
file_uris.append(entry_uri)
normalized_uri = uri
@@ -558,7 +663,8 @@ class _GrepMixin:
except Exception:
return file_uris
if not root_stat.get("isDir", False):
- file_uris.append(normalized_uri)
+ if allowed_uris is None or normalized_uri in allowed_uris:
+ file_uris.append(normalized_uri)
return file_uris
await search_recursive(uri, 0)
@@ -614,11 +720,13 @@ class _GrepMixin:
lines = content.split("\n")
for line_num, line in enumerate(lines, 1):
if compiled_pattern.search(line):
- matches.append({
- "line": line_num,
- "uri": entry_uri,
- "content": line,
- })
+ matches.append(
+ {
+ "line": line_num,
+ "uri": entry_uri,
+ "content": line,
+ }
+ )
return matches, 1
except Exception as e:
logger.debug(f"Failed to grep {entry_uri}: {e}")
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 9c33cb033..1717a8bd3 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -230,7 +230,7 @@ func TestFindUsesDefaultLimitAndPreservesEmptyValues(t *testing.T) {
}
func TestListAndTreeSendQueryOptions(t *testing.T) {
- wantTreeLimits := []string{"0", "3"}
+ treeCalls := 0
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/api/v1/fs/ls":
@@ -243,11 +243,21 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
if got := r.URL.Query().Get("sort_order"); got != "desc" {
t.Fatalf("sort_order = %q", got)
}
+ if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod", "team=search"}) {
+ t.Fatalf("tags = %#v", got)
+ }
case "/api/v1/fs/tree":
- if got := r.URL.Query().Get("level_limit"); got != wantTreeLimits[0] {
- t.Fatalf("level_limit = %q, want %q", got, wantTreeLimits[0])
+ if treeCalls == 0 {
+ if got := r.URL.Query().Get("level_limit"); got != "0" {
+ t.Fatalf("level_limit = %q, want 0", got)
+ }
+ if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod"}) {
+ t.Fatalf("tags = %#v", got)
+ }
+ } else if got := r.URL.Query().Get("level_limit"); got != "3" {
+ t.Fatalf("level_limit = %q, want 3", got)
}
- wantTreeLimits = wantTreeLimits[1:]
+ treeCalls++
default:
t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
}
@@ -259,10 +269,11 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
NodeLimit: 200,
SortBy: "mtime",
SortOrder: "desc",
+ Tags: []string{"env=prod", "team=search"},
}); err != nil {
t.Fatal(err)
}
- if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{LevelLimit: Int(0)}); err != nil {
+ if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{LevelLimit: Int(0), Tags: []string{"env=prod"}}); err != nil {
t.Fatal(err)
}
if _, err := client.Tree(context.Background(), "viking://resources/docs", nil); err != nil {
@@ -613,7 +624,7 @@ func TestSearchContextSendsContextOptionsAndRejectsModeOverride(t *testing.T) {
func TestWriteSendsProcessingModeAndExtra(t *testing.T) {
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
body := readJSONBody(t, r)
- if body["processing_mode"] != "vectors_only" || body["future_flag"] != float64(0) || body["wait"] != true {
+ if body["processing_mode"] != "vectors_only" || body["future_flag"] != float64(0) || body["wait"] != true || !reflect.DeepEqual(body["tags"], []any{}) || body["tag_mode"] != "replace" {
t.Fatalf("body = %#v", body)
}
writeOK(t, w, map[string]any{"uri": "viking://resources/a.md"})
@@ -622,6 +633,8 @@ func TestWriteSendsProcessingModeAndExtra(t *testing.T) {
if _, err := client.Write(context.Background(), "resources/a.md", "", &WriteOptions{
ProcessingMode: "vectors_only",
+ Tags: []string{},
+ TagMode: "replace",
Wait: true,
Extra: map[string]any{"future_flag": 0},
}); err != nil {
@@ -629,6 +642,62 @@ func TestWriteSendsProcessingModeAndExtra(t *testing.T) {
}
}
+func TestFilesystemTagProjectionOptionsAreSent(t *testing.T) {
+ requests := 0
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ requests++
+ switch requests {
+ case 1:
+ if r.URL.Query().Get("include_tags") != "true" {
+ t.Fatalf("list query = %s", r.URL.RawQuery)
+ }
+ case 2:
+ if r.URL.Query().Get("include_tags") != "true" {
+ t.Fatalf("tree query = %s", r.URL.RawQuery)
+ }
+ case 3:
+ body := readJSONBody(t, r)
+ if body["include_tags"] != true {
+ t.Fatalf("grep body = %#v", body)
+ }
+ case 4:
+ if _, ok := r.URL.Query()["include_tags"]; ok {
+ t.Fatalf("default list query unexpectedly includes tags projection: %s", r.URL.RawQuery)
+ }
+ case 5:
+ body := readJSONBody(t, r)
+ if !reflect.DeepEqual(body["tags"], []any{"team=search", "env=prod"}) || body["include_tags"] != true {
+ t.Fatalf("glob body = %#v", body)
+ }
+ }
+ if requests == 3 || requests == 5 {
+ writeOK(t, w, map[string]any{})
+ return
+ }
+ writeOK(t, w, []any{})
+ }))
+ defer closeServer()
+
+ if _, err := client.List(context.Background(), "resources", &ListOptions{IncludeTags: true}); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := client.Tree(context.Background(), "resources", &TreeOptions{IncludeTags: true}); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := client.Grep(context.Background(), "resources", "needle", &GrepOptions{IncludeTags: true}); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := client.List(context.Background(), "resources", nil); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := client.Glob(context.Background(), "**/*.md", "resources", &GlobOptions{
+ Tags: []string{"team=search", "env=prod"},
+ IncludeTags: true,
+ }); err != nil {
+ t.Fatal(err)
+ }
+}
+
func TestBatchWriteAndDownloadBytes(t *testing.T) {
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.Method + " " + r.URL.Path {
@@ -1726,12 +1795,15 @@ func TestGrepForwardsLevelLimit(t *testing.T) {
if got, ok := body["level_limit"]; !ok || got != float64(3) {
t.Fatalf("level_limit = %#v (ok=%v)", body["level_limit"], ok)
}
+ if !reflect.DeepEqual(body["tags"], []any{"env=prod"}) {
+ t.Fatalf("tags = %#v", body["tags"])
+ }
writeOK(t, w, map[string]any{"matches": []any{}})
}))
defer closeServer()
level := 3
- if _, err := client.Grep(context.Background(), "viking://user", "pat", &GrepOptions{LevelLimit: &level}); err != nil {
+ if _, err := client.Grep(context.Background(), "viking://user", "pat", &GrepOptions{LevelLimit: &level, Tags: []string{"env=prod"}}); err != nil {
t.Fatal(err)
}
}
diff --git a/sdk/go/filesystem.go b/sdk/go/filesystem.go
index 01c8268fb..a9ff82e0a 100644
--- a/sdk/go/filesystem.go
+++ b/sdk/go/filesystem.go
@@ -32,6 +32,12 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any
queryInt(query, "abs_limit", absLimit)
queryBool(query, "show_all_hidden", opts.ShowAllHidden)
queryInt(query, "node_limit", nodeLimit)
+ if opts.Tags != nil {
+ query["tags"] = opts.Tags
+ }
+ if opts.IncludeTags {
+ query.Set("include_tags", "true")
+ }
if opts.SortBy != "" {
query.Set("sort_by", opts.SortBy)
}
@@ -71,6 +77,12 @@ func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]map
queryBool(query, "show_all_hidden", opts.ShowAllHidden)
queryInt(query, "node_limit", nodeLimit)
queryInt(query, "level_limit", levelLimit)
+ if opts.Tags != nil {
+ query["tags"] = opts.Tags
+ }
+ if opts.IncludeTags {
+ query.Set("include_tags", "true")
+ }
var result []map[string]any
err := c.doJSON(ctx, http.MethodGet, "/api/v1/fs/tree", query, nil, &result)
return result, err
@@ -200,6 +212,14 @@ func (c *Client) Write(ctx context.Context, uri string, content string, opts *Wr
setFloatPtr(payload, "timeout", opts.Timeout)
setAny(payload, "telemetry", opts.Telemetry)
setString(payload, "processing_mode", opts.ProcessingMode)
+ if opts.Tags != nil {
+ payload["tags"] = opts.Tags
+ tagMode := opts.TagMode
+ if tagMode == "" {
+ tagMode = "replace"
+ }
+ payload["tag_mode"] = tagMode
+ }
if err := mergeExtra(payload, opts.Extra); err != nil {
return nil, err
}
diff --git a/sdk/go/retrieval.go b/sdk/go/retrieval.go
index 3f7f10f59..042bcfe73 100644
--- a/sdk/go/retrieval.go
+++ b/sdk/go/retrieval.go
@@ -166,6 +166,12 @@ func (c *Client) Grep(ctx context.Context, uri, pattern string, opts *GrepOption
if opts.ExcludeURI != "" {
payload["exclude_uri"] = NormalizeURI(opts.ExcludeURI)
}
+ if opts.Tags != nil {
+ payload["tags"] = opts.Tags
+ }
+ if opts.IncludeTags {
+ payload["include_tags"] = true
+ }
var result map[string]any
err := c.doJSON(ctx, http.MethodPost, "/api/v1/search/grep", nil, payload, &result)
return result, err
@@ -186,6 +192,12 @@ func (c *Client) Glob(ctx context.Context, pattern string, uri string, opts *Glo
if opts.NodeLimit != nil {
payload["node_limit"] = *opts.NodeLimit
}
+ if opts.Tags != nil {
+ payload["tags"] = opts.Tags
+ }
+ if opts.IncludeTags {
+ payload["include_tags"] = true
+ }
var result map[string]any
err := c.doJSON(ctx, http.MethodPost, "/api/v1/search/glob", nil, payload, &result)
return result, err
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 3ec22ccbf..4f7d2beae 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -179,6 +179,8 @@ type ListOptions struct {
NodeLimit int
SortBy string
SortOrder string
+ Tags []string
+ IncludeTags bool
}
// TreeOptions controls Tree.
@@ -188,6 +190,8 @@ type TreeOptions struct {
ShowAllHidden bool
NodeLimit int
LevelLimit *int
+ Tags []string
+ IncludeTags bool
}
// RemoveOptions controls Remove.
@@ -204,6 +208,8 @@ type WriteOptions struct {
Timeout *float64
Telemetry any
ProcessingMode string
+ Tags []string
+ TagMode string
Extra map[string]any
}
@@ -320,11 +326,15 @@ type GrepOptions struct {
NodeLimit *int
LevelLimit *int
ExcludeURI string
+ Tags []string
+ IncludeTags bool
}
// GlobOptions controls Glob.
type GlobOptions struct {
- NodeLimit *int
+ NodeLimit *int
+ Tags []string
+ IncludeTags bool
}
// CreateSessionOptions controls CreateSession.
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index b895c92fa..5fff2ff96 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -1063,6 +1063,8 @@ class AsyncHTTPClient:
sort_by: Optional[str] = None,
sort_order: str = "asc",
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Any]:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
@@ -1078,6 +1080,10 @@ class AsyncHTTPClient:
params["sort_order"] = sort_order
if extra_fields:
params["extra_fields"] = list(extra_fields)
+ if tags is not None:
+ params["tags"] = tags
+ if include_tags:
+ params["include_tags"] = True
response = await self._request(
"GET",
"/api/v1/fs/ls",
@@ -1094,6 +1100,8 @@ class AsyncHTTPClient:
node_limit: int = 1000,
level_limit: int = 3,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Dict[str, Any]]:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
@@ -1105,6 +1113,10 @@ class AsyncHTTPClient:
}
if extra_fields:
params["extra_fields"] = list(extra_fields)
+ if tags is not None:
+ params["tags"] = tags
+ if include_tags:
+ params["include_tags"] = True
response = await self._request(
"GET",
"/api/v1/fs/tree",
@@ -1407,6 +1419,8 @@ class AsyncHTTPClient:
case_insensitive: bool = False,
node_limit: int = 256,
exclude_uri: Optional[str] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict[str, Any]:
request_json = {
"uri": VikingURI.normalize(uri),
@@ -1416,6 +1430,10 @@ class AsyncHTTPClient:
}
if exclude_uri is not None:
request_json["exclude_uri"] = VikingURI.normalize(exclude_uri)
+ if tags is not None:
+ request_json["tags"] = list(tags)
+ if include_tags:
+ request_json["include_tags"] = True
response = await self._request("POST", "/api/v1/search/grep", json=request_json)
return self._handle_response(response)
@@ -1425,6 +1443,8 @@ class AsyncHTTPClient:
uri: str = "viking://",
node_limit: int = 256,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict[str, Any]:
json_body: Dict[str, Any] = {
"pattern": pattern,
@@ -1433,6 +1453,10 @@ class AsyncHTTPClient:
}
if extra_fields is not None:
json_body["extra_fields"] = list(extra_fields)
+ if tags is not None:
+ json_body["tags"] = list(tags)
+ if include_tags:
+ json_body["include_tags"] = True
response = await self._request(
"POST",
"/api/v1/search/glob",
@@ -2360,6 +2384,8 @@ class SyncHTTPClient:
sort_by: Optional[str] = None,
sort_order: str = "asc",
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Any]:
return run_async(
self._async_client.ls(
@@ -2373,6 +2399,8 @@ class SyncHTTPClient:
sort_by=sort_by,
sort_order=sort_order,
extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
)
)
@@ -2385,6 +2413,8 @@ class SyncHTTPClient:
node_limit: int = 1000,
level_limit: int = 3,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> List[Dict[str, Any]]:
return run_async(
self._async_client.tree(
@@ -2395,6 +2425,8 @@ class SyncHTTPClient:
node_limit=node_limit,
level_limit=level_limit,
extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
)
)
@@ -2557,6 +2589,8 @@ class SyncHTTPClient:
case_insensitive: bool = False,
node_limit: int = 256,
exclude_uri: Optional[str] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict[str, Any]:
return run_async(
self._async_client.grep(
@@ -2565,6 +2599,8 @@ class SyncHTTPClient:
case_insensitive=case_insensitive,
node_limit=node_limit,
exclude_uri=exclude_uri,
+ tags=tags,
+ include_tags=include_tags,
)
)
@@ -2574,10 +2610,17 @@ class SyncHTTPClient:
uri: str = "viking://",
node_limit: int = 256,
extra_fields: Optional[List[str]] = None,
+ tags: Optional[List[str]] = None,
+ include_tags: bool = False,
) -> Dict[str, Any]:
return run_async(
self._async_client.glob(
- pattern, uri=uri, node_limit=node_limit, extra_fields=extra_fields
+ pattern,
+ uri=uri,
+ node_limit=node_limit,
+ extra_fields=extra_fields,
+ tags=tags,
+ include_tags=include_tags,
)
)
diff --git a/sdk/python/openviking_sdk/options.py b/sdk/python/openviking_sdk/options.py
index e04cd5769..59e1da7d4 100644
--- a/sdk/python/openviking_sdk/options.py
+++ b/sdk/python/openviking_sdk/options.py
@@ -89,6 +89,8 @@ class UpdateSkillOptions(AddSkillOptions, total=False):
class WriteOptions(_ExtraOptions, total=False):
telemetry: Any
processing_mode: ProcessingMode
+ tags: List[str]
+ tag_mode: Literal["replace", "append"]
class BatchWriteOptions(_ExtraOptions, total=False):
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index 909802b27..47212b97b 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -363,6 +363,39 @@ async def test_async_http_client_write_forwards_processing_mode():
assert payload["processing_mode"] == "vectors_only"
+async def test_async_http_client_write_forwards_explicit_tags_and_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": {}}
+
+ await client.write(
+ "viking://resources/demo.md",
+ "updated",
+ options={"tags": [], "tag_mode": "replace"},
+ )
+
+ payload = fake_http.post.await_args.kwargs["json"]
+ assert payload["tags"] == []
+ assert payload["tag_mode"] == "replace"
+
+
+async def test_async_http_client_filesystem_tags_are_omission_aware():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ client._request = AsyncMock(return_value=object())
+ client._handle_response = lambda _response: []
+
+ await client.ls("viking://resources")
+ await client.tree("viking://resources", tags=["env=prod"])
+
+ ls_params = client._request.await_args_list[0].kwargs["params"]
+ tree_params = client._request.await_args_list[1].kwargs["params"]
+ assert "tags" not in ls_params
+ assert tree_params["tags"] == ["env=prod"]
+
+
@pytest.mark.asyncio
async def test_async_http_client_write_omits_default_processing_mode_for_legacy_servers():
client = AsyncHTTPClient(url="http://localhost:1933")
@@ -422,6 +455,24 @@ def test_sync_http_client_reindex_forwards_to_async_client():
)
+def test_sync_http_client_forwards_tags_to_filesystem_methods():
+ client = SyncHTTPClient(url="http://localhost:1933")
+
+ with (
+ patch.object(client._async_client, "ls", return_value=[]) as mock_ls,
+ patch.object(client._async_client, "tree", return_value=[]) as mock_tree,
+ patch.object(client._async_client, "grep", return_value={}) as mock_grep,
+ patch("openviking_sdk.client.run_async", side_effect=[[], [], {}]),
+ ):
+ client.ls("viking://resources", tags=["env=prod"])
+ client.tree("viking://resources", tags=["env=prod"])
+ client.grep("viking://resources", "Sample", tags=["env=prod"])
+
+ assert mock_ls.call_args.kwargs["tags"] == ["env=prod"]
+ assert mock_tree.call_args.kwargs["tags"] == ["env=prod"]
+ assert mock_grep.call_args.kwargs["tags"] == ["env=prod"]
+
+
def test_sync_http_client_batch_add_messages_forwards_to_async_client():
client = SyncHTTPClient(url="http://localhost:1933")
messages = [
@@ -1141,6 +1192,20 @@ async def test_grep_normalizes_uri_and_exclude_uri():
)
+async def test_grep_omits_unset_tags_and_forwards_explicit_tags():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))
+ client._http = fake_http
+ client._handle_response = lambda _response: {"count": 0, "matches": []}
+
+ await client.grep("viking://resources", pattern="Sample")
+ await client.grep("viking://resources", pattern="Sample", tags=["env=prod"])
+
+ assert "tags" not in fake_http.post.await_args_list[0].kwargs["json"]
+ assert fake_http.post.await_args_list[1].kwargs["json"]["tags"] == ["env=prod"]
+
+
@pytest.mark.asyncio
async def test_glob_normalizes_scope_uri():
client = AsyncHTTPClient(url="http://localhost:1933")
@@ -1183,6 +1248,28 @@ async def test_glob_preserves_explicit_empty_extra_fields():
)
+async def test_glob_omits_unset_tags_and_forwards_tag_options():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))
+ client._http = fake_http
+ client._handle_response = lambda _response: {"count": 0, "matches": []}
+
+ await client.glob("**/*.md")
+ await client.glob(
+ "**/*.md",
+ tags=["team=search", "env=prod"],
+ include_tags=True,
+ )
+
+ plain_request = fake_http.post.await_args_list[0].kwargs["json"]
+ tagged_request = fake_http.post.await_args_list[1].kwargs["json"]
+ assert "tags" not in plain_request
+ assert "include_tags" not in plain_request
+ assert tagged_request["tags"] == ["team=search", "env=prod"]
+ assert tagged_request["include_tags"] is True
+
+
@pytest.mark.asyncio
async def test_record_id_passthrough_is_limited_to_stat_and_read():
record_id = "0123456789abcdef0123456789abcdef"
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index 2d3e779b5..e4c0c4553 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -25,6 +25,7 @@ import type {
ListOptions,
GetSkillOptions,
GrepOptions,
+ GlobOptions,
ImportPackOptions,
Message,
PreflightAssetOptions,
@@ -450,6 +451,8 @@ export class OpenVikingClient {
exclude_uri: options.excludeUri
? normalizeURI(options.excludeUri)
: undefined,
+ tags: options.tags,
+ include_tags: options.includeTags || undefined,
}),
});
}
@@ -457,10 +460,18 @@ export class OpenVikingClient {
glob(
pattern: string,
uri = "viking://",
- nodeLimit = 256,
+ options: GlobOptions | number = {},
): Promise<JsonObject> {
+ const resolvedOptions: GlobOptions =
+ typeof options === "number" ? { nodeLimit: options } : options;
return this.request("POST", "/api/v1/search/glob", {
- body: { pattern, uri: normalizeURI(uri), node_limit: nodeLimit },
+ body: compact({
+ pattern,
+ uri: normalizeURI(uri),
+ node_limit: resolvedOptions.nodeLimit ?? 256,
+ tags: resolvedOptions.tags,
+ include_tags: resolvedOptions.includeTags || undefined,
+ }),
});
}
/** List directory contents. */
@@ -476,6 +487,8 @@ export class OpenVikingClient {
node_limit: options.nodeLimit ?? 1000,
sort_by: options.sortBy,
sort_order: options.sortOrder,
+ tags: options.tags,
+ include_tags: options.includeTags || undefined,
},
});
}
@@ -489,6 +502,8 @@ export class OpenVikingClient {
show_all_hidden: options.showAllHidden ?? false,
node_limit: options.nodeLimit ?? 1000,
level_limit: options.levelLimit ?? 3,
+ tags: options.tags,
+ include_tags: options.includeTags || undefined,
},
});
}
@@ -575,6 +590,9 @@ export class OpenVikingClient {
content,
mode: options.mode,
processing_mode: options.processingMode,
+ tags: options.tags,
+ tag_mode:
+ options.tags === undefined ? undefined : (options.tagMode ?? "replace"),
wait: options.wait,
timeout: options.timeout,
telemetry: options.telemetry,
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 9b0c635b0..55b289f01 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -96,6 +96,8 @@ export interface AddResourceOptions extends WaitOptions {
export interface WriteOptions extends WaitOptions {
mode?: string;
processingMode?: ProcessingMode;
+ tags?: string[];
+ tagMode?: "replace" | "append";
extra?: JsonObject;
}
/** One file write in a batch. */
@@ -183,6 +185,14 @@ export interface GrepOptions {
nodeLimit?: number;
levelLimit?: number;
excludeUri?: string;
+ tags?: string[];
+ includeTags?: boolean;
+}
+/** File glob options. */
+export interface GlobOptions {
+ nodeLimit?: number;
+ tags?: string[];
+ includeTags?: boolean;
}
/** Directory listing options. */
export interface ListOptions {
@@ -194,6 +204,8 @@ export interface ListOptions {
nodeLimit?: number;
sortBy?: "name" | "mtime";
sortOrder?: "asc" | "desc";
+ tags?: string[];
+ includeTags?: boolean;
}
/** Directory tree options. */
export interface TreeOptions {
@@ -202,6 +214,8 @@ export interface TreeOptions {
showAllHidden?: boolean;
nodeLimit?: number;
levelLimit?: number;
+ tags?: string[];
+ includeTags?: boolean;
}
/** Session message payload. */
export interface Message {
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index 5075b9eb6..38f65a024 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -58,6 +58,35 @@ describe("OpenVikingClient", () => {
});
});
+ it("sends glob tags only when requested", async () => {
+ const fetcher = vi
+ .fn<typeof fetch>()
+ .mockImplementation(async () => ok({ matches: [] }));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ fetch: fetcher,
+ });
+
+ await client.glob("**/*.md", "resources");
+ await client.glob("**/*.md", "resources", {
+ tags: ["team=search", "env=prod"],
+ includeTags: true,
+ });
+
+ expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toEqual({
+ pattern: "**/*.md",
+ uri: "viking://resources",
+ node_limit: 256,
+ });
+ expect(JSON.parse(String(fetcher.mock.calls[1]![1]?.body))).toEqual({
+ pattern: "**/*.md",
+ uri: "viking://resources",
+ node_limit: 256,
+ tags: ["team=search", "env=prod"],
+ include_tags: true,
+ });
+ });
+
it("assembles context with dedicated options and rejects mode override", async () => {
const fetcher = vi
.fn<typeof fetch>()
@@ -406,6 +435,23 @@ describe("OpenVikingClient", () => {
});
});
+ it("sends explicit tags for write, list, tree, and grep", async () => {
+ const fetcher = vi.fn<typeof fetch>().mockImplementation(async () => ok({}));
+ const client = new OpenVikingClient({ baseUrl: "https://example.com", fetch: fetcher });
+
+ await client.write("resources/demo.md", "updated", { tags: [], tagMode: "replace" });
+ await client.list("resources", { tags: ["env=prod"], includeTags: true });
+ await client.tree("resources", { tags: ["env=prod"], includeTags: true });
+ await client.grep("resources", "needle", { tags: ["env=prod"], includeTags: true });
+
+ expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toMatchObject({ tags: [], tag_mode: "replace" });
+ expect(new URL(String(fetcher.mock.calls[1]![0])).searchParams.get("tags")).toBe("env=prod");
+ expect(new URL(String(fetcher.mock.calls[1]![0])).searchParams.get("include_tags")).toBe("true");
+ expect(new URL(String(fetcher.mock.calls[2]![0])).searchParams.get("tags")).toBe("env=prod");
+ expect(new URL(String(fetcher.mock.calls[2]![0])).searchParams.get("include_tags")).toBe("true");
+ expect(JSON.parse(String(fetcher.mock.calls[3]![1]?.body))).toMatchObject({ tags: ["env=prod"], include_tags: true });
+ });
+
it("supports batch write, byte download, and resource extra", async () => {
const fetcher = vi
.fn<typeof fetch>()
diff --git a/tests/server/test_api_content.py b/tests/server/test_api_content.py
index a9487a036..b291fe3e7 100644
--- a/tests/server/test_api_content.py
+++ b/tests/server/test_api_content.py
@@ -29,6 +29,18 @@ def test_write_content_request_defaults_processing_mode():
assert request.processing_mode == "semantic_and_vectors"
+def test_write_content_request_accepts_tags_and_tag_mode():
+ request = WriteContentRequest(
+ uri="viking://resources/demo.md",
+ content="updated",
+ tags=["Env=Prod", "team=search"],
+ tag_mode="append",
+ )
+
+ assert request.tags == ["Env=Prod", "team=search"]
+ assert request.tag_mode == "append"
+
+
async def test_write_forwards_processing_mode_to_service(monkeypatch):
seen = {}
@@ -53,6 +65,31 @@ async def test_write_forwards_processing_mode_to_service(monkeypatch):
assert seen["processing_mode"] == "vectors_only"
+async def test_write_forwards_tags_and_tag_mode_to_service(monkeypatch):
+ seen = {}
+
+ async def fake_write(**kwargs):
+ seen.update(kwargs)
+ return {"uri": kwargs["uri"]}
+
+ service = SimpleNamespace(fs=SimpleNamespace(write=fake_write))
+ monkeypatch.setattr(content_router, "get_service", lambda: service)
+ ctx = RequestContext(user=UserIdentifier("account-1", "user-1"), role=Role.USER)
+
+ await content_router.write(
+ WriteContentRequest(
+ uri="viking://resources/demo.md",
+ content="updated",
+ tags=["env=prod"],
+ tag_mode="append",
+ ),
+ ctx,
+ )
+
+ assert seen["tags"] == ["env=prod"]
+ assert seen["tag_mode"] == "append"
+
+
async def _first_child_uri(client, uri: str) -> str:
response = await client.get(
"/api/v1/fs/ls",
diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.py
index 926d4023f..63425d749 100644
--- a/tests/server/test_api_search.py
+++ b/tests/server/test_api_search.py
@@ -4,6 +4,7 @@
"""Tests for search endpoints: find, search, grep, glob."""
from datetime import datetime, timezone
+from types import SimpleNamespace
import httpx
import pytest
@@ -11,6 +12,7 @@ import pytest
from openviking.models.embedder.base import EmbedResult
from openviking.server.auth import get_request_context
from openviking.server.identity import RequestContext, Role
+from openviking.server.routers import search as search_router
from openviking.storage.viking_fs import VikingFS
from openviking.utils.time_utils import parse_iso_datetime
from openviking_cli.exceptions import InvalidArgumentError
@@ -998,6 +1000,54 @@ async def test_grep(client_with_resource):
assert resp.json()["status"] == "ok"
+async def test_grep_forwards_tags_to_filesystem_service(monkeypatch):
+ seen = {}
+
+ async def fake_grep(uri, pattern, **kwargs):
+ seen.update(uri=uri, pattern=pattern, **kwargs)
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+
+ monkeypatch.setattr(
+ search_router,
+ "get_service",
+ lambda: SimpleNamespace(fs=SimpleNamespace(grep=fake_grep)),
+ )
+
+ await search_router.grep(
+ search_router.GrepRequest(
+ uri="viking://resources", pattern="OpenViking", tags=["team=search", "env=prod"]
+ ),
+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
+ )
+
+ assert seen["tags"] == ["team=search", "env=prod"]
+
+
+async def test_grep_forwards_include_tags_to_filesystem_service(monkeypatch):
+ seen = {}
+
+ async def fake_grep(uri, pattern, **kwargs):
+ seen.update(uri=uri, pattern=pattern, **kwargs)
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+
+ monkeypatch.setattr(
+ search_router,
+ "get_service",
+ lambda: SimpleNamespace(fs=SimpleNamespace(grep=fake_grep)),
+ )
+
+ await search_router.grep(
+ search_router.GrepRequest(
+ uri="viking://resources", pattern="OpenViking", include_tags=True
+ ),
+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
+ )
+
+ assert seen["include_tags"] is True
+
+
async def test_grep_case_insensitive(client_with_resource):
client, uri = client_with_resource
parent_uri = "/".join(uri.split("/")[:-1]) + "/"
@@ -1175,3 +1225,28 @@ async def test_glob_explicit_empty_extra_fields_returns_entry_objects(client_wit
assert matches
assert all(isinstance(match, dict) for match in matches)
assert all("uri" in match and "isDir" in match for match in matches)
+
+
+async def test_glob_forwards_tags_and_tag_projection_to_filesystem_service(monkeypatch):
+ seen = {}
+
+ async def fake_glob(pattern, **kwargs):
+ seen.update(pattern=pattern, **kwargs)
+ return {"matches": [], "count": 0}
+
+ monkeypatch.setattr(
+ search_router,
+ "get_service",
+ lambda: SimpleNamespace(fs=SimpleNamespace(glob=fake_glob)),
+ )
+
+ await search_router.glob(
+ search_router.GlobRequest(
+ pattern="**/*.md", tags=["env=prod"], include_tags=True
+ ),
+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
+ )
+
+ assert seen["tags"] == ["env=prod"]
+ assert seen["include_tags"] is True
diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.py
index 4cdf734d2..e7170f7ce 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -250,3 +250,26 @@ async def test_ls_user_container_lists_only_caller_space(app, client, service):
assert response.status_code == 200, response.text
names = {entry["name"] for entry in response.json()["result"]}
assert names == {"alice"}
+
+
+async def test_ls_forwards_tags_to_filesystem_service(monkeypatch):
+ seen = {}
+
+ async def fake_ls(uri, **kwargs):
+ seen.update(uri=uri, **kwargs)
+ return []
+
+ monkeypatch.setattr(
+ filesystem,
+ "get_service",
+ lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls)),
+ )
+
+ await filesystem.ls(
+ uri="viking://resources",
+ tags=["team=search", "env=prod"],
+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
+ )
+
+ assert seen["tags"] == ["team=search", "env=prod"]
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index afe848db9..b6416cb3d 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -31,6 +31,33 @@ class _FakeVikingFS:
self.events.append(("mv", from_uri, to_uri))
+async def test_write_forwards_tags_and_tag_mode_to_content_coordinator(monkeypatch, request_context):
+ seen = {}
+
+ class FakeCoordinator:
+ def __init__(self, **_kwargs):
+ pass
+
+ async def write(self, **kwargs):
+ seen.update(kwargs)
+ return {"uri": kwargs["uri"]}
+
+ monkeypatch.setattr("openviking.service.fs_service.ContentWriteCoordinator", FakeCoordinator)
+ service = FSService(viking_fs=object())
+
+ await service.write(
+ "viking://resources/demo.md",
+ "updated",
+ request_context,
+ tags=["env=prod"],
+ tag_mode="append",
+ )
+
+ assert seen["tags"] == ["env=prod"]
+ assert seen["tag_mode"] == "append"
+
+
class _FakeWatchManager:
def __init__(self, *, events=None):
self.validate_calls = []
@@ -208,6 +235,380 @@ async def test_grep_projects_memory_content_but_keeps_resource_fast_path(request
assert "content_transform" not in viking_fs.grep.await_args.kwargs
+async def test_grep_projects_tags_for_each_match(request_context):
+ matches = [
+ {"uri": "viking://resources/a.md", "line": 1, "content": "needle"},
+ {"uri": "viking://resources/b.md", "line": 2, "content": "needle"},
+ ]
+ viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": matches, "count": 2}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {
+ "uri": "viking://resources/a.md",
+ "level": 2,
+ "search_tags": ["team=search", "env=prod"],
+ },
+ {
+ "uri": "viking://resources/b.md",
+ "level": 2,
+ "search_tags": [],
+ },
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.grep(
+ "viking://resources", "needle", ctx=request_context, include_tags=True
+ )
+
+ assert result["matches"] == [
+ {
+ "uri": "viking://resources/a.md",
+ "line": 1,
+ "content": "needle",
+ "tags": ["team=search", "env=prod"],
+ },
+ {
+ "uri": "viking://resources/b.md",
+ "line": 2,
+ "content": "needle",
+ "tags": [],
+ },
+ ]
+
+
+async def test_grep_skips_tag_projection_without_tags_or_include_tags(request_context):
+ matches = [{"uri": "viking://resources/a.md", "line": 1, "content": "needle"}]
+ viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": matches, "count": 1}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("plain grep should not load tags")
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+
+ result = await service.grep("viking://resources", "needle", ctx=request_context)
+
+ assert result["matches"] == matches
+
+
+async def test_grep_projects_tags_when_include_tags_is_requested(request_context):
+ matches = [{"uri": "viking://resources/a.md", "line": 1, "content": "needle"}]
+ viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": matches, "count": 1}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [{"uri": "viking://resources/a.md", "level": 2, "search_tags": ["env=prod"]}]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+
+ result = await service.grep(
+ "viking://resources", "needle", ctx=request_context, include_tags=True
+ )
+
+ assert result["matches"] == [{**matches[0], "tags": ["env=prod"]}]
+
+
+async def test_ls_and_tree_skip_tag_projection_without_tags_or_include_tags(request_context):
+ entries = [{"uri": "viking://resources/a.md", "isDir": False}]
+ viking_fs = SimpleNamespace(
+ ls=AsyncMock(return_value=entries),
+ tree=AsyncMock(return_value=entries),
+ )
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("plain filesystem reads should not load tags")
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+
+ assert await service.ls("viking://resources", ctx=request_context) == entries
+ assert await service.tree("viking://resources", ctx=request_context) == entries
+
+
+async def test_glob_skips_tag_projection_without_tags_or_include_tags(request_context):
+ expected = {"matches": ["viking://resources/a.md"], "count": 1}
+ viking_fs = SimpleNamespace(glob=AsyncMock(return_value=expected))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("plain glob should not load tags")
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+
+ assert await service.glob("**/*.md", ctx=request_context) == expected
+ assert viking_fs.glob.await_args.kwargs["extra_fields"] is None
+
+
+async def test_glob_filters_and_projects_tags_before_applying_node_limit(request_context):
+ entries = [
+ {"uri": "viking://resources/a.md", "isDir": False},
+ {"uri": "viking://resources/b.md", "isDir": False},
+ {"uri": "viking://resources/c.md", "isDir": False},
+ ]
+ viking_fs = SimpleNamespace(glob=AsyncMock(return_value={"matches": entries, "count": 3}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": "viking://resources/a.md", "level": 2, "search_tags": ["team=search"]},
+ {
+ "uri": "viking://resources/b.md",
+ "level": 2,
+ "search_tags": ["team=search", "env=prod"],
+ },
+ {
+ "uri": "viking://resources/c.md",
+ "level": 2,
+ "search_tags": ["team=search", "env=prod"],
+ },
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.glob(
+ "**/*.md",
+ ctx=request_context,
+ tags=["team=search", "env=prod"],
+ node_limit=1,
+ )
+
+ assert result == {
+ "matches": [
+ {
+ "uri": "viking://resources/b.md",
+ "isDir": False,
+ "tags": ["team=search", "env=prod"],
+ }
+ ],
+ "count": 1,
+ }
+ assert viking_fs.glob.await_args.kwargs["extra_fields"] == []
+ assert viking_fs.glob.await_args.kwargs["node_limit"] is None
+
+
+async def test_glob_tag_filter_keeps_zero_node_limit_unbounded(request_context):
+ entries = [
+ {"uri": "viking://resources/a.md", "isDir": False},
+ {"uri": "viking://resources/b.md", "isDir": False},
+ ]
+ viking_fs = SimpleNamespace(glob=AsyncMock(return_value={"matches": entries, "count": 2}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": "viking://resources/a.md", "level": 2, "search_tags": ["env=prod"]},
+ {"uri": "viking://resources/b.md", "level": 2, "search_tags": ["env=prod"]},
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.glob(
+ "**/*.md", ctx=request_context, tags=["env=prod"], node_limit=0
+ )
+
+ assert result["count"] == 2
+ assert [entry["uri"] for entry in result["matches"]] == [
+ "viking://resources/a.md",
+ "viking://resources/b.md",
+ ]
+
+
+async def test_grep_passes_tags_to_vikingfs_without_prequerying_vikingdb(request_context):
+ viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": [], "count": 0}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("tagged grep should not pre-query VikingDB")
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ await service.grep(
+ "viking://resources",
+ "needle",
+ ctx=request_context,
+ tags=["team=search", "env=prod"],
+ )
+
+ assert viking_fs.grep.await_args.kwargs["tag_filter"] == {
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "search_tags", "conds": ["team=search"]},
+ {"op": "must", "field": "search_tags", "conds": ["env=prod"]},
+ ],
+ }
+
+
+async def test_tagged_grep_reuses_tags_returned_by_viking_fs(request_context):
+ matches = [
+ {
+ "uri": "viking://resources/a.md",
+ "line": 1,
+ "content": "needle",
+ "tags": ["team=search", "env=prod"],
+ }
+ ]
+ viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": matches, "count": 1}))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ raise AssertionError("tagged grep should reuse VikingFS tag projection")
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.grep(
+ "viking://resources",
+ "needle",
+ ctx=request_context,
+ tags=["team=search", "env=prod"],
+ )
+
+ assert result["matches"] == matches
+
+
+async def test_ls_projects_tags_filters_with_and_before_applying_node_limit(request_context):
+ entries = [
+ {"uri": "viking://resources/a.md", "isDir": False},
+ {"uri": "viking://resources/b.md", "isDir": False},
+ {"uri": "viking://resources/c.md", "isDir": False},
+ ]
+ viking_fs = SimpleNamespace(ls=AsyncMock(return_value=entries))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": "viking://resources/a.md", "level": 2, "search_tags": ["team=search"]},
+ {
+ "uri": "viking://resources/b.md",
+ "level": 2,
+ "search_tags": ["team=search", "env=prod"],
+ },
+ {
+ "uri": "viking://resources/c.md",
+ "level": 2,
+ "search_tags": ["team=search", "env=prod"],
+ },
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.ls(
+ "viking://resources",
+ ctx=request_context,
+ tags=["team=search", "env=prod"],
+ node_limit=1,
+ )
+
+ assert result == [
+ {"uri": "viking://resources/b.md", "isDir": False, "tags": ["team=search", "env=prod"]}
+ ]
+ assert viking_fs.ls.await_args.kwargs["node_limit"] is None
+
+
+async def test_ls_tag_filter_keeps_zero_node_limit_unbounded_for_entry_and_simple_output(
+ request_context,
+):
+ entries = [
+ {"uri": "viking://resources/a.md", "isDir": False},
+ {"uri": "viking://resources/b.md", "isDir": False},
+ ]
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": entry["uri"], "level": 2, "search_tags": ["env=prod"]}
+ for entry in entries
+ ]
+
+ entry_service = FSService(
+ viking_fs=SimpleNamespace(ls=AsyncMock(return_value=entries)), vikingdb=FakeVikingDB()
+ )
+ entry_result = await entry_service.ls(
+ "viking://resources", ctx=request_context, tags=["env=prod"], node_limit=0
+ )
+
+ simple_service = FSService(
+ viking_fs=SimpleNamespace(ls=AsyncMock(return_value=entries)), vikingdb=FakeVikingDB()
+ )
+ simple_result = await simple_service.ls(
+ "viking://resources",
+ ctx=request_context,
+ simple=True,
+ tags=["env=prod"],
+ node_limit=0,
+ )
+
+ assert [entry["uri"] for entry in entry_result] == [
+ "viking://resources/a.md",
+ "viking://resources/b.md",
+ ]
+ assert simple_result == ["viking://resources/a.md", "viking://resources/b.md"]
+
+
+async def test_tree_projects_directory_tags_from_abstract_and_overview_records(request_context):
+ directory = {"uri": "viking://resources/docs", "isDir": True}
+ viking_fs = SimpleNamespace(tree=AsyncMock(return_value=[directory]))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": "viking://resources/docs", "level": 0, "search_tags": ["team=search"]},
+ {
+ "uri": "viking://resources/docs",
+ "level": 1,
+ "search_tags": ["env=prod", "team=search"],
+ },
+ {"uri": "viking://resources/docs", "level": 2, "search_tags": ["ignored=true"]},
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.tree(
+ "viking://resources",
+ ctx=request_context,
+ tags=["team=search", "env=prod"],
+ )
+
+ assert result == [
+ {"uri": "viking://resources/docs", "isDir": True, "tags": ["team=search", "env=prod"]}
+ ]
+ assert viking_fs.tree.await_args.kwargs["node_limit"] is None
+
+
+async def test_tree_tag_filter_keeps_zero_node_limit_unbounded(request_context):
+ entries = [
+ {"uri": "viking://resources/a.md", "isDir": False},
+ {"uri": "viking://resources/b.md", "isDir": False},
+ ]
+ viking_fs = SimpleNamespace(tree=AsyncMock(return_value=entries))
+
+ class FakeVikingDB:
+ async def filter(self, **_kwargs):
+ return [
+ {"uri": entry["uri"], "level": 2, "search_tags": ["env=prod"]}
+ for entry in entries
+ ]
+
+ service = FSService(viking_fs=viking_fs, vikingdb=FakeVikingDB())
+ result = await service.tree(
+ "viking://resources", ctx=request_context, tags=["env=prod"], node_limit=0
+ )
+
+ assert [entry["uri"] for entry in result] == [
+ "viking://resources/a.md",
+ "viking://resources/b.md",
+ ]
+ assert viking_fs.tree.await_args.kwargs["node_limit"] is None
+
+
@pytest.mark.asyncio
async def test_resource_rm_enqueues_parent_delete_refresh_and_waits(request_context):
viking_fs = _FakeVikingFS()
diff --git a/tests/storage/test_content_write_processing_mode.py b/tests/storage/test_content_write_processing_mode.py
index 68737f530..66a541ea4 100644
--- a/tests/storage/test_content_write_processing_mode.py
+++ b/tests/storage/test_content_write_processing_mode.py
@@ -15,6 +15,7 @@ from openviking.storage.abstract_overview import (
)
from openviking.storage.content_write import ContentWriteCoordinator
from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessAction
+from openviking.utils.ingest_options import IngestOptions
from openviking_cli.session.user_id import UserIdentifier
@@ -42,6 +43,9 @@ class _FakeVikingFS:
def _uri_to_path(self, uri, ctx=None):
return f"/fake/{uri}"
+ async def _ensure_access(self, uri, ctx, action):
+ del uri, ctx, action
+
def _sidecar(level=ContextLevel.ABSTRACT, body="Original body."):
return render_abstract_overview(
@@ -127,6 +131,7 @@ async def test_direct_write_skips_semantic_refresh_for_vectors_only_and_sidecar_
ctx=ctx,
written_bytes=len("Updated body only.".encode()),
telemetry_id="",
+ ingest_options=IngestOptions.from_search_tags(["team=search"], mode="append"),
)
written = sidecar_fs.write_file.await_args.args[1]
@@ -134,10 +139,33 @@ async def test_direct_write_skips_semantic_refresh_for_vectors_only_and_sidecar_
assert parse_abstract_overview(written).metadata == parse_abstract_overview(current).metadata
sidecar_coordinator._enqueue_semantic_refresh.assert_not_awaited()
vectorize_directory.assert_awaited_once()
+ assert vectorize_directory.await_args.kwargs["ingest_options"] == IngestOptions(
+ search_tags=["team=search"], search_tag_mode="append"
+ )
assert sidecar_result["semantic_status"] == "skipped"
assert sidecar_result["vector_status"] == "queued"
+async def test_write_builds_ingest_options_before_scheduling_resource_refresh(ctx):
+ coordinator = ContentWriteCoordinator(viking_fs=_FakeVikingFS())
+ coordinator._safe_stat = AsyncMock(return_value={"isDir": False})
+ coordinator._resolve_root_uri = AsyncMock(return_value="viking://resources")
+ coordinator._write_direct_with_refresh = AsyncMock(return_value={"uri": "viking://resources/demo.md"})
+
+ await coordinator.write(
+ uri="viking://resources/demo.md",
+ content="updated",
+ ctx=ctx,
+ tags=["team=search"],
+ tag_mode="append",
+ )
+
+ ingest_options = coordinator._write_direct_with_refresh.await_args.kwargs["ingest_options"]
+ assert ingest_options.search_tags == ["team=search"]
+ assert ingest_options.search_tag_mode == "append"
+
+
@pytest.mark.asyncio
async def test_vectors_only_write_wait_reports_embedding_status(monkeypatch, ctx):
fake_fs = _FakeVikingFS()
diff --git a/tests/storage/test_semantic_dag_incremental.py b/tests/storage/test_semantic_dag_incremental.py
index 908d72119..192d08168 100644
--- a/tests/storage/test_semantic_dag_incremental.py
+++ b/tests/storage/test_semantic_dag_incremental.py
@@ -16,6 +16,7 @@ from openviking.storage.abstract_overview import (
render_abstract_overview,
)
from openviking.storage.queuefs.semantic_dag import SemanticDagExecutor
+from openviking.utils.ingest_options import IngestOptions
from openviking_cli.session.user_id import UserIdentifier
@@ -64,6 +65,8 @@ class _FakeProcessor:
self.summarized_files = []
self.sync_calls = []
self.vectorized_files = []
+ self.file_ingest_options = {}
+ self.directory_ingest_options = {}
def _parse_overview_md(self, overview_content):
results = {}
@@ -98,8 +101,11 @@ class _FakeProcessor:
ctx=None,
use_summary=False,
ingest_options=None,
+ creator_acl_grant=None,
):
+ del creator_acl_grant
self.vectorized_files.append(file_path)
+ self.file_ingest_options[file_path] = ingest_options
async def _vectorize_directory(
self,
@@ -109,7 +115,10 @@ class _FakeProcessor:
overview,
ctx=None,
ingest_options=None,
+ creator_acl_grant=None,
):
+ del creator_acl_grant
+ self.directory_ingest_options[uri] = ingest_options
return None
async def _sync_topdown_recursive(
@@ -133,7 +142,6 @@ class _FakeProcessor:
@pytest.mark.asyncio
async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypatch):
-
root_uri = "viking://resources/root"
tree = {
root_uri: [
@@ -189,6 +197,56 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypa
assert "- b.txt: old-b" in overview
+async def test_content_write_tags_apply_only_to_changed_file(monkeypatch):
+ root_uri = "viking://resources/root"
+ changed_uri = f"{root_uri}/a.txt"
+ fake_fs = _FakeVikingFS(
+ tree={
+ root_uri: [
+ {"name": "a.txt", "isDir": False},
+ {"name": "b.txt", "isDir": False},
+ ],
+ },
+ file_contents={
+ changed_uri: "new content",
+ f"{root_uri}/b.txt": "unchanged",
+ f"{root_uri}/.overview.md": render_abstract_overview(
+ ContextLevel.OVERVIEW,
+ root_uri,
+ "FILES:\n- a.txt: old-a\n- b.txt: old-b",
+ {},
+ ),
+ f"{root_uri}/.abstract.md": "old-abstract",
+ },
+ )
+ monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs)
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_dag.get_openviking_config",
+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),
+ )
+
+ processor = _FakeProcessor(fake_fs)
+ ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)
+ tag_options = IngestOptions(search_tags=["team=search"])
+ executor = SemanticDagExecutor(
+ processor=processor,
+ context_type="resource",
+ max_concurrent_llm=2,
+ ctx=ctx,
+ incremental_update=True,
+ target_uri=root_uri,
+ changes={"modified": [changed_uri]},
+ ingest_options=tag_options,
+ generation_trigger="content_write",
+ )
+
+ await executor.run(root_uri)
+
+ assert processor.file_ingest_options == {changed_uri: tag_options}
+ assert processor.directory_ingest_options[root_uri] == IngestOptions()
+
+
@pytest.mark.asyncio
async def test_pending_refresh_rebuilds_every_sampled_file_summary(monkeypatch):
root_uri = "viking://resources/wide"
diff --git a/tests/storage/test_semantic_dag_skip_files.py b/tests/storage/test_semantic_dag_skip_files.py
index 505305daf..9b6092063 100644
--- a/tests/storage/test_semantic_dag_skip_files.py
+++ b/tests/storage/test_semantic_dag_skip_files.py
@@ -72,6 +72,7 @@ class _FakeProcessor:
overview,
ctx=None,
ingest_options=None,
+ creator_acl_grant=None,
):
pass
@@ -87,6 +88,7 @@ class _FakeProcessor:
ctx=None,
use_summary=False,
ingest_options=None,
+ creator_acl_grant=None,
):
self.vectorized_files.append(file_path)
diff --git a/tests/storage/test_viking_fs_grep.py b/tests/storage/test_viking_fs_grep.py
index 249fa59f8..b56e8c831 100644
--- a/tests/storage/test_viking_fs_grep.py
+++ b/tests/storage/test_viking_fs_grep.py
@@ -31,6 +31,18 @@ class _FailingVectorStore:
raise RuntimeError("remote keyword search failed")
+class _KeywordFailingButTagFilterWorkingStore:
+ def __init__(self):
+ self.filter_calls = []
+
+ async def search_by_keywords(self, **kwargs):
+ raise RuntimeError("remote keyword search failed")
+
+ async def filter(self, **kwargs):
+ self.filter_calls.append(kwargs)
+ return [{"uri": "viking://resources/tagged.md"}]
+
+
@pytest.fixture
def fs(monkeypatch):
viking_fs = VikingFS(agfs=_DummyAgfs())
@@ -104,6 +116,41 @@ async def test_grep_vikingdb_auto_remote_limit_uses_five_times_node_limit(
assert result == {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
assert vector_store.calls[0]["limit"] == expected_remote_limit
+ assert vector_store.calls[0]["output_fields"] == ["uri"]
+
+
+async def test_grep_vikingdb_does_not_project_tags_without_filter_or_request(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+ vector_store = _DummyVectorStore(
+ results=[{"uri": "viking://resources/a.md", "search_tags": ["env=prod"]}]
+ )
+ monkeypatch.setattr(fs, "_get_vector_store", lambda: vector_store)
+
+ async def fake_grep_in_files(file_uris, pattern, case_insensitive, node_limit, ctx):
+ return {
+ "matches": [{"uri": "viking://resources/a.md", "line": 1, "content": "needle"}],
+ "count": 1,
+ "match_count": 1,
+ "files_scanned": 1,
+ }
+
+ monkeypatch.setattr(fs, "_grep_in_files", fake_grep_in_files)
+
+ result = await fs._grep_vikingdb_then_fs(
+ uri="viking://resources",
+ pattern="needle",
+ exclude_uri=None,
+ case_insensitive=False,
+ node_limit=1,
+ level_limit=3,
+ ctx=None,
+ )
+
+ assert vector_store.calls[0]["output_fields"] == ["uri"]
+ assert result["matches"] == [
+ {"uri": "viking://resources/a.md", "line": 1, "content": "needle"}
+ ]
@pytest.mark.asyncio
@@ -148,6 +195,40 @@ async def test_grep_vikingdb_remote_error_falls_back_to_fs(monkeypatch):
]
+async def test_grep_vikingdb_tagged_remote_error_falls_back_with_tag_allowlist(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+ vector_store = _KeywordFailingButTagFilterWorkingStore()
+ monkeypatch.setattr(fs, "_get_vector_store", lambda: vector_store)
+
+ calls = []
+
+ async def fake_grep_fs(**kwargs):
+ calls.append(kwargs)
+ return {"matches": [], "count": 0, "match_count": 0, "files_scanned": 0}
+
+ monkeypatch.setattr(fs, "_grep_fs", fake_grep_fs)
+
+ await fs._grep_vikingdb_then_fs(
+ uri="viking://resources",
+ pattern="needle",
+ exclude_uri=None,
+ case_insensitive=False,
+ node_limit=10,
+ level_limit=3,
+ ctx=None,
+ tag_filter={"op": "must", "field": "search_tags", "conds": ["env=prod"]},
+ )
+
+ assert vector_store.filter_calls[0]["filter"] == And(
+ [
+ PathScope("uri", "viking://resources", depth=3),
+ RawDSL({"op": "must", "field": "search_tags", "conds": ["env=prod"]}),
+ ]
+ )
+ assert calls[0]["allowed_uris"] == {"viking://resources/tagged.md"}
+
+
@pytest.mark.asyncio
async def test_grep_vikingdb_pushes_exclude_uri_to_filter(monkeypatch):
fs = VikingFS(agfs=_DummyAgfs())
@@ -213,6 +294,59 @@ async def test_grep_vikingdb_keeps_local_exclude_uri_guard(monkeypatch):
assert grep_in_files_calls == [["viking://resources/keep.md"]]
+async def test_grep_vikingdb_pushes_tag_filter_into_bm25_request(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+ vector_store = _DummyVectorStore(
+ results=[
+ {"uri": "viking://resources/untagged.md"},
+ {"uri": "viking://resources/tagged.md", "search_tags": ["env=prod"]},
+ ]
+ )
+ monkeypatch.setattr(fs, "_get_vector_store", lambda: vector_store)
+
+ calls = []
+
+ async def fake_grep_in_files(file_uris, pattern, case_insensitive, node_limit, ctx):
+ calls.append(file_uris)
+ return {
+ "matches": [{"uri": "viking://resources/tagged.md", "line": 1, "content": "needle"}],
+ "count": 1,
+ "match_count": 1,
+ "files_scanned": len(file_uris),
+ }
+
+ monkeypatch.setattr(fs, "_grep_in_files", fake_grep_in_files)
+
+ result = await fs._grep_vikingdb_then_fs(
+ uri="viking://resources",
+ pattern="needle",
+ exclude_uri=None,
+ case_insensitive=False,
+ node_limit=1,
+ level_limit=3,
+ ctx=None,
+ tag_filter={"op": "must", "field": "search_tags", "conds": ["env=prod"]},
+ )
+
+ assert calls == [["viking://resources/untagged.md", "viking://resources/tagged.md"]]
+ assert vector_store.calls[0]["limit"] == 5
+ assert vector_store.calls[0]["filter"] == And(
+ [
+ PathScope("uri", "viking://resources", depth=3),
+ RawDSL({"op": "must", "field": "search_tags", "conds": ["env=prod"]}),
+ ]
+ )
+ assert result["matches"] == [
+ {
+ "uri": "viking://resources/tagged.md",
+ "line": 1,
+ "content": "needle",
+ "tags": ["env=prod"],
+ }
+ ]
+
+
@pytest.mark.asyncio
async def test_grep_preserves_dfs_order_and_node_limit(monkeypatch):
fs = VikingFS(agfs=_DummyAgfs())
@@ -276,6 +410,44 @@ async def test_grep_preserves_dfs_order_and_node_limit(monkeypatch):
]
+async def test_grep_allowed_uris_filters_before_node_limit(monkeypatch):
+ fs = VikingFS(agfs=_DummyAgfs())
+
+ async def fake_stat(uri, ctx=None, skip_count=False):
+ return {"isDir": True}
+
+ async def fake_ls(uri, ctx=None, **kwargs):
+ return [
+ {"name": "untagged.md", "isDir": False},
+ {"name": "tagged.md", "isDir": False},
+ ]
+
+ def fake_agfs_read(path, offset=0, size=-1):
+ return b"match"
+
+ monkeypatch.setattr(fs, "stat", fake_stat)
+ monkeypatch.setattr(fs, "ls", fake_ls)
+ monkeypatch.setattr(
+ fs,
+ "_uri_to_path",
+ lambda uri, ctx=None: uri.replace("viking://", "/"),
+ )
+ monkeypatch.setattr(fs.agfs, "read", fake_agfs_read, raising=False)
+
+ result = await fs.grep(
+ "viking://resources",
+ pattern="match",
+ node_limit=1,
+ allowed_uris={"viking://resources/tagged.md"},
+ )
+
+ assert result["matches"] == [
+ {"line": 1, "uri": "viking://resources/tagged.md", "content": "match"}
+ ]
+ assert result["files_scanned"] == 1
+
+
@pytest.mark.asyncio
async def test_grep_applies_content_transform_before_matching(monkeypatch):
fs = VikingFS(agfs=_DummyAgfs())
diff --git a/tests/unit/session/memory/test_embedding_template.py b/tests/unit/session/memory/test_embedding_template.py
index d1dffea5a..e88974a7c 100644
--- a/tests/unit/session/memory/test_embedding_template.py
+++ b/tests/unit/session/memory/test_embedding_template.py
@@ -15,6 +15,7 @@ from openviking.session.memory.merge_op import MergeOp
from openviking.session.memory.merge_op.base import FieldType
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
+from openviking.utils.ingest_options import IngestOptions
class TestMemoryFieldSchema:
@@ -101,6 +102,53 @@ class TestContentTemplateRendering:
class TestEmbeddingTextConstruction:
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ ("tags", "mode"),
+ [(["team=search"], "replace"), (["env=prod"], "append"), ([], "replace")],
+ )
+ async def test_vectorization_preserves_write_tag_mode(self, tags, mode):
+ registry = MemoryTypeRegistry(load_schemas=False)
+ memory_dir = PromptManager._get_bundled_templates_dir() / "memory"
+ registry.load_from_yaml(str(memory_dir / "trajectories.yaml"))
+ uri = "viking://user/alice/memories/trajectories/exchange.md"
+ updater = MemoryUpdater(registry=registry, vikingdb=Mock())
+ updater._viking_fs = Mock()
+ updater._viking_fs.read_file = AsyncMock(
+ return_value=MemoryFileUtils.write(
+ MemoryFile(
+ uri=uri,
+ memory_type="trajectories",
+ content="# exchange\nbody",
+ extra_fields={
+ "trajectory_name": "exchange",
+ "retrieval_anchor": "Stage: final",
+ },
+ )
+ )
+ )
+ updater._vikingdb.enqueue_embedding_msg = AsyncMock(return_value=True)
+ result = MemoryUpdateResult()
+ result.add_written(uri)
+
+ with patch.object(EmbeddingMsgConverter, "from_context") as mock_from_context:
+ mock_from_context.side_effect = lambda context: SimpleNamespace(
+ telemetry_id=None,
+ id="msg-1",
+ message=context.get_vectorization_text(),
+ context_data={},
+ )
+ await updater._vectorize_memories(
+ result,
+ SimpleNamespace(user=None, account_id="default"),
+ uri_memory_type_map={uri: "trajectories"},
+ ingest_options=IngestOptions(search_tags=tags, search_tag_mode=mode),
+ )
+
+ embedding_msg = updater._vikingdb.enqueue_embedding_msg.await_args.args[0]
+ assert embedding_msg.context_data["search_tags"] == tags
+ assert embedding_msg.context_data["_upsert_options"] == {"search_tag_mode": mode}
+
@pytest.mark.asyncio
async def test_trajectory_vectorization_adds_source_experience_search_tags(self):
registry = MemoryTypeRegistry(load_schemas=False)