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
"""Namespace helpers for account/user/session URIs."""
from __future__ import annotations
from dataclasses import dataclass
from typing import Optional
from openviking.core.identifiers import validate_user_id
from openviking.core.peer_id import normalize_peer_id
from openviking.server.identity import RequestContext, Role
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.uri import VikingURI
_CONTENT_TYPES_BY_SCOPE = {
"user": {"memories": "memory", "resources": "resource", "skills": "skill"},
"agent": {"skills": "skill"},
"system": {"example-skills": "skill"},
}
_PEER_CONTENT_SEGMENTS = frozenset({"memories", "resources"})
_USER_RELATIVE_ROOT_SEGMENTS = frozenset({"peers", "privacy", "sessions"})
_CONTENT_SEGMENT_BY_KIND = {"resource": "resources", "skill": "skills"}
class NamespaceShapeError(ValueError):
"""Raised when a URI does not match the supported namespace shape."""
@dataclass(frozen=True)
class ResolvedNamespace:
"""Namespace information parsed from a canonical URI."""
uri: str
scope: str
owner_user_id: Optional[str] = None
is_container: bool = False
@dataclass(frozen=True)
class UriClassification:
"""Viking URI classification derived from path structure."""
parts: tuple[str, ...]
scope: str
content_index: Optional[int]
context_type: str
@property
def is_memory(self) -> bool:
return self.context_type == "memory"
@property
def is_skill(self) -> bool:
return self.context_type == "skill"
@property
def is_system(self) -> bool:
return self.scope == "system"
@property
def is_user_namespace_root(self) -> bool:
return _is_namespace_root_parts(self.parts, "user")
@property
def is_memory_root(self) -> bool:
return (
self.is_memory
and self.content_index is not None
and len(self.parts) == self.content_index + 1
)
@property
def is_skill_namespace(self) -> bool:
return (
self.is_skill
and self.content_index is not None
and len(self.parts) == self.content_index + 1
)
@property
def is_skill_root(self) -> bool:
return (
self.is_skill
and self.content_index is not None
and len(self.parts) == self.content_index + 2
)
def uri_parts(uri: str) -> list[str]:
"""Return canonical Viking URI path segments without query parameters."""
normalized = uri.split("?", 1)[0]
if not normalized.startswith("viking://"):
raise ValueError("URI must start with 'viking://'")
if normalized == "viking://":
return []
normalized = normalized.rstrip("/")
return [part for part in normalized[len("viking://") :].split("/") if part]
def uri_depth(uri: str) -> int:
"""Return the number of normalized Viking URI path segments."""
return len(uri_parts(uri))
def uri_leaf_name(uri: str) -> str:
"""Return the final normalized Viking URI path segment."""
parts = uri_parts(uri)
return parts[-1] if parts else ""
def relative_uri_path(root_uri: str, uri: str) -> str:
"""Return uri's slash-separated path relative to root_uri, or empty when not nested."""
root_parts = uri_parts(root_uri)
parts = uri_parts(uri)
if parts == root_parts or parts[: len(root_parts)] != root_parts:
return ""
return "/".join(parts[len(root_parts) :])
def _content_segment_index(parts: tuple[str, ...]) -> Optional[int]:
"""Return the content segment for a supported namespace shape."""
if len(parts) >= 2 and parts[:2] == ("agent", "skills"):
return 1
if len(parts) >= 3 and parts[:3] == ("system", "compile", "example-skills"):
return 2
if len(parts) < 2 or parts[0] != "user":
return None
if len(parts) >= 5 and parts[2] == "peers" and parts[4] in _PEER_CONTENT_SEGMENTS:
return 4
if len(parts) >= 3 and parts[2] in _CONTENT_TYPES_BY_SCOPE["user"]:
return 2
return None
def _is_namespace_root_parts(parts: tuple[str, ...], scope: str) -> bool:
return scope == "user" and parts[:1] == ("user",) and len(parts) == 2
def classify_uri(uri: str) -> UriClassification:
parts = tuple(uri_parts(uri))
content_index = _content_segment_index(parts)
context_type = "resource"
if content_index is not None:
context_type = _CONTENT_TYPES_BY_SCOPE.get(parts[0], {}).get(
parts[content_index], "resource"
)
return UriClassification(
parts=parts,
scope=parts[0] if parts else "",
content_index=content_index,
context_type=context_type,
)
def context_type_for_uri(uri: str) -> str:
return classify_uri(uri).context_type
def canonical_user_root(ctx: RequestContext) -> str:
return f"viking://user/{user_space_fragment(ctx)}"
def user_space_fragment(ctx: RequestContext) -> str:
return ctx.user.user_id
def canonical_session_root(ctx: RequestContext) -> str:
return f"{canonical_user_root(ctx)}/sessions"
def canonical_session_uri(ctx: RequestContext, session_id: Optional[str] = None) -> str:
root = canonical_session_root(ctx)
if not session_id:
return root
return f"{root}/{session_id}"
def is_session_uri(uri: str) -> bool:
parts = uri_parts(uri)
return len(parts) >= 3 and parts[0] == "user" and parts[2] == "sessions"
AGENT_SKILLS_ROOT = "viking://agent/skills"
def visible_roots(ctx: RequestContext) -> list[str]:
return [
"viking://resources",
"viking://agent",
canonical_user_root(ctx),
]
def is_hidden_by_actor_peer_view(uri: str, ctx: RequestContext) -> bool:
"""Return whether uri points to another peer hidden by the actor peer view."""
suffix = _actor_peer_view_user_suffix(uri, ctx)
return bool(
suffix and len(suffix) >= 2 and suffix[0] == "peers" and suffix[1] != ctx.actor_peer_id
)
def may_include_hidden_actor_peers(uri: str, ctx: RequestContext) -> bool:
"""Return whether recursive data under uri may include hidden peers."""
suffix = _actor_peer_view_user_suffix(uri, ctx)
return suffix is not None and (not suffix or suffix == ["peers"])
def _actor_peer_view_user_suffix(uri: str, ctx: RequestContext) -> Optional[list[str]]:
"""Return uri's suffix under the current user root when actor peer view is active.
The actor peer view filters only the current user's ``peers`` collection.
It applies to filesystem and retrieval views, but does not change
tenant/user identity or hide non-peer user content.
"""
if not ctx.actor_peer_id:
return None
try:
resolve_uri(uri)
except NamespaceShapeError:
return None
parts = uri_parts(uri)
user_root_parts = ["user", ctx.user.user_id]
if parts[: len(user_root_parts)] != user_root_parts:
return None
return parts[len(user_root_parts) :]
def resolve_uri(
uri: str,
) -> ResolvedNamespace:
"""Parse a canonical URI into its namespace and owner tuple."""
parsed = VikingURI(uri)
canonical_uri = parsed.uri.rstrip("/") or "viking://"
parts = uri_parts(uri)
if not parts:
return ResolvedNamespace(uri="viking://", scope="", is_container=True)
scope = parts[0]
if scope == "user":
return _resolve_user_uri(parts)
if scope == "agent":
return ResolvedNamespace(uri=canonical_uri, scope=scope)
if scope == "~":
# The home alias is expanded at the request boundary only. Reaching the
# canonical parser with it (internal callers or storage paths) means no
# identity is available, so fail closed instead of creating a literal
# '~' namespace.
raise NamespaceShapeError(f"Home alias URI is not canonical: {'/'.join(parts)}")
if scope == "session":
raise NamespaceShapeError(f"Legacy session URI is not canonical: {'/'.join(parts)}")
if scope in {"resources", "temp", "queue", "upload"}:
return ResolvedNamespace(uri=canonical_uri, scope=scope)
return ResolvedNamespace(uri=canonical_uri, scope=scope)
def resolve_request_uri(uri: str, ctx: RequestContext) -> str:
"""Resolve supported URI aliases at an authenticated request boundary.
The ``~`` home alias resolves to the authenticated user's namespace.
The uid-less ``viking://user/<reserved>`` shorthand is no longer expanded:
it fails closed with a hint pointing at ``viking://~/...``.
"""
# Every authenticated request context carries an effective user identity,
# including ROOT contexts produced by dev, API-key, and trusted auth modes.
# Resolve the home alias for every role; keep the role-dependent handling
# of ambiguous uid-less user paths below.
parts = uri_parts(uri)
if parts and parts[0] == "~":
return resolve_current_user_uri(uri, ctx)
if ctx.role in {Role.USER, Role.ADMIN}:
return resolve_current_user_uri(uri, ctx)
return resolve_uri(uri).uri
def resolve_current_user_uri(uri: str, ctx: RequestContext) -> str:
"""Resolve a URI field whose contract explicitly denotes the current user.
The supported alias is ``viking://~``. ``viking://user/<reserved-segment>`` used to
expand to the caller's space; it now fails closed with a corrective hint,
because the same spelling is a valid explicit-uid URI for a user literally
named after the reserved segment.
"""
parts = uri_parts(uri)
if not parts:
return "viking://"
if parts[0] == "~":
if len(parts) == 1:
return canonical_user_root(ctx)
return f"{canonical_user_root(ctx)}/{'/'.join(parts[1:])}"
if (
parts[0] == "user"
and len(parts) >= 2
# Self-id escape: a caller literally named e.g. "resources" keeps
# viking://user/resources as their canonical root.
and parts[1] != ctx.user.user_id
and _is_reserved_user_root_segment(parts[1])
):
rest = "/".join(parts[1:])
raise NamespaceShapeError(
f"'viking://user/{rest}' no longer expands to the current user's space: "
f"'{parts[1]}' is a reserved name, not a user id. Use 'viking://~/{rest}' "
f"for the current user, or 'viking://user/{{user_id}}/{rest}' for an "
f"explicit user."
)
# Bare 'viking://user' and explicit-uid forms fall through to the canonical
# parser; the bare form keeps container semantics (is_container=True).
return resolve_uri(uri).uri
def is_accessible(uri: str, ctx: RequestContext) -> bool:
if getattr(ctx.role, "value", ctx.role) == "root":
return True
try:
target = resolve_uri(uri)
except NamespaceShapeError:
return False
if target.scope in {"", "resources", "agent", "temp", "queue"}:
return True
if target.scope == "upload":
return False
if target.scope == "user":
if target.owner_user_id and target.owner_user_id != ctx.user.user_id:
return False
return True
return True
def is_content_root_uri(
uri: str,
*,
kind: str,
) -> bool:
try:
resolve_uri(uri)
except (ValueError, NamespaceShapeError):
return False
parts = uri_parts(uri)
if kind == "resource" and parts == ["resources"]:
return True
classification = classify_uri(uri)
return (
classification.context_type == kind
and classification.content_index is not None
and len(parts) == classification.content_index + 1
)
def _validate_peer_id_segments(parts: list[str]) -> None:
if len(parts) >= 4 and parts[0] == "user" and parts[2] == "peers":
_require_peer_id_segment(parts[3])
def _require_peer_id_segment(peer_id: str) -> None:
try:
if normalize_peer_id(peer_id) is None:
raise ValueError("peer_id must not be empty")
except ValueError as exc:
raise NamespaceShapeError(str(exc)) from exc
def owner_fields_for_uri(
uri: str,
) -> dict:
try:
resolved = resolve_uri(uri)
except (ValueError, NamespaceShapeError):
return {
"uri": uri.rstrip("/"),
"owner_user_id": None,
}
return {
"uri": resolved.uri,
"owner_user_id": resolved.owner_user_id,
}
def content_owner_context_for_uri(uri: str, ctx: RequestContext) -> RequestContext:
"""Use the canonical URI owner for content writes performed with caller authority."""
owner_user_id = owner_fields_for_uri(uri).get("owner_user_id")
if not owner_user_id or owner_user_id == ctx.user.user_id:
return ctx
return RequestContext(
user=UserIdentifier(ctx.account_id, owner_user_id),
role=ctx.role,
group_ids=ctx.group_ids,
actor_peer_id=ctx.actor_peer_id,
from_oauth=ctx.from_oauth,
api_key=ctx.api_key,
bypass_acl=ctx.bypass_acl,
)
def owner_space_for_uri(uri: str) -> str:
"""Derive the legacy owner_space bucket from the canonical URI owner."""
resolved = resolve_uri(uri)
if resolved.scope == "user" and resolved.owner_user_id:
return resolved.owner_user_id
return ""
def _resolve_user_uri(
parts: list[str],
) -> ResolvedNamespace:
if len(parts) == 1:
return ResolvedNamespace(uri="viking://user", scope="user", is_container=True)
second = parts[1]
user_id = second
validation_error = validate_user_id(user_id)
if validation_error:
raise NamespaceShapeError(f"Invalid user_id: {validation_error}")
if len(parts) == 2:
return ResolvedNamespace(
uri=f"viking://user/{user_id}",
scope="user",
owner_user_id=user_id,
)
suffix = parts[2:]
canonical = f"viking://user/{user_id}"
if suffix:
canonical = f"{canonical}/{'/'.join(suffix)}"
_validate_peer_id_segments(parts)
return ResolvedNamespace(
uri=canonical,
scope="user",
owner_user_id=user_id,
)
def _is_reserved_user_root_segment(segment: str) -> bool:
"""Return whether a first-level user segment is a reserved space name.
Reserved names (``memories``, ``resources``, ``skills``, ``peers``,
``privacy``, ``sessions``) are rejected at request boundaries when they
appear without an explicit user id, because they are ambiguous with a user
literally named after them.
"""
return segment in _CONTENT_TYPES_BY_SCOPE["user"] or segment in _USER_RELATIVE_ROOT_SEGMENTS