Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

fix(core): import the hnsw backend lazily in leann-core (#409)

Yifan Chen00ac7cd54c36
diff --git a/packages/leann-core/src/leann/api.py b/packages/leann-core/src/leann/api.py
index 99c4432..e374a46 100644
--- a/packages/leann-core/src/leann/api.py
+++ b/packages/leann-core/src/leann/api.py
@@ -17,7 +17,6 @@ from pathlib import Path
from typing import Any, Literal, Optional, Union
import numpy as np
-from leann_backend_hnsw.convert_to_csr import prune_hnsw_embeddings_inplace
from leann.interactive_utils import create_api_session
from leann.interface import LeannBackendSearcherInterface
@@ -1189,6 +1188,8 @@ class LeannBuilder:
self.chunks.clear()
if needs_recompute:
+ from leann_backend_hnsw.convert_to_csr import prune_hnsw_embeddings_inplace
+
prune_hnsw_embeddings_inplace(str(index_file))
diff --git a/tests/test_cpu_only_install.py b/tests/test_cpu_only_install.py
index 0d5c2f4..3e40eb5 100644
--- a/tests/test_cpu_only_install.py
+++ b/tests/test_cpu_only_install.py
@@ -1,5 +1,6 @@
"""Packaging metadata checks for CPU-only installs."""
+import ast
from pathlib import Path
import pytest
@@ -15,6 +16,21 @@ def _load_leann_pyproject():
return tomllib.loads(pyproject_path.read_text())
+def _leann_core_source_files():
+ package_root = Path(__file__).resolve().parents[1] / "packages" / "leann-core" / "src" / "leann"
+ return sorted(package_root.rglob("*.py"))
+
+
+def _module_scope_imports(source: str):
+ """Yield (lineno, module) for every import executed at module scope."""
+ for node in ast.parse(source).body:
+ if isinstance(node, ast.Import):
+ for alias in node.names:
+ yield node.lineno, alias.name
+ elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+ yield node.lineno, node.module
+
+
def _load_leann_core_pyproject():
pyproject_path = (
Path(__file__).resolve().parents[1] / "packages" / "leann-core" / "pyproject.toml"
@@ -59,3 +75,26 @@ def test_leann_cpu_extra_defined():
assert "cpu" in extras
assert "leann-core[cpu]>=0.1.0" in extras["cpu"]
+
+
+def test_leann_core_does_not_import_a_backend_at_module_scope():
+ """leann-core declares no leann-backend-* dependency, so importing one eagerly
+ turns `import leann` into a ModuleNotFoundError for anyone who installed
+ leann-core on its own or paired it with a non-HNSW backend."""
+ data = _load_leann_core_pyproject()
+ deps = data["project"].get("dependencies", [])
+ assert not any(dep.startswith("leann-backend") for dep in deps), (
+ "leann-core now depends on a backend; this test needs revisiting"
+ )
+
+ offenders = [
+ f"{path.name}:{lineno} imports {module}"
+ for path in _leann_core_source_files()
+ for lineno, module in _module_scope_imports(path.read_text(encoding="utf-8"))
+ if module.split(".")[0].startswith("leann_backend")
+ ]
+
+ assert not offenders, (
+ "leann-core must import backends lazily inside the functions that use them: "
+ + "; ".join(offenders)
+ )