ci: Wire fs_backend Python tests into CI

Signed-off-by: Alberto Perdomo <aperdomo@redhat.com>

Author: albertoperdomo2

.github/workflows/ci-test.yaml

@@ -38,8 +38,16 @@ jobs:
           go-version: "${{ env.GO_VERSION }}"
           cache-dependency-path: ./go.sum
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Install dependencies
-        run: go mod download
+        run: |
+          go mod download
+          python -m pip install --upgrade pip
+          python -m pip install -r kv_connectors/llmd_fs_backend/tests/requirements-cpu.txt
 
       - name: Run unit tests
         run: make unit-test

Makefile

@@ -17,6 +17,7 @@ BUILDER := $(shell command -v buildah >/dev/null 2>&1 && echo buildah || echo $(
 UDS_TOKENIZER_IMAGE ?= llm-d-uds-tokenizer:e2e-test
 FS_BACKEND_NAME ?= llmd-fs-backend
 FS_BACKEND_DEV_IMG ?= $(IMAGE_TAG_BASE)/$(FS_BACKEND_NAME):$(DEV_VERSION)
+FS_BACKEND_CPU_TESTS ?= kv_connectors/llmd_fs_backend/tests/test_file_mapper.py kv_connectors/llmd_fs_backend/tests/test_storage_events.py
 
 # go source files
 SRC = $(shell find . -type f -name '*.go')
@@ -57,13 +58,30 @@ clang:
 test: unit-test e2e-test ## Run all tests (unit + e2e)
 
 .PHONY: unit-test
-unit-test: unit-test-uds  ## Run unit tests
+unit-test: unit-test-uds unit-test-fs-backend-cpu  ## Run unit tests
 
 .PHONY: unit-test-uds
 unit-test-uds: check-go download-zmq ## Run unit tests
 	@printf "\033[33;1m==== Running unit tests ====\033[0m\n"
 	@go test -v ./pkg/...
 
+.PHONY: unit-test-fs-backend-cpu
+unit-test-fs-backend-cpu: ## Run CPU-safe FS backend Python unit tests
+	@printf "\033[33;1m==== Running CPU-safe FS backend unit tests ====\033[0m\n"
+	@tests=(); \
+	for test_path in $(FS_BACKEND_CPU_TESTS); do \
+		if [ -e "$$test_path" ]; then \
+			tests+=("$$test_path"); \
+		else \
+			echo "Skipping missing FS backend CPU test path: $$test_path"; \
+		fi; \
+	done; \
+	if [ "$${#tests[@]}" -eq 0 ]; then \
+		echo "No FS backend CPU test paths found."; \
+		exit 0; \
+	fi; \
+	python3 -m pytest -q "$${tests[@]}"
+
 .PHONY: unit-test-race
 unit-test-race: check-go download-zmq ## Run unit tests with Go race detector enabled
 	@printf "\033[33;1m==== Running unit tests with race detector ====\033[0m\n"

kv_connectors/llmd_fs_backend/tests/conftest.py

@@ -22,8 +22,6 @@
 sys.path.insert(0, str(Path(__file__).parent))
 
 import pytest
-import torch
-from vllm.config import VllmConfig, set_current_vllm_config
 
 
 def pytest_addoption(parser):
@@ -35,20 +33,38 @@ def pytest_addoption(parser):
     parser.addoption("--obj-ca_bundle", default=None)
 
 
-@pytest.fixture(scope="session", autouse=True)
-def require_cuda():
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers",
+        "no_cuda_required: mark a test as not requiring CUDA setup/teardown",
+    )
+
+
+@pytest.fixture(autouse=True)
+def require_cuda(request):
     """Skip all tests in this session if CUDA is not available."""
+    if request.node.get_closest_marker("no_cuda_required"):
+        return
+
+    import torch
+
     if not torch.cuda.is_available():
         pytest.skip("CUDA not available")
 
 
 @pytest.fixture(autouse=True)
-def cuda_teardown():
+def cuda_teardown(request):
     """Ensure CUDA and C++ thread-pool resources from one test are fully
     released before the next test starts. Without this, async destructors
     can cause 'cudaErrorUnknown' or stale file-open errors in subsequent tests.
     """
+    if request.node.get_closest_marker("no_cuda_required"):
+        yield
+        return
+
     yield
+    import torch
+
     gc.collect()  # force Python GC to call C++ destructors immediately
     torch.cuda.synchronize()  # surface any async CUDA errors in the right test
     torch.cuda.empty_cache()  # free cached allocations so next test starts clean
@@ -61,6 +77,8 @@ def default_vllm_config():
     that use get_current_vllm_config() outside of a full engine context.
     This matches vLLM's internal test fixture pattern.
     """
+    from vllm.config import VllmConfig, set_current_vllm_config
+
     # Use empty VllmConfig() which provides sensible defaults
     with set_current_vllm_config(VllmConfig()):
         yield

kv_connectors/llmd_fs_backend/tests/requirements-cpu.txt

@@ -0,0 +1,3 @@
+pytest
+msgpack
+pyzmq

kv_connectors/llmd_fs_backend/tests/test_file_mapper.py

@@ -0,0 +1,53 @@
+# Copyright 2026 The llm-d Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.no_cuda_required
+
+CONNECTOR_ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_file_mapper_class():
+    module_path = CONNECTOR_ROOT / "llmd_fs_backend" / "file_mapper.py"
+    spec = importlib.util.spec_from_file_location("file_mapper_under_test", module_path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module.FileMapper
+
+
+def test_file_mapper_masks_hashes_to_lower_64_bits():
+    file_mapper = load_file_mapper_class()(
+        root_dir="/tmp/kv-cache",
+        model_name="test-model",
+        gpu_block_size=16,
+        gpu_blocks_per_file=16,
+        tp_size=1,
+        pp_size=1,
+        pcp_size=1,
+        rank=0,
+        dtype="float16",
+    )
+
+    assert file_mapper.get_file_name((1 << 72) + 0x1234).endswith(
+        "/000/00/0000000000001234.bin"
+    )
+    assert file_mapper.get_file_name(b"\x01\x02").endswith(
+        "/000/00/0000000000000102.bin"
+    )