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(release): publish all backends and test loopback bind (#447)

Zhifei Lia63f484a0b00
diff --git a/.github/workflows/build-reusable.yml b/.github/workflows/build-reusable.yml
index 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/dist
cd ../..
+ # 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/leann
retry 3 uv build
diff --git a/.github/workflows/release-manual.yml b/.github/workflows/release-manual.yml
index 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 lock
git 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.md
git commit -m "chore: release v${{ inputs.version }}"
git push origin main
COMMIT_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 release
run: |
# Check if tag already exists
diff --git a/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py b/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py
index 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, Optional
import numpy as np
import zmq
+from leann.embedding_server_endpoint import bind_zmq_embedding_socket
# Set up logging based on environment variable
LOG_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 periodically
rep_socket.setsockopt(zmq.RCVTIMEO, 1000) # 1 second timeout
diff --git a/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py b/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py
index 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, Optional
import msgpack
import numpy as np
import zmq
+from leann.embedding_server_endpoint import bind_zmq_embedding_socket
# Set up logging based on environment variable
LOG_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.py
new file mode 100644
index 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 endpoint
diff --git a/scripts/bump_version.sh b/scripts/bump_version.sh
index 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 ]; then
echo "Usage: $0 <new_version>"
exit 1
fi
NEW_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 located
SCRIPT_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.py
new file mode 100644
index 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