Skip to content

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

feat(retrieve): use tags metadata for cross-subtree retrieval (#1162)

13ernkastele72b614b3db2
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 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.py
index 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_tags
from openviking_cli.client.base import BaseClient
from openviking_cli.session.user_id import UserIdentifier
from 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.py
index 55bce1c47..58d0d43f2 100644
--- a/openviking/core/context.py
+++ b/openviking/core/context.py
@@ -7,6 +7,7 @@ from enum import Enum
from typing import Any, Dict, List, Optional
from uuid import uuid4
+from openviking.utils.tag_utils import parse_tags
from openviking.utils.time_utils import format_iso8601, parse_iso_datetime
from openviking_cli.session.user_id import UserIdentifier
from 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_count
self.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 None
except (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 None
diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.py
index 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, Role
from openviking.storage import VikingDBManager, VikingDBManagerProxy
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import get_current_telemetry
+from openviking.utils.tag_utils import expand_query_tags, merge_tags, parse_tags
from openviking.utils.time_utils import parse_iso_datetime
from openviking_cli.retrieve.types import (
ContextType,
@@ -50,6 +51,9 @@ class HierarchicalRetriever:
DIRECTORY_DOMINANCE_RATIO = 1.2 # Directory score must exceed max child score
GLOBAL_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 points
starting_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 search
candidates = 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.py
index 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 Response
from openviking.server.telemetry import run_operation
from openviking.telemetry import TelemetryRequest
+from openviking.utils.tag_utils import canonicalize_user_tags
from openviking_cli.exceptions import InvalidArgumentError
from 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 be
automatically re-processed at the specified interval.
@@ -80,6 +82,7 @@ class AddResourceRequest(BaseModel):
exclude: Optional[str] = None
directly_upload_media: bool = True
preserve_structure: Optional[bool] = None
+ tags: Optional[str] = None
telemetry: TelemetryRequest = False
watch_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.py
index a0aa97dbf..3b2b11f2c 100644
--- a/openviking/server/routers/search.py
+++ b/openviking/server/routers/search.py
@@ -14,6 +14,7 @@ from openviking.server.identity import RequestContext
from openviking.server.models import Response
from openviking.server.telemetry import run_operation
from openviking.telemetry import TelemetryRequest
+from openviking.utils.tag_utils import expand_query_tags
def _sanitize_floats(obj: Any) -> Any:
@@ -40,6 +41,7 @@ class FindRequest(BaseModel):
limit: int = 10
node_limit: Optional[int] = None
score_threshold: Optional[float] = None
+ tags: Optional[str] = None
filter: Optional[Dict[str, Any]] = None
include_provenance: bool = False
telemetry: TelemetryRequest = False
@@ -54,6 +56,7 @@ class SearchRequest(BaseModel):
limit: int = 10
node_limit: Optional[int] = None
score_threshold: Optional[float] = None
+ tags: Optional[str] = None
filter: Optional[Dict[str, Any]] = None
include_provenance: bool = False
telemetry: 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.py
index 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 ResourceProcessor
from openviking.utils.skill_processor import SkillProcessor
+from openviking.utils.tag_utils import canonicalize_user_tags
from 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"] = tags
await self._handle_watch_task_creation(
path=path,
to_uri=to,
diff --git a/openviking/service/search_service.py b/openviking/service/search_service.py
index 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, Optional
from openviking.server.identity import RequestContext
from openviking.storage.viking_fs import VikingFS
+from openviking.utils.tag_utils import expand_query_tags
from openviking_cli.exceptions import NotInitializedError
from 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 = None
if 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 result
diff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.py
index 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]] = None
parent_uri: Optional[str] = None
use_summary: bool = False
+ tags: Optional[List[str]] = None
# For directory tasks
abstract: Optional[str] = None
overview: 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 = processor
self._context_type = context_type
@@ -89,6 +91,7 @@ class SemanticDagExecutor:
self._recursive = recursive
self._lifecycle_lock_handle_id = lifecycle_lock_handle_id
self._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.py
index ba27d841a..a54bbd471 100644
--- a/openviking/storage/queuefs/semantic_msg.py
+++ b/openviking/storage/queuefs/semantic_msg.py
@@ -8,6 +8,8 @@ from datetime import datetime
from typing import Any, Dict, List, Optional
from uuid import uuid4
+from openviking.utils.tag_utils import parse_tags
+
@dataclass
class SemanticMsg:
@@ -41,6 +43,7 @@ class SemanticMsg:
target_uri: str = ""
lifecycle_lock_handle_id: str = ""
is_code_repo: bool = False
+ tags: List[str] = None
changes: 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_uri
self.lifecycle_lock_handle_id = lifecycle_lock_handle_id
self.is_code_repo = is_code_repo
+ self.tags = parse_tags(tags)
self.changes = changes
def 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.py
index 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 = executor
if 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.py
index 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_directories
if 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.py
index 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)
+
@staticmethod
def _tenant_filter(
ctx: RequestContext, context_type: Optional[str] = None
diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.py
index 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.py
index 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, Union
if 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.py
index cf442cc0a..b78274567 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -15,6 +15,12 @@ from openviking.server.identity import RequestContext
from openviking.storage.queuefs import get_queue_manager
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
from openviking.storage.viking_fs import 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_logger
from 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.uri
owner_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 Files
try:
@@ -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.py
index 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.py
index d67a4b545..2433be3e5 100644
--- a/openviking/utils/summarizer.py
+++ b/openviking/utils/summarizer.py
@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any, Dict, List
from openviking.core.directories import get_context_type_for_uri
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
from openviking.telemetry import get_current_telemetry
+from openviking.utils.tag_utils import parse_tags
from openviking_cli.utils import get_logger
if TYPE_CHECKING:
@@ -56,7 +57,7 @@ class Summarizer:
enqueued_count = 0
telemetry = 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 URI
context_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 += 1
diff --git a/openviking/utils/tag_utils.py b/openviking/utils/tag_utils.py
new file mode 100644
index 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.py
index 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.py
index 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, Union
import httpx
from openviking.telemetry import TelemetryRequest, normalize_telemetry_request
+from openviking.utils.tag_utils import serialize_tags
from openviking_cli.client.base import BaseClient
from 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.py
index 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.py
index b3540011f..5b6d90e67 100644
--- a/openviking_cli/retrieve/types.py
+++ b/openviking_cli/retrieve/types.py
@@ -244,6 +244,7 @@ class TypedQuery:
intent: Query intent description
priority: 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: str
priority: int = 3
target_directories: List[str] = field(default_factory=list)
+ tags: List[str] = field(default_factory=list)
@dataclass
diff --git a/tests/client/test_search.py b/tests/client/test_search.py
index 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 SyncHTTPClient
class 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.py
index 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.py
new file mode 100644
index 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.py
index 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.asyncio
async def test_retrieve_honors_target_directories_scope_filter():
diff --git a/tests/server/conftest.py b/tests/server/conftest.py
index 577420d56..bdfddabd3 100644
--- a/tests/server/conftest.py
+++ b/tests/server/conftest.py
@@ -3,12 +3,14 @@
"""Shared fixtures for OpenViking server tests."""
+import json
import shutil
import socket
import threading
import time
from pathlib import Path
from types import SimpleNamespace
+from unittest.mock import patch
import httpx
import pytest
@@ -24,7 +26,9 @@ from openviking.service.core import OpenVikingService
from openviking.storage.transaction import reset_lock_manager
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.config.embedding_config import EmbeddingConfig
+from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton
from 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.py
index 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.py
index 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_resource
resp = await client.post(
diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.py
index 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].tags
diff --git a/tests/utils/test_tag_utils.py b/tests/utils/test_tag_utils.py
new file mode 100644
index 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"
+ )