Skip to content

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

fix(release): fail wheel builds without ragfs bindings (#1466)

Qin Haojie0fd0594b13f0
diff --git a/.github/workflows/_build.yml b/.github/workflows/_build.yml
index 18c6ac314..d97a0824c 100644
--- a/.github/workflows/_build.yml
+++ b/.github/workflows/_build.yml
@@ -140,13 +140,21 @@ jobs:
# Retry apt-get update
for i in 1 2 3 4 5; do apt-get update && break || sleep 5; done
apt-get install -y \
- git ca-certificates cmake build-essential tzdata curl \
+ git ca-certificates cmake build-essential clang tzdata curl \
libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
libffi-dev liblzma-dev libgdbm-dev libnss3-dev libncurses5-dev \
libncursesw5-dev tk-dev uuid-dev libexpat1-dev
ln -fs /usr/share/zoneinfo/Etc/UTC /etc/localtime
dpkg-reconfigure -f noninteractive tzdata
+ - name: Select compiler toolchain (Linux)
+ run: |
+ echo "CC=clang" >> "$GITHUB_ENV"
+ echo "CXX=clang++" >> "$GITHUB_ENV"
+ echo "OV_REQUIRE_RAGFS_BUILD=1" >> "$GITHUB_ENV"
+ clang --version
+ clang++ --version
+
- uses: actions/checkout@v6
with:
submodules: recursive
@@ -280,6 +288,36 @@ jobs:
mv dist_fixed/*.whl dist/
rmdir dist_fixed
+ - name: Smoke test built wheel (Linux)
+ shell: bash
+ run: |
+ "$PYTHON_BIN" -m pip install --upgrade pip
+ "$PYTHON_BIN" -m pip install --force-reinstall dist/*.whl
+
+ cd "$RUNNER_TEMP"
+ "$PYTHON_BIN" - <<'PY'
+ import importlib.util
+
+ from openviking.pyagfs import get_binding_client
+ import openviking.storage.vectordb.engine as engine
+
+ binding_client, _ = get_binding_client()
+ if binding_client is None:
+ raise SystemExit("ragfs binding client was not installed")
+
+ print(f"Loaded RAGFS binding client {binding_client.__name__}")
+ print(f"Loaded runtime engine variant {engine.ENGINE_VARIANT}")
+ print(f"Available engine variants {engine.AVAILABLE_ENGINE_VARIANTS}")
+
+ module_name = f"openviking.storage.vectordb.engine._{engine.ENGINE_VARIANT}"
+ backend_spec = importlib.util.find_spec(module_name)
+ if backend_spec is None or backend_spec.origin is None:
+ raise SystemExit(f"backend module {module_name} was not installed")
+
+ print(f"Imported backend module {module_name}")
+ print(f"Backend module origin {backend_spec.origin}")
+ PY
+
- name: Store the distribution packages
uses: actions/upload-artifact@v7
with:
@@ -368,6 +406,10 @@ jobs:
- name: Install build dependencies
run: uv pip install setuptools setuptools_scm cmake wheel build
+ - name: Require ragfs native artifact for wheel builds
+ shell: bash
+ run: echo "OV_REQUIRE_RAGFS_BUILD=1" >> "$GITHUB_ENV"
+
- name: Resolve OpenViking version for Rust CLI (macOS/Windows)
shell: bash
run: |
@@ -427,6 +469,37 @@ jobs:
- name: Build package (Wheel Only)
run: uv build --wheel
+ - name: Smoke test built wheel (macOS)
+ if: runner.os == 'macOS'
+ shell: bash
+ run: |
+ python -m pip install --upgrade pip
+ python -m pip install --force-reinstall dist/*.whl
+
+ cd "$RUNNER_TEMP"
+ python - <<'PY'
+ import importlib.util
+
+ from openviking.pyagfs import get_binding_client
+ import openviking.storage.vectordb.engine as engine
+
+ binding_client, _ = get_binding_client()
+ if binding_client is None:
+ raise SystemExit("ragfs binding client was not installed")
+
+ print(f"Loaded RAGFS binding client {binding_client.__name__}")
+ print(f"Loaded runtime engine variant {engine.ENGINE_VARIANT}")
+ print(f"Available engine variants {engine.AVAILABLE_ENGINE_VARIANTS}")
+
+ module_name = f"openviking.storage.vectordb.engine._{engine.ENGINE_VARIANT}"
+ backend_spec = importlib.util.find_spec(module_name)
+ if backend_spec is None or backend_spec.origin is None:
+ raise SystemExit(f"backend module {module_name} was not installed")
+
+ print(f"Imported backend module {module_name}")
+ print(f"Backend module origin {backend_spec.origin}")
+ PY
+
- name: Smoke test built wheel (Windows)
if: runner.os == 'Windows'
shell: bash
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index 0007a4da6..ff7024a9d 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -1,10 +1,14 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
from enum import Enum
-from typing import Optional
+from typing import Any, Optional
from pydantic import BaseModel, Field, model_validator
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
class DirectoryMarkerMode(str, Enum):
"""How S3 directory markers should be persisted."""
@@ -97,12 +101,60 @@ class AGFSConfig(BaseModel):
description="[Deprecated in favor of `storage.workspace`] RAGFS data storage path. This will be ignored if `storage.workspace` is set.",
)
+ port: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS service port. Ignored by RAGFS.",
+ )
+
+ log_level: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS log level. Ignored by RAGFS.",
+ )
+
+ url: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS service URL. Ignored by RAGFS.",
+ )
+
+ mode: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS client mode. Ignored by RAGFS.",
+ )
+
+ impl: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS binding implementation selector. Ignored by RAGFS.",
+ )
+
backend: str = Field(
default="local", description="RAGFS storage backend: 'local' | 's3' | 'memory'"
)
timeout: int = Field(default=10, description="RAGFS request timeout (seconds)")
+ retry_times: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS retry count. Ignored by RAGFS.",
+ )
+
+ use_ssl: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS SSL switch. Ignored by RAGFS.",
+ )
+
+ lib_path: Any = Field(
+ default=None,
+ exclude=True,
+ description="[Deprecated] Legacy AGFS binding library path. Ignored by RAGFS.",
+ )
+
# S3 backend configuration
# These settings are used when backend is set to 's3'.
# RAGFS will act as a gateway to the specified S3 bucket.
@@ -113,6 +165,23 @@ class AGFSConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
"""Validate configuration completeness and consistency"""
+ deprecated_fields = (
+ "port",
+ "log_level",
+ "url",
+ "mode",
+ "impl",
+ "retry_times",
+ "use_ssl",
+ "lib_path",
+ )
+ for field_name in deprecated_fields:
+ if field_name in self.model_fields_set:
+ logger.warning(
+ "AGFSConfig: 'storage.agfs.%s' is deprecated and ignored after the RAGFS migration.",
+ field_name,
+ )
+
if self.backend not in ["local", "s3", "memory"]:
raise ValueError(
f"Invalid RAGFS backend: '{self.backend}'. Must be one of: 'local', 's3', 'memory'"
diff --git a/setup.py b/setup.py
index f90be1f32..e82478c26 100644
--- a/setup.py
+++ b/setup.py
@@ -28,8 +28,8 @@ resolve_openviking_version = importlib.import_module(
).resolve_openviking_version
CMAKE_PATH = shutil.which("cmake") or "cmake"
-C_COMPILER_PATH = shutil.which("gcc") or "gcc"
-CXX_COMPILER_PATH = shutil.which("g++") or "g++"
+C_COMPILER_PATH = os.environ.get("CC") or shutil.which("gcc") or "gcc"
+CXX_COMPILER_PATH = os.environ.get("CXX") or shutil.which("g++") or "g++"
ENGINE_SOURCE_DIR = "src/"
ENGINE_BUILD_CONFIG = get_host_engine_build_config(platform.machine())
@@ -228,22 +228,32 @@ class OpenVikingBuildExt(build_ext):
"""Build ragfs-python (Rust RAGFS binding) via maturin and copy the native
extension into ``openviking/lib/`` so it ships inside the openviking wheel.
"""
+ require_ragfs_artifact = self._should_require_ragfs_artifact()
ragfs_python_dir = Path("crates/ragfs-python").resolve()
ragfs_lib_dir = Path("openviking/lib").resolve()
if not ragfs_python_dir.exists():
- print("[Info] ragfs-python source directory not found. Skipping.")
+ message = "ragfs-python source directory not found."
+ if require_ragfs_artifact:
+ raise RuntimeError(message)
+ print(f"[Info] {message} Skipping.")
return
if os.environ.get("OV_SKIP_RAGFS_BUILD") == "1":
- print("[OK] Skipping ragfs-python build (OV_SKIP_RAGFS_BUILD=1)")
+ message = "Skipping ragfs-python build (OV_SKIP_RAGFS_BUILD=1)"
+ if require_ragfs_artifact:
+ raise RuntimeError(f"{message} is incompatible with required wheel artifacts.")
+ print(f"[OK] {message}")
return
if importlib.util.find_spec("maturin") is None:
- print(
- "[SKIP] maturin not found. ragfs-python (Rust binding) will not be built.\n"
+ message = (
+ "maturin not found. ragfs-python (Rust binding) will not be built.\n"
" Install maturin to enable: pip install maturin"
)
+ if require_ragfs_artifact:
+ raise RuntimeError(message)
+ print(f"[SKIP] {message}")
return
import tempfile
@@ -285,7 +295,10 @@ class OpenVikingBuildExt(build_ext):
# Extract the native .so/.pyd from the built wheel.
whl_files = list(Path(tmpdir).glob("ragfs_python-*.whl"))
if not whl_files:
- print("[Warning] maturin produced no wheel. Skipping ragfs-python.")
+ message = "maturin produced no wheel for ragfs-python."
+ if require_ragfs_artifact:
+ raise RuntimeError(message)
+ print(f"[Warning] {message}")
return
ragfs_lib_dir.mkdir(parents=True, exist_ok=True)
@@ -307,7 +320,10 @@ class OpenVikingBuildExt(build_ext):
break
if not extracted:
- print("[Warning] Could not find ragfs_python .so/.pyd in built wheel.")
+ message = "Could not find ragfs_python .so/.pyd in built wheel."
+ if require_ragfs_artifact:
+ raise RuntimeError(message)
+ print(f"[Warning] {message}")
else:
self._copy_artifacts_to_build_lib(target_lib=target_path)
@@ -318,10 +334,22 @@ class OpenVikingBuildExt(build_ext):
error_detail += exc.stdout.decode("utf-8", errors="replace")
if exc.stderr:
error_detail += exc.stderr.decode("utf-8", errors="replace")
+ if require_ragfs_artifact:
+ error_message = f"Failed to build ragfs-python: {exc}"
+ if error_detail:
+ error_message += f"\n{error_detail}"
+ raise RuntimeError(error_message) from exc
print(f"[Warning] Failed to build ragfs-python: {exc}")
if error_detail:
print(error_detail)
+ def _should_require_ragfs_artifact(self) -> bool:
+ """Fail wheel builds closed when ragfs-python cannot be bundled."""
+ required = os.environ.get("OV_REQUIRE_RAGFS_BUILD")
+ if required is not None:
+ return required == "1"
+ return "bdist_wheel" in sys.argv
+
def build_extension(self, ext):
"""Build a single Python native extension artifact using CMake."""
if getattr(self, "_engine_extensions_built", False):
diff --git a/tests/misc/test_abi3_packaging_config.py b/tests/misc/test_abi3_packaging_config.py
index 3df323254..e60a7c056 100644
--- a/tests/misc/test_abi3_packaging_config.py
+++ b/tests/misc/test_abi3_packaging_config.py
@@ -74,6 +74,15 @@ def test_build_workflow_smoke_tests_windows_wheel_engine_import():
assert "engine.ENGINE_VARIANT" in build_workflow
+def test_build_workflow_smoke_tests_linux_and_macos_ragfs_binding_import():
+ build_workflow = _read_text(".github/workflows/_build.yml")
+
+ assert "Smoke test built wheel (Linux)" in build_workflow
+ assert "Smoke test built wheel (macOS)" in build_workflow
+ assert "from openviking.pyagfs import get_binding_client" in build_workflow
+ assert "Loaded RAGFS binding client" in build_workflow
+
+
def test_windows_abi3_backend_uses_stable_python_linkage():
setup_py = _read_text("setup.py")
src_cmake = _read_text("src/CMakeLists.txt")
diff --git a/tests/misc/test_root_docker_image_packaging.py b/tests/misc/test_root_docker_image_packaging.py
index 75c34d2a7..b146474b7 100644
--- a/tests/misc/test_root_docker_image_packaging.py
+++ b/tests/misc/test_root_docker_image_packaging.py
@@ -75,6 +75,18 @@ def test_root_build_system_includes_maturin_for_isolated_builds():
assert 'shutil.which("maturin")' not in setup_py
+def test_root_build_system_honors_ci_compiler_overrides_and_requires_ragfs_for_wheels():
+ setup_py = _read_text("setup.py")
+ build_workflow = _read_text(".github/workflows/_build.yml")
+
+ assert 'os.environ.get("CC")' in setup_py
+ assert 'os.environ.get("CXX")' in setup_py
+ assert "OV_REQUIRE_RAGFS_BUILD" in setup_py
+ assert 'echo "CC=clang" >> "$GITHUB_ENV"' in build_workflow
+ assert 'echo "CXX=clang++" >> "$GITHUB_ENV"' in build_workflow
+ assert 'echo "OV_REQUIRE_RAGFS_BUILD=1" >> "$GITHUB_ENV"' in build_workflow
+
+
def test_rust_crates_declare_the_repo_minimum_rust_version():
makefile = _read_text("Makefile")
min_rust_version = _extract_rust_version(