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(retrieve): use tags metadata for cross-subtree retrieval (#1162)
13ernkastele72b614b3db2
diff --git a/openviking/async_client.py b/openviking/async_client.pyindex f4ef9f493..b304b776b 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -210,6 +210,7 @@ class AsyncOpenViking:build_index: bool = True,summarize: bool = False,watch_interval: float = 0,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,**kwargs,) -> Dict[str, Any]:@@ -242,6 +243,7 @@ class AsyncOpenViking:timeout=timeout,build_index=build_index,summarize=summarize,+ tags=tags,telemetry=telemetry,watch_interval=watch_interval,**kwargs,@@ -308,6 +310,7 @@ class AsyncOpenViking:limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""@@ -333,6 +336,7 @@ class AsyncOpenViking:limit=limit,score_threshold=score_threshold,filter=filter,+ tags=tags,telemetry=telemetry,)@@ -343,6 +347,7 @@ class AsyncOpenViking:limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""Semantic search"""@@ -353,6 +358,7 @@ class AsyncOpenViking:limit=limit,score_threshold=score_threshold,filter=filter,+ tags=tags,telemetry=telemetry,)diff --git a/openviking/client/local.py b/openviking/client/local.pyindex b173b44ab..0dfdb766f 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -14,6 +14,7 @@ from openviking.telemetry.execution import (attach_telemetry_payload,run_with_telemetry,)+from openviking.utils.tag_utils import canonicalize_user_tags, expand_query_tagsfrom openviking_cli.client.base import BaseClientfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils import run_async@@ -83,6 +84,7 @@ class LocalClient(BaseClient):summarize: bool = False,telemetry: TelemetryRequest = False,watch_interval: float = 0,+ tags: Optional[Union[str, List[str]]] = None,**kwargs,) -> Dict[str, Any]:"""Add resource to OpenViking."""@@ -104,6 +106,7 @@ class LocalClient(BaseClient):build_index=build_index,summarize=summarize,watch_interval=watch_interval,+ tags=canonicalize_user_tags(tags),**kwargs,),)@@ -263,6 +266,7 @@ class LocalClient(BaseClient):limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict[str, Any]] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Any:"""Semantic search without session context."""@@ -276,6 +280,7 @@ class LocalClient(BaseClient):limit=limit,score_threshold=score_threshold,filter=filter,+ tags=expand_query_tags(tags),),)return attach_telemetry_payload(@@ -291,6 +296,7 @@ class LocalClient(BaseClient):limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict[str, Any]] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Any:"""Semantic search with optional session context."""@@ -308,6 +314,7 @@ class LocalClient(BaseClient):limit=limit,score_threshold=score_threshold,filter=filter,+ tags=expand_query_tags(tags),)execution = await run_with_telemetry(diff --git a/openviking/core/context.py b/openviking/core/context.pyindex 55bce1c47..58d0d43f2 100644--- a/openviking/core/context.py+++ b/openviking/core/context.py@@ -7,6 +7,7 @@ from enum import Enumfrom typing import Any, Dict, List, Optionalfrom uuid import uuid4+from openviking.utils.tag_utils import parse_tagsfrom openviking.utils.time_utils import format_iso8601, parse_iso_datetimefrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.uri import VikingURI@@ -67,6 +68,7 @@ class Context:active_count: int = 0,related_uri: Optional[List[str]] = None,meta: Optional[Dict[str, Any]] = None,+ tags: Optional[List[str] | str] = None,level: int | ContextLevel | None = None,session_id: Optional[str] = None,user: Optional[UserIdentifier] = None,@@ -90,6 +92,9 @@ class Context:self.active_count = active_countself.related_uri = related_uri or []self.meta = meta or {}+ self.tags = parse_tags(tags if tags is not None else self.meta.get("tags"))+ if self.tags and "tags" not in self.meta:+ self.meta["tags"] = list(self.tags)try:self.level = int(level) if level is not None else Noneexcept (TypeError, ValueError):@@ -172,6 +177,7 @@ class Context:"active_count": self.active_count,"vector": self.vector,"meta": self.meta,+ "tags": self.tags,"related_uri": self.related_uri,"session_id": self.session_id,"account_id": self.account_id,@@ -225,6 +231,13 @@ class Context:active_count=data.get("active_count", 0),related_uri=data.get("related_uri", []),meta=data.get("meta", {}),+ tags=(+ data.get("tags")+ if data.get("tags") is not None+ else data.get("meta", {}).get("tags")+ if isinstance(data.get("meta"), dict)+ else None+ ),level=(data.get("level")if data.get("level") is not Nonediff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex 3192ccff8..25870d6d4 100644--- a/openviking/retrieve/hierarchical_retriever.py+++ b/openviking/retrieve/hierarchical_retriever.py@@ -22,6 +22,7 @@ from openviking.server.identity import RequestContext, Rolefrom openviking.storage import VikingDBManager, VikingDBManagerProxyfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import get_current_telemetry+from openviking.utils.tag_utils import expand_query_tags, merge_tags, parse_tagsfrom openviking.utils.time_utils import parse_iso_datetimefrom openviking_cli.retrieve.types import (ContextType,@@ -50,6 +51,9 @@ class HierarchicalRetriever:DIRECTORY_DOMINANCE_RATIO = 1.2 # Directory score must exceed max child scoreGLOBAL_SEARCH_TOPK = 10 # Global retrieval count (more candidates = better rerank precision)HOTNESS_ALPHA = 0.2 # Weight for hotness score in final ranking (0 = disabled)+ MAX_TAG_EXPANSION_TAGS = 8 # Upper bound on expansion tags collected per query.+ TAG_EXPANSION_LIMIT = 8 # Upper bound on extra nodes discovered via tags.+ TAG_EXPANSION_SCORE = 0.15 # Lower seed score for tag-expanded nodes.LEVEL_URI_SUFFIX = {0: ".abstract.md", 1: ".overview.md"}def __init__(@@ -113,6 +117,7 @@ class HierarchicalRetriever:vector_proxy = VikingDBManagerProxy(self.vector_store, ctx)target_dirs = [d for d in (query.target_directories or []) if d]+ query_tags = expand_query_tags(query.tags)if not await vector_proxy.collection_exists_bound():logger.warning(@@ -146,6 +151,7 @@ class HierarchicalRetriever:sparse_query_vector=sparse_query_vector,context_type=query.context_type.value if query.context_type else None,target_dirs=target_dirs,+ tags=query_tags,scope_dsl=scope_dsl,limit=max(limit, self.GLOBAL_SEARCH_TOPK),)@@ -167,11 +173,22 @@ class HierarchicalRetriever:f" [{i}] URI: {uri}, score: {score:.4f}, level: {level}, account_id: {account_id}")+ expanded_points, expanded_candidates = await self._expand_starting_points_by_tags(+ vector_proxy=vector_proxy,+ global_results=global_results,+ explicit_tags=query_tags,+ context_type=query.context_type.value if query.context_type else None,+ target_dirs=target_dirs,+ scope_dsl=scope_dsl,+ limit=self.TAG_EXPANSION_LIMIT,+ )+# Step 3: Merge starting pointsstarting_points = self._merge_starting_points(query.query,root_uris,global_results,+ extra_points=expanded_points,mode=mode,)@@ -183,6 +200,10 @@ class HierarchicalRetriever:initial_candidates,mode=mode,)+ initial_candidates = self._merge_initial_candidates(+ initial_candidates,+ expanded_candidates,+ )# Step 4: Recursive searchcandidates = await self._recursive_search(@@ -229,6 +250,7 @@ class HierarchicalRetriever:sparse_query_vector: Optional[Dict[str, float]],context_type: Optional[str],target_dirs: List[str],+ tags: List[str],scope_dsl: Optional[Dict[str, Any]],limit: int,) -> List[Dict[str, Any]]:@@ -238,6 +260,7 @@ class HierarchicalRetriever:sparse_query_vector=sparse_query_vector,context_type=context_type,target_directories=target_dirs,+ tags=tags,extra_filter=scope_dsl,limit=limit,)@@ -284,6 +307,7 @@ class HierarchicalRetriever:query: str,root_uris: List[str],global_results: List[Dict[str, Any]],+ extra_points: Optional[List[Tuple[str, float]]] = None,mode: str = "thinking",) -> List[Tuple[str, float]]:"""Merge starting points.@@ -320,8 +344,111 @@ class HierarchicalRetriever:points.append((uri, 0.0))seen.add(uri)+ for uri, score in extra_points or []:+ if uri not in seen:+ points.append((uri, score))+ seen.add(uri)+return points+ def _merge_initial_candidates(+ self,+ *candidate_groups: Optional[List[Dict[str, Any]]],+ ) -> List[Dict[str, Any]]:+ merged: Dict[str, Dict[str, Any]] = {}+ for group in candidate_groups:+ for candidate in group or []:+ uri = candidate.get("uri", "")+ if not uri:+ continue+ previous = merged.get(uri)+ if previous is None or candidate.get("_score", 0.0) > previous.get("_score", 0.0):+ merged[uri] = candidate+ return sorted(merged.values(), key=lambda item: item.get("_score", 0.0), reverse=True)++ async def _expand_starting_points_by_tags(+ self,+ vector_proxy: VikingDBManagerProxy,+ global_results: List[Dict[str, Any]],+ explicit_tags: List[str],+ context_type: Optional[str],+ target_dirs: List[str],+ scope_dsl: Optional[Dict[str, Any]],+ limit: int,+ ) -> Tuple[List[Tuple[str, float]], List[Dict[str, Any]]]:+ expansion_tags = self._collect_expansion_tags(global_results, explicit_tags)+ if not expansion_tags or limit <= 0:+ return [], []++ tag_matches = await vector_proxy.search_by_tags_in_tenant(+ tags=expansion_tags,+ context_type=context_type,+ target_directories=target_dirs,+ extra_filter=scope_dsl,+ levels=[0, 1, 2],+ limit=limit,+ )+ telemetry = get_current_telemetry()+ telemetry.count("retrieval.tag_expansion.tags", len(expansion_tags))+ telemetry.count("retrieval.tag_expansion.matches", len(tag_matches))++ seen_uris = {result.get("uri", "") for result in global_results}+ expansion_points: Dict[str, float] = {}+ expansion_candidates: Dict[str, Dict[str, Any]] = {}+ expansion_tag_set = set(expansion_tags)++ for match in tag_matches:+ uri = match.get("uri", "")+ if not uri or uri in seen_uris:+ continue++ overlap = expansion_tag_set.intersection(parse_tags(match.get("tags")))+ score = self._score_tag_expansion(len(overlap))++ if match.get("level", 2) == 2:+ candidate = dict(match)+ candidate["_score"] = score+ previous = expansion_candidates.get(uri)+ if previous is None or score > previous.get("_score", 0.0):+ expansion_candidates[uri] = candidate++ start_uri = self._start_uri_from_record(match)+ if start_uri and score > expansion_points.get(start_uri, 0.0):+ expansion_points[start_uri] = score++ return list(expansion_points.items()), list(expansion_candidates.values())++ def _collect_expansion_tags(+ self,+ global_results: List[Dict[str, Any]],+ explicit_tags: List[str],+ ) -> List[str]:+ collected = [explicit_tags]+ for result in global_results:+ collected.append(parse_tags(result.get("tags")))+ return merge_tags(*collected, max_tags=self.MAX_TAG_EXPANSION_TAGS)++ def _score_tag_expansion(self, overlap_count: int) -> float:+ if overlap_count <= 1:+ return self.TAG_EXPANSION_SCORE+ return self.TAG_EXPANSION_SCORE * (1.0 + 0.2 * min(overlap_count - 1, 3))++ def _start_uri_from_record(self, record: Dict[str, Any]) -> str:+ uri = record.get("uri", "")+ if not uri:+ return ""+ if record.get("level", 2) != 2:+ return uri++ parent_uri = record.get("parent_uri")+ if parent_uri:+ return parent_uri++ normalized = uri.rstrip("/")+ if "/" not in normalized:+ return ""+ return normalized.rsplit("/", 1)[0]+def _prepare_initial_candidates(self,query: str,diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.pyindex 45ac3f3db..ca8155144 100644--- a/openviking/server/routers/resources.py+++ b/openviking/server/routers/resources.py@@ -20,6 +20,7 @@ from openviking.server.local_input_guard import (from openviking.server.models import Responsefrom openviking.server.telemetry import run_operationfrom openviking.telemetry import TelemetryRequest+from openviking.utils.tag_utils import canonicalize_user_tagsfrom openviking_cli.exceptions import InvalidArgumentErrorfrom openviking_cli.utils.config.open_viking_config import get_openviking_config@@ -50,6 +51,7 @@ class AddResourceRequest(BaseModel):exclude: Glob pattern for files to exclude during parsing.directly_upload_media: Whether to directly upload media files. Default is True.preserve_structure: Whether to preserve directory structure when adding directories.+ tags: Optional semicolon-delimited tags to persist on indexed contexts.watch_interval: Watch interval in minutes for automatic resource monitoring.- watch_interval > 0: Creates or updates a watch task. The resource will beautomatically re-processed at the specified interval.@@ -80,6 +82,7 @@ class AddResourceRequest(BaseModel):exclude: Optional[str] = Nonedirectly_upload_media: bool = Truepreserve_structure: Optional[bool] = None+ tags: Optional[str] = Nonetelemetry: TelemetryRequest = Falsewatch_interval: float = 0@@ -213,6 +216,7 @@ async def add_resource(instruction=request.instruction,wait=request.wait,timeout=request.timeout,+ tags=canonicalize_user_tags(request.tags),allow_local_path_resolution=allow_local_path_resolution,**kwargs,),diff --git a/openviking/server/routers/search.py b/openviking/server/routers/search.pyindex a0aa97dbf..3b2b11f2c 100644--- a/openviking/server/routers/search.py+++ b/openviking/server/routers/search.py@@ -14,6 +14,7 @@ from openviking.server.identity import RequestContextfrom openviking.server.models import Responsefrom openviking.server.telemetry import run_operationfrom openviking.telemetry import TelemetryRequest+from openviking.utils.tag_utils import expand_query_tagsdef _sanitize_floats(obj: Any) -> Any:@@ -40,6 +41,7 @@ class FindRequest(BaseModel):limit: int = 10node_limit: Optional[int] = Nonescore_threshold: Optional[float] = None+ tags: Optional[str] = Nonefilter: Optional[Dict[str, Any]] = Noneinclude_provenance: bool = Falsetelemetry: TelemetryRequest = False@@ -54,6 +56,7 @@ class SearchRequest(BaseModel):limit: int = 10node_limit: Optional[int] = Nonescore_threshold: Optional[float] = None+ tags: Optional[str] = Nonefilter: Optional[Dict[str, Any]] = Noneinclude_provenance: bool = Falsetelemetry: TelemetryRequest = False@@ -94,6 +97,7 @@ async def find(target_uri=request.target_uri,limit=actual_limit,score_threshold=request.score_threshold,+ tags=expand_query_tags(request.tags),filter=request.filter,),)@@ -129,6 +133,7 @@ async def search(session=session,limit=actual_limit,score_threshold=request.score_threshold,+ tags=expand_query_tags(request.tags),filter=request.filter,)diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.pyindex 056a09fd0..b2ecd05cb 100644--- a/openviking/service/resource_service.py+++ b/openviking/service/resource_service.py@@ -23,6 +23,7 @@ from openviking.telemetry.resource_summary import ()from openviking.utils.resource_processor import ResourceProcessorfrom openviking.utils.skill_processor import SkillProcessor+from openviking.utils.tag_utils import canonicalize_user_tagsfrom openviking_cli.exceptions import (ConflictError,DeadlineExceededError,@@ -105,6 +106,7 @@ class ResourceService:instruction: str = "",wait: bool = False,timeout: Optional[float] = None,+ tags: Optional[List[str]] = None,build_index: bool = True,summarize: bool = False,watch_interval: float = 0,@@ -159,6 +161,7 @@ class ResourceService:telemetry.set("resource.flags.build_index", build_index)telemetry.set("resource.flags.summarize", summarize)telemetry.set("resource.flags.watch_enabled", watch_enabled)+ tags = canonicalize_user_tags(tags)try:# add_resource only supports resources scope@@ -187,6 +190,7 @@ class ResourceService:scope="resources",to=to,parent=parent,+ tags=tags,build_index=build_index,summarize=summarize,allow_local_path_resolution=allow_local_path_resolution,@@ -219,6 +223,8 @@ class ResourceService:if watch_interval > 0:try:processor_kwargs = self._sanitize_watch_processor_kwargs(kwargs)+ if tags:+ processor_kwargs["tags"] = tagsawait self._handle_watch_task_creation(path=path,to_uri=to,diff --git a/openviking/service/search_service.py b/openviking/service/search_service.pyindex af2562dcf..edd4e3cfd 100644--- a/openviking/service/search_service.py+++ b/openviking/service/search_service.py@@ -6,10 +6,11 @@ Search Service for OpenViking.Provides semantic search operations: search, find."""-from typing import TYPE_CHECKING, Any, Dict, Optional+from typing import TYPE_CHECKING, Any, Dict, List, Optionalfrom openviking.server.identity import RequestContextfrom openviking.storage.viking_fs import VikingFS+from openviking.utils.tag_utils import expand_query_tagsfrom openviking_cli.exceptions import NotInitializedErrorfrom openviking_cli.utils import get_logger@@ -43,6 +44,7 @@ class SearchService:session: Optional["Session"] = None,limit: int = 10,score_threshold: Optional[float] = None,+ tags: Optional[List[str]] = None,filter: Optional[Dict] = None,) -> Any:"""Complex search with session context.@@ -59,6 +61,7 @@ class SearchService:FindResult"""viking_fs = self._ensure_initialized()+ tags = expand_query_tags(tags)session_info = Noneif session:@@ -71,6 +74,7 @@ class SearchService:session_info=session_info,limit=limit,score_threshold=score_threshold,+ tags=tags,filter=filter,)return result@@ -82,6 +86,7 @@ class SearchService:target_uri: str = "",limit: int = 10,score_threshold: Optional[float] = None,+ tags: Optional[List[str]] = None,filter: Optional[Dict] = None,) -> Any:"""Semantic search without session context.@@ -97,12 +102,14 @@ class SearchService:FindResult"""viking_fs = self._ensure_initialized()+ tags = expand_query_tags(tags)result = await viking_fs.find(query=query,ctx=ctx,target_uri=target_uri,limit=limit,score_threshold=score_threshold,+ tags=tags,filter=filter,)return resultdiff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.pyindex bbd7d6008..335f0d374 100644--- a/openviking/storage/queuefs/semantic_dag.py+++ b/openviking/storage/queuefs/semantic_dag.py@@ -58,6 +58,7 @@ class VectorizeTask:summary_dict: Optional[Dict[str, str]] = Noneparent_uri: Optional[str] = Noneuse_summary: bool = False+ tags: Optional[List[str]] = None# For directory tasksabstract: Optional[str] = Noneoverview: Optional[str] = None@@ -78,6 +79,7 @@ class SemanticDagExecutor:recursive: bool = True,lifecycle_lock_handle_id: str = "",is_code_repo: bool = False,+ tags: Optional[List[str]] = None,):self._processor = processorself._context_type = context_type@@ -89,6 +91,7 @@ class SemanticDagExecutor:self._recursive = recursiveself._lifecycle_lock_handle_id = lifecycle_lock_handle_idself._is_code_repo = is_code_repo+ self._tags = list(tags or [])self._llm_sem = asyncio.Semaphore(max_concurrent_llm)self._viking_fs = get_viking_fs()self._nodes: Dict[str, DirNode] = {}@@ -197,6 +200,7 @@ class SemanticDagExecutor:ctx=task.ctx,semantic_msg_id=task.semantic_msg_id,use_summary=task.use_summary,+ tags=task.tags,))else:@@ -208,6 +212,7 @@ class SemanticDagExecutor:task.overview,ctx=task.ctx,semantic_msg_id=task.semantic_msg_id,+ tags=task.tags,))else:@@ -451,6 +456,7 @@ class SemanticDagExecutor:summary_dict=summary_dict,parent_uri=parent_uri,use_summary=use_summary,+ tags=self._tags,)await self._add_vectorize_task(task)except Exception as e:@@ -569,6 +575,7 @@ class SemanticDagExecutor:semantic_msg_id=self._semantic_msg_id,abstract=abstract,overview=overview,+ tags=self._tags,)await self._add_vectorize_task(task)except Exception as e:diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.pyindex ba27d841a..a54bbd471 100644--- a/openviking/storage/queuefs/semantic_msg.py+++ b/openviking/storage/queuefs/semantic_msg.py@@ -8,6 +8,8 @@ from datetime import datetimefrom typing import Any, Dict, List, Optionalfrom uuid import uuid4+from openviking.utils.tag_utils import parse_tags+@dataclassclass SemanticMsg:@@ -41,6 +43,7 @@ class SemanticMsg:target_uri: str = ""lifecycle_lock_handle_id: str = ""is_code_repo: bool = False+ tags: List[str] = Nonechanges: Optional[Dict[str, List[str]]] = (None # {"added": [...], "modified": [...], "deleted": [...]})@@ -59,6 +62,7 @@ class SemanticMsg:target_uri: str = "",lifecycle_lock_handle_id: str = "",is_code_repo: bool = False,+ tags: Optional[str | List[str]] = None,changes: Optional[Dict[str, List[str]]] = None,):self.id = str(uuid4())@@ -74,6 +78,7 @@ class SemanticMsg:self.target_uri = target_uriself.lifecycle_lock_handle_id = lifecycle_lock_handle_idself.is_code_repo = is_code_repo+ self.tags = parse_tags(tags)self.changes = changesdef to_dict(self) -> Dict[str, Any]:@@ -114,6 +119,7 @@ class SemanticMsg:target_uri=data.get("target_uri", ""),lifecycle_lock_handle_id=data.get("lifecycle_lock_handle_id", ""),is_code_repo=data.get("is_code_repo", False),+ tags=data.get("tags"),changes=data.get("changes"),)if "id" in data and data["id"]:diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.pyindex a069c0bf9..53c6a0cbc 100644--- a/openviking/storage/queuefs/semantic_processor.py+++ b/openviking/storage/queuefs/semantic_processor.py@@ -305,6 +305,7 @@ class SemanticProcessor(DequeueHandlerBase):recursive=msg.recursive,lifecycle_lock_handle_id=msg.lifecycle_lock_handle_id,is_code_repo=msg.is_code_repo,+ tags=msg.tags,)self._dag_executor = executorif msg.lifecycle_lock_handle_id:@@ -1238,6 +1239,7 @@ class SemanticProcessor(DequeueHandlerBase):overview: str,ctx: Optional[RequestContext] = None,semantic_msg_id: Optional[str] = None,+ tags: Optional[List[str]] = None,) -> None:"""Create directory Context and enqueue to EmbeddingQueue."""@@ -1255,6 +1257,7 @@ class SemanticProcessor(DequeueHandlerBase):context_type=context_type,ctx=active_ctx,semantic_msg_id=semantic_msg_id,+ tags=tags,)async def _vectorize_single_file(@@ -1266,6 +1269,7 @@ class SemanticProcessor(DequeueHandlerBase):ctx: Optional[RequestContext] = None,semantic_msg_id: Optional[str] = None,use_summary: bool = False,+ tags: Optional[List[str]] = None,) -> None:"""Vectorize a single file using its content or summary."""from openviking.utils.embedding_utils import vectorize_file@@ -1279,4 +1283,5 @@ class SemanticProcessor(DequeueHandlerBase):ctx=active_ctx,semantic_msg_id=semantic_msg_id,use_summary=use_summary,+ tags=tags,)diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex 6619ca177..1d14246df 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -878,6 +878,7 @@ class VikingFS:target_uri: str = "",limit: int = 10,score_threshold: Optional[float] = None,+ tags: Optional[List[str]] = None,filter: Optional[Dict] = None,ctx: Optional[RequestContext] = None,):@@ -926,6 +927,7 @@ class VikingFS:context_type=context_type,intent="",target_directories=[target_uri] if target_uri else None,+ tags=tags or [],)real_ctx = self._ctx_or_default(ctx)@@ -966,6 +968,7 @@ class VikingFS:session_info: Optional[Dict] = None,limit: int = 10,score_threshold: Optional[float] = None,+ tags: Optional[List[str]] = None,filter: Optional[Dict] = None,ctx: Optional[RequestContext] = None,):@@ -1026,6 +1029,8 @@ class VikingFS:target_abstract=target_abstract,)typed_queries = query_plan.queries+ for tq in typed_queries:+ tq.tags = list(tags or [])# Set target_directoriesif target_uri_list:for tq in typed_queries:@@ -1041,6 +1046,7 @@ class VikingFS:intent="",priority=1,target_directories=target_uri_list,+ tags=tags or [],)]else:@@ -1052,6 +1058,7 @@ class VikingFS:intent="",priority=1,target_directories=target_uri_list,+ tags=tags or [],)for ctx_type in [ContextType.MEMORY, ContextType.RESOURCE, ContextType.SKILL]]diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.pyindex ce5dc8e7b..ea841db04 100644--- a/openviking/storage/viking_vector_index_backend.py+++ b/openviking/storage/viking_vector_index_backend.py@@ -19,8 +19,10 @@ logger = get_logger(__name__)RETRIEVAL_OUTPUT_FIELDS = ["uri",+ "parent_uri","level","context_type",+ "tags","abstract","active_count","updated_at",@@ -777,6 +779,7 @@ class VikingVectorIndexBackend:ctx=ctx,context_type=context_type,target_directories=target_directories,+ tags=None,extra_filter=extra_filter,)return await self.search(@@ -796,6 +799,7 @@ class VikingVectorIndexBackend:sparse_query_vector: Optional[Dict[str, float]] = None,context_type: Optional[str] = None,target_directories: Optional[List[str]] = None,+ tags: Optional[List[str]] = None,extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,limit: int = 10,) -> List[Dict[str, Any]]:@@ -807,6 +811,7 @@ class VikingVectorIndexBackend:ctx=ctx,context_type=context_type,target_directories=target_directories,+ tags=tags,extra_filter=extra_filter,),In("level", [0, 1, 2]), # TODO: smj fix this@@ -837,6 +842,7 @@ class VikingVectorIndexBackend:ctx=ctx,context_type=context_type,target_directories=target_directories,+ tags=None,extra_filter=extra_filter,),)@@ -849,6 +855,38 @@ class VikingVectorIndexBackend:ctx=ctx,)+ async def search_by_tags_in_tenant(+ self,+ ctx: RequestContext,+ tags: List[str],+ context_type: Optional[str] = None,+ target_directories: Optional[List[str]] = None,+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,+ levels: Optional[List[int]] = None,+ limit: int = 10,+ ) -> List[Dict[str, Any]]:+ if not tags:+ return []++ merged_filter = self._build_scope_filter(+ ctx=ctx,+ context_type=context_type,+ target_directories=target_directories,+ tags=tags,+ extra_filter=extra_filter,+ )+ if levels:+ merged_filter = self._merge_filters(merged_filter, In("level", levels))++ return await self.filter(+ filter=merged_filter,+ limit=limit,+ output_fields=RETRIEVAL_OUTPUT_FIELDS,+ order_by="active_count",+ order_desc=True,+ ctx=ctx,+ )+async def search_similar_memories(self,owner_space: Optional[str],@@ -1014,6 +1052,7 @@ class VikingVectorIndexBackend:ctx: RequestContext,context_type: Optional[str],target_directories: Optional[List[str]],+ tags: Optional[List[str]],extra_filter: Optional[FilterExpr | Dict[str, Any]],) -> Optional[FilterExpr]:filters: List[FilterExpr] = []@@ -1033,6 +1072,10 @@ class VikingVectorIndexBackend:if uri_conds:filters.append(Or(uri_conds))+ tag_filter = self._build_tag_filter(tags)+ if tag_filter:+ filters.append(tag_filter)+if extra_filter:if isinstance(extra_filter, dict):filters.append(RawDSL(extra_filter))@@ -1042,6 +1085,17 @@ class VikingVectorIndexBackend:merged = self._merge_filters(*filters)return merged+ @staticmethod+ def _build_tag_filter(tags: Optional[List[str]]) -> Optional[FilterExpr]:+ normalized = [tag for tag in tags or [] if tag]+ if not normalized:+ return None++ tag_filters = [In("tags", [tag]) for tag in normalized]+ if len(tag_filters) == 1:+ return tag_filters[0]+ return Or(tag_filters)+@staticmethoddef _tenant_filter(ctx: RequestContext, context_type: Optional[str] = Nonediff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.pyindex 899e6a1af..0e3d6f431 100644--- a/openviking/storage/vikingdb_manager.py+++ b/openviking/storage/vikingdb_manager.py@@ -426,6 +426,7 @@ class VikingDBManagerProxy:sparse_query_vector: Optional[Dict[str, float]] = None,context_type: Optional[str] = None,target_directories: Optional[List[str]] = None,+ tags: Optional[List[str]] = None,extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,limit: int = 10,) -> List[Dict[str, Any]]:@@ -435,6 +436,7 @@ class VikingDBManagerProxy:sparse_query_vector=sparse_query_vector,context_type=context_type,target_directories=target_directories,+ tags=tags,extra_filter=extra_filter,limit=limit,)@@ -460,6 +462,25 @@ class VikingDBManagerProxy:limit=limit,)+ async def search_by_tags_in_tenant(+ self,+ tags: List[str],+ context_type: Optional[str] = None,+ target_directories: Optional[List[str]] = None,+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,+ levels: Optional[List[int]] = None,+ limit: int = 10,+ ) -> List[Dict[str, Any]]:+ return await self._manager.search_by_tags_in_tenant(+ self._ctx,+ tags=tags,+ context_type=context_type,+ target_directories=target_directories,+ extra_filter=extra_filter,+ levels=levels,+ limit=limit,+ )+async def search_similar_memories(self,owner_space: Optional[str],diff --git a/openviking/sync_client.py b/openviking/sync_client.pyindex f11056371..64046c360 100644--- a/openviking/sync_client.py+++ b/openviking/sync_client.py@@ -6,7 +6,7 @@ Synchronous OpenViking client implementation.from __future__ import annotations-from typing import TYPE_CHECKING, Any, Dict, List, Optional+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Unionif TYPE_CHECKING:from openviking.session import Session@@ -105,6 +105,7 @@ class SyncOpenViking:timeout: float = None,build_index: bool = True,summarize: bool = False,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,**kwargs,) -> Dict[str, Any]:@@ -129,6 +130,7 @@ class SyncOpenViking:timeout=timeout,build_index=build_index,summarize=summarize,+ tags=tags,telemetry=telemetry,**kwargs,)@@ -155,12 +157,21 @@ class SyncOpenViking:limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""Execute complex retrieval (intent analysis, hierarchical retrieval)."""return run_async(self._async_client.search(- query, target_uri, session, session_id, limit, score_threshold, filter, telemetry+ query=query,+ target_uri=target_uri,+ session=session,+ session_id=session_id,+ limit=limit,+ score_threshold=score_threshold,+ filter=filter,+ tags=tags,+ telemetry=telemetry,))@@ -171,17 +182,19 @@ class SyncOpenViking:limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""Quick retrieval"""return run_async(self._async_client.find(- query,- target_uri,- limit,- score_threshold,- filter,- telemetry,+ query=query,+ target_uri=target_uri,+ limit=limit,+ score_threshold=score_threshold,+ filter=filter,+ tags=tags,+ telemetry=telemetry,))diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex cf442cc0a..b78274567 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -15,6 +15,12 @@ from openviking.server.identity import RequestContextfrom openviking.storage.queuefs import get_queue_managerfrom openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverterfrom openviking.storage.viking_fs import get_viking_fs+from openviking.utils.tag_utils import (+ AUTO_TAG_NAMESPACE,+ extract_context_tags,+ merge_tags,+ namespace_tags,+)from openviking_cli.utils import VikingURI, get_loggerfrom openviking_cli.utils.config import get_openviking_config@@ -134,6 +140,7 @@ async def vectorize_directory_meta(context_type: str = "resource",ctx: Optional[RequestContext] = None,semantic_msg_id: Optional[str] = None,+ tags: Optional[str | list[str]] = None,) -> None:"""Vectorize directory metadata (.abstract.md and .overview.md).@@ -151,6 +158,11 @@ async def vectorize_directory_meta(parent_uri = VikingURI(uri).parent.uriowner_space = _owner_space_for_uri(uri, ctx)+ resolved_tags = extract_context_tags(+ uri,+ texts=[abstract, overview],+ inherited_tags=tags,+ )# Vectorize L0: .abstract.md (abstract)context_abstract = Context(@@ -163,6 +175,7 @@ async def vectorize_directory_meta(user=ctx.user,account_id=ctx.account_id,owner_space=owner_space,+ tags=resolved_tags,)context_abstract.set_vectorize(Vectorize(text=abstract))msg_abstract = EmbeddingMsgConverter.from_context(context_abstract)@@ -189,6 +202,7 @@ async def vectorize_directory_meta(user=ctx.user,account_id=ctx.account_id,owner_space=owner_space,+ tags=resolved_tags,)context_overview.set_vectorize(Vectorize(text=overview))msg_overview = EmbeddingMsgConverter.from_context(context_overview)@@ -215,6 +229,7 @@ async def vectorize_file(ctx: Optional[RequestContext] = None,semantic_msg_id: Optional[str] = None,use_summary: bool = False,+ tags: Optional[str | list[str]] = None,) -> None:"""Vectorize a single file.@@ -236,6 +251,15 @@ async def vectorize_file(file_name = summary_dict.get("name") or os.path.basename(file_path)summary = summary_dict.get("summary", "")+ summary_tags = namespace_tags(+ summary_dict.get("tags"),+ AUTO_TAG_NAMESPACE,+ )+ resolved_tags = extract_context_tags(+ file_path,+ texts=[summary, file_name],+ inherited_tags=merge_tags(tags, summary_tags),+ )context = Context(uri=file_path,@@ -247,6 +271,7 @@ async def vectorize_file(user=ctx.user,account_id=ctx.account_id,owner_space=_owner_space_for_uri(file_path, ctx),+ tags=resolved_tags,)content_type = get_resource_content_type(file_name)@@ -347,7 +372,10 @@ async def index_resource(overview = content.decode("utf-8")if abstract or overview:- await vectorize_directory_meta(uri, abstract, overview, ctx=ctx)+ directory_tags = extract_context_tags(uri, texts=[abstract, overview])+ await vectorize_directory_meta(uri, abstract, overview, ctx=ctx, tags=directory_tags)+ else:+ directory_tags = extract_context_tags(uri)# 2. Index Filestry:@@ -368,7 +396,11 @@ async def index_resource(# For direct indexing, we might not have summaries.# We pass empty summary_dict, vectorize_file will try to read content for text files.await vectorize_file(- file_path=file_uri, summary_dict={"name": file_name}, parent_uri=uri, ctx=ctx+ file_path=file_uri,+ summary_dict={"name": file_name},+ parent_uri=uri,+ ctx=ctx,+ tags=directory_tags,)except Exception as e:diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.pyindex c12109c79..8fd79e895 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -123,6 +123,7 @@ class ResourceProcessor:"source_path": None,}telemetry = get_current_telemetry()+ resource_tags = kwargs.pop("tags", None)with telemetry.measure("resource.process"):# ============ Phase 1: Parse source and writes to temp viking fs ============@@ -278,6 +279,7 @@ class ResourceProcessor:lifecycle_lock_handle_id=lifecycle_lock_handle_id,temp_uris=[temp_uri_for_summarize],is_code_repo=is_code_repo,+ tags=resource_tags,**kwargs,)except Exception as e:diff --git a/openviking/utils/summarizer.py b/openviking/utils/summarizer.pyindex d67a4b545..2433be3e5 100644--- a/openviking/utils/summarizer.py+++ b/openviking/utils/summarizer.py@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any, Dict, Listfrom openviking.core.directories import get_context_type_for_urifrom openviking.storage.queuefs import SemanticMsg, get_queue_managerfrom openviking.telemetry import get_current_telemetry+from openviking.utils.tag_utils import parse_tagsfrom openviking_cli.utils import get_loggerif TYPE_CHECKING:@@ -56,7 +57,7 @@ class Summarizer:enqueued_count = 0telemetry = get_current_telemetry()- for uri, temp_uri in zip(resource_uris, temp_uris):+ for uri, temp_uri in zip(resource_uris, temp_uris, strict=True):# Determine context_type based on URIcontext_type = get_context_type_for_uri(uri)@@ -72,6 +73,7 @@ class Summarizer:target_uri=uri if uri != temp_uri else None,lifecycle_lock_handle_id=lifecycle_lock_handle_id,is_code_repo=kwargs.get("is_code_repo", False),+ tags=parse_tags(kwargs.get("tags")),)await semantic_queue.enqueue(msg)enqueued_count += 1diff --git a/openviking/utils/tag_utils.py b/openviking/utils/tag_utils.pynew file mode 100644index 000000000..ca55a54bc--- /dev/null+++ b/openviking/utils/tag_utils.py@@ -0,0 +1,302 @@+"""Tag parsing and lightweight extraction helpers."""++from __future__ import annotations++import re+from collections import Counter+from typing import Iterable, List, Sequence++_TAG_SPLIT_RE = re.compile(r"[;,\n]+")+_TAG_NAMESPACE_RE = re.compile(r"[a-z0-9][a-z0-9-]{0,15}")+_WORD_RE = re.compile(r"[a-z0-9][a-z0-9.+-]{1,31}")+_CJK_RE = re.compile(r"[\u4e00-\u9fff]{2,16}")+_CJK_SPLIT_RE = re.compile(r"[的了和与及在中对用为将把等以及、/]+")+_MULTI_DASH_RE = re.compile(r"-{2,}")+USER_TAG_NAMESPACE = "user"+AUTO_TAG_NAMESPACE = "auto"+_GENERIC_PATH_SEGMENTS = {+ "agent",+ "agents",+ "default",+ "memories",+ "resource",+ "resources",+ "session",+ "sessions",+ "skill",+ "skills",+ "user",+ "users",+ "viking",+}+_STOP_WORDS = {+ "about",+ "after",+ "also",+ "and",+ "best",+ "build",+ "content",+ "demo",+ "details",+ "document",+ "documents",+ "example",+ "examples",+ "feature",+ "features",+ "file",+ "files",+ "first",+ "for",+ "from",+ "guide",+ "how",+ "into",+ "just",+ "more",+ "overview",+ "project",+ "related",+ "resource",+ "resources",+ "sample",+ "summary",+ "test",+ "testing",+ "that",+ "the",+ "their",+ "them",+ "these",+ "this",+ "using",+ "with",+}+++def _normalize_namespace(value: str) -> str:+ namespace = str(value or "").strip().lower()+ if not namespace:+ return ""++ namespace = re.sub(r"[^0-9a-z-]+", "-", namespace)+ namespace = _MULTI_DASH_RE.sub("-", namespace).strip("-.")+ if not _TAG_NAMESPACE_RE.fullmatch(namespace):+ return ""+ return namespace+++def _normalize_tag_body(value: str) -> str:+ tag = str(value or "").strip().lower()+ if not tag:+ return ""++ tag = re.sub(r"[\s_/]+", "-", tag)+ tag = re.sub(r"[^0-9a-z\u4e00-\u9fff.+-]+", "-", tag)+ tag = _MULTI_DASH_RE.sub("-", tag).strip("-.+")+ if len(tag) < 2:+ return ""+ return tag+++def _normalize_tag(value: str, default_namespace: str | None = None) -> str:+ raw = str(value or "").strip()+ if not raw:+ return ""++ namespace = ""+ body = raw+ if ":" in raw:+ candidate_namespace, body = raw.split(":", 1)+ namespace = _normalize_namespace(candidate_namespace)+ if not namespace:+ return ""++ normalized_body = _normalize_tag_body(body)+ if not normalized_body:+ return ""++ if not namespace and default_namespace:+ namespace = _normalize_namespace(default_namespace)++ if namespace:+ return f"{namespace}:{normalized_body}"+ return normalized_body+++def parse_tags(+ tags: str | Sequence[str] | None,+ *,+ default_namespace: str | None = None,+) -> List[str]:+ """Parse semicolon-delimited tags or a string sequence into normalized tags."""+ if not tags:+ return []++ if isinstance(tags, str):+ raw_items = _TAG_SPLIT_RE.split(tags)+ else:+ raw_items = []+ for item in tags:+ if item is None:+ continue+ if isinstance(item, str):+ raw_items.extend(_TAG_SPLIT_RE.split(item))+ else:+ raw_items.append(str(item))++ seen = set()+ normalized: List[str] = []+ for item in raw_items:+ tag = _normalize_tag(item, default_namespace=default_namespace)+ if not tag or tag in seen:+ continue+ seen.add(tag)+ normalized.append(tag)+ return normalized+++def serialize_tags(+ tags: str | Sequence[str] | None,+ *,+ default_namespace: str | None = None,+) -> str | None:+ parsed = parse_tags(tags, default_namespace=default_namespace)+ if not parsed:+ return None+ return ";".join(parsed)+++def merge_tags(*sources: str | Sequence[str] | None, max_tags: int = 8) -> List[str]:+ merged: List[str] = []+ seen = set()+ for source in sources:+ for tag in parse_tags(source):+ if tag in seen:+ continue+ merged.append(tag)+ seen.add(tag)+ if len(merged) >= max_tags:+ return merged+ return merged+++def _force_namespace(tags: str | Sequence[str] | None, namespace: str) -> List[str]:+ normalized_namespace = _normalize_namespace(namespace)+ if not normalized_namespace:+ return []++ forced: List[str] = []+ seen = set()+ for tag in parse_tags(tags):+ body = tag.split(":", 1)[1] if ":" in tag else tag+ normalized = f"{normalized_namespace}:{body}"+ if normalized in seen:+ continue+ seen.add(normalized)+ forced.append(normalized)+ return forced+++def canonicalize_user_tags(tags: str | Sequence[str] | None) -> List[str]:+ """Canonicalize persisted user-provided tags as ``user:<tag>``."""+ return _force_namespace(tags, USER_TAG_NAMESPACE)+++def namespace_tags(tags: str | Sequence[str] | None, namespace: str) -> List[str]:+ """Apply a namespace to every tag body, overriding any existing prefix."""+ return _force_namespace(tags, namespace)+++def expand_query_tags(+ tags: str | Sequence[str] | None,+ *,+ namespaces: Sequence[str] = (USER_TAG_NAMESPACE, AUTO_TAG_NAMESPACE),+) -> List[str]:+ """Expand bare query tags across known namespaces for backwards-compatible search."""+ normalized = parse_tags(tags)+ if not normalized:+ return []++ expanded: List[str] = []+ seen = set()+ for tag in normalized:+ candidates = [tag] if ":" in tag else [f"{namespace}:{tag}" for namespace in namespaces]+ for candidate in candidates:+ if candidate in seen:+ continue+ seen.add(candidate)+ expanded.append(candidate)+ return expanded+++def _extract_path_tags(uri: str) -> List[str]:+ raw_path = str(uri or "").removeprefix("viking://")+ if not raw_path:+ return []++ results: List[str] = []+ for segment in raw_path.split("/"):+ cleaned = segment.strip()+ if not cleaned or cleaned.startswith("."):+ continue+ cleaned = cleaned.rsplit(".", 1)[0]+ normalized = _normalize_tag(cleaned)+ if not normalized or normalized in _GENERIC_PATH_SEGMENTS:+ continue+ results.append(normalized)+ for token in normalized.split("-"):+ if len(token) >= 3 and token not in _GENERIC_PATH_SEGMENTS:+ results.append(token)+ return results+++def _extract_text_tags(texts: Iterable[str]) -> List[str]:+ words: Counter[str] = Counter()+ bigrams: Counter[str] = Counter()+ cjk_terms: Counter[str] = Counter()++ for text in texts:+ if not text:+ continue++ lowered = text.lower()+ english_tokens = [+ token+ for token in (_normalize_tag(token) for token in _WORD_RE.findall(lowered))+ if token and len(token) >= 3 and token not in _STOP_WORDS+ ]+ for token in english_tokens:+ words[token] += 1+ for left, right in zip(english_tokens, english_tokens[1:], strict=False):+ if left == right:+ continue+ bigrams[f"{left}-{right}"] += 1++ for chunk in _CJK_RE.findall(text):+ for part in _CJK_SPLIT_RE.split(chunk):+ normalized = _normalize_tag(part)+ if normalized:+ cjk_terms[normalized] += 1++ ranked = [tag for tag, _ in bigrams.most_common(4)]+ ranked.extend(tag for tag, _ in cjk_terms.most_common(4))+ ranked.extend(tag for tag, _ in words.most_common(6))+ return ranked+++def extract_context_tags(+ uri: str,+ texts: Sequence[str] | None = None,+ inherited_tags: str | Sequence[str] | None = None,+ max_tags: int = 8,+) -> List[str]:+ """Build conservative tags from path segments, text keywords, and inherited tags."""+ text_values = [text for text in (texts or []) if text]+ return merge_tags(+ inherited_tags,+ namespace_tags(_extract_path_tags(uri), AUTO_TAG_NAMESPACE),+ namespace_tags(_extract_text_tags(text_values), AUTO_TAG_NAMESPACE),+ max_tags=max_tags,+ )diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.pyindex 0cf30c9ec..c108bb7b8 100644--- a/openviking_cli/client/base.py+++ b/openviking_cli/client/base.py@@ -42,6 +42,7 @@ class BaseClient(ABC):wait: bool = False,timeout: Optional[float] = None,watch_interval: float = 0,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Dict[str, Any]:"""Add resource to OpenViking."""@@ -156,6 +157,7 @@ class BaseClient(ABC):limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Any:"""Semantic search without session context."""@@ -170,6 +172,7 @@ class BaseClient(ABC):limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Any:"""Semantic search with optional session context."""diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.pyindex 5b1fb9a9a..0131e9973 100644--- a/openviking_cli/client/http.py+++ b/openviking_cli/client/http.py@@ -14,6 +14,7 @@ from typing import Any, Dict, List, Optional, Unionimport httpxfrom openviking.telemetry import TelemetryRequest, normalize_telemetry_request+from openviking.utils.tag_utils import serialize_tagsfrom openviking_cli.client.base import BaseClientfrom openviking_cli.exceptions import (AlreadyExistsError,@@ -330,6 +331,7 @@ class AsyncHTTPClient(BaseClient):exclude: Optional[str] = None,directly_upload_media: bool = True,preserve_structure: Optional[bool] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Dict[str, Any]:"""Add resource to OpenViking."""@@ -349,6 +351,7 @@ class AsyncHTTPClient(BaseClient):"include": include,"exclude": exclude,"directly_upload_media": directly_upload_media,+ "tags": serialize_tags(tags),"telemetry": telemetry,}if preserve_structure is not None:@@ -588,6 +591,7 @@ class AsyncHTTPClient(BaseClient):node_limit: Optional[int] = None,score_threshold: Optional[float] = None,filter: Optional[Dict[str, Any]] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> FindResult:"""Semantic search without session context."""@@ -603,6 +607,7 @@ class AsyncHTTPClient(BaseClient):"limit": actual_limit,"score_threshold": score_threshold,"filter": filter,+ "tags": serialize_tags(tags),"telemetry": telemetry,},)@@ -619,6 +624,7 @@ class AsyncHTTPClient(BaseClient):node_limit: Optional[int] = None,score_threshold: Optional[float] = None,filter: Optional[Dict[str, Any]] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> FindResult:"""Semantic search with optional session context."""@@ -636,6 +642,7 @@ class AsyncHTTPClient(BaseClient):"limit": actual_limit,"score_threshold": score_threshold,"filter": filter,+ "tags": serialize_tags(tags),"telemetry": telemetry,},)diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.pyindex 5d003508a..6fd72b0ce 100644--- a/openviking_cli/client/sync_http.py+++ b/openviking_cli/client/sync_http.py@@ -151,6 +151,7 @@ class SyncHTTPClient:include: Optional[str] = None,exclude: Optional[str] = None,directly_upload_media: bool = True,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,) -> Dict[str, Any]:"""Add resource to OpenViking."""@@ -158,18 +159,19 @@ class SyncHTTPClient:raise ValueError("Cannot specify both 'to' and 'parent' at the same time.")return run_async(self._async_client.add_resource(- path,- to,- parent,- reason,- instruction,- wait,- timeout,- strict,- ignore_dirs,- include,- exclude,- directly_upload_media,+ path=path,+ to=to,+ parent=parent,+ reason=reason,+ instruction=instruction,+ wait=wait,+ timeout=timeout,+ strict=strict,+ ignore_dirs=ignore_dirs,+ include=include,+ exclude=exclude,+ directly_upload_media=directly_upload_media,+ tags=tags,telemetry=telemetry,))@@ -202,6 +204,7 @@ class SyncHTTPClient:node_limit: Optional[int] = None,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""Semantic search with optional session context."""@@ -215,6 +218,7 @@ class SyncHTTPClient:node_limit=node_limit,score_threshold=score_threshold,filter=filter,+ tags=tags,telemetry=telemetry,))@@ -227,17 +231,19 @@ class SyncHTTPClient:node_limit: Optional[int] = None,score_threshold: Optional[float] = None,filter: Optional[Dict] = None,+ tags: Optional[Union[str, List[str]]] = None,telemetry: TelemetryRequest = False,):"""Semantic search without session context."""return run_async(self._async_client.find(- query,- target_uri,- limit,- node_limit,- score_threshold,- filter,+ query=query,+ target_uri=target_uri,+ limit=limit,+ node_limit=node_limit,+ score_threshold=score_threshold,+ filter=filter,+ tags=tags,telemetry=telemetry,))diff --git a/openviking_cli/retrieve/types.py b/openviking_cli/retrieve/types.pyindex b3540011f..5b6d90e67 100644--- a/openviking_cli/retrieve/types.py+++ b/openviking_cli/retrieve/types.py@@ -244,6 +244,7 @@ class TypedQuery:intent: Query intent descriptionpriority: Priority (1-5, 1 is highest)target_directories: Directory URIs located by LLM+ tags: Explicit tag constraints supplied by the caller"""query: str@@ -251,6 +252,7 @@ class TypedQuery:intent: strpriority: int = 3target_directories: List[str] = field(default_factory=list)+ tags: List[str] = field(default_factory=list)@dataclassdiff --git a/tests/client/test_search.py b/tests/client/test_search.pyindex f24e161e8..6d99f6317 100644--- a/tests/client/test_search.py+++ b/tests/client/test_search.py@@ -3,7 +3,12 @@"""Search tests"""+from types import SimpleNamespace+from unittest.mock import AsyncMock+from openviking.message import TextPart+from openviking.sync_client import SyncOpenViking+from openviking_cli.client.sync_http import SyncHTTPClientclass TestFind:@@ -74,3 +79,83 @@ class TestSearch:result = await client.search(query="sample", target_uri=parent_uri)assert hasattr(result, "resources")+++class TestSyncWrappers:+ def test_sync_http_client_find_forwards_keyword_args(self):+ mock_find = AsyncMock(return_value="ok")+ client = object.__new__(SyncHTTPClient)+ client._async_client = SimpleNamespace(find=mock_find)++ result = client.find(+ query="sample",+ target_uri="viking://resources/demo",+ limit=5,+ node_limit=3,+ score_threshold=0.25,+ filter={"kind": "resource"},+ tags=["machine-learning"],+ telemetry=True,+ )++ assert result == "ok"+ mock_find.assert_awaited_once_with(+ query="sample",+ target_uri="viking://resources/demo",+ limit=5,+ node_limit=3,+ score_threshold=0.25,+ filter={"kind": "resource"},+ tags=["machine-learning"],+ telemetry=True,+ )++ def test_sync_openviking_search_and_find_forward_keyword_args(self):+ mock_search = AsyncMock(return_value="search-ok")+ mock_find = AsyncMock(return_value="find-ok")+ client = object.__new__(SyncOpenViking)+ client._async_client = SimpleNamespace(search=mock_search, find=mock_find)++ search_result = client.search(+ query="sample",+ target_uri="viking://resources/demo",+ session="session-object",+ session_id="sess-1",+ limit=4,+ score_threshold=0.2,+ filter={"kind": "resource"},+ tags=["feature-store"],+ telemetry=True,+ )+ find_result = client.find(+ query="sample",+ target_uri="viking://resources/demo",+ limit=2,+ score_threshold=0.1,+ filter={"kind": "resource"},+ tags=["feature-store"],+ telemetry=True,+ )++ assert search_result == "search-ok"+ assert find_result == "find-ok"+ mock_search.assert_awaited_once_with(+ query="sample",+ target_uri="viking://resources/demo",+ session="session-object",+ session_id="sess-1",+ limit=4,+ score_threshold=0.2,+ filter={"kind": "resource"},+ tags=["feature-store"],+ telemetry=True,+ )+ mock_find.assert_awaited_once_with(+ query="sample",+ target_uri="viking://resources/demo",+ limit=2,+ score_threshold=0.1,+ filter={"kind": "resource"},+ tags=["feature-store"],+ telemetry=True,+ )diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex 45af89ee6..c28a3bf2c 100644--- a/tests/retrieve/test_hierarchical_retriever_rerank.py+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -39,6 +39,7 @@ class DummyStorage:sparse_query_vector=None,context_type=None,target_directories=None,+ tags=None,extra_filter=None,limit: int = 10,):@@ -49,6 +50,7 @@ class DummyStorage:"sparse_query_vector": sparse_query_vector,"context_type": context_type,"target_directories": target_directories,+ "tags": tags,"extra_filter": extra_filter,"limit": limit,}@@ -114,6 +116,18 @@ class DummyStorage:]return []+ async def search_by_tags_in_tenant(+ self,+ ctx,+ tags,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ levels=None,+ limit: int = 10,+ ):+ return []+class LevelTwoGlobalStorage(DummyStorage):async def search_global_roots_in_tenant(@@ -123,6 +137,7 @@ class LevelTwoGlobalStorage(DummyStorage):sparse_query_vector=None,context_type=None,target_directories=None,+ tags=None,extra_filter=None,limit: int = 10,):@@ -133,6 +148,7 @@ class LevelTwoGlobalStorage(DummyStorage):"sparse_query_vector": sparse_query_vector,"context_type": context_type,"target_directories": target_directories,+ "tags": tags,"extra_filter": extra_filter,"limit": limit,}diff --git a/tests/retrieve/test_hierarchical_retriever_tags.py b/tests/retrieve/test_hierarchical_retriever_tags.pynew file mode 100644index 000000000..8aa47ad0b--- /dev/null+++ b/tests/retrieve/test_hierarchical_retriever_tags.py@@ -0,0 +1,259 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""Hierarchical retriever tag expansion tests."""++import pytest++from openviking.models.embedder.base import EmbedResult+from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever+from openviking.server.identity import RequestContext, Role+from openviking_cli.retrieve.types import ContextType, TypedQuery+from openviking_cli.session.user_id import UserIdentifier+++class DummyEmbedder:+ def embed(self, _text: str, is_query: bool = False) -> EmbedResult:+ return EmbedResult(dense_vector=[0.1, 0.2, 0.3])+++class TagExpansionStorage:+ def __init__(self) -> None:+ self.collection_name = "context"+ self.global_search_calls = []+ self.tag_search_calls = []+ self.child_search_calls = []++ async def collection_exists_bound(self) -> bool:+ return True++ async def search_global_roots_in_tenant(+ self,+ ctx,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ tags=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.global_search_calls.append(+ {+ "ctx": ctx,+ "context_type": context_type,+ "target_directories": target_directories,+ "tags": tags,+ "extra_filter": extra_filter,+ "limit": limit,+ }+ )+ return [+ {+ "uri": "viking://resources/machine-learning",+ "parent_uri": "viking://resources",+ "abstract": "Machine learning notes",+ "_score": 0.9,+ "level": 1,+ "context_type": "resource",+ "tags": ["auto:model-training"],+ }+ ]++ async def search_by_tags_in_tenant(+ self,+ ctx,+ tags,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ levels=None,+ limit: int = 10,+ ):+ self.tag_search_calls.append(+ {+ "ctx": ctx,+ "tags": tags,+ "context_type": context_type,+ "target_directories": target_directories,+ "extra_filter": extra_filter,+ "levels": levels,+ "limit": limit,+ }+ )+ return [+ {+ "uri": "viking://resources/data-engineering/feature-store.md",+ "parent_uri": "viking://resources/data-engineering",+ "abstract": "Feature store guidance for model training",+ "level": 2,+ "context_type": "resource",+ "tags": ["auto:model-training", "auto:feature-store"],+ }+ ]++ async def search_children_in_tenant(+ self,+ ctx,+ parent_uri: str,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.child_search_calls.append(parent_uri)+ if parent_uri == "viking://resources/data-engineering":+ return [+ {+ "uri": "viking://resources/data-engineering/feature-store.md",+ "parent_uri": "viking://resources/data-engineering",+ "abstract": "Feature store guidance for model training",+ "_score": 0.95,+ "level": 2,+ "context_type": "resource",+ "tags": ["auto:model-training", "auto:feature-store"],+ }+ ]+ return []+++class ExplicitTagStorage(TagExpansionStorage):+ async def search_global_roots_in_tenant(+ self,+ ctx,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ tags=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.global_search_calls.append(+ {+ "ctx": ctx,+ "context_type": context_type,+ "target_directories": target_directories,+ "tags": tags,+ "extra_filter": extra_filter,+ "limit": limit,+ }+ )+ return []++ async def search_by_tags_in_tenant(+ self,+ ctx,+ tags,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ levels=None,+ limit: int = 10,+ ):+ self.tag_search_calls.append(+ {+ "ctx": ctx,+ "tags": tags,+ "context_type": context_type,+ "target_directories": target_directories,+ "extra_filter": extra_filter,+ "levels": levels,+ "limit": limit,+ }+ )+ return [+ {+ "uri": "viking://resources/architecture/microservices.md",+ "parent_uri": "viking://resources/architecture",+ "abstract": "Microservice architecture patterns",+ "level": 2,+ "context_type": "resource",+ "tags": ["auto:microservice"],+ }+ ]++ async def search_children_in_tenant(+ self,+ ctx,+ parent_uri: str,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.child_search_calls.append(parent_uri)+ if parent_uri == "viking://resources/architecture":+ return [+ {+ "uri": "viking://resources/architecture/microservices.md",+ "parent_uri": "viking://resources/architecture",+ "abstract": "Microservice architecture patterns",+ "_score": 0.88,+ "level": 2,+ "context_type": "resource",+ "tags": ["auto:microservice"],+ }+ ]+ return []+++def _ctx() -> RequestContext:+ return RequestContext(user=UserIdentifier("acc1", "user1", "agent1"), role=Role.ROOT)++[email protected](autouse=True)+def _disable_viking_fs(monkeypatch):+ monkeypatch.setattr("openviking.retrieve.hierarchical_retriever.get_viking_fs", lambda: None)+++async def test_retrieve_expands_related_subtree_from_global_hit_tags():+ storage = TagExpansionStorage()+ retriever = HierarchicalRetriever(storage=storage, embedder=DummyEmbedder(), rerank_config=None)++ result = await retriever.retrieve(+ TypedQuery(+ query="model training best practices",+ context_type=ContextType.RESOURCE,+ intent="",+ ),+ ctx=_ctx(),+ limit=3,+ )++ assert storage.tag_search_calls+ assert storage.tag_search_calls[0]["tags"] == ["auto:model-training"]+ assert "viking://resources/data-engineering" in storage.child_search_calls+ assert [ctx.uri for ctx in result.matched_contexts] == [+ "viking://resources/data-engineering/feature-store.md"+ ]+++async def test_retrieve_uses_explicit_tags_when_global_search_returns_nothing():+ storage = ExplicitTagStorage()+ retriever = HierarchicalRetriever(storage=storage, embedder=DummyEmbedder(), rerank_config=None)++ result = await retriever.retrieve(+ TypedQuery(+ query="architecture guidance",+ context_type=ContextType.RESOURCE,+ intent="",+ tags=["microservice"],+ ),+ ctx=_ctx(),+ limit=3,+ )++ assert storage.global_search_calls+ assert storage.global_search_calls[0]["tags"] == ["user:microservice", "auto:microservice"]+ assert storage.tag_search_calls+ assert storage.tag_search_calls[0]["tags"] == ["user:microservice", "auto:microservice"]+ assert [ctx.uri for ctx in result.matched_contexts] == [+ "viking://resources/architecture/microservices.md"+ ]diff --git a/tests/retrieve/test_hierarchical_retriever_target_dirs.py b/tests/retrieve/test_hierarchical_retriever_target_dirs.pyindex 6df26a238..ea2281d50 100644--- a/tests/retrieve/test_hierarchical_retriever_target_dirs.py+++ b/tests/retrieve/test_hierarchical_retriever_target_dirs.py@@ -29,6 +29,7 @@ class DummyStorage:sparse_query_vector=None,context_type=None,target_directories=None,+ tags=None,extra_filter=None,limit: int = 10,):@@ -39,6 +40,7 @@ class DummyStorage:"sparse_query_vector": sparse_query_vector,"context_type": context_type,"target_directories": target_directories,+ "tags": tags,"extra_filter": extra_filter,"limit": limit,}@@ -70,6 +72,18 @@ class DummyStorage:)return []+ async def search_by_tags_in_tenant(+ self,+ ctx,+ tags,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ levels=None,+ limit: int = 10,+ ):+ return []+@pytest.mark.asyncioasync def test_retrieve_honors_target_directories_scope_filter():diff --git a/tests/server/conftest.py b/tests/server/conftest.pyindex 577420d56..bdfddabd3 100644--- a/tests/server/conftest.py+++ b/tests/server/conftest.py@@ -3,12 +3,14 @@"""Shared fixtures for OpenViking server tests."""+import jsonimport shutilimport socketimport threadingimport timefrom pathlib import Pathfrom types import SimpleNamespace+from unittest.mock import patchimport httpximport pytest@@ -24,7 +26,9 @@ from openviking.service.core import OpenVikingServicefrom openviking.storage.transaction import reset_lock_managerfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.config.embedding_config import EmbeddingConfig+from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingletonfrom openviking_cli.utils.config.vlm_config import VLMConfig+from tests.utils.mock_agfs import MockLocalAGFS# ---------------------------------------------------------------------------# Paths@@ -84,6 +88,44 @@ def _install_fake_vlm(monkeypatch):monkeypatch.setattr(VLMConfig, "get_vision_completion_async", _fake_get_vision_completion)[email protected](scope="function")+def _configure_test_env(monkeypatch, tmp_path):+ """Provide an isolated local config for in-process server tests."""+ config_path = tmp_path / "ov.conf"+ config_path.write_text(+ json.dumps(+ {+ "storage": {+ "workspace": str(tmp_path / "workspace"),+ "agfs": {"backend": "local", "mode": "binding-client"},+ "vectordb": {"backend": "local"},+ },+ "embedding": {+ "dense": {+ "provider": "openai",+ "model": "test-embedder",+ "api_base": "http://127.0.0.1:11434/v1",+ "dimension": 2048,+ }+ },+ "encryption": {"enabled": False},+ "server": {"host": "127.0.0.1"},+ }+ ),+ encoding="utf-8",+ )++ mock_agfs = MockLocalAGFS(root_path=tmp_path / "mock_agfs_root")++ monkeypatch.setenv("OPENVIKING_CONFIG_FILE", str(config_path))+ OpenVikingConfigSingleton.reset_instance()++ with patch("openviking.utils.agfs_utils.create_agfs_client", return_value=mock_agfs):+ yield++ OpenVikingConfigSingleton.reset_instance()++# ---------------------------------------------------------------------------# Core fixtures: service + app + async client (HTTP API tests, in-process)# ---------------------------------------------------------------------------@@ -126,7 +168,7 @@ def upload_temp_dir(temp_dir: Path, monkeypatch) -> Path:@pytest_asyncio.fixture(scope="function")-async def service(temp_dir: Path, monkeypatch):+async def service(temp_dir: Path, monkeypatch, _configure_test_env):"""Create and initialize an OpenVikingService in embedded mode."""reset_lock_manager()fake_embedder_cls = _install_fake_embedder(monkeypatch)@@ -180,7 +222,7 @@ async def client_with_resource(client, service, sample_markdown_file):@pytest_asyncio.fixture(scope="function")-async def running_server(temp_dir: Path, monkeypatch):+async def running_server(temp_dir: Path, monkeypatch, _configure_test_env):"""Start a real uvicorn server in a background thread."""await AsyncOpenViking.reset()reset_lock_manager()diff --git a/tests/server/test_api_resources.py b/tests/server/test_api_resources.pyindex 2357fd5a4..f4ad0c456 100644--- a/tests/server/test_api_resources.py+++ b/tests/server/test_api_resources.py@@ -132,6 +132,39 @@ async def test_add_resource_with_telemetry_includes_resource_breakdown(}+async def test_add_resource_forwards_tags_to_service(+ client: httpx.AsyncClient,+ service,+ monkeypatch,+ upload_temp_dir,+):+ captured = {}++ async def fake_add_resource(**kwargs):+ captured.update(kwargs)+ return {+ "status": "success",+ "root_uri": "viking://resources/demo",+ }++ monkeypatch.setattr(service.resources, "add_resource", fake_add_resource)++ demo_file = upload_temp_dir / "demo.md"+ demo_file.write_text("# demo\n")++ resp = await client.post(+ "/api/v1/resources",+ json={+ "temp_file_id": demo_file.name,+ "reason": "tagged resource",+ "tags": "auto:machine-learning;feature-store",+ },+ )++ assert resp.status_code == 200+ assert captured["tags"] == ["user:machine-learning", "user:feature-store"]++async def test_add_resource_with_summary_only_telemetry(client: httpx.AsyncClient,sample_markdown_file,diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.pyindex 07a2922ab..2969d989a 100644--- a/tests/server/test_api_search.py+++ b/tests/server/test_api_search.py@@ -65,6 +65,63 @@ async def test_find_no_results(client: httpx.AsyncClient):assert resp.json()["status"] == "ok"+async def test_find_forwards_tags_to_service(client_with_resource, service, monkeypatch):+ client, _ = client_with_resource+ captured = {}++ async def fake_find(**kwargs):+ captured.update(kwargs)++ class _Result:+ def to_dict(self, include_provenance: bool = False):+ return {"resources": [], "memories": [], "skills": []}++ return _Result()++ monkeypatch.setattr(service.search, "find", fake_find)++ resp = await client.post(+ "/api/v1/search/find",+ json={"query": "sample", "tags": "machine-learning;feature-store"},+ )++ assert resp.status_code == 200+ assert captured["tags"] == [+ "user:machine-learning",+ "auto:machine-learning",+ "user:feature-store",+ "auto:feature-store",+ ]+++async def test_search_forwards_tags_to_service(client, service, monkeypatch):+ captured = {}++ async def fake_search(**kwargs):+ captured.update(kwargs)++ class _Result:+ def to_dict(self, include_provenance: bool = False):+ return {"resources": [], "memories": [], "skills": []}++ return _Result()++ monkeypatch.setattr(service.search, "search", fake_search)++ resp = await client.post(+ "/api/v1/search/search",+ json={"query": "sample", "tags": "machine-learning;feature-store"},+ )++ assert resp.status_code == 200+ assert captured["tags"] == [+ "user:machine-learning",+ "auto:machine-learning",+ "user:feature-store",+ "auto:feature-store",+ ]++async def test_search_basic(client_with_resource):client, uri = client_with_resourceresp = await client.post(diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.pyindex 5be9a387e..d14a1fe0a 100644--- a/tests/unit/test_vectorize_file_strategy.py+++ b/tests/unit/test_vectorize_file_strategy.py@@ -107,3 +107,37 @@ async def test_vectorize_file_truncates_content_when_content_only(monkeypatch):text = queue.items[0].get_vectorization_text()assert text.startswith("A" * 1000)assert text.endswith("...(truncated for embedding)")+++async def test_vectorize_file_forces_summary_tags_into_auto_namespace(monkeypatch):+ queue = DummyQueue()+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("content"))+ monkeypatch.setattr(+ embedding_utils,+ "get_openviking_config",+ lambda: types.SimpleNamespace(+ embedding=types.SimpleNamespace(text_source="summary_first", max_input_chars=1000)+ ),+ )+ monkeypatch.setattr(+ embedding_utils.EmbeddingMsgConverter,+ "from_context",+ lambda context: context,+ )++ await embedding_utils.vectorize_file(+ file_path="viking://user/default/resources/ml-notes.md",+ summary_dict={+ "name": "ml-notes.md",+ "summary": "short summary",+ "tags": "user:model-training;pytorch",+ },+ parent_uri="viking://user/default/resources",+ ctx=DummyReq(),+ )++ assert len(queue.items) == 1+ assert "auto:model-training" in queue.items[0].tags+ assert "user:model-training" not in queue.items[0].tagsdiff --git a/tests/utils/test_tag_utils.py b/tests/utils/test_tag_utils.pynew file mode 100644index 000000000..d8ae5ec34--- /dev/null+++ b/tests/utils/test_tag_utils.py@@ -0,0 +1,77 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""Tests for tag normalization and namespace expansion helpers."""++from openviking.utils.tag_utils import (+ AUTO_TAG_NAMESPACE,+ USER_TAG_NAMESPACE,+ canonicalize_user_tags,+ expand_query_tags,+ extract_context_tags,+ namespace_tags,+ parse_tags,+ serialize_tags,+)+++def test_parse_tags_preserves_explicit_namespace():+ assert parse_tags("user:machine-learning;auto:pytorch") == [+ "user:machine-learning",+ "auto:pytorch",+ ]+++def test_canonicalize_user_tags_adds_default_namespace():+ assert canonicalize_user_tags("machine-learning;feature-store") == [+ "user:machine-learning",+ "user:feature-store",+ ]+++def test_canonicalize_user_tags_rewrites_explicit_auto_namespace():+ assert canonicalize_user_tags("auto:pytorch;feature-store") == [+ "user:pytorch",+ "user:feature-store",+ ]+++def test_expand_query_tags_matches_both_known_namespaces_for_bare_input():+ assert expand_query_tags("machine-learning") == [+ "user:machine-learning",+ "auto:machine-learning",+ ]+++def test_expand_query_tags_preserves_namespaced_input():+ assert expand_query_tags("auto:pytorch;user:model-training") == [+ "auto:pytorch",+ "user:model-training",+ ]+++def test_extract_context_tags_namespaces_auto_generated_terms():+ tags = extract_context_tags(+ "viking://resources/ml/feature-store.md",+ texts=["Feature store guidance for model training systems."],+ inherited_tags=["user:retrieval"],+ )+ assert "user:retrieval" in tags+ assert any(tag.startswith(f"{AUTO_TAG_NAMESPACE}:") for tag in tags if tag != "user:retrieval")+++def test_namespace_tags_overrides_existing_prefix():+ assert namespace_tags("user:feature-store;model-training", AUTO_TAG_NAMESPACE) == [+ "auto:feature-store",+ "auto:model-training",+ ]+++def test_serialize_tags_preserves_namespaces():+ assert (+ serialize_tags(+ ["user:machine-learning", "auto:feature-store"],+ default_namespace=USER_TAG_NAMESPACE,+ )+ == "user:machine-learning;auto:feature-store"+ )