[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
fix(release): publish all backends and test loopback bind (#447)
Zhifei Lia63f484a0b00
diff --git a/.github/workflows/build-reusable.yml b/.github/workflows/build-reusable.ymlindex 537c106..5df17bd 100644--- a/.github/workflows/build-reusable.yml+++ b/.github/workflows/build-reusable.yml@@ -412,6 +412,16 @@ jobs:retry 3 uv build --wheel --python ${{ matrix.python }} --find-links ${GITHUB_WORKSPACE}/packages/leann-core/distcd ../..+ # Build GPU backends as thin Python wheels. Their CUDA runtime is supplied by+ # the installed FlashLib dependency; compilation happens when those backends run.+ cd packages/leann-backend-flashlib+ retry 3 uv build --wheel --python ${{ matrix.python }}+ cd ../..++ cd packages/leann-backend-flashlib-ivf+ retry 3 uv build --wheel --python ${{ matrix.python }}+ cd ../..+# Build meta package (platform independent)cd packages/leannretry 3 uv builddiff --git a/.github/workflows/release-manual.yml b/.github/workflows/release-manual.ymlindex 8054edb..f2afe25 100644--- a/.github/workflows/release-manual.yml+++ b/.github/workflows/release-manual.yml@@ -86,9 +86,10 @@ jobs:COMMIT_SHA=$(git rev-parse HEAD)else./scripts/bump_version.sh ${{ inputs.version }}+ uv lockgit config user.name "GitHub Actions"git config user.email "[email protected]"- git add packages/*/pyproject.toml+ git add packages/*/pyproject.toml uv.lock docker/Dockerfile docker/Dockerfile.cpu docker/README.mdgit commit -m "chore: release v${{ inputs.version }}"git push origin mainCOMMIT_SHA=$(git rev-parse HEAD)@@ -146,6 +147,52 @@ jobs:echo "✅ Published to PyPI!"+ - name: Verify every package reached PyPI+ env:+ RELEASE_VERSION: ${{ inputs.version }}+ run: |+ python - <<'PY'+ import json+ import os+ import time+ import urllib.error+ import urllib.request++ version = os.environ["RELEASE_VERSION"]+ packages = [+ "leann",+ "leann-core",+ "leann-backend-hnsw",+ "leann-backend-diskann",+ "leann-backend-ivf",+ "leann-backend-flashlib",+ "leann-backend-flashlib-ivf",+ ]+ deadline = time.time() + 180+ missing = {}++ for package in packages:+ while True:+ try:+ url = f"https://pypi.org/pypi/{package}/json"+ with urllib.request.urlopen(url, timeout=20) as response:+ data = json.load(response)+ files = data.get("releases", {}).get(version, [])+ if files:+ print(f"OK {package} {version}: {len(files)} files")+ break+ missing[package] = "version has no files"+ except urllib.error.HTTPError as exc:+ missing[package] = f"HTTP {exc.code}"++ if time.time() >= deadline:+ raise SystemExit(+ f"PyPI verification failed for {package} {version}: {missing[package]}"+ )+ time.sleep(10)++ PY+- name: Create releaserun: |# Check if tag already existsdiff --git a/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py b/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.pyindex 880a502..dc7eb42 100644--- a/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py+++ b/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py@@ -14,6 +14,7 @@ from typing import Any, Optionalimport numpy as npimport zmq+from leann.embedding_server_endpoint import bind_zmq_embedding_socket# Set up logging based on environment variableLOG_LEVEL = os.getenv("LEANN_LOG_LEVEL", "WARNING").upper()@@ -123,11 +124,8 @@ def create_diskann_embedding_server(socket = context.socket(zmq.REP) # REP socket for both BaseSearcher and DiskANN C++ REQ clients- zmq_host = os.getenv("LEANN_EMBEDDING_SERVER_HOST", "127.0.0.1")- if ":" in zmq_host and not zmq_host.startswith("["):- zmq_host = f"[{zmq_host}]" # literal IPv6 needs brackets in ZMQ endpoints- socket.bind(f"tcp://{zmq_host}:{zmq_port}")- logger.info(f"DiskANN ZMQ REP server listening on {zmq_host}:{zmq_port}")+ endpoint = bind_zmq_embedding_socket(socket, zmq_port)+ logger.info(f"DiskANN ZMQ REP server listening on {endpoint}")socket.setsockopt(zmq.RCVTIMEO, 1000)socket.setsockopt(zmq.SNDTIMEO, 1000)@@ -263,11 +261,8 @@ def create_diskann_embedding_server(context = zmq.Context()rep_socket = context.socket(zmq.REP)- zmq_host = os.getenv("LEANN_EMBEDDING_SERVER_HOST", "127.0.0.1")- if ":" in zmq_host and not zmq_host.startswith("["):- zmq_host = f"[{zmq_host}]" # literal IPv6 needs brackets in ZMQ endpoints- rep_socket.bind(f"tcp://{zmq_host}:{zmq_port}")- logger.info(f"DiskANN ZMQ REP server listening on {zmq_host}:{zmq_port}")+ endpoint = bind_zmq_embedding_socket(rep_socket, zmq_port)+ logger.info(f"DiskANN ZMQ REP server listening on {endpoint}")# Set receive timeout so we can check shutdown_event periodicallyrep_socket.setsockopt(zmq.RCVTIMEO, 1000) # 1 second timeoutdiff --git a/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py b/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.pyindex 8208abc..af805c2 100644--- a/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py+++ b/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py@@ -15,6 +15,7 @@ from typing import Any, Optionalimport msgpackimport numpy as npimport zmq+from leann.embedding_server_endpoint import bind_zmq_embedding_socket# Set up logging based on environment variableLOG_LEVEL = os.getenv("LEANN_LOG_LEVEL", "WARNING").upper()@@ -168,11 +169,8 @@ def create_hnsw_embedding_server(context = zmq.Context()rep_socket = context.socket(zmq.REP)- zmq_host = os.getenv("LEANN_EMBEDDING_SERVER_HOST", "127.0.0.1")- if ":" in zmq_host and not zmq_host.startswith("["):- zmq_host = f"[{zmq_host}]" # literal IPv6 needs brackets in ZMQ endpoints- rep_socket.bind(f"tcp://{zmq_host}:{zmq_port}")- logger.info(f"HNSW ZMQ REP server listening on {zmq_host}:{zmq_port}")+ endpoint = bind_zmq_embedding_socket(rep_socket, zmq_port)+ logger.info(f"HNSW ZMQ REP server listening on {endpoint}")rep_socket.setsockopt(zmq.RCVTIMEO, 1000)rep_socket.setsockopt(zmq.SNDTIMEO, 1000)rep_socket.setsockopt(zmq.LINGER, 0)diff --git a/packages/leann-core/src/leann/embedding_server_endpoint.py b/packages/leann-core/src/leann/embedding_server_endpoint.pynew file mode 100644index 0000000..a053ed7--- /dev/null+++ b/packages/leann-core/src/leann/embedding_server_endpoint.py@@ -0,0 +1,35 @@+"""Shared bind-endpoint handling for LEANN's local ZMQ embedding servers."""++from __future__ import annotations++import os+from collections.abc import Mapping+from typing import Protocol++DEFAULT_EMBEDDING_SERVER_HOST = "127.0.0.1"+EMBEDDING_SERVER_HOST_ENV = "LEANN_EMBEDDING_SERVER_HOST"+++class BindableSocket(Protocol):+ def bind(self, endpoint: str) -> None: ...+++def zmq_bind_endpoint(port: int, environ: Mapping[str, str] | None = None) -> str:+ """Return a ZMQ endpoint that stays on loopback unless explicitly overridden."""+ env = os.environ if environ is None else environ+ host = env.get(EMBEDDING_SERVER_HOST_ENV, DEFAULT_EMBEDDING_SERVER_HOST).strip()+ host = host or DEFAULT_EMBEDDING_SERVER_HOST+ if ":" in host and not host.startswith("["):+ host = f"[{host}]"+ return f"tcp://{host}:{port}"+++def bind_zmq_embedding_socket(+ socket: BindableSocket,+ port: int,+ environ: Mapping[str, str] | None = None,+) -> str:+ """Bind an embedding-server socket and return the endpoint for logging/tests."""+ endpoint = zmq_bind_endpoint(port, environ)+ socket.bind(endpoint)+ return endpointdiff --git a/scripts/bump_version.sh b/scripts/bump_version.shindex a88bcc1..036a44b 100755--- a/scripts/bump_version.sh+++ b/scripts/bump_version.sh@@ -1,31 +1,40 @@#!/bin/bash+set -euo pipefail+if [ $# -eq 0 ]; thenecho "Usage: $0 <new_version>"exit 1fiNEW_VERSION=$1+if [[ ! "$NEW_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ echo "Invalid version '$NEW_VERSION'; expected X.Y.Z"+ exit 1+fi-# Get the directory where the script is locatedSCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"-# Update all pyproject.toml files+sed_edit() {+ if [[ "$OSTYPE" == "darwin"* ]]; then+ sed -E -i '' "$@"+ else+ sed -E -i "$@"+ fi+}+echo "Updating versions in $PROJECT_ROOT/packages/"+while IFS= read -r -d '' file; do+ sed_edit "s/^version = \"[^\"]+\"/version = \"${NEW_VERSION}\"/" "$file"+ sed_edit "s/(\"(leann-core|leann-backend-hnsw|leann-backend-diskann|leann-backend-ivf)(\[[^]]+\])?[=<>~!]*)[0-9]+\.[0-9]+\.[0-9]+/\1${NEW_VERSION}/g" "$file"+done < <(find "$PROJECT_ROOT/packages" -name "pyproject.toml" -print0)-# Use different sed syntax for macOS vs Linux-if [[ "$OSTYPE" == "darwin"* ]]; then- # Update version fields- find "$PROJECT_ROOT/packages" -name "pyproject.toml" -exec sed -i '' "s/version = \".*\"/version = \"$NEW_VERSION\"/" {} \;- # Update leann-core dependencies- find "$PROJECT_ROOT/packages" -name "pyproject.toml" -exec sed -i '' "s/leann-core==[0-9.]*/leann-core==$NEW_VERSION/" {} \;-else- # Update version fields- find "$PROJECT_ROOT/packages" -name "pyproject.toml" -exec sed -i "s/version = \".*\"/version = \"$NEW_VERSION\"/" {} \;- # Update leann-core dependencies- find "$PROJECT_ROOT/packages" -name "pyproject.toml" -exec sed -i "s/leann-core==[0-9.]*/leann-core==$NEW_VERSION/" {} \;-fi+for file in "$PROJECT_ROOT/docker/Dockerfile" "$PROJECT_ROOT/docker/Dockerfile.cpu"; do+ sed_edit "s/^ARG LEANN_VERSION=.*/ARG LEANN_VERSION=${NEW_VERSION}/" "$file"+done+sed_edit "s/(--build-arg LEANN_VERSION=)[0-9]+\.[0-9]+\.[0-9]+/\1${NEW_VERSION}/g" \+ "$PROJECT_ROOT/docker/README.md"-echo "✅ Version updated to $NEW_VERSION"-echo "✅ Dependencies updated to use leann-core==$NEW_VERSION"+echo "✅ Package versions and internal dependencies updated to $NEW_VERSION"+echo "✅ Docker defaults and examples updated to $NEW_VERSION"diff --git a/tests/test_embedding_server_bind.py b/tests/test_embedding_server_bind.pynew file mode 100644index 0000000..720102f--- /dev/null+++ b/tests/test_embedding_server_bind.py@@ -0,0 +1,66 @@+from pathlib import Path++import pytest+from leann.embedding_server_endpoint import (+ bind_zmq_embedding_socket,+ zmq_bind_endpoint,+)+++class RecordingSocket:+ def __init__(self):+ self.endpoint: str | None = None++ def bind(self, endpoint: str) -> None:+ self.endpoint = endpoint+++ ("environment", "expected"),+ [+ ({}, "tcp://127.0.0.1:5555"),+ ({"LEANN_EMBEDDING_SERVER_HOST": "0.0.0.0"}, "tcp://0.0.0.0:5555"),+ ({"LEANN_EMBEDDING_SERVER_HOST": "::1"}, "tcp://[::1]:5555"),+ ({"LEANN_EMBEDDING_SERVER_HOST": "[::1]"}, "tcp://[::1]:5555"),+ ({"LEANN_EMBEDDING_SERVER_HOST": ""}, "tcp://127.0.0.1:5555"),+ ],+)+def test_zmq_bind_endpoint_stays_local_by_default(environment, expected):+ assert zmq_bind_endpoint(5555, environment) == expected+++def test_bind_zmq_embedding_socket_uses_resolved_loopback_endpoint(monkeypatch):+ monkeypatch.delenv("LEANN_EMBEDDING_SERVER_HOST", raising=False)+ socket = RecordingSocket()++ endpoint = bind_zmq_embedding_socket(socket, 6123)++ assert endpoint == "tcp://127.0.0.1:6123"+ assert socket.endpoint == endpoint+++def test_bind_zmq_embedding_socket_creates_a_real_loopback_listener():+ zmq = pytest.importorskip("zmq")+ context = zmq.Context()+ socket = context.socket(zmq.REP)+ try:+ bind_zmq_embedding_socket(socket, 0)+ actual_endpoint = socket.getsockopt(zmq.LAST_ENDPOINT).decode()+ assert actual_endpoint.startswith("tcp://127.0.0.1:")+ assert not actual_endpoint.endswith(":*")+ finally:+ socket.close(linger=0)+ context.term()+++def test_all_embedding_servers_use_the_shared_bind_helper():+ root = Path(__file__).resolve().parents[1] / "packages"+ servers = [+ root / "leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py",+ root / "leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py",+ ]++ for server in servers:+ source = server.read_text(encoding="utf-8")+ assert "bind_zmq_embedding_socket(" in source+ assert '.bind(f"tcp://' not in source