[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
feat: reduce cold start latency with daemonized embedding server reuse (#258)
Andy Lee88445502942a
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.pyindex 592fddb..c354675 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@@ -48,6 +48,8 @@ def create_diskann_embedding_server(model_name: str = "sentence-transformers/all-mpnet-base-v2",embedding_mode: str = "sentence-transformers",distance_metric: str = "l2",+ enable_warmup: bool = False,+ daemon_ttl: int = 0,):"""Create and start a ZMQ-based embedding server for DiskANN backend.@@ -72,6 +74,19 @@ def create_diskann_embedding_server(finally:sys.path.pop(0)+ if enable_warmup:+ try:+ logger.info("Starting warmup embedding request...")+ _ = compute_embeddings(+ ["__LEANN_WARMUP__"],+ model_name,+ mode=embedding_mode,+ provider_options=PROVIDER_OPTIONS,+ )+ logger.info("Warmup complete.")+ except Exception as exc:+ logger.warning(f"Warmup failed (continuing): {exc}")+# Check port availabilityimport socket@@ -259,6 +274,7 @@ def create_diskann_embedding_server(e2e_start = time.time()# REP socket receives single-part messagesmessage = rep_socket.recv()+ last_activity[0] = time.time()# Check for empty messages - REP socket requires response to every requestif not message:@@ -385,6 +401,7 @@ def create_diskann_embedding_server(# Add shutdown coordinationshutdown_event = threading.Event()+ last_activity = [time.time()]def shutdown_zmq_server():"""Gracefully shutdown ZMQ server."""@@ -437,6 +454,12 @@ def create_diskann_embedding_server(# Keep the main thread alivetry:while not shutdown_event.is_set():+ if daemon_ttl > 0 and (time.time() - last_activity[0]) >= daemon_ttl:+ logger.info(+ f"No requests for {daemon_ttl} seconds, shutting down daemon on port {zmq_port}"+ )+ shutdown_zmq_server()+ returntime.sleep(0.1) # Check shutdown more frequentlyexcept KeyboardInterrupt:logger.info("DiskANN Server shutting down...")@@ -479,6 +502,22 @@ if __name__ == "__main__":choices=["l2", "mips", "cosine"],help="Distance metric for similarity computation",)+ parser.add_argument(+ "--enable-warmup",+ action="store_true",+ help="Preload model by running one warmup embedding at startup",+ )+ parser.add_argument(+ "--daemon-mode",+ action="store_true",+ help="Run as daemon mode (enables idle TTL checks)",+ )+ parser.add_argument(+ "--daemon-ttl",+ type=int,+ default=0,+ help="Idle TTL in seconds for daemon mode; 0 disables auto-exit",+ )args = parser.parse_args()@@ -489,4 +528,6 @@ if __name__ == "__main__":model_name=args.model_name,embedding_mode=args.embedding_mode,distance_metric=args.distance_metric,+ enable_warmup=args.enable_warmup,+ daemon_ttl=args.daemon_ttl if args.daemon_mode else 0,)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.pyindex b55fa24..c93a996 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@@ -61,6 +61,8 @@ def create_hnsw_embedding_server(model_name: str = "sentence-transformers/all-mpnet-base-v2",distance_metric: str = "mips",embedding_mode: str = "sentence-transformers",+ enable_warmup: bool = False,+ daemon_ttl: int = 0,):"""Create and start a ZMQ-based embedding server for HNSW backend.@@ -85,6 +87,19 @@ def create_hnsw_embedding_server(finally:sys.path.pop(0)+ if enable_warmup:+ try:+ logger.info("Starting warmup embedding request...")+ _ = compute_embeddings(+ ["__LEANN_WARMUP__"],+ model_name,+ mode=embedding_mode,+ provider_options=PROVIDER_OPTIONS,+ )+ logger.info("Warmup complete.")+ except Exception as exc:+ logger.warning(f"Warmup failed (continuing): {exc}")+# Check port availabilityimport socket@@ -335,6 +350,7 @@ def create_hnsw_embedding_server(try:logger.debug("🔍 Waiting for ZMQ message...")request_bytes = rep_socket.recv()+ last_activity[0] = time.time()except zmq.Again:continue@@ -402,6 +418,7 @@ def create_hnsw_embedding_server(# Add shutdown coordinationshutdown_event = threading.Event()+ last_activity = [time.time()]def shutdown_zmq_server():"""Gracefully shutdown ZMQ server."""@@ -454,6 +471,12 @@ def create_hnsw_embedding_server(# Keep the main thread alivetry:while not shutdown_event.is_set():+ if daemon_ttl > 0 and (time.time() - last_activity[0]) >= daemon_ttl:+ logger.info(+ f"No requests for {daemon_ttl} seconds, shutting down daemon on port {zmq_port}"+ )+ shutdown_zmq_server()+ returntime.sleep(0.1) # Check shutdown more frequentlyexcept KeyboardInterrupt:logger.info("HNSW Server shutting down...")@@ -492,6 +515,22 @@ if __name__ == "__main__":choices=["sentence-transformers", "openai", "mlx", "ollama"],help="Embedding backend mode",)+ parser.add_argument(+ "--enable-warmup",+ action="store_true",+ help="Preload model by running one warmup embedding at startup",+ )+ parser.add_argument(+ "--daemon-mode",+ action="store_true",+ help="Run as daemon mode (enables idle TTL checks)",+ )+ parser.add_argument(+ "--daemon-ttl",+ type=int,+ default=0,+ help="Idle TTL in seconds for daemon mode; 0 disables auto-exit",+ )args = parser.parse_args()@@ -502,4 +541,6 @@ if __name__ == "__main__":model_name=args.model_name,distance_metric=args.distance_metric,embedding_mode=args.embedding_mode,+ enable_warmup=args.enable_warmup,+ daemon_ttl=args.daemon_ttl if args.daemon_mode else 0,)diff --git a/packages/leann-core/src/leann/api.py b/packages/leann-core/src/leann/api.pyindex f6156ca..34440cf 100644--- a/packages/leann-core/src/leann/api.py+++ b/packages/leann-core/src/leann/api.py@@ -884,6 +884,8 @@ class LeannBuilder:embedding_mode=passage_meta_mode,passages_file=str(meta_path),distance_metric=distance_metric,+ use_daemon=False,+ enable_warmup=False,provider_options=passage_provider_options,)if not server_started:@@ -946,6 +948,8 @@ class LeannSearcher:index_path: str,enable_warmup: bool = True,recompute_embeddings: bool = True,+ use_daemon: bool = True,+ daemon_ttl_seconds: int = 900,**backend_kwargs,):# Fix path resolution for Colab and other environments@@ -985,9 +989,13 @@ class LeannSearcher:# Warmup flag: keep using the existing enable_warmup parameter,# but default it to True so cold-start happens earlier.self._warmup: bool = bool(enable_warmup)+ self._use_daemon: bool = bool(use_daemon)+ self._daemon_ttl_seconds: int = int(daemon_ttl_seconds)final_kwargs = {**self.meta_data.get("backend_kwargs", {}), **backend_kwargs}final_kwargs["enable_warmup"] = self._warmup+ final_kwargs["use_daemon"] = self._use_daemon+ final_kwargs["daemon_ttl_seconds"] = self._daemon_ttl_secondsif self.embedding_options:final_kwargs.setdefault("embedding_options", self.embedding_options)self.backend_impl: LeannBackendSearcherInterface = backend_factory.searcher(@@ -997,23 +1005,17 @@ class LeannSearcher:# Optional one-shot warmup at construction time to hide cold-start latency.if self._warmup:- try:- _ = self.backend_impl.compute_query_embedding(- "__LEANN_WARMUP__",- use_server_if_available=self.recompute_embeddings,- )- except Exception as exc:- logger.warning(f"Warmup embedding failed (ignored): {exc}")+ self.warmup()- # Optional one-shot warmup at construction time to hide cold-start latency.- if self._warmup:- try:- _ = self.backend_impl.compute_query_embedding(- "__LEANN_WARMUP__",- use_server_if_available=self.recompute_embeddings,- )- except Exception as exc:- logger.warning(f"Warmup embedding failed (ignored): {exc}")+ def warmup(self) -> None:+ """Warm up embedding path so first user query is faster."""+ try:+ _ = self.backend_impl.compute_query_embedding(+ "__LEANN_WARMUP__",+ use_server_if_available=self.recompute_embeddings,+ )+ except Exception as exc:+ logger.warning(f"Warmup embedding failed (ignored): {exc}")def search(self,@@ -1109,6 +1111,9 @@ class LeannSearcher:zmq_port = self.backend_impl._ensure_server_running(self.meta_path_str,port=expected_zmq_port,+ enable_warmup=self._warmup,+ use_daemon=self._use_daemon,+ daemon_ttl_seconds=self._daemon_ttl_seconds,**kwargs,)del expected_zmq_portdiff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.pyindex d4d2907..59ee874 100644--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@ -14,6 +14,7 @@ from llama_index.core.node_parser import SentenceSplitterfrom tqdm import tqdmfrom .api import LeannBuilder, LeannChat, LeannSearcher+from .embedding_server_manager import EmbeddingServerManagerfrom .interactive_utils import create_cli_sessionfrom .registry import register_project_directoryfrom .settings import (@@ -370,6 +371,81 @@ Examples:default=None,help="Prompt template to prepend to query for embedding (e.g., 'query: ' for search)",)+ search_parser.add_argument(+ "--daemon",+ dest="use_daemon",+ action=argparse.BooleanOptionalAction,+ default=True,+ help="Enable/disable cross-process daemon reuse for embedding server (default: enabled)",+ )+ search_parser.add_argument(+ "--daemon-ttl",+ type=int,+ default=900,+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",+ )+ search_parser.add_argument(+ "--warmup",+ dest="enable_warmup",+ action=argparse.BooleanOptionalAction,+ default=True,+ help="Enable/disable warmup when starting embedding server (default: enabled)",+ )++ # Warmup command+ warmup_parser = subparsers.add_parser("warmup", help="Warm up an index embedding server")+ warmup_parser.add_argument("index_name", help="Index name")+ warmup_parser.add_argument(+ "--daemon",+ dest="use_daemon",+ action=argparse.BooleanOptionalAction,+ default=True,+ help="Enable/disable daemon mode for warmup (default: enabled)",+ )+ warmup_parser.add_argument(+ "--daemon-ttl",+ type=int,+ default=900,+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",+ )+ warmup_parser.add_argument(+ "--warmup",+ dest="enable_warmup",+ action=argparse.BooleanOptionalAction,+ default=True,+ help="Enable/disable warmup request itself (default: enabled)",+ )++ # Daemon command+ daemon_parser = subparsers.add_parser("daemon", help="Manage embedding daemons")+ daemon_subparsers = daemon_parser.add_subparsers(dest="daemon_command")++ daemon_start = daemon_subparsers.add_parser("start", help="Start daemon for an index")+ daemon_start.add_argument("index_name", help="Index name")+ daemon_start.add_argument(+ "--daemon-ttl",+ type=int,+ default=900,+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",+ )+ daemon_start.add_argument(+ "--warmup",+ dest="enable_warmup",+ action=argparse.BooleanOptionalAction,+ default=True,+ help="Enable/disable startup warmup (default: enabled)",+ )++ daemon_stop = daemon_subparsers.add_parser("stop", help="Stop daemon(s)")+ daemon_stop.add_argument("index_name", nargs="?", help="Index name to stop")+ daemon_stop.add_argument(+ "--all",+ action="store_true",+ help="Stop all LEANN embedding daemons",+ )++ daemon_status = daemon_subparsers.add_parser("status", help="Show daemon status")+ daemon_status.add_argument("index_name", nargs="?", help="Optional index name filter")# Ask commandask_parser = subparsers.add_parser("ask", help="Ask questions")@@ -1814,111 +1890,105 @@ Examples:print(f" - {file_path}")print(f" chunks: {chunk_display}")- async def search_documents(self, args):- index_name = args.index_name- query = args.query-- # First try to find the index in current project- index_path = self.get_index_path(index_name)+ def _resolve_index_path(+ self,+ index_name: str,+ *,+ non_interactive: bool = True,+ purpose: str = "use",+ ) -> Optional[str]:+ """Resolve index path from current project or registered projects."""if self.index_exists(index_name):- # Found in current project, use it- pass- else:- # Search across all registered projects (like list_indexes does)- all_matches = self._find_all_matching_indexes(index_name)- if not all_matches:- print(- f"Index '{index_name}' not found. Use 'leann build {index_name} --docs <dir> [<dir2> ...]' to create it."- )- return- elif len(all_matches) == 1:- # Found exactly one match, use it- match = all_matches[0]- if match["kind"] == "cli":- index_path = str(match["index_dir"] / "documents.leann")- else:- # App format: use the meta file to construct the path- meta_file = match["meta_file"]- file_base = match["file_base"]- index_path = str(meta_file.parent / f"{file_base}.leann")+ return self.get_index_path(index_name)+ all_matches = self._find_all_matching_indexes(index_name)+ if not all_matches:+ print(+ f"Index '{index_name}' not found. Use 'leann build {index_name} --docs <dir> [<dir2> ...]' to create it."+ )+ return None++ def _match_to_path(match: dict[str, Any]) -> str:+ if match["kind"] == "cli":+ return str(match["index_dir"] / "documents.leann")+ meta_file = match["meta_file"]+ file_base = match["file_base"]+ return str(meta_file.parent / f"{file_base}.leann")++ if len(all_matches) == 1:+ match = all_matches[0]+ project_info = (+ "current project"+ if match["is_current"]+ else f"project '{match['project_path'].name}'"+ )+ print(f"Using index '{index_name}' from {project_info}")+ return _match_to_path(match)++ if non_interactive:+ current_matches = [m for m in all_matches if m["is_current"]]+ match = current_matches[0] if current_matches else all_matches[0]+ location_desc = (+ "current project"+ if match["is_current"]+ else f"project '{match['project_path'].name}'"+ )+ print(+ f"Found {len(all_matches)} indexes named '{index_name}', using index from {location_desc}"+ )+ return _match_to_path(match)++ print(f"Found {len(all_matches)} indexes named '{index_name}':")+ for i, match in enumerate(all_matches, 1):+ project_path = match["project_path"]+ is_current = match["is_current"]+ kind = match.get("kind", "cli")+ if is_current:+ print(f" {i}. 🏠 Current project ({'CLI' if kind == 'cli' else 'APP'})")+ else:+ print(f" {i}. 📂 {project_path.name} ({'CLI' if kind == 'cli' else 'APP'})")++ try:+ choice = input(f"Which index to {purpose}? (1-{len(all_matches)}): ").strip()+ choice_idx = int(choice) - 1+ if 0 <= choice_idx < len(all_matches):+ match = all_matches[choice_idx]project_info = ("current project"if match["is_current"]else f"project '{match['project_path'].name}'")print(f"Using index '{index_name}' from {project_info}")- else:- # Multiple matches found- if args.non_interactive:- # Non-interactive mode: automatically select the best match- # Priority: current project first, then first available- current_matches = [m for m in all_matches if m["is_current"]]- if current_matches:- match = current_matches[0]- location_desc = "current project"- else:- match = all_matches[0]- location_desc = f"project '{match['project_path'].name}'"-- if match["kind"] == "cli":- index_path = str(match["index_dir"] / "documents.leann")- else:- meta_file = match["meta_file"]- file_base = match["file_base"]- index_path = str(meta_file.parent / f"{file_base}.leann")+ return _match_to_path(match)+ print("Invalid choice. Aborting.")+ return None+ except (ValueError, KeyboardInterrupt):+ print("Invalid input. Aborting.")+ return None- print(- f"Found {len(all_matches)} indexes named '{index_name}', using index from {location_desc}"- )- else:- # Interactive mode: ask user to choose- print(f"Found {len(all_matches)} indexes named '{index_name}':")- for i, match in enumerate(all_matches, 1):- project_path = match["project_path"]- is_current = match["is_current"]- kind = match.get("kind", "cli")-- if is_current:- print(- f" {i}. 🏠 Current project ({'CLI' if kind == 'cli' else 'APP'})"- )- else:- print(- f" {i}. 📂 {project_path.name} ({'CLI' if kind == 'cli' else 'APP'})"- )+ async def search_documents(self, args):+ index_name = args.index_name+ query = args.query- try:- choice = input(f"Which index to search? (1-{len(all_matches)}): ").strip()- choice_idx = int(choice) - 1- if 0 <= choice_idx < len(all_matches):- match = all_matches[choice_idx]- if match["kind"] == "cli":- index_path = str(match["index_dir"] / "documents.leann")- else:- meta_file = match["meta_file"]- file_base = match["file_base"]- index_path = str(meta_file.parent / f"{file_base}.leann")-- project_info = (- "current project"- if match["is_current"]- else f"project '{match['project_path'].name}'"- )- print(f"Using index '{index_name}' from {project_info}")- else:- print("Invalid choice. Aborting search.")- return- except (ValueError, KeyboardInterrupt):- print("Invalid input. Aborting search.")- return+ index_path = self._resolve_index_path(+ index_name,+ non_interactive=args.non_interactive,+ purpose="search",+ )+ if not index_path:+ return# Build provider_options for runtime overrideprovider_options = {}if args.embedding_prompt_template:provider_options["prompt_template"] = args.embedding_prompt_template- searcher = LeannSearcher(index_path=index_path)+ searcher = LeannSearcher(+ index_path=index_path,+ enable_warmup=args.enable_warmup,+ use_daemon=args.use_daemon,+ daemon_ttl_seconds=args.daemon_ttl,+ )results = searcher.search(query,top_k=args.top_k,@@ -1954,6 +2024,105 @@ Examples:print(f" Source: {result.metadata.get('source', '')}")print()+ async def warmup_index(self, args):+ index_path = self._resolve_index_path(+ args.index_name,+ non_interactive=True,+ purpose="warm up",+ )+ if not index_path:+ return++ searcher = LeannSearcher(+ index_path=index_path,+ recompute_embeddings=True,+ enable_warmup=args.enable_warmup,+ use_daemon=args.use_daemon,+ daemon_ttl_seconds=args.daemon_ttl,+ )+ if args.enable_warmup:+ searcher.warmup()+ print(+ f"Warmed index '{args.index_name}' (daemon={'on' if args.use_daemon else 'off'}, ttl={args.daemon_ttl}s)"+ )++ async def daemon_command(self, args):+ if not args.daemon_command:+ print("Please specify one of: start, stop, status")+ return++ if args.daemon_command == "status":+ records = EmbeddingServerManager.list_daemons()+ if args.index_name:+ index_path = self._resolve_index_path(+ args.index_name,+ non_interactive=True,+ purpose="check daemon status for",+ )+ if not index_path:+ return+ meta_path = str(Path(f"{index_path}.meta.json").resolve())+ records = [+ r+ for r in records+ if r.get("config_signature", {}).get("passages_file") == meta_path+ ]++ if not records:+ print("No active embedding daemons.")+ return++ print(f"Active embedding daemons: {len(records)}")+ for record in records:+ cfg = record.get("config_signature", {})+ print(+ f"- pid={record.get('pid')} port={record.get('port')} backend={record.get('backend_module_name')} model={cfg.get('model_name')}"+ )+ return++ if args.daemon_command == "start":+ index_path = self._resolve_index_path(+ args.index_name,+ non_interactive=True,+ purpose="start daemon for",+ )+ if not index_path:+ return++ searcher = LeannSearcher(+ index_path=index_path,+ recompute_embeddings=True,+ enable_warmup=args.enable_warmup,+ use_daemon=True,+ daemon_ttl_seconds=args.daemon_ttl,+ )+ searcher.warmup()+ print(+ f"Daemon started for '{args.index_name}' (ttl={args.daemon_ttl}s, warmup={'on' if args.enable_warmup else 'off'})"+ )+ return++ if args.daemon_command == "stop":+ if args.all:+ stopped = EmbeddingServerManager.stop_daemons()+ print(f"Stopped {stopped} daemon(s).")+ return++ if not args.index_name:+ print("Provide an index name or pass --all.")+ return++ index_path = self._resolve_index_path(+ args.index_name,+ non_interactive=True,+ purpose="stop daemon for",+ )+ if not index_path:+ return+ meta_path = str(Path(f"{index_path}.meta.json").resolve())+ stopped = EmbeddingServerManager.stop_daemons(passages_file=meta_path)+ print(f"Stopped {stopped} daemon(s) for index '{args.index_name}'.")+async def ask_questions(self, args):index_name = args.index_nameindex_path = self.get_index_path(index_name)@@ -2148,6 +2317,11 @@ Examples:elif args.command == "search":with suppress_cpp_output(suppress):await self.search_documents(args)+ elif args.command == "warmup":+ with suppress_cpp_output(suppress):+ await self.warmup_index(args)+ elif args.command == "daemon":+ await self.daemon_command(args)elif args.command == "ask":with suppress_cpp_output(suppress):await self.ask_questions(args)diff --git a/packages/leann-core/src/leann/embedding_server_manager.py b/packages/leann-core/src/leann/embedding_server_manager.pyindex b9224ac..ac95e51 100644--- a/packages/leann-core/src/leann/embedding_server_manager.py+++ b/packages/leann-core/src/leann/embedding_server_manager.py@@ -1,4 +1,6 @@import atexit+import contextlib+import hashlibimport jsonimport loggingimport os@@ -7,7 +9,7 @@ import subprocessimport sysimport timefrom pathlib import Path-from typing import Optional+from typing import Any, Optionalfrom .settings import encode_provider_options@@ -20,6 +22,7 @@ logging.basicConfig(format="%(levelname)s - %(name)s - %(message)s",)logger = logging.getLogger(__name__)+_LOCK_STALE_SECONDS = 600def _is_colab_environment() -> bool:@@ -46,6 +49,17 @@ def _check_port(port: int) -> bool:return s.connect_ex(("localhost", port)) == 0+def _pid_is_alive(pid: int) -> bool:+ """Best-effort liveness check for a process id."""+ if pid <= 0:+ return False+ try:+ os.kill(pid, 0)+ return True+ except OSError:+ return False++# Note: All cross-process scanning helpers removed for simplicity@@ -146,6 +160,8 @@ class EmbeddingServerManager:self.server_port: Optional[int] = None# Track last-started config for in-process reuse onlyself._server_config: Optional[dict] = None+ self._daemon_mode = False+ self._registry_path: Optional[Path] = Noneself._atexit_registered = False# Also register a weakref finalizer to ensure cleanup when manager is GC'edtry:@@ -166,12 +182,16 @@ class EmbeddingServerManager:# passages_file may be present in kwargs for server CLI, but we don't need it hereprovider_options = kwargs.pop("provider_options", None)passages_file = kwargs.get("passages_file", "")+ distance_metric = kwargs.get("distance_metric", "")+ use_daemon = bool(kwargs.get("use_daemon", True))+ daemon_ttl_seconds = int(kwargs.get("daemon_ttl_seconds", 900))config_signature = self._build_config_signature(model_name=model_name,embedding_mode=embedding_mode,provider_options=provider_options,passages_file=passages_file,+ distance_metric=distance_metric,)# If this manager already has a live server, just reuse it@@ -184,11 +204,22 @@ class EmbeddingServerManager:logger.info("Reusing in-process server")return True, self.server_port- # Configuration changed, stop existing server before starting a new one- if self.server_process and self.server_process.poll() is None:+ # Configuration changed, stop existing ephemeral server before starting a new one+ if self.server_process and self.server_process.poll() is None and not self._daemon_mode:logger.info("Existing server configuration differs; restarting embedding server")self.stop_server()+ # Reuse an already-running daemon from registry if possible.+ if use_daemon and not _is_colab_environment():+ with self._registry_lock(config_signature):+ adopted = self._adopt_registered_server(config_signature)+ if adopted is not None:+ self.server_process = None+ self.server_port = adopted+ self._server_config = config_signature+ self._daemon_mode = True+ return True, adopted+# For Colab environment, use a different strategyif _is_colab_environment():logger.info("Detected Colab environment, using alternative startup strategy")@@ -208,8 +239,34 @@ class EmbeddingServerManager:logger.error("No available ports found")return False, port- # Start a new server- return self._start_new_server(+ # Start a new server (guarded by lock in daemon mode to avoid race).+ if use_daemon and not _is_colab_environment():+ with self._registry_lock(config_signature):+ adopted = self._adopt_registered_server(config_signature)+ if adopted is not None:+ self.server_process = None+ self.server_port = adopted+ self._server_config = config_signature+ self._daemon_mode = True+ return True, adopted+ started, actual_port = self._start_new_server(+ actual_port,+ model_name,+ embedding_mode,+ provider_options=provider_options,+ config_signature=config_signature,+ **kwargs,+ )+ if started:+ self._daemon_mode = True+ self._registry_path = self._write_registry_record(+ port=actual_port,+ config_signature=config_signature,+ daemon_ttl_seconds=daemon_ttl_seconds,+ )+ return started, actual_port++ started, actual_port = self._start_new_server(actual_port,model_name,embedding_mode,@@ -217,6 +274,9 @@ class EmbeddingServerManager:config_signature=config_signature,**kwargs,)+ if started:+ self._daemon_mode = False+ return started, actual_portdef _build_config_signature(self,@@ -225,12 +285,17 @@ class EmbeddingServerManager:embedding_mode: str,provider_options: Optional[dict],passages_file: Optional[str],+ distance_metric: Optional[str],) -> dict:"""Create a signature describing the current server configuration."""+ passages_path = ""+ if passages_file:+ passages_path = _safe_resolve(Path(passages_file))return {"model_name": model_name,- "passages_file": passages_file or "",+ "passages_file": passages_path,"embedding_mode": embedding_mode,+ "distance_metric": distance_metric or "","provider_options": provider_options or {},"passages_signature": _build_passages_signature(passages_file),}@@ -337,6 +402,12 @@ class EmbeddingServerManager:command.extend(["--embedding-mode", embedding_mode])if kwargs.get("distance_metric"):command.extend(["--distance-metric", kwargs["distance_metric"]])+ if kwargs.get("enable_warmup", True):+ command.append("--enable-warmup")+ if kwargs.get("use_daemon", True):+ command.append("--daemon-mode")+ ttl = int(kwargs.get("daemon_ttl_seconds", 900))+ command.extend(["--daemon-ttl", str(ttl)])return command@@ -441,6 +512,15 @@ class EmbeddingServerManager:def stop_server(self):"""Stops the embedding server process if it's running."""+ if self._daemon_mode:+ # Daemon is intentionally process-global: this manager detaches by default.+ self.server_process = None+ self.server_port = None+ self._server_config = None+ self._daemon_mode = False+ self._registry_path = None+ return+if not self.server_process:return@@ -505,7 +585,7 @@ class EmbeddingServerManager:passdef _adopt_existing_server(self, *args, **kwargs) -> None:- # Removed: cross-process adoption no longer supported+ # Legacy no-op retained for compatibility.returndef _launch_server_process_colab(@@ -572,3 +652,182 @@ class EmbeddingServerManager:logger.error(f"Colab server failed to start within {max_wait} seconds.")self.stop_server()return False, port++ @staticmethod+ def _registry_dir() -> Path:+ return Path.home() / ".leann" / "servers"++ @contextlib.contextmanager+ def _registry_lock(self, config_signature: dict[str, Any]):+ """Best-effort cross-process lock around a daemon registry key."""+ lock_file = None+ lock_info_path: Optional[Path] = None+ try:+ lock_path = self._registry_dir()+ lock_path.mkdir(parents=True, exist_ok=True)+ lock_key = self._registry_key(config_signature)+ lock_file = (lock_path / f"{lock_key}.lock").open("a+")+ lock_info_path = lock_path / f"{lock_key}.lockinfo.json"+ self._recover_stale_lock_info(lock_info_path)+ try:+ import fcntl++ fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)+ except Exception:+ # Non-POSIX or unavailable locking: proceed without hard lock.+ pass+ self._write_lock_info(lock_info_path)+ yield+ finally:+ if lock_info_path is not None:+ lock_info_path.unlink(missing_ok=True)+ if lock_file is not None:+ try:+ import fcntl++ fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)+ except Exception:+ pass+ lock_file.close()++ def _recover_stale_lock_info(self, lock_info_path: Path) -> None:+ if not lock_info_path.exists():+ return+ try:+ info = json.loads(lock_info_path.read_text(encoding="utf-8"))+ pid = int(info.get("pid") or 0)+ ts = float(info.get("ts") or 0)+ except Exception:+ lock_info_path.unlink(missing_ok=True)+ return++ age = (time.time() - ts) if ts else (_LOCK_STALE_SECONDS + 1)+ if age > _LOCK_STALE_SECONDS or (pid > 0 and not _pid_is_alive(pid)):+ lock_info_path.unlink(missing_ok=True)++ def _write_lock_info(self, lock_info_path: Path) -> None:+ payload = {"pid": os.getpid(), "ts": time.time()}+ tmp_path = lock_info_path.with_suffix(".tmp")+ tmp_path.write_text(json.dumps(payload), encoding="utf-8")+ os.replace(tmp_path, lock_info_path)++ def _registry_key(self, config_signature: dict[str, Any]) -> str:+ payload = {+ "backend_module_name": self.backend_module_name,+ "config_signature": config_signature,+ }+ encoded = json.dumps(payload, sort_keys=True, ensure_ascii=True).encode("utf-8")+ return hashlib.sha256(encoded).hexdigest()++ def _write_registry_record(+ self,+ *,+ port: int,+ config_signature: dict[str, Any],+ daemon_ttl_seconds: int,+ ) -> Path:+ registry_dir = self._registry_dir()+ registry_dir.mkdir(parents=True, exist_ok=True)+ registry_path = registry_dir / f"{self._registry_key(config_signature)}.json"+ record = {+ "pid": self.server_process.pid if self.server_process else None,+ "port": port,+ "backend_module_name": self.backend_module_name,+ "daemon_ttl_seconds": int(daemon_ttl_seconds),+ "created_at": time.time(),+ "config_signature": config_signature,+ }+ tmp_path = registry_path.with_suffix(".json.tmp")+ tmp_path.write_text(json.dumps(record, indent=2), encoding="utf-8")+ os.replace(tmp_path, registry_path)+ return registry_path++ def _adopt_registered_server(self, config_signature: dict[str, Any]) -> Optional[int]:+ registry_dir = self._registry_dir()+ if not registry_dir.exists():+ return None++ target = registry_dir / f"{self._registry_key(config_signature)}.json"+ if not target.exists():+ return None++ try:+ record = json.loads(target.read_text(encoding="utf-8"))+ except Exception:+ target.unlink(missing_ok=True)+ return None++ if record.get("backend_module_name") != self.backend_module_name:+ target.unlink(missing_ok=True)+ return None+ if record.get("config_signature") != config_signature:+ target.unlink(missing_ok=True)+ return None++ pid = int(record.get("pid") or 0)+ port = int(record.get("port") or 0)+ if not _pid_is_alive(pid) or not _check_port(port):+ target.unlink(missing_ok=True)+ return None++ self._registry_path = target+ logger.info("Reusing daemonized embedding server on port %s", port)+ return port++ @classmethod+ def list_daemons(cls) -> list[dict[str, Any]]:+ registry_dir = cls._registry_dir()+ if not registry_dir.exists():+ return []++ records: list[dict[str, Any]] = []+ for record_path in sorted(registry_dir.glob("*.json")):+ try:+ record = json.loads(record_path.read_text(encoding="utf-8"))+ except Exception:+ record_path.unlink(missing_ok=True)+ continue++ pid = int(record.get("pid") or 0)+ port = int(record.get("port") or 0)+ alive = _pid_is_alive(pid) and _check_port(port)+ if not alive:+ record_path.unlink(missing_ok=True)+ continue++ record["record_path"] = str(record_path)+ records.append(record)+ return records++ @classmethod+ def stop_daemons(+ cls,+ *,+ backend_module_name: Optional[str] = None,+ passages_file: Optional[str] = None,+ ) -> int:+ resolved_passages_file = _safe_resolve(Path(passages_file)) if passages_file else None+ stopped = 0+ for record in cls.list_daemons():+ if backend_module_name and record.get("backend_module_name") != backend_module_name:+ continue++ record_passages = (+ record.get("config_signature", {}).get("passages_file")+ if isinstance(record.get("config_signature"), dict)+ else None+ )+ if resolved_passages_file and record_passages != resolved_passages_file:+ continue++ pid = int(record.get("pid") or 0)+ try:+ os.kill(pid, 15)+ stopped += 1+ except OSError:+ pass++ record_path = record.get("record_path")+ if record_path:+ Path(record_path).unlink(missing_ok=True)+ return stoppeddiff --git a/packages/leann-core/src/leann/searcher_base.py b/packages/leann-core/src/leann/searcher_base.pyindex 1def0ae..a891782 100644--- a/packages/leann-core/src/leann/searcher_base.py+++ b/packages/leann-core/src/leann/searcher_base.py@@ -42,6 +42,9 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):self.embedding_mode = self.meta.get("embedding_mode", "sentence-transformers")self.embedding_options = self.meta.get("embedding_options", {})+ self.enable_warmup = bool(kwargs.get("enable_warmup", True))+ self.use_daemon = bool(kwargs.get("use_daemon", True))+ self.daemon_ttl_seconds = int(kwargs.get("daemon_ttl_seconds", 900))self.embedding_server_manager = EmbeddingServerManager(backend_module_name=backend_module_name,@@ -88,7 +91,9 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):embedding_mode=self.embedding_mode,passages_file=passages_source_file,distance_metric=distance_metric,- enable_warmup=kwargs.get("enable_warmup", False),+ enable_warmup=kwargs.get("enable_warmup", self.enable_warmup),+ use_daemon=kwargs.get("use_daemon", self.use_daemon),+ daemon_ttl_seconds=kwargs.get("daemon_ttl_seconds", self.daemon_ttl_seconds),provider_options=search_provider_options,)if not server_started:@@ -131,7 +136,11 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):passages_source_file = self.index_dir / f"{self.index_path.name}.meta.json"# Convert to absolute path to ensure server can find itzmq_port = self._ensure_server_running(- str(passages_source_file.resolve()), zmq_port+ str(passages_source_file.resolve()),+ zmq_port,+ enable_warmup=self.enable_warmup,+ use_daemon=self.use_daemon,+ daemon_ttl_seconds=self.daemon_ttl_seconds,)return self._compute_embedding_via_server([query], zmq_port)[diff --git a/tests/support/fake_embedding_server_module.py b/tests/support/fake_embedding_server_module.pynew file mode 100644index 0000000..a4c64cf--- /dev/null+++ b/tests/support/fake_embedding_server_module.py@@ -0,0 +1,59 @@+import argparse+import signal+import socket+import time+++def main() -> None:+ parser = argparse.ArgumentParser(description="Fake embedding server for e2e tests")+ parser.add_argument("--zmq-port", type=int, required=True)+ parser.add_argument("--model-name", type=str, required=True)+ parser.add_argument("--passages-file", type=str, default="")+ parser.add_argument("--distance-metric", type=str, default="")+ parser.add_argument("--embedding-mode", type=str, default="sentence-transformers")+ parser.add_argument("--enable-warmup", action="store_true")+ parser.add_argument("--daemon-mode", action="store_true")+ parser.add_argument("--daemon-ttl", type=int, default=0)+ args = parser.parse_args()++ stop = {"value": False}+ last_activity = time.time()++ def _handle_signal(signum, frame):+ stop["value"] = True++ signal.signal(signal.SIGTERM, _handle_signal)+ signal.signal(signal.SIGINT, _handle_signal)++ # Bind and keep accepting connections so _check_port sees the process as alive.+ server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)+ server.bind(("127.0.0.1", args.zmq_port))+ server.listen(16)+ server.settimeout(0.2)++ try:+ while not stop["value"]:+ if args.daemon_mode and args.daemon_ttl > 0:+ if (time.time() - last_activity) >= args.daemon_ttl:+ break+ try:+ conn, _addr = server.accept()+ # liveness probes connect+close without sending payload; do not+ # treat them as activity so TTL expiry can still be observed.+ try:+ conn.settimeout(0.01)+ payload = conn.recv(1)+ if payload:+ last_activity = time.time()+ except Exception:+ pass+ conn.close()+ except socket.timeout:+ pass+ finally:+ server.close()+++if __name__ == "__main__":+ main()diff --git a/tests/test_cli_daemon_workflow.py b/tests/test_cli_daemon_workflow.pynew file mode 100644index 0000000..43323e0--- /dev/null+++ b/tests/test_cli_daemon_workflow.py@@ -0,0 +1,212 @@+import argparse+import asyncio+from pathlib import Path+from typing import Any++from leann.cli import LeannCLI+++def test_search_passes_daemon_flags_to_searcher(monkeypatch):+ cli = LeannCLI()+ monkeypatch.setattr(+ cli,+ "_resolve_index_path",+ lambda *args, **kwargs: "/tmp/demo/documents.leann",+ )++ captured: dict[str, dict[str, Any]] = {"init": {}, "search": {}}++ class DummySearcher:+ def __init__(self, *args, **kwargs):+ captured["init"] = kwargs++ def search(self, *args, **kwargs):+ captured["search"] = kwargs+ return []++ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)++ args = argparse.Namespace(+ index_name="demo",+ query="hello",+ top_k=3,+ complexity=64,+ beam_width=1,+ prune_ratio=0.0,+ recompute_embeddings=True,+ pruning_strategy="global",+ non_interactive=True,+ show_metadata=False,+ embedding_prompt_template=None,+ use_daemon=True,+ daemon_ttl=222,+ enable_warmup=True,+ )+ asyncio.run(cli.search_documents(args))++ assert captured["init"]["enable_warmup"] is True+ assert captured["init"]["use_daemon"] is True+ assert captured["init"]["daemon_ttl_seconds"] == 222+ assert captured["search"]["recompute_embeddings"] is True+++def test_warmup_command_calls_searcher_warmup(monkeypatch):+ cli = LeannCLI()+ monkeypatch.setattr(+ cli,+ "_resolve_index_path",+ lambda *args, **kwargs: "/tmp/demo/documents.leann",+ )++ state: dict[str, int] = {"warmup_called": 0}++ class DummySearcher:+ def __init__(self, *args, **kwargs):+ pass++ def warmup(self):+ state["warmup_called"] += 1++ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)++ args = argparse.Namespace(+ index_name="demo",+ use_daemon=True,+ daemon_ttl=120,+ enable_warmup=True,+ )+ asyncio.run(cli.warmup_index(args))+ assert state["warmup_called"] == 1+++def test_daemon_status_filters_by_index(monkeypatch, capsys):+ cli = LeannCLI()+ monkeypatch.setattr(+ cli,+ "_resolve_index_path",+ lambda *args, **kwargs: "/tmp/demo/documents.leann",+ )+ meta_path = str(Path("/tmp/demo/documents.leann.meta.json").resolve())++ monkeypatch.setattr(+ "leann.cli.EmbeddingServerManager.list_daemons",+ lambda: [+ {+ "pid": 101,+ "port": 5557,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {"passages_file": meta_path, "model_name": "m1"},+ },+ {+ "pid": 202,+ "port": 5558,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {+ "passages_file": "/tmp/other/doc.meta.json",+ "model_name": "m2",+ },+ },+ ],+ )++ args = argparse.Namespace(daemon_command="status", index_name="demo")+ asyncio.run(cli.daemon_command(args))+ out = capsys.readouterr().out+ assert "Active embedding daemons: 1" in out+ assert "pid=101" in out+ assert "pid=202" not in out+++def test_daemon_stop_by_index_calls_stop_daemons(monkeypatch):+ cli = LeannCLI()+ monkeypatch.setattr(+ cli,+ "_resolve_index_path",+ lambda *args, **kwargs: "/tmp/demo/documents.leann",+ )+ captured: dict[str, dict[str, Any]] = {"kwargs": {}}++ def fake_stop_daemons(**kwargs):+ captured["kwargs"] = kwargs+ return 1++ monkeypatch.setattr("leann.cli.EmbeddingServerManager.stop_daemons", fake_stop_daemons)++ args = argparse.Namespace(daemon_command="stop", index_name="demo", all=False)+ asyncio.run(cli.daemon_command(args))++ assert captured["kwargs"]["passages_file"].endswith("documents.leann.meta.json")+++def test_daemon_start_calls_searcher_warmup(monkeypatch):+ cli = LeannCLI()+ monkeypatch.setattr(+ cli,+ "_resolve_index_path",+ lambda *args, **kwargs: "/tmp/demo/documents.leann",+ )++ state: dict[str, Any] = {"warmup_called": 0, "init_kwargs": {}}++ class DummySearcher:+ def __init__(self, *args, **kwargs):+ state["init_kwargs"] = kwargs++ def warmup(self):+ state["warmup_called"] += 1++ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)++ args = argparse.Namespace(+ daemon_command="start",+ index_name="demo",+ daemon_ttl=88,+ enable_warmup=True,+ )+ asyncio.run(cli.daemon_command(args))++ assert state["warmup_called"] == 1+ assert state["init_kwargs"]["use_daemon"] is True+ assert state["init_kwargs"]["daemon_ttl_seconds"] == 88+++def test_daemon_status_all_lists_records(monkeypatch, capsys):+ cli = LeannCLI()+ monkeypatch.setattr(+ "leann.cli.EmbeddingServerManager.list_daemons",+ lambda: [+ {+ "pid": 301,+ "port": 6001,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {"model_name": "m-a"},+ },+ {+ "pid": 302,+ "port": 6002,+ "backend_module_name": "leann_backend_diskann.diskann_embedding_server",+ "config_signature": {"model_name": "m-b"},+ },+ ],+ )+ args = argparse.Namespace(daemon_command="status", index_name=None)+ asyncio.run(cli.daemon_command(args))+ out = capsys.readouterr().out+ assert "Active embedding daemons: 2" in out+ assert "pid=301" in out+ assert "pid=302" in out+++def test_daemon_stop_all_calls_manager(monkeypatch):+ cli = LeannCLI()+ captured = {"called": False}++ def fake_stop_daemons(**kwargs):+ captured["called"] = True+ assert kwargs == {}+ return 2++ monkeypatch.setattr("leann.cli.EmbeddingServerManager.stop_daemons", fake_stop_daemons)+ args = argparse.Namespace(daemon_command="stop", index_name=None, all=True)+ asyncio.run(cli.daemon_command(args))+ assert captured["called"] is Truediff --git a/tests/test_embedding_server_cli_flags.py b/tests/test_embedding_server_cli_flags.pynew file mode 100644index 0000000..5cc8281--- /dev/null+++ b/tests/test_embedding_server_cli_flags.py@@ -0,0 +1,39 @@+import os+import subprocess+import sys+from pathlib import Path+++def _run_help(module_name: str) -> str:+ root = Path(__file__).resolve().parents[1]+ extra_paths = [+ str(root / "packages" / "leann-core" / "src"),+ str(root / "packages" / "leann-backend-hnsw"),+ str(root / "packages" / "leann-backend-diskann"),+ ]+ env = os.environ.copy()+ existing = env.get("PYTHONPATH", "")+ env["PYTHONPATH"] = os.pathsep.join(extra_paths + ([existing] if existing else []))++ proc = subprocess.run(+ [sys.executable, "-m", module_name, "--help"],+ check=True,+ text=True,+ capture_output=True,+ env=env,+ )+ return proc.stdout+++def test_hnsw_server_help_has_daemon_and_warmup_flags():+ out = _run_help("leann_backend_hnsw.hnsw_embedding_server")+ assert "--enable-warmup" in out+ assert "--daemon-mode" in out+ assert "--daemon-ttl" in out+++def test_diskann_server_help_has_daemon_and_warmup_flags():+ out = _run_help("leann_backend_diskann.diskann_embedding_server")+ assert "--enable-warmup" in out+ assert "--daemon-mode" in out+ assert "--daemon-ttl" in outdiff --git a/tests/test_embedding_server_manager.py b/tests/test_embedding_server_manager.pyindex 71e91f3..8dd3d79 100644--- a/tests/test_embedding_server_manager.py+++ b/tests/test_embedding_server_manager.py@@ -1,13 +1,16 @@import json+import os+import threadingimport time+from typing import Any, castimport pytestfrom leann.embedding_server_manager import EmbeddingServerManagerclass DummyProcess:- def __init__(self):- self.pid = 12345+ def __init__(self, pid=12345):+ self.pid = pidself._terminated = Falsedef poll(self):@@ -102,6 +105,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):port=6000,model_name="test-model",passages_file=str(meta_path),+ use_daemon=False,)assert okassert port == 6000@@ -114,6 +118,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):port=6000,model_name="test-model",passages_file=str(meta_path),+ use_daemon=False,)assert okassert port_again == 6000@@ -128,6 +133,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):port=6000,model_name="test-model",passages_file=str(meta_path),+ use_daemon=False,)assert okassert port_third == 6000@@ -135,3 +141,373 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):updated_signature = start_calls[1]["passages_signature"]assert updated_signature != initial_signature+++def test_list_daemons_ignores_stale_records(tmp_path, monkeypatch):+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))++ stale = registry_dir / "stale.json"+ stale.write_text(+ json.dumps(+ {+ "pid": 999999,+ "port": 65531,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {"passages_file": "/tmp/a.meta.json"},+ }+ ),+ encoding="utf-8",+ )++ records = EmbeddingServerManager.list_daemons()+ assert records == []+ assert not stale.exists()+++def test_stop_daemons_filters_by_backend_and_passages(tmp_path, monkeypatch):+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))++ meta_path = (tmp_path / "x.meta.json").resolve()+ record = registry_dir / "daemon.json"+ record.write_text(+ json.dumps(+ {+ "pid": 12345,+ "port": 6001,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {"passages_file": str(meta_path)},+ }+ ),+ encoding="utf-8",+ )++ monkeypatch.setattr(+ EmbeddingServerManager,+ "list_daemons",+ classmethod(+ lambda cls: [+ {+ "pid": 12345,+ "port": 6001,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": {"passages_file": str(meta_path)},+ "record_path": str(record),+ }+ ]+ ),+ )++ killed: list[tuple[int, int]] = []++ def fake_kill(pid: int, sig: int):+ killed.append((pid, sig))++ monkeypatch.setattr(os, "kill", fake_kill)++ stopped = EmbeddingServerManager.stop_daemons(+ backend_module_name="leann_backend_hnsw.hnsw_embedding_server",+ passages_file=str(meta_path),+ )+ assert stopped == 1+ assert killed == [(12345, 15)]+ assert not record.exists()+++def test_daemon_registry_reuse_across_manager_instances(tmp_path, monkeypatch):+ """Second manager should adopt the daemon started by first manager."""+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))+ monkeypatch.setattr(+ "leann.embedding_server_manager._get_available_port",+ lambda start_port: start_port,+ )+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: True)+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: pid == 22222)++ starts = []++ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):+ starts.append((port, model_name, embedding_mode))+ self.server_process = DummyProcess(pid=22222)+ self.server_port = port+ self._server_config = kwargs.get("config_signature")+ return True, port++ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)++ manager1 = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ ok1, port1 = manager1.start_server(+ port=6011,+ model_name="test-model",+ use_daemon=True,+ daemon_ttl_seconds=120,+ )+ assert ok1 and port1 == 6011+ assert len(starts) == 1++ manager2 = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ ok2, port2 = manager2.start_server(+ port=6011,+ model_name="test-model",+ use_daemon=True,+ daemon_ttl_seconds=120,+ )+ assert ok2 and port2 == 6011+ # No second process spawn: adopted from registry.+ assert len(starts) == 1+ assert manager2.server_process is None+++def test_stale_registry_falls_back_to_fresh_start(tmp_path, monkeypatch):+ """If registry points to dead daemon, manager should start a new process."""+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))+ monkeypatch.setattr(+ "leann.embedding_server_manager._get_available_port",+ lambda start_port: start_port,+ )++ starts = []++ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):+ starts.append(port)+ self.server_process = DummyProcess(pid=33333)+ self.server_port = port+ self._server_config = kwargs.get("config_signature")+ return True, port++ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)++ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ signature = manager._build_config_signature(+ model_name="test-model",+ embedding_mode="sentence-transformers",+ provider_options=None,+ passages_file=None,+ distance_metric=None,+ )+ stale_file = registry_dir / f"{manager._registry_key(signature)}.json"+ stale_file.write_text(+ json.dumps(+ {+ "pid": 999999,+ "port": 6012,+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",+ "config_signature": signature,+ }+ ),+ encoding="utf-8",+ )++ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: False)++ ok, port = manager.start_server(+ port=6012,+ model_name="test-model",+ use_daemon=True,+ )+ assert ok and port == 6012+ assert starts == [6012]+ assert stale_file.exists()+ refreshed = json.loads(stale_file.read_text(encoding="utf-8"))+ assert refreshed["pid"] == 33333+++def test_build_server_command_includes_daemon_and_warmup_flags():+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ command = manager._build_server_command(+ port=6020,+ model_name="m",+ embedding_mode="sentence-transformers",+ distance_metric="mips",+ enable_warmup=True,+ use_daemon=True,+ daemon_ttl_seconds=321,+ )+ assert "--enable-warmup" in command+ assert "--daemon-mode" in command+ assert "--daemon-ttl" in command+ ttl_idx = command.index("--daemon-ttl")+ assert command[ttl_idx + 1] == "321"++ command_no_daemon = manager._build_server_command(+ port=6020,+ model_name="m",+ embedding_mode="sentence-transformers",+ enable_warmup=False,+ use_daemon=False,+ )+ assert "--daemon-mode" not in command_no_daemon+ assert "--enable-warmup" not in command_no_daemon+++def test_corrupted_registry_file_is_recovered_on_start(tmp_path, monkeypatch):+ """Invalid registry json should not block startup; file is replaced."""+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))+ monkeypatch.setattr(+ "leann.embedding_server_manager._get_available_port",+ lambda start_port: start_port,+ )++ starts = []++ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):+ starts.append(port)+ self.server_process = DummyProcess(pid=44444)+ self.server_port = port+ self._server_config = kwargs.get("config_signature")+ return True, port++ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)++ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ signature = manager._build_config_signature(+ model_name="test-model",+ embedding_mode="sentence-transformers",+ provider_options=None,+ passages_file=None,+ distance_metric=None,+ )+ record_path = registry_dir / f"{manager._registry_key(signature)}.json"+ record_path.write_text("{invalid-json", encoding="utf-8")++ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: False)++ ok, port = manager.start_server(port=6030, model_name="test-model", use_daemon=True)+ assert ok and port == 6030+ assert starts == [6030]+ data = json.loads(record_path.read_text(encoding="utf-8"))+ assert data["pid"] == 44444+++def test_stop_server_detaches_when_daemon_mode(monkeypatch):+ """Daemon mode should detach manager without terminating shared process."""+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ manager.server_process = cast(Any, DummyProcess(pid=55555))+ manager.server_port = 6031+ manager._server_config = {"model_name": "m"}+ manager._daemon_mode = True++ # If terminate is called this test should fail.+ called = {"terminate": 0}++ def fail_terminate():+ called["terminate"] += 1+ raise AssertionError("terminate should not be called in daemon detach path")++ manager.server_process.terminate = fail_terminate # type: ignore[method-assign]++ manager.stop_server()+ assert called["terminate"] == 0+ assert manager.server_process is None+ assert manager.server_port is None+ assert manager._server_config is None+++def test_concurrent_daemon_start_only_spawns_once(tmp_path, monkeypatch):+ """Concurrent calls should be serialized by registry lock for same signature."""+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))+ monkeypatch.setattr(+ "leann.embedding_server_manager._get_available_port",+ lambda start_port: start_port,+ )+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: True)+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: pid in (77777,))++ starts = []++ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):+ # Force overlap window between two starters.+ time.sleep(0.05)+ starts.append((self, port))+ self.server_process = DummyProcess(pid=77777)+ self.server_port = port+ self._server_config = kwargs.get("config_signature")+ return True, port++ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)++ results = []++ def runner():+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ ok, port = manager.start_server(port=6040, model_name="test-model", use_daemon=True)+ results.append((ok, port))++ t1 = threading.Thread(target=runner)+ t2 = threading.Thread(target=runner)+ t1.start()+ t2.start()+ t1.join(timeout=5)+ t2.join(timeout=5)++ assert len(results) == 2+ assert all(ok and port == 6040 for ok, port in results)+ # Exactly one actual process start, one adopts registry record.+ assert len(starts) == 1+++def test_registry_record_write_is_atomic(tmp_path, monkeypatch):+ """Registry writes should go through temp file + os.replace."""+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))++ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ manager.server_process = cast(Any, DummyProcess(pid=88888))++ calls = []+ real_replace = os.replace++ def tracked_replace(src, dst):+ calls.append((str(src), str(dst)))+ return real_replace(src, dst)++ monkeypatch.setattr(os, "replace", tracked_replace)++ path = manager._write_registry_record(+ port=6060,+ config_signature={"model_name": "m"},+ daemon_ttl_seconds=123,+ )+ assert path.exists()+ assert calls, "os.replace should be used for atomic write"+ src, dst = calls[0]+ assert src.endswith(".json.tmp")+ assert dst.endswith(".json")+++def test_stale_lock_info_removed_when_pid_dead(tmp_path, monkeypatch):+ registry_dir = tmp_path / "servers"+ registry_dir.mkdir()+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)++ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")+ signature = manager._build_config_signature(+ model_name="x",+ embedding_mode="sentence-transformers",+ provider_options=None,+ passages_file=None,+ distance_metric=None,+ )+ key = manager._registry_key(signature)+ lock_info = registry_dir / f"{key}.lockinfo.json"+ lock_info.write_text(json.dumps({"pid": 999999, "ts": time.time()}), encoding="utf-8")++ with manager._registry_lock(signature):+ pass++ assert not lock_info.exists()diff --git a/tests/test_embedding_server_manager_e2e.py b/tests/test_embedding_server_manager_e2e.pynew file mode 100644index 0000000..f2d45f5--- /dev/null+++ b/tests/test_embedding_server_manager_e2e.py@@ -0,0 +1,82 @@+import os+import time+from pathlib import Path++from leann.embedding_server_manager import EmbeddingServerManager+++def _configure_fake_module_env(monkeypatch):+ root = Path(__file__).resolve().parents[1]+ support_path = str(root / "tests" / "support")+ existing = os.environ.get("PYTHONPATH", "")+ joined = support_path if not existing else f"{support_path}{os.pathsep}{existing}"+ monkeypatch.setenv("PYTHONPATH", joined)+++def _wait_until(predicate, timeout=5.0, interval=0.05):+ deadline = time.time() + timeout+ while time.time() < deadline:+ if predicate():+ return True+ time.sleep(interval)+ return False+++def test_daemon_reuse_with_real_subprocess(tmp_path, monkeypatch):+ _configure_fake_module_env(monkeypatch)+ monkeypatch.setattr(+ EmbeddingServerManager, "_registry_dir", staticmethod(lambda: tmp_path / "servers")+ )++ manager1 = EmbeddingServerManager("fake_embedding_server_module")+ ok1, port1 = manager1.start_server(+ port=6151,+ model_name="fake-model",+ use_daemon=True,+ daemon_ttl_seconds=60,+ enable_warmup=True,+ )+ assert ok1 and port1 == 6151+ assert manager1.server_process is not None+ pid1 = manager1.server_process.pid++ manager2 = EmbeddingServerManager("fake_embedding_server_module")+ ok2, port2 = manager2.start_server(+ port=6151,+ model_name="fake-model",+ use_daemon=True,+ daemon_ttl_seconds=60,+ )+ assert ok2 and port2 == 6151+ # Adoption path: no newly spawned process object attached.+ assert manager2.server_process is None++ records = EmbeddingServerManager.list_daemons()+ assert len(records) == 1+ assert int(records[0]["pid"]) == pid1++ stopped = EmbeddingServerManager.stop_daemons(+ backend_module_name="fake_embedding_server_module"+ )+ assert stopped == 1+++def test_daemon_ttl_expiry_with_real_subprocess(tmp_path, monkeypatch):+ _configure_fake_module_env(monkeypatch)+ monkeypatch.setattr(+ EmbeddingServerManager, "_registry_dir", staticmethod(lambda: tmp_path / "servers")+ )++ manager = EmbeddingServerManager("fake_embedding_server_module")+ ok, port = manager.start_server(+ port=6152,+ model_name="fake-model",+ use_daemon=True,+ daemon_ttl_seconds=1,+ enable_warmup=False,+ )+ assert ok and port == 6152++ # Fake daemon should self-exit after idle TTL.+ expired = _wait_until(lambda: len(EmbeddingServerManager.list_daemons()) == 0, timeout=4.0)+ assert expireddiff --git a/tests/test_prompt_template_persistence.py b/tests/test_prompt_template_persistence.pyindex 56391ff..fe260ac 100644--- a/tests/test_prompt_template_persistence.py+++ b/tests/test_prompt_template_persistence.py@@ -607,6 +607,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:searcher.embedding_model = searcher.meta["embedding_model"]searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")searcher.embedding_options = searcher.meta.get("embedding_options", {})+ searcher.enable_warmup = False+ searcher.use_daemon = False+ searcher.daemon_ttl_seconds = 0# Mock compute_embeddings to capture the query textcaptured_queries = []@@ -662,11 +665,14 @@ class TestQueryTemplateApplicationInComputeEmbedding:searcher.embedding_model = searcher.meta["embedding_model"]searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")searcher.embedding_options = searcher.meta.get("embedding_options", {})+ searcher.enable_warmup = False+ searcher.use_daemon = False+ searcher.daemon_ttl_seconds = 0# Mock the server methods to capture the query textcaptured_queries = []- def mock_ensure_server_running(passages_file, port):+ def mock_ensure_server_running(passages_file, port, **kwargs):return portdef mock_compute_embedding_via_server(chunks, port):@@ -718,6 +724,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:searcher.embedding_model = searcher.meta["embedding_model"]searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")searcher.embedding_options = searcher.meta.get("embedding_options", {})+ searcher.enable_warmup = False+ searcher.use_daemon = False+ searcher.daemon_ttl_seconds = 0captured_queries = []@@ -768,6 +777,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:searcher.embedding_model = searcher.meta["embedding_model"]searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")searcher.embedding_options = searcher.meta.get("embedding_options", {})+ searcher.enable_warmup = False+ searcher.use_daemon = False+ searcher.daemon_ttl_seconds = 0query_template = "task: search result | query: "original_query = "vector database"@@ -791,7 +803,7 @@ class TestQueryTemplateApplicationInComputeEmbedding:# Capture queries from server pathserver_queries = []- def mock_ensure_server_running(passages_file, port):+ def mock_ensure_server_running(passages_file, port, **kwargs):return portdef mock_compute_embedding_via_server(chunks, port):@@ -843,6 +855,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:searcher.embedding_model = searcher.meta["embedding_model"]searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")searcher.embedding_options = searcher.meta.get("embedding_options", {})+ searcher.enable_warmup = False+ searcher.use_daemon = False+ searcher.daemon_ttl_seconds = 0captured_queries = []