Class VikingURI

openviking_cli/utils/uri.py:14–322

Viking URI handler. URI Format: viking:// / Scopes: - resources: Independent resource scope (viking://resources/{project}/...) - user: User scope (viking://user/...), including sessions under viking://user/{user_id}/sessions/{session_id} - session: Legacy

class VikingURI:
    """
    Viking URI handler.

    URI Format: viking://<scope>/<path>

    Scopes:
    - resources: Independent resource scope (viking://resources/{project}/...)
    - user: User scope (viking://user/...), including sessions under
      viking://user/{user_id}/sessions/{session_id}
    - session: Legacy alias for user sessions (viking://session/{session_id}/...)
    - agent: Agent capabilities scope (viking://agent/skills/..., viking://agent/endpoints/...)
    - queue: Queue scope (viking://queue/...)

    Examples:
    - viking://resources/my_project/docs/api
    - viking://user/memories/preferences/code_style
    - viking://user/skills/pdf
    - viking://user/alice/sessions/session123/messages.jsonl
    """

    SCHEME = "viking"
    # SCOPES that can be listed in root directory (ov ls)
    LISTABLE_SCOPES = {
        "resources",
        "user",
        "agent",
    }
    PUBLIC_SCOPES = frozenset(LISTABLE_SCOPES)
    LEGACY_SCOPES = frozenset({"session"})
    INTERNAL_SCOPES = frozenset({"temp", "queue", "upload"})
    # All valid scopes that can be addressed by the URI parser/storage internals.
    # Public API handlers must not use this as their external whitelist.
    VISITABLE_SCOPES = PUBLIC_SCOPES | LEGACY_SCOPES | INTERNAL_SCOPES

    def __init__(self, uri: str):
        """
        Initialize URI handler.

        Accepts both full-format (viking://...) and short-format (/resources, resources)
        URIs. Short-format URIs are automatically normalized to full format.

        Args:
            uri: URI string (full or short format)
        """
        self.uri = self.normalize(uri)
        self._parsed = self._parse()

    def _parse(self) -> Dict[str, str]:
        """
        Parse Viking URI into components.

        Returns:
            Dictionary with URI components
        """
        if not self.uri.startswith(f"{self.SCHEME}://"):
            raise ValueError(f"URI must start with '{self.SCHEME}://'")