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.

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__.py
index 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.py
index 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_llm
from .embedding_server_manager import EmbeddingServerManager
from .interface import LeannBackendFactoryInterface
from .metadata_filter import MetadataFilterEngine
-from .registry import BACKEND_REGISTRY
+from .registry import BACKEND_REGISTRY, autodiscover_backends
logger = 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.py
new file mode 100644
index 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