[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: add Atlas Cloud LLM provider (#388)
nb2134c129dda018b
diff --git a/apps/base_rag_example.py b/apps/base_rag_example.pyindex 67e198b..1aab9f4 100644--- a/apps/base_rag_example.py+++ b/apps/base_rag_example.py@@ -29,7 +29,13 @@ from leann.registry import register_project_directory# Optional import: older PyPI builds may not include settingstry:- from leann.settings import resolve_ollama_host, resolve_openai_api_key, resolve_openai_base_url+ from leann.settings import (+ resolve_atlascloud_api_key,+ resolve_atlascloud_base_url,+ resolve_ollama_host,+ resolve_openai_api_key,+ resolve_openai_base_url,+ )except ImportError:# Minimal fallbacks if settings helpers are unavailableimport os@@ -43,6 +49,17 @@ except ImportError:def resolve_openai_base_url(value: str | None) -> str | None:return value or os.getenv("OPENAI_BASE_URL")+ def resolve_atlascloud_api_key(value: str | None) -> str | None:+ return value or os.getenv("ATLASCLOUD_API_KEY") or os.getenv("ATLAS_CLOUD_API_KEY")++ def resolve_atlascloud_base_url(value: str | None) -> str | None:+ return (+ value+ or os.getenv("ATLASCLOUD_BASE_URL")+ or os.getenv("ATLAS_CLOUD_BASE_URL")+ or "https://api.atlascloud.ai/v1"+ )+dotenv.load_dotenv()@@ -135,8 +152,8 @@ class BaseRAGExample(ABC):"--llm",type=str,default="openai",- choices=["openai", "ollama", "hf", "simulated"],- help="LLM backend: openai, ollama, or hf (default: openai)",+ choices=["openai", "ollama", "hf", "simulated", "atlascloud", "atlas-cloud", "atlas"],+ help="LLM backend: openai, ollama, hf, atlascloud, or simulated (default: openai)",)llm_group.add_argument("--llm-model",@@ -271,6 +288,13 @@ class BaseRAGExample(ABC):resolved_key = resolve_openai_api_key(args.llm_api_key)if resolved_key:config["api_key"] = resolved_key+ elif args.llm in {"atlascloud", "atlas-cloud", "atlas"}:+ config["type"] = "atlascloud"+ config["model"] = args.llm_model or "deepseek-ai/deepseek-v4-pro"+ config["base_url"] = resolve_atlascloud_base_url(args.llm_api_base)+ resolved_key = resolve_atlascloud_api_key(args.llm_api_key)+ if resolved_key:+ config["api_key"] = resolved_keyelif args.llm == "ollama":config["model"] = args.llm_model or "llama3.2:1b"config["host"] = resolve_ollama_host(args.llm_host)diff --git a/packages/leann-core/src/leann/chat.py b/packages/leann-core/src/leann/chat.pyindex a36383f..6f16eaf 100644--- a/packages/leann-core/src/leann/chat.py+++ b/packages/leann-core/src/leann/chat.py@@ -13,6 +13,8 @@ from typing import Any, Optional, castfrom .settings import (resolve_anthropic_api_key,resolve_anthropic_base_url,+ resolve_atlascloud_api_key,+ resolve_atlascloud_base_url,resolve_minimax_api_key,resolve_minimax_base_url,resolve_novita_api_key,@@ -1082,6 +1084,65 @@ class NovitaChat(LLMInterface):return f"Error: Could not get a response from Novita. Details: {e}"+class AtlasCloudChat(LLMInterface):+ """LLM interface for Atlas Cloud models via the OpenAI-compatible API."""++ def __init__(+ self,+ model: str = "deepseek-ai/deepseek-v4-pro",+ api_key: Optional[str] = None,+ base_url: Optional[str] = None,+ ):+ self.model = model+ self.base_url = resolve_atlascloud_base_url(base_url)+ self.api_key = resolve_atlascloud_api_key(api_key)++ if not self.api_key:+ raise ValueError(+ "Atlas Cloud API key is required. Set ATLASCLOUD_API_KEY or ATLAS_CLOUD_API_KEY environment variable or pass api_key parameter."+ )++ logger.info(+ "Initializing Atlas Cloud Chat with model='%s' and base_url='%s'",+ model,+ self.base_url,+ )++ try:+ import openai++ self.client = openai.OpenAI(api_key=self.api_key, base_url=self.base_url)+ except ImportError:+ raise ImportError(+ "The 'openai' library is required for Atlas Cloud models. Please install it with 'pip install openai'."+ )++ def ask(self, prompt: str, **kwargs) -> str:+ params = {+ "model": self.model,+ "messages": [{"role": "user", "content": prompt}],+ "temperature": kwargs.get("temperature", 0.7),+ "max_tokens": kwargs.get("max_tokens", 1000),+ }++ if "top_p" in kwargs:+ params["top_p"] = kwargs["top_p"]++ logger.info(f"Sending request to Atlas Cloud with model {self.model}")++ try:+ response = cast(Any, self.client.chat.completions).create(**params)+ logger.info(+ f"Total tokens = {response.usage.total_tokens}, prompt tokens = {response.usage.prompt_tokens}, completion tokens = {response.usage.completion_tokens}"+ )+ if response.choices[0].finish_reason == "length":+ logger.warning("The query is exceeding the maximum allowed number of tokens")+ return response.choices[0].message.content.strip()+ except Exception as e:+ logger.error(f"Error communicating with Atlas Cloud: {e}")+ return f"Error: Could not get a response from Atlas Cloud. Details: {e}"++class SimulatedChat(LLMInterface):"""A simple simulated chat for testing and development."""@@ -1152,6 +1213,12 @@ def get_llm(llm_config: Optional[dict[str, Any]] = None) -> LLMInterface:api_key=llm_config.get("api_key"),base_url=llm_config.get("base_url"),)+ elif llm_type in {"atlascloud", "atlas-cloud", "atlas"}:+ return AtlasCloudChat(+ model=model or "deepseek-ai/deepseek-v4-pro",+ api_key=llm_config.get("api_key"),+ base_url=llm_config.get("base_url"),+ )elif llm_type == "simulated":return SimulatedChat()else:diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.pyindex 405cf2c..967342c 100644--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@ -22,6 +22,8 @@ from .interactive_utils import create_cli_sessionfrom .registry import register_project_directoryfrom .settings import (resolve_anthropic_base_url,+ resolve_atlascloud_api_key,+ resolve_atlascloud_base_url,resolve_minimax_api_key,resolve_minimax_base_url,resolve_ollama_host,@@ -626,7 +628,18 @@ Examples:"--llm",type=str,default="ollama",- choices=["simulated", "ollama", "hf", "openai", "anthropic", "minimax", "novita"],+ choices=[+ "simulated",+ "ollama",+ "hf",+ "openai",+ "anthropic",+ "minimax",+ "novita",+ "atlascloud",+ "atlas-cloud",+ "atlas",+ ],help="LLM provider (default: ollama)",)ask_parser.add_argument(@@ -676,7 +689,7 @@ Examples:"--api-key",type=str,default=None,- help="API key for cloud LLM providers (OpenAI, Anthropic)",+ help="API key for cloud LLM providers",)ask_parser.add_argument("--metadata-filters",@@ -700,7 +713,18 @@ Examples:"--llm",type=str,default="ollama",- choices=["simulated", "ollama", "hf", "openai", "anthropic", "minimax", "novita"],+ choices=[+ "simulated",+ "ollama",+ "hf",+ "openai",+ "anthropic",+ "minimax",+ "novita",+ "atlascloud",+ "atlas-cloud",+ "atlas",+ ],help="LLM provider (default: ollama)",)react_parser.add_argument(@@ -731,7 +755,7 @@ Examples:"--api-key",type=str,default=None,- help="API key for cloud LLM providers (OpenAI, Anthropic)",+ help="API key for cloud LLM providers",)react_parser.add_argument("--serper-api-key",@@ -3332,6 +3356,14 @@ Examples:resolved_api_key = resolve_minimax_api_key(args.api_key)if resolved_api_key:llm_config["api_key"] = resolved_api_key+ elif args.llm in {"atlascloud", "atlas-cloud", "atlas"}:+ llm_config["type"] = "atlascloud"+ if args.model == "qwen3:8b":+ llm_config["model"] = "deepseek-ai/deepseek-v4-pro"+ llm_config["base_url"] = resolve_atlascloud_base_url(args.api_base)+ resolved_api_key = resolve_atlascloud_api_key(args.api_key)+ if resolved_api_key:+ llm_config["api_key"] = resolved_api_key# Parse --metadata-filters JSON string (mirrors `leann search`).# Run before constructing LeannChat so invalid filters fail fast without@@ -3619,6 +3651,14 @@ Examples:resolved_api_key = resolve_minimax_api_key(args.api_key)if resolved_api_key:llm_config["api_key"] = resolved_api_key+ elif args.llm in {"atlascloud", "atlas-cloud", "atlas"}:+ llm_config["type"] = "atlascloud"+ if args.model == "qwen3:8b":+ llm_config["model"] = "deepseek-ai/deepseek-v4-pro"+ llm_config["base_url"] = resolve_atlascloud_base_url(args.api_base)+ resolved_api_key = resolve_atlascloud_api_key(args.api_key)+ if resolved_api_key:+ llm_config["api_key"] = resolved_api_keyfrom .react_agent import create_react_agentdiff --git a/packages/leann-core/src/leann/settings.py b/packages/leann-core/src/leann/settings.pyindex 3d6afb8..a43e217 100644--- a/packages/leann-core/src/leann/settings.py+++ b/packages/leann-core/src/leann/settings.py@@ -15,6 +15,7 @@ _DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1"_DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com"_DEFAULT_MINIMAX_BASE_URL = "https://api.minimax.io/v1"_DEFAULT_NOVITA_BASE_URL = "https://api.novita.ai/openai"+_DEFAULT_ATLASCLOUD_BASE_URL = "https://api.atlascloud.ai/v1"def _clean_url(value: str) -> str:@@ -154,6 +155,35 @@ def resolve_novita_api_key(explicit: str | None = None) -> str | None:return openai_key+def resolve_atlascloud_base_url(explicit: str | None = None) -> str:+ """Resolve the base URL for Atlas Cloud OpenAI-compatible services."""++ candidates = (+ explicit,+ os.getenv("LEANN_ATLASCLOUD_BASE_URL"),+ os.getenv("LEANN_ATLAS_CLOUD_BASE_URL"),+ os.getenv("ATLASCLOUD_BASE_URL"),+ os.getenv("ATLAS_CLOUD_BASE_URL"),+ os.getenv("ATLASCLOUD_API_BASE"),+ os.getenv("ATLAS_CLOUD_API_BASE"),+ )++ for candidate in candidates:+ if candidate:+ return _clean_url(candidate)++ return _clean_url(_DEFAULT_ATLASCLOUD_BASE_URL)+++def resolve_atlascloud_api_key(explicit: str | None = None) -> str | None:+ """Resolve the API key for Atlas Cloud services."""++ if explicit:+ return explicit++ return os.getenv("ATLASCLOUD_API_KEY") or os.getenv("ATLAS_CLOUD_API_KEY")++def encode_provider_options(options: dict[str, Any] | None) -> str | None:"""Serialize provider options for child processes."""diff --git a/tests/test_atlascloud_provider.py b/tests/test_atlascloud_provider.pynew file mode 100644index 0000000..09091df--- /dev/null+++ b/tests/test_atlascloud_provider.py@@ -0,0 +1,240 @@+"""+Tests for Atlas Cloud provider integration.++These tests validate Atlas Cloud provider settings, chat class, and factory+integration without triggering LEANN's compiled backend imports.+"""++import os+import sys+from unittest.mock import MagicMock, patch++import pytest++_LEANN_SRC = os.path.join(os.path.dirname(__file__), "..", "packages", "leann-core", "src")+if _LEANN_SRC not in sys.path:+ sys.path.insert(0, os.path.abspath(_LEANN_SRC))++if "leann" not in sys.modules:+ import types++ _stub = types.ModuleType("leann")+ _stub.__path__ = [os.path.join(os.path.abspath(_LEANN_SRC), "leann")]+ sys.modules["leann"] = _stub++from leann.settings import ( # noqa: E402+ resolve_atlascloud_api_key,+ resolve_atlascloud_base_url,+)+++class TestAtlasCloudSettings:+ """Test Atlas Cloud settings resolver functions."""++ def test_resolve_atlascloud_api_key_explicit(self):+ assert resolve_atlascloud_api_key("test-key") == "test-key"++ def test_resolve_atlascloud_api_key_from_primary_env(self):+ with patch.dict(os.environ, {"ATLASCLOUD_API_KEY": "atlas-key"}, clear=True):+ assert resolve_atlascloud_api_key() == "atlas-key"++ def test_resolve_atlascloud_api_key_from_spaced_env(self):+ with patch.dict(os.environ, {"ATLAS_CLOUD_API_KEY": "atlas-cloud-key"}, clear=True):+ assert resolve_atlascloud_api_key() == "atlas-cloud-key"++ def test_resolve_atlascloud_api_key_does_not_fallback_to_openai(self):+ with patch.dict(os.environ, {"OPENAI_API_KEY": "openai-key"}, clear=True):+ assert resolve_atlascloud_api_key() is None++ def test_resolve_atlascloud_base_url_default(self):+ with patch.dict(os.environ, {}, clear=True):+ assert resolve_atlascloud_base_url() == "https://api.atlascloud.ai/v1"++ def test_resolve_atlascloud_base_url_explicit(self):+ assert resolve_atlascloud_base_url("https://custom.url/v1") == "https://custom.url/v1"++ def test_resolve_atlascloud_base_url_env_precedence(self):+ with patch.dict(+ os.environ,+ {+ "LEANN_ATLASCLOUD_BASE_URL": "https://leann.url/v1",+ "ATLAS_CLOUD_BASE_URL": "https://fallback.url/v1",+ },+ clear=True,+ ):+ assert resolve_atlascloud_base_url() == "https://leann.url/v1"++ def test_resolve_atlascloud_base_url_strips_trailing_slash(self):+ assert (+ resolve_atlascloud_base_url("https://api.atlascloud.ai/v1/")+ == "https://api.atlascloud.ai/v1"+ )+++class TestAtlasCloudChat:+ """Test AtlasCloudChat class."""++ def test_init_requires_api_key(self):+ from leann.chat import AtlasCloudChat++ with patch.dict(os.environ, {}, clear=True):+ with pytest.raises(ValueError, match="Atlas Cloud API key is required"):+ AtlasCloudChat(api_key=None)++ @patch("openai.OpenAI")+ def test_init_with_api_key(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ chat = AtlasCloudChat(api_key="test-key")+ assert chat.model == "deepseek-ai/deepseek-v4-pro"+ assert chat.api_key == "test-key"+ assert chat.base_url == "https://api.atlascloud.ai/v1"+ mock_openai_cls.assert_called_once_with(+ api_key="test-key", base_url="https://api.atlascloud.ai/v1"+ )++ @patch("openai.OpenAI")+ def test_init_custom_model(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ chat = AtlasCloudChat(model="qwen/qwen3.5-27b", api_key="test-key")+ assert chat.model == "qwen/qwen3.5-27b"++ @patch("openai.OpenAI")+ def test_init_custom_base_url(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ chat = AtlasCloudChat(api_key="test-key", base_url="https://custom.atlas.url/v1")+ assert chat.base_url == "https://custom.atlas.url/v1"++ @patch("openai.OpenAI")+ def test_ask_returns_response(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ mock_client = MagicMock()+ mock_openai_cls.return_value = mock_client++ mock_response = MagicMock()+ mock_response.choices = [MagicMock()]+ mock_response.choices[0].message.content = "Hello from Atlas Cloud!"+ mock_response.choices[0].finish_reason = "stop"+ mock_response.usage.total_tokens = 100+ mock_response.usage.prompt_tokens = 50+ mock_response.usage.completion_tokens = 50+ mock_client.chat.completions.create.return_value = mock_response++ chat = AtlasCloudChat(api_key="test-key")+ result = chat.ask("Hello")++ assert result == "Hello from Atlas Cloud!"+ mock_client.chat.completions.create.assert_called_once()++ @patch("openai.OpenAI")+ def test_ask_with_kwargs(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ mock_client = MagicMock()+ mock_openai_cls.return_value = mock_client++ mock_response = MagicMock()+ mock_response.choices = [MagicMock()]+ mock_response.choices[0].message.content = "Response"+ mock_response.choices[0].finish_reason = "stop"+ mock_response.usage.total_tokens = 50+ mock_response.usage.prompt_tokens = 25+ mock_response.usage.completion_tokens = 25+ mock_client.chat.completions.create.return_value = mock_response++ chat = AtlasCloudChat(api_key="test-key")+ chat.ask("Hello", temperature=0.5, max_tokens=500, top_p=0.9)++ call_kwargs = mock_client.chat.completions.create.call_args[1]+ assert call_kwargs["temperature"] == 0.5+ assert call_kwargs["max_tokens"] == 500+ assert call_kwargs["top_p"] == 0.9++ @patch("openai.OpenAI")+ def test_ask_handles_error(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat++ mock_client = MagicMock()+ mock_openai_cls.return_value = mock_client+ mock_client.chat.completions.create.side_effect = Exception("API error")++ chat = AtlasCloudChat(api_key="test-key")+ result = chat.ask("Hello")++ assert "Error" in result+ assert "Atlas Cloud" in result+++class TestGetLLMFactory:+ """Test get_llm factory function with Atlas Cloud types."""++ @patch("openai.OpenAI")+ def test_get_llm_atlascloud(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat, get_llm++ llm = get_llm({"type": "atlascloud", "api_key": "test-key"})+ assert isinstance(llm, AtlasCloudChat)+ assert llm.model == "deepseek-ai/deepseek-v4-pro"++ @patch("openai.OpenAI")+ @pytest.mark.parametrize("provider_type", ["atlascloud", "atlas-cloud", "atlas"])+ def test_get_llm_atlascloud_aliases(self, mock_openai_cls, provider_type):+ from leann.chat import AtlasCloudChat, get_llm++ llm = get_llm({"type": provider_type, "api_key": "test-key"})+ assert isinstance(llm, AtlasCloudChat)++ @patch("openai.OpenAI")+ def test_get_llm_atlascloud_custom_model(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat, get_llm++ llm = get_llm(+ {+ "type": "atlascloud",+ "model": "qwen/qwen3.5-27b",+ "api_key": "test-key",+ }+ )+ assert isinstance(llm, AtlasCloudChat)+ assert llm.model == "qwen/qwen3.5-27b"++ @patch("openai.OpenAI")+ def test_get_llm_atlascloud_custom_base_url(self, mock_openai_cls):+ from leann.chat import AtlasCloudChat, get_llm++ llm = get_llm(+ {+ "type": "atlascloud",+ "api_key": "test-key",+ "base_url": "https://custom.atlas.url/v1",+ }+ )+ assert isinstance(llm, AtlasCloudChat)+ assert llm.base_url == "https://custom.atlas.url/v1"+++ not (os.getenv("ATLASCLOUD_API_KEY") or os.getenv("ATLAS_CLOUD_API_KEY")),+ reason="ATLASCLOUD_API_KEY or ATLAS_CLOUD_API_KEY not set; skipping live API test",+)+class TestAtlasCloudLiveAPI:+ """Live API tests for Atlas Cloud provider."""++ def test_atlascloud_deepseek_live(self):+ from leann.chat import AtlasCloudChat++ chat = AtlasCloudChat(model="deepseek-ai/deepseek-v4-pro")+ response = chat.ask("Say hello in one word.", max_tokens=10)+ assert isinstance(response, str)+ assert len(response) > 0++ def test_atlascloud_via_get_llm_live(self):+ from leann.chat import get_llm++ llm = get_llm({"type": "atlascloud"})+ response = llm.ask("What is 1+1? Reply with just the number.", max_tokens=10)+ assert isinstance(response, str)+ assert len(response) > 0