Skip to content

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

7.6 KB
Raw Blame
"""AGFS Python SDK - Client library for AGFS Server API"""

__version__ = "0.1.7"

import glob
import importlib.util
import logging
import os
import sys
import sysconfig
from pathlib import Path

from .async_client import AsyncAGFSClient
from .exceptions import (
    AGFSAlreadyExistsError,
    AGFSClientError,
    AGFSConfigError,
    AGFSConnectionError,
    AGFSDirectoryNotEmptyError,
    AGFSFileExistsError,
    AGFSHTTPError,
    AGFSInternalError,
    AGFSInvalidOperationError,
    AGFSInvalidPathError,
    AGFSIoError,
    AGFSIsADirectoryError,
    AGFSMountPointExistsError,
    AGFSMountPointNotFoundError,
    AGFSNetworkError,
    AGFSNotADirectoryError,
    AGFSNotFoundError,
    AGFSNotSupportedError,
    AGFSPathNotFoundError,
    AGFSPermissionDeniedError,
    AGFSPluginError,
    AGFSResourceExhaustedError,
    AGFSSerializationError,
    AGFSTimeoutError,
    GitConcurrentCommitError,
    GitRestoreWritebackPartialError,
)
from .helpers import cp, download, upload
from .leader import LeaderCandidate, Leadership
from .protocols import AGFSSyncClientProtocol

_logger = logging.getLogger(__name__)

# Directory that ships pre-built native libraries (Rust .so/.dylib).
_LIB_DIR = Path(__file__).resolve().parent.parent / "lib"


def _is_compatible_ragfs_extension(path: str, ext_suffix: str) -> bool:
    """Return whether a vendored ragfs_python extension can be loaded here."""
    name = Path(path).name
    if not name.startswith("ragfs_python"):
        return False

    # CPython-specific extensions are only safe for the exact running
    # interpreter ABI tag. Reject both Unix-style `.cpython-312-...` and
    # Windows-style `.cp312-...` artifacts unless they exactly match
    # the active EXT_SUFFIX.
    if name.startswith("ragfs_python.cp") and not name.startswith("ragfs_python.abi3."):
        return name == f"ragfs_python{ext_suffix}"

    # Stable ABI artifacts are intentionally interpreter-independent.
    if name.startswith("ragfs_python.abi3."):
        return True

    # Keep accepting generic platform extensions when projects ship them.
    return name.endswith((".so", ".dylib", ".pyd"))


def _find_ragfs_so():
    """Locate the ragfs_python native extension inside openviking/lib/.

    Returns the path to the ``.so`` / ``.dylib`` / ``.pyd`` file, or *None*.
    """
    try:
        ext_suffix = sysconfig.get_config_var("EXT_SUFFIX") or ".so"
        # Exact match first: ragfs_python.cpython-312-darwin.so or ragfs_python.abi3.so
        exact = _LIB_DIR / f"ragfs_python{ext_suffix}"
        if exact.exists():
            return str(exact)
        # Try abi3 suffix explicitly first (stable ABI)
        abi3_suffix = ".abi3.so"
        if sys.platform == "win32":
            abi3_suffix = ".abi3.pyd"
        abi3_exact = _LIB_DIR / f"ragfs_python{abi3_suffix}"
        if abi3_exact.exists():
            return str(abi3_exact)
        # Glob fallback: keep stable/generic artifacts, but never load a
        # CPython-version-specific binary whose tag differs from EXT_SUFFIX.
        for pattern in ("ragfs_python.cpython-*", "ragfs_python.abi3.*", "ragfs_python.*"):
            for match in sorted(glob.glob(str(_LIB_DIR / pattern))):
                if _is_compatible_ragfs_extension(match, ext_suffix):
                    return match
    except Exception:
        pass
    return None


def _load_rust_module():
    """Load the complete Rust PyO3 module from the installed or vendored artifact.

    Prefers the pip-installed ``ragfs_python`` package (e.g. from maturin develop),
    then falls back to the vendored native extension in openviking/lib/.
    """
    try:
        import ragfs_python as rust_module

        return rust_module
    except ImportError:
        pass

    # Fallback: vendored .so in openviking/lib/
    try:
        so_path = _find_ragfs_so()
        if so_path:
            spec = importlib.util.spec_from_file_location("ragfs_python", so_path)
            if spec is None or spec.loader is None:
                raise ImportError(f"Unable to load Rust binding spec from {so_path}")
            mod = importlib.util.module_from_spec(spec)
            spec.loader.exec_module(mod)
            return mod
    except Exception:
        pass

    raise ImportError("Rust binding not available")


def _load_rust_binding():
    """Attempt to load the Rust (PyO3) binding client."""
    module = _load_rust_module()
    return module.RAGFSBindingClient, None


def get_binding_client():
    """Get the RAGFS binding client class.

    Returns:
        ``(RAGFSBindingClient_class, BindingFileHandle_class)``
    """
    try:
        client, fh = _load_rust_binding()
        _logger.info("Loaded RAGFS Rust binding")
        return client, fh
    except ImportError as exc:
        raise ImportError("ragfs_python native library is not available: " + str(exc)) from exc


def get_privacy_matcher_class():
    """Return the native RAGFS PrivacyMatcher class."""
    try:
        module = _load_rust_module()
        return module.PrivacyMatcher
    except (ImportError, AttributeError) as exc:
        raise ImportError(
            "ragfs_python PrivacyMatcher is not available; rebuild the native extension"
        ) from exc


def get_privacy_extractor_class():
    """Return the native fixed-rule credential extractor."""
    try:
        return _load_rust_module().PrivacyExtractor
    except (ImportError, AttributeError) as exc:
        raise ImportError(
            "ragfs_python PrivacyExtractor is not available; rebuild the native extension"
        ) from exc


def reopen_rust_tracing_file() -> None:
    """Reopen the Rust tracing log file after Python rotates the active file."""
    try:
        import ragfs_python as rust_module
    except ImportError:
        so_path = _find_ragfs_so()
        if not so_path:
            return
        spec = importlib.util.spec_from_file_location("ragfs_python", so_path)
        if spec is None or spec.loader is None:
            return
        rust_module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(rust_module)

    reopen_hook = getattr(rust_module, "reopen_tracing_file", None)
    if callable(reopen_hook):
        reopen_hook()


# Module-level defaults
# Ensure module import never fails, even if bindings are unavailable
try:
    RAGFSBindingClient, BindingFileHandle = get_binding_client()
    # Backward compatibility alias
    AGFSBindingClient = RAGFSBindingClient
except Exception:
    _logger.warning(
        "Failed to initialize RAGFSBindingClient during module import; "
        "RAGFSBindingClient will be None. Use get_binding_client() for explicit handling."
    )
    RAGFSBindingClient = None
    AGFSBindingClient = None
    BindingFileHandle = None

__all__ = [
    "AsyncAGFSClient",
    "LeaderCandidate",
    "Leadership",
    "AGFSSyncClientProtocol",
    "AGFSBindingClient",
    "RAGFSBindingClient",
    "BindingFileHandle",
    "get_binding_client",
    "AGFSClientError",
    "AGFSConnectionError",
    "AGFSTimeoutError",
    "AGFSHTTPError",
    "AGFSNotSupportedError",
    "AGFSNotFoundError",
    "AGFSPathNotFoundError",
    "AGFSAlreadyExistsError",
    "AGFSFileExistsError",
    "AGFSPermissionDeniedError",
    "AGFSInvalidPathError",
    "AGFSNotADirectoryError",
    "AGFSIsADirectoryError",
    "AGFSDirectoryNotEmptyError",
    "AGFSInvalidOperationError",
    "AGFSResourceExhaustedError",
    "AGFSIoError",
    "AGFSConfigError",
    "AGFSMountPointNotFoundError",
    "AGFSMountPointExistsError",
    "AGFSSerializationError",
    "AGFSNetworkError",
    "AGFSInternalError",
    "AGFSPluginError",
    "GitConcurrentCommitError",
    "GitRestoreWritebackPartialError",
    "cp",
    "upload",
    "download",
]