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.

feat: Add HTTP API server for LEANN vector DB (#212)

Aakash Sureshadf160e10ee6
diff --git a/packages/leann-core/pyproject.toml b/packages/leann-core/pyproject.toml
index f4f6ad6..de1dd01 100644
--- a/packages/leann-core/pyproject.toml
+++ b/packages/leann-core/pyproject.toml
@@ -45,6 +45,11 @@ colab = [
"transformers>=4.30.0,<4.46", # 4.46.0 switches to PEP 604 typing (int | None), breaks Py3.9
"accelerate>=0.20.0,<1.0.0", # Limit accelerate version
]
+server = [
+ "fastapi>=0.115.0",
+ "pydantic>=2.0.0",
+ "uvicorn[standard]>=0.34.0",
+]
[project.scripts]
leann = "leann.cli:main"
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index 6a93748..6475631 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -406,6 +406,17 @@ Examples:
"--force", "-f", action="store_true", help="Force removal without confirmation"
)
+ # Serve command (HTTP API server)
+ serve_parser = subparsers.add_parser(
+ "serve", help="Start HTTP API server for LEANN vector DB"
+ )
+ serve_parser.add_argument(
+ "--host", type=str, default=None, help="Host to bind to (default: 0.0.0.0)"
+ )
+ serve_parser.add_argument(
+ "--port", type=int, default=None, help="Port to bind to (default: 8000)"
+ )
+
return parser
def register_project_dir(self):
@@ -1715,6 +1726,35 @@ Examples:
_ask_once(query)
+ async def serve_api(self, args):
+ """Start the HTTP API server."""
+ import os
+
+ try:
+ from .server import main as server_main
+
+ # Override host/port if provided via CLI args
+ if args.host:
+ os.environ["LEANN_SERVER_HOST"] = args.host
+ if args.port:
+ os.environ["LEANN_SERVER_PORT"] = str(args.port)
+
+ # Run the server (this is blocking, so we don't await it)
+ # The server_main function handles uvicorn.run which blocks
+ server_main()
+ except ImportError as e:
+ print(
+ "❌ HTTP server dependencies not installed.\n"
+ "Install them with:\n"
+ " uv pip install 'leann-core[server]'\n"
+ "or:\n"
+ " uv pip install 'fastapi>=0.115' 'pydantic>=2' 'uvicorn[standard]'\n"
+ )
+ raise SystemExit(1) from e
+ except Exception as e:
+ print(f"❌ Error starting server: {e}")
+ raise SystemExit(1) from e
+
async def run(self, args=None):
parser = self.create_parser()
@@ -1740,6 +1780,9 @@ Examples:
with suppress_cpp_output(suppress):
await self.search_documents(args)
elif args.command == "ask":
+ await self.ask_questions(args)
+ elif args.command == "serve":
+ await self.serve_api(args)
with suppress_cpp_output(suppress):
await self.ask_questions(args)
else:
diff --git a/packages/leann-core/src/leann/server.py b/packages/leann-core/src/leann/server.py
new file mode 100644
index 0000000..e58bfe6
--- /dev/null
+++ b/packages/leann-core/src/leann/server.py
@@ -0,0 +1,196 @@
+"""
+Minimal HTTP API server for LEANN.
+
+This exposes LEANN indexes over HTTP so clients can:
+- List available indexes
+- Run semantic search against an index
+
+The design intentionally keeps dependencies optional:
+- FastAPI + pydantic are imported lazily inside `create_app()`
+- uvicorn is imported lazily inside `main()`
+
+This way, core LEANN usage is unaffected unless you actually run the server.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from .api import LeannSearcher
+from .cli import LeannCLI
+
+
+def _ensure_fastapi():
+ """Lazy import FastAPI and Pydantic, with a clear error if missing."""
+ try:
+ from fastapi import FastAPI, HTTPException # type: ignore
+ from pydantic import BaseModel # type: ignore
+ except ImportError as e: # pragma: no cover - dependency error path
+ raise RuntimeError(
+ "FastAPI and pydantic are required for the LEANN HTTP server.\n"
+ "Install them with:\n\n"
+ " uv pip install 'fastapi>=0.115' 'pydantic>=2' 'uvicorn[standard]'\n"
+ ) from e
+
+ return FastAPI, HTTPException, BaseModel
+
+
+def _resolve_index_path(index_name: str) -> str:
+ """
+ Resolve an index path for the HTTP server.
+
+ For now we use the same convention as the CLI:
+ - Look in the current project's `.leann/indexes/<name>/documents.leann`.
+
+ This keeps behavior predictable when running `leann serve` from a project root.
+ """
+ cli = LeannCLI()
+ index_path = cli.get_index_path(index_name)
+ if not cli.index_exists(index_name):
+ raise FileNotFoundError(
+ f"Index '{index_name}' not found in current project. "
+ f"Build it with: leann build {index_name} --docs ./your_docs"
+ )
+ return index_path
+
+
+def _list_current_project_indexes() -> list[dict[str, Any]]:
+ """
+ Return machine-readable index metadata for the current project.
+
+ This mirrors `LeannCLI.list_indexes()` but only for the current project
+ and without printing to stdout.
+ """
+ cli = LeannCLI()
+ current_path = Path.cwd()
+ indexes: list[dict[str, Any]] = []
+
+ for idx in cli._discover_indexes_in_project(current_path): # type: ignore[attr-defined]
+ # `idx` includes keys like: name, type (cli/app), status, size_mb
+ indexes.append(
+ {
+ "name": idx.get("name", ""),
+ "type": idx.get("type", "cli"),
+ "status": idx.get("status", ""),
+ "size_mb": idx.get("size_mb", 0.0),
+ "project_path": str(current_path),
+ }
+ )
+
+ return indexes
+
+
+def create_app():
+ """
+ Create and return a FastAPI application exposing LEANN as a simple vector DB.
+
+ Endpoints:
+ - GET /health -> basic health check
+ - GET /indexes -> list indexes in current project
+ - POST /indexes/{name}/search -> semantic search
+ """
+
+ FastAPI, HTTPException, BaseModel = _ensure_fastapi()
+
+ class SearchRequest(BaseModel):
+ query: str
+ top_k: int = 5
+ complexity: int = 64
+ beam_width: int = 1
+ prune_ratio: float = 0.0
+ recompute_embeddings: bool = True
+ pruning_strategy: str = "global"
+ use_grep: bool = False
+
+ class SearchResultModel(BaseModel):
+ id: str
+ score: float
+ text: str
+ metadata: dict[str, Any]
+
+ app = FastAPI(
+ title="LEANN Vector DB Server",
+ description=(
+ "HTTP API for querying LEANN indexes.\n\n"
+ "This is a minimal first version focused on search. "
+ "Run it from a project root where `.leann/indexes` exists."
+ ),
+ version="0.1.0",
+ )
+
+ @app.get("/health")
+ async def health() -> dict[str, str]:
+ return {"status": "ok"}
+
+ @app.get("/indexes")
+ async def list_indexes() -> list[dict[str, Any]]:
+ """
+ List indexes for the current project (the working directory where the server runs).
+ """
+ return _list_current_project_indexes()
+
+ @app.post("/indexes/{index_name}/search", response_model=list[SearchResultModel])
+ async def search_index(index_name: str, body: SearchRequest):
+ """
+ Run semantic search against an existing LEANN index.
+ """
+ try:
+ index_path = _resolve_index_path(index_name)
+ except FileNotFoundError as e:
+ raise HTTPException(status_code=404, detail=str(e)) # type: ignore[misc]
+
+ searcher = LeannSearcher(index_path=index_path)
+ results = searcher.search(
+ query=body.query,
+ top_k=body.top_k,
+ complexity=body.complexity,
+ beam_width=body.beam_width,
+ prune_ratio=body.prune_ratio,
+ recompute_embeddings=body.recompute_embeddings,
+ pruning_strategy=body.pruning_strategy, # type: ignore[arg-type]
+ use_grep=body.use_grep,
+ )
+
+ # Normalize into JSON-serializable structures
+ return [
+ SearchResultModel(
+ id=r.id,
+ score=float(r.score),
+ text=r.text,
+ metadata=dict(r.metadata or {}),
+ )
+ for r in results
+ ]
+
+ return app
+
+
+def main() -> None:
+ """
+ Entrypoint to run the HTTP server with uvicorn.
+
+ Example:
+ uv run python -m leann.server
+ # or, after wiring a CLI command:
+ leann serve
+ """
+ try:
+ import uvicorn # type: ignore
+ except ImportError as e: # pragma: no cover - dependency error path
+ raise RuntimeError(
+ "uvicorn is required to run the LEANN HTTP server.\n"
+ "Install it with:\n\n"
+ " uv pip install 'uvicorn[standard]'\n"
+ ) from e
+
+ app = create_app()
+ host = os.getenv("LEANN_SERVER_HOST", "0.0.0.0")
+ port = int(os.getenv("LEANN_SERVER_PORT", "8000"))
+
+ uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__": # pragma: no cover
+ main()