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
"""Protocol types for synchronous AGFS-like clients."""
from __future__ import annotations
from collections.abc import Iterator
from typing import Any, Awaitable, BinaryIO, Dict, Literal, Protocol, overload, runtime_checkable
AGFSByteStream = Iterator[bytes]
@runtime_checkable
class AGFSSyncClientProtocol(Protocol):
"""AGFS binding contract used by OpenViking."""
def ls(
self,
path: str = "/",
ctx: Dict[str, str] | None = None,
*,
offset: int = 0,
limit: int | None = None,
sort_by: str | None = None,
sort_order: str = "asc",
) -> list[Dict[str, Any]]:
"""List a sorted directory range."""
@overload
def read(
self,
path: str,
offset: int = 0,
size: int = -1,
stream: Literal[False] = False,
) -> bytes:
"""Read file content from AGFS."""
@overload
def read(
self,
path: str,
offset: int = 0,
size: int = -1,
stream: Literal[True] = True,
) -> AGFSByteStream:
"""Read file content from AGFS."""
@overload
def cat(
self,
path: str,
offset: int = 0,
size: int = -1,
stream: Literal[False] = False,
) -> bytes:
"""Read file content from AGFS."""
@overload
def cat(
self,
path: str,
offset: int = 0,
size: int = -1,
stream: Literal[True] = True,
) -> AGFSByteStream:
"""Read file content or a byte stream from AGFS."""
def write(
self,
path: str,
data: bytes | Iterator[bytes] | BinaryIO,
max_retries: int = 3,
) -> str:
"""Write file content to AGFS and return the backend result."""
def mkdir(self, path: str, mode: str = "755") -> Dict[str, Any]:
"""Create a directory in AGFS."""
def ensure_parent_dirs(self, path: str, mode: str = "755") -> Dict[str, Any]:
"""Ensure parent directories exist for the given AGFS path."""
def rm(self, path: str, recursive: bool = False, force: bool = True) -> Dict[str, Any]:
"""Remove a file or directory from AGFS."""
def stat(self, path: str) -> Dict[str, Any]:
"""Return AGFS metadata for the given path."""
def mv(self, old_path: str, new_path: str) -> Dict[str, Any]:
"""Move or rename a path inside AGFS."""
def copy_within_mount(self, src_path: str, dst_path: str) -> Dict[str, Any]:
"""Attempt a same-mount verbatim copy and report whether it was used."""
def grep(self, **kwargs: Any) -> Dict[str, Any]:
"""Run a grep-like search through the AGFS backend."""
def tree_directory(
self,
path: str,
show_hidden: bool = False,
node_limit: int | None = None,
level_limit: int | None = None,
ctx: Dict[str, str] | None = None,
*,
offset: int = 0,
sort_by: str | None = None,
sort_order: str = "asc",
directories_only: bool = False,
) -> list[Dict[str, Any]]:
"""Return a sorted range from a directory tree."""
def glob_directory(
self,
path: str,
pattern: str,
show_hidden: bool = False,
page_size: int | None = None,
level_limit: int | None = None,
continuation_token: str | None = None,
) -> Dict[str, Any]:
"""Return one page of flat glob matches for the given AGFS directory."""
def pathlock_acquire_batch_async(
self,
ctx: Dict[str, str],
requests: list[Dict[str, str]],
timeout_secs: float = 0.0,
owner_lease_ref: Dict[str, Any] | None = None,
) -> Awaitable[Dict[str, Any]]:
"""Acquire a PathLock batch without blocking a Python worker thread."""
def leader_try_acquire_async(
self, key: str, holder_id: str, ttl_secs: float
) -> Awaitable[str | None]:
"""Try to acquire leadership and return an opaque lease reference."""
def leader_validate(self) -> None:
"""Validate that distributed leadership is available."""
def leader_renew_async(self, lease_ref: str, ttl_secs: float) -> Awaitable[bool]:
"""Renew leadership while its hidden ownership token still matches."""
def leader_release_async(self, lease_ref: str) -> Awaitable[None]:
"""Release leadership while its hidden ownership token still matches."""