Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
Feat/cli unify tags flag (#4599)
Jiahui Zhoubbc1f9bab00e
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 511ca9d3d..5464fac19 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -449,10 +449,10 @@ enum Commands {/// locally, e.g. --args dry_run:true (supported keys: catalog, dry_run, skip_failed)#[arg(long = "args")]resource_args: Option<String>,- /// Explicit k=v retrieval tag to apply after import. Can be repeated.- #[arg(long = "tag", value_name = "k=v", help_heading = "Common options")]+ /// Comma-separated k=v retrieval tags to apply after import+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]tags: Vec<String>,- /// Tag update mode when --tag is provided+ /// Tag update mode when --tags is provided#[arg(long = "tag-mode",default_value = "replace",@@ -1218,10 +1218,10 @@ enum Commands {/// Preview prune_orphans deletions without mutating vectors#[arg(long, help_heading = "Common options")]dry_run: bool,- /// Explicit k=v retrieval tag for rebuilt vector records. Can be repeated.- #[arg(long = "tag", value_name = "k=v", help_heading = "Common options")]+ /// Comma-separated k=v retrieval tags for rebuilt vector records+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]tags: Vec<String>,- /// Tag update mode when --tag is provided+ /// Tag update mode when --tags is provided#[arg(long = "tag-mode",default_value = "replace",@@ -4568,10 +4568,8 @@ mod tests {"ov","add-resource","./README.md",- "--tag",- "team=search",- "--tag",- "env=test",+ "--tags",+ "team=search,env=test","--tag-mode","append",])@@ -5543,7 +5541,7 @@ mod tests {"prune_orphans","--wait=false","--dry-run",- "--tag",+ "--tags","team=search","--tag-mode","append",diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex bd0b01ebf..f39aed1bf 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -58,7 +58,7 @@ The `find()` method performs pure vector similarity search for simple query scen| image_url | str | No | None | Image query as a `data:image/...;base64,...`, `http(s)://`, or `viking://` URI. Requires a multimodal embedding model || target_uri | str \| List[str] | No | "" | Limit search to specific URI prefix || context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |-| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |+| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form (lowercase letters/digits/`_`/`-`/`.`, starting with a letter or digit, key<=64, value<=128). Multiple tags are combined with AND; a result must contain every requested tag || node_limit | int | No | None | Maximum number of results || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filter |@@ -176,7 +176,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \}'```-Tags must use strict `k=v` strings. When multiple tags are provided, `find()` requires all of them; the example above only returns contexts whose explicit retrieval tags contain both `env=prod` and `team=search`.+Tags must use strict `k=v` strings: both key and value are non-empty, contain exactly one `=`, are made only of lowercase letters, digits, `_`, `-`, `.` and start with a letter or digit (the server trims whitespace and lowercases). The key is capped at 64 and the value at 128 characters. When multiple tags are provided, `find()` requires all of them; the example above only returns contexts whose explicit retrieval tags contain both `env=prod` and `team=search`.**Python SDK**@@ -396,7 +396,7 @@ The `search()` method adds session context understanding and intent analysis cap| session | Session | No | None | Session for context-aware search (SDK) || session_id | str | No | None | Session ID for context-aware search (HTTP) || context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |-| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |+| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form (lowercase letters/digits/`_`/`-`/`.`, starting with a letter or digit, key<=64, value<=128). Multiple tags are combined with AND; a result must contain every requested tag || node_limit | int | No | None | Maximum number of results || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filter |diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.mdindex c2ea88e34..df49478ca 100644--- a/docs/en/api/12-content.md+++ b/docs/en/api/12-content.md@@ -491,7 +491,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png### set_tags()-Set explicit `k=v` tags used by retrieval filters. `replace` replaces existing tags, while `append` adds tags. When the target is a directory, `recursive=true` applies the update to files below it.+Set explicit `k=v` tags used by retrieval filters. Both key and value are non-empty, contain exactly one `=`, are made only of lowercase letters, digits, `_`, `-`, `.` and start with a letter or digit (the server trims whitespace and lowercases); the key is capped at 64 and the value at 128 characters, and invalid tags are rejected. `replace` replaces existing tags, while `append` adds tags. When the target is a directory, `recursive=true` applies the update to files below it.**Python SDK**diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex 169aa01b9..59c1c1274 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -58,7 +58,7 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、带| image_url | str | 否 | None | 图片查询,支持 `data:image/...;base64,...`、`http(s)://` 或 `viking://` URI;需要 multimodal embedding 模型 || target_uri | str \| List[str] | 否 | "" | 限制搜索范围到指定的 URI 前缀 || context_type | str \| List[str] | 否 | None | 限定一个或多个 `ContextType` 取值:`memory`、`resource` 或 `skill` |-| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |+| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式(小写字母/数字/`_`/`-`/`.`,以字母或数字开头,key≤64、value≤128)。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 || limit | int | 否 | 10 | 最大返回结果数 || node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 limit || score_threshold | float | 否 | None | 最低相关性分数阈值 |@@ -177,7 +177,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \}'```-Tags 必须使用严格的 `k=v` 字符串。传入多个 tags 时,`find()` 会要求全部命中;上面的例子只返回显式检索标签同时包含 `env=prod` 和 `team=search` 的上下文。+Tags 必须使用严格的 `k=v` 字符串:key 和 value 都非空,只能有一个 `=`,仅由小写字母、数字、`_`、`-`、`.` 组成且以字母或数字开头(服务端会去空白并转小写),key 最长 64、value 最长 128 字符。传入多个 tags 时,`find()` 会要求全部命中;上面的例子只返回显式检索标签同时包含 `env=prod` 和 `team=search` 的上下文。**Python SDK**@@ -397,7 +397,7 @@ openviking find "红色海报风格" --image ./poster.png --uri "viking://resour| session | Session | 否 | None | 用于上下文感知搜索的会话(SDK)|| session_id | str | 否 | None | 用于上下文感知搜索的会话 ID(HTTP)|| context_type | str \| List[str] | 否 | None | 限定一个或多个 `ContextType` 取值:`memory`、`resource` 或 `skill` |-| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |+| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式(小写字母/数字/`_`/`-`/`.`,以字母或数字开头,key≤64、value≤128)。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 || limit | int | 否 | 10 | 最大返回结果数 || node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 limit || score_threshold | float | 否 | None | 最低相关性分数阈值 |diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.mdindex fe2febb93..6f877ddf3 100644--- a/docs/zh/api/12-content.md+++ b/docs/zh/api/12-content.md@@ -491,7 +491,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png### set_tags()-设置用于检索过滤的显式 `k=v` 标签。`replace` 替换已有标签,`append` 追加标签;对目录设置 `recursive=true` 时会更新目录下的文件。+设置用于检索过滤的显式 `k=v` 标签。key 和 value 都非空、只能有一个 `=`,仅由小写字母、数字、`_`、`-`、`.` 组成且以字母或数字开头(服务端会去空白并转小写),key 最长 64、value 最长 128 字符;不合规的标签会被拒绝。`replace` 替换已有标签,`append` 追加标签;对目录设置 `recursive=true` 时会更新目录下的文件。**Python SDK**diff --git a/openviking/utils/tags.py b/openviking/utils/tags.pyindex c9c581ae6..a6faa5e08 100644--- a/openviking/utils/tags.py+++ b/openviking/utils/tags.py@@ -5,6 +5,7 @@from __future__ import annotationsimport logging+import refrom collections import OrderedDictfrom typing import Any, Iterable@@ -12,12 +13,25 @@ from openviking_cli.exceptions import InvalidArgumentErrorlogger = logging.getLogger(__name__)+# Explicit search tags are meant to be small, enumerable business dimensions+# (env, team, source, ...). Constrain both sides of ``k=v`` so tags stay stable+# identifiers rather than free-form text: bounded length and a predictable+# character set after lower-casing (no internal spaces, no ``=``).+MAX_TAG_KEY_LENGTH = 64+MAX_TAG_VALUE_LENGTH = 128+MAX_TAG_LENGTH = MAX_TAG_KEY_LENGTH + 1 + MAX_TAG_VALUE_LENGTH+_TAG_TOKEN_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]*$")+def normalize_search_tag(tag: str) -> str:"""Validate and normalize a single k=v search tag."""value = str(tag).strip().lower()if not value:raise InvalidArgumentError("search tag must be a non-empty k=v string")+ if len(value) > MAX_TAG_LENGTH:+ raise InvalidArgumentError(+ f"invalid search tag '{tag}': exceeds max length {MAX_TAG_LENGTH}"+ )if value.count("=") != 1:raise InvalidArgumentError(f"invalid search tag '{tag}': expected strict k=v format")@@ -26,6 +40,19 @@ def normalize_search_tag(tag: str) -> str:raise InvalidArgumentError(f"invalid search tag '{tag}': key and value must both be non-empty")+ if len(key) > MAX_TAG_KEY_LENGTH:+ raise InvalidArgumentError(+ f"invalid search tag '{tag}': key exceeds max length {MAX_TAG_KEY_LENGTH}"+ )+ if len(raw_value) > MAX_TAG_VALUE_LENGTH:+ raise InvalidArgumentError(+ f"invalid search tag '{tag}': value exceeds max length {MAX_TAG_VALUE_LENGTH}"+ )+ if not _TAG_TOKEN_RE.match(key) or not _TAG_TOKEN_RE.match(raw_value):+ raise InvalidArgumentError(+ f"invalid search tag '{tag}': key and value may only contain lowercase "+ "letters, digits, '_', '-', '.', and must start with a letter or digit"+ )return f"{key}={raw_value}"diff --git a/tests/unit/test_search_tags_filter.py b/tests/unit/test_search_tags_filter.pyindex f51435864..a7b584746 100644--- a/tests/unit/test_search_tags_filter.py+++ b/tests/unit/test_search_tags_filter.py@@ -3,9 +3,19 @@import logging+import pytest+from openviking.server.routers.search import _resolve_search_filterfrom openviking.utils import tags as tags_module-from openviking.utils.tags import build_search_tags_filter, merge_search_tags, normalize_search_tags+from openviking.utils.tags import (+ MAX_TAG_KEY_LENGTH,+ MAX_TAG_VALUE_LENGTH,+ build_search_tags_filter,+ merge_search_tags,+ normalize_search_tag,+ normalize_search_tags,+)+from openviking_cli.exceptions import InvalidArgumentErrordef test_search_tags_filter_keeps_single_tag_as_single_must():@@ -30,6 +40,44 @@ def test_search_tags_duplicate_keys_keep_last_value():assert normalize_search_tags(["channel=web", "channel=app"]) == ["channel=app"]+def test_search_tag_allows_dot_dash_underscore():+ assert normalize_search_tag("doc_type=api-v1.2") == "doc_type=api-v1.2"+++ "tag",+ [+ "team=search platform", # internal space+ "team=with/slash", # unsupported char+ "team=值", # non-ascii+ "-team=search", # must start with letter/digit+ "team=-search",+ "te=am=search", # more than one '='+ ],+)+def test_search_tag_rejects_disallowed_characters(tag):+ with pytest.raises(InvalidArgumentError):+ normalize_search_tag(tag)+++def test_search_tag_rejects_over_length_key():+ over_key = "k" * (MAX_TAG_KEY_LENGTH + 1)+ with pytest.raises(InvalidArgumentError):+ normalize_search_tag(f"{over_key}=v")+++def test_search_tag_rejects_over_length_value():+ over_value = "v" * (MAX_TAG_VALUE_LENGTH + 1)+ with pytest.raises(InvalidArgumentError):+ normalize_search_tag(f"team={over_value}")+++def test_search_tag_accepts_boundary_lengths():+ key = "k" * MAX_TAG_KEY_LENGTH+ value = "v" * MAX_TAG_VALUE_LENGTH+ assert normalize_search_tag(f"{key}={value}") == f"{key}={value}"++def test_discard_invalid_search_tags_logs_one_warning_for_batch(caplog):tags_module.logger.addHandler(caplog.handler)try: