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 Atlas Cloud LLM provider (#388)

nb2134c129dda018b
diff --git a/apps/base_rag_example.py b/apps/base_rag_example.py
index 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 settings
try:
- 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 unavailable
import 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_key
elif 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.py
index 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, cast
from .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.py
index 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_session
from .registry import register_project_directory
from .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_key
from .react_agent import create_react_agent
diff --git a/packages/leann-core/src/leann/settings.py b/packages/leann-core/src/leann/settings.py
index 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.py
new file mode 100644
index 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