[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.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
perf: lazy-load the public API so importing leann.mcp stays lightweight (#437)
Samuel Pedrosobcd8ac3d2a61
diff --git a/packages/leann-core/src/leann/__init__.py b/packages/leann-core/src/leann/__init__.pyindex bd9f327..65b6abe 100644--- a/packages/leann-core/src/leann/__init__.py+++ b/packages/leann-core/src/leann/__init__.py@@ -24,11 +24,26 @@ elif system == "Linux":os.environ.setdefault("FAISS_NUM_THREADS", "1")os.environ.setdefault("OMP_WAIT_POLICY", "PASSIVE")-from .api import LeannBuilder, LeannChat, LeannSearcher-from .react_agent import ReActAgent, create_react_agent-from .registry import BACKEND_REGISTRY, autodiscover_backends+from typing import TYPE_CHECKING, Any-autodiscover_backends()+if TYPE_CHECKING:+ from .api import LeannBuilder, LeannChat, LeannSearcher+ from .react_agent import ReActAgent, create_react_agent+ from .registry import BACKEND_REGISTRY++# The public API is resolved lazily (PEP 562). Importing a lightweight+# submodule such as ``leann.mcp`` or ``leann.settings`` must not pull in the+# whole stack (api -> chat -> embedding server -> faiss backends), which costs+# gigabytes of resident memory for processes that only need a few helpers.+# Backend auto-discovery runs when ``leann.api`` is first imported.+_LAZY_ATTRS = {+ "LeannBuilder": ".api",+ "LeannChat": ".api",+ "LeannSearcher": ".api",+ "ReActAgent": ".react_agent",+ "create_react_agent": ".react_agent",+ "BACKEND_REGISTRY": ".registry",+}__all__ = ["BACKEND_REGISTRY",@@ -38,3 +53,21 @@ __all__ = ["ReActAgent","create_react_agent",]+++def __getattr__(name: str) -> Any:+ module_name = _LAZY_ATTRS.get(name)+ if module_name is None:+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")+ import importlib++ if name == "BACKEND_REGISTRY":+ # Make sure backends are discovered before handing out the registry.+ importlib.import_module(".api", __name__)+ value = getattr(importlib.import_module(module_name, __name__), name)+ globals()[name] = value # cache so __getattr__ is only hit once per name+ return value+++def __dir__() -> list[str]:+ return sorted(set(globals()) | set(__all__))diff --git a/packages/leann-core/src/leann/api.py b/packages/leann-core/src/leann/api.pyindex 918e068..ca2d621 100644--- a/packages/leann-core/src/leann/api.py+++ b/packages/leann-core/src/leann/api.py@@ -25,7 +25,7 @@ from .chat import get_llmfrom .embedding_server_manager import EmbeddingServerManagerfrom .interface import LeannBackendFactoryInterfacefrom .metadata_filter import MetadataFilterEngine-from .registry import BACKEND_REGISTRY+from .registry import BACKEND_REGISTRY, autodiscover_backendslogger = logging.getLogger(__name__)@@ -1869,3 +1869,9 @@ class LeannChat:self.cleanup()except Exception:pass+++# Register installed ``leann-backend-*`` packages. This used to live in+# ``leann/__init__.py``; it runs here so that anything importing ``leann.api``+# (directly or through the lazy package attributes) still sees every backend.+autodiscover_backends()diff --git a/tests/test_lazy_package_import.py b/tests/test_lazy_package_import.pynew file mode 100644index 0000000..cb404ad--- /dev/null+++ b/tests/test_lazy_package_import.py@@ -0,0 +1,104 @@+"""Importing light submodules must not pull in the whole LEANN stack.++Regression tests for eager package initialisation: ``import leann.mcp`` used to+execute ``leann/__init__.py``, which imported ``leann.api`` and auto-discovered+every backend (faiss included), costing gigabytes for processes that never run+a search.+"""++import os+import subprocess+import sys+import textwrap+from pathlib import Path+++def _run(code: str, extra_path: Path | None = None) -> subprocess.CompletedProcess:+ env = None+ if extra_path is not None:+ paths = [str(extra_path), *filter(None, [os.environ.get("PYTHONPATH")])]+ env = {**os.environ, "PYTHONPATH": os.pathsep.join(paths)}+ return subprocess.run(+ [sys.executable, "-c", textwrap.dedent(code)],+ capture_output=True,+ text=True,+ timeout=120,+ env=env,+ )+++def test_importing_mcp_does_not_load_heavy_modules():+ result = _run(+ """+ import sys+ import leann.mcp+ heavy = [m for m in ("leann.api", "leann.chat", "leann.embedding_server_manager",+ "leann.react_agent", "faiss") if m in sys.modules]+ print(",".join(heavy))+ """+ )+ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == ""+++def test_public_api_is_still_importable_from_package():+ result = _run(+ """+ import leann+ from leann import LeannBuilder, LeannChat, LeannSearcher, ReActAgent+ from leann import create_react_agent, BACKEND_REGISTRY+ import leann.api+ assert LeannBuilder is leann.api.LeannBuilder+ assert LeannSearcher is leann.api.LeannSearcher+ assert LeannChat is leann.api.LeannChat+ assert BACKEND_REGISTRY is leann.api.BACKEND_REGISTRY+ assert set(leann.__all__) <= set(dir(leann))+ print("ok")+ """+ )+ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == "ok"+++def test_unknown_attribute_raises_attribute_error():+ result = _run(+ """+ import leann+ try:+ leann.does_not_exist+ except AttributeError as e:+ print("AttributeError", "does_not_exist" in str(e))+ """+ )+ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == "AttributeError True"+++def test_backends_are_discovered_when_api_is_imported(tmp_path):+ """Backend auto-discovery must still run for ``from leann.api import ...``."""+ dist = tmp_path / "leann_backend_lazyprobe-0.0.0.dist-info"+ dist.mkdir()+ (dist / "METADATA").write_text(+ "Metadata-Version: 2.1\nName: leann-backend-lazyprobe\nVersion: 0.0.0\n"+ )+ (tmp_path / "leann_backend_lazyprobe.py").write_text(+ "from leann.registry import register_backend\n\n\n"+ "@register_backend('lazyprobe')\n"+ "class Probe:\n"+ " pass\n"+ )+ for statement in (+ "from leann.api import LeannSearcher",+ "from leann import LeannSearcher",+ "from leann import BACKEND_REGISTRY",+ ):+ result = _run(+ f"""+ {statement}+ from leann.registry import BACKEND_REGISTRY+ print("lazyprobe" in BACKEND_REGISTRY)+ """,+ extra_path=tmp_path,+ )+ assert result.returncode == 0, f"{statement}: {result.stderr}"+ assert result.stdout.strip() == "True", statement