Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: add Atlas Cloud provider preset
binyangzhu000-sudo1c77074fef26
diff --git a/docs/en/cli/commands/config.md b/docs/en/cli/commands/config.mdindex 55f22f7..57d8315 100644--- a/docs/en/cli/commands/config.md+++ b/docs/en/cli/commands/config.md@@ -30,6 +30,7 @@ Initialize configuration. This is the **lazy one-step setup** — if you pass `-- **DeepSeek preset**: `deepseek-v4-flash` (LLM only — no embedder preset)- **Anthropic preset**: `claude-opus-4-8` (LLM only — no embedder preset, pair with an OpenAI-compatible embedder)- **OrcaRouter preset**: `orcarouter/auto` (OpenAI-compatible gateway; key `ORCAROUTER_API_KEY`)+- **Atlas Cloud preset**: `deepseek-ai/deepseek-v4-flash` (LLM only — no embedder preset, pair with an OpenAI-compatible embedder; key `ATLASCLOUD_API_KEY`)- **Google Gemini preset**: `gemini-3.8-flash` (LLM only — no embedder preset, pair with an OpenAI-compatible embedder; alias `gemini`)```bash@@ -40,7 +41,7 @@ he config init [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `google` / `orcarouter` / `deepseek` / `bailian` / `vllm`) |+| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `google` / `orcarouter` / `atlascloud` / `deepseek` / `bailian` / `vllm`) || `--api-key` | `-k` | API key for both LLM and embedder || `--base-url` | `-u` | Custom API base URL (optional) |@@ -66,6 +67,10 @@ he config embedder -p openai -k sk-your-openai-key# OrcaRouter (OpenAI-compatible gateway)he config init -p orcarouter -k or-your-orcarouter-key+# Atlas Cloud (LLM only — pair with an OpenAI-compatible embedder)+he config llm -p atlascloud -k your-atlascloud-key+he config embedder -p openai -k sk-your-openai-key+# Google Gemini (LLM only — pair with an OpenAI-compatible embedder)he config llm -p google -k your-google-api-keyhe config embedder -p openai -k sk-your-openai-key@@ -123,7 +128,7 @@ he config llm [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `orcarouter`, `deepseek`, `bailian`, `vllm`) |+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `orcarouter`, `atlascloud`, `deepseek`, `bailian`, `vllm`) || `--api-key` | `-k` | LLM API key || `--model` | `-m` | LLM model name || `--base-url` | `-u` | Custom API base URL |@@ -166,7 +171,7 @@ he config embedder [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `orcarouter`, `deepseek`, `bailian`, `vllm`) |+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `orcarouter`, `atlascloud`, `deepseek`, `bailian`, `vllm`) || `--api-key` | `-k` | Embedder API key || `--model` | `-m` | Embedder model name || `--base-url` | `-u` | Custom API base URL |diff --git a/docs/en/concepts/provider-system.md b/docs/en/concepts/provider-system.mdindex 404b307..bccee20 100644--- a/docs/en/concepts/provider-system.md+++ b/docs/en/concepts/provider-system.md@@ -1,6 +1,6 @@# Provider System-Hyper-Extract supports these ways to connect to LLMs: **OpenAI**, **Anthropic**, **Google Gemini**, **Alibaba Bailian**, **DeepSeek**, **OrcaRouter**, and **local vLLM**. All use the same `create_client()` interface — only the first line changes.+Hyper-Extract supports these ways to connect to LLMs: **OpenAI**, **Anthropic**, **Google Gemini**, **Alibaba Bailian**, **DeepSeek**, **OrcaRouter**, **Atlas Cloud**, and **local vLLM**. All use the same `create_client()` interface — only the first line changes.---@@ -15,6 +15,7 @@ Hyper-Extract supports these ways to connect to LLMs: **OpenAI**, **Anthropic**,| **Google Gemini** | gemini-3.8-flash / gemini-2.5-flash / gemini-2.5-pro | ✅ (tool calling) | ✅ | LLM only — no embedder path in this repo (pair with an OpenAI-compatible embedder). Needs `hyperextract[google]`. Keys: `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Alias: `gemini` || **DeepSeek** | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI-compatible. V4 models default to "thinking" mode, which Hyper-Extract auto-disables (`extra_body`) so structured extraction works. LLM only — no embeddings API. Keys: `DEEPSEEK_API_KEY` || **OrcaRouter** | `orcarouter/auto`, `openai/gpt-4o-mini`, `anthropic/claude-haiku-4-5`, `deepseek/...`, `gemini/...` | ✅ | ✅ | OpenAI-compatible gateway routing 150+ models from OpenAI, Anthropic, Google, DeepSeek, Qwen, MiniMax, xAI behind one endpoint and key. Keys: `ORCAROUTER_API_KEY` |+| **Atlas Cloud** | `deepseek-ai/deepseek-v4-flash`, `deepseek-ai/deepseek-v4-pro`, `moonshotai/kimi-k3`, `qwen/qwen3.5-plus`, `openai/gpt-5.5`, `anthropic/claude-sonnet-4.6` | ✅ | ✅ | OpenAI-compatible gateway serving DeepSeek, Z.ai, Moonshot, Qwen, MiniMax, OpenAI, Anthropic and Google models under vendor-prefixed ids. LLM only — no embeddings API. `glm-5.x` models reject the forced `tool_choice` structured extraction uses; pick another model. Keys: `ATLASCLOUD_API_KEY` || **Alibaba Bailian** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | Works out of the box || **Alibaba Bailian** | qwen-max / deepseek-v3 | ❌ | ❌ | Only `json_object`; not compatible with function-calling structured output |@@ -80,6 +81,15 @@ llm, emb = create_client(# Key: ORCAROUTER_API_KEY (fallback: OPENAI_API_KEY).llm, emb = create_client("orcarouter")+# Atlas Cloud — OpenAI-compatible gateway with vendor-prefixed model ids+# (deepseek-ai/..., moonshotai/..., qwen/..., openai/..., anthropic/...).+# LLM only — pair it with an OpenAI-compatible embedder.+# Key: ATLASCLOUD_API_KEY. Override model with "atlascloud:moonshotai/kimi-k3".+llm, emb = create_client(+ llm="atlascloud",+ embedder="openai:text-embedding-3-small",+)+# Local vLLMllm, emb = create_client(llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",diff --git a/docs/en/python/guides/provider-configuration.md b/docs/en/python/guides/provider-configuration.mdindex 480f7cb..c3ebaa3 100644--- a/docs/en/python/guides/provider-configuration.md+++ b/docs/en/python/guides/provider-configuration.md@@ -1,6 +1,6 @@# Provider Configuration Guide-Configure Hyper-Extract to work with OpenAI, Bailian (Alibaba Cloud), DeepSeek, OrcaRouter, or local vLLM deployments.+Configure Hyper-Extract to work with OpenAI, Bailian (Alibaba Cloud), DeepSeek, OrcaRouter, Atlas Cloud, or local vLLM deployments.---@@ -64,6 +64,23 @@ llm, emb = create_client("orcarouter")# Or override the model: create_client("orcarouter:openai/gpt-4o-mini", ...)```+### Atlas Cloud++```python+from hyperextract import create_client, AutoGraph++# Atlas Cloud is an OpenAI-compatible gateway (DeepSeek, Z.ai, Moonshot, Qwen,+# MiniMax, OpenAI, Anthropic, Google) with vendor-prefixed model ids.+# LLM only — pair it with an OpenAI-compatible embedder.+# Key: ATLASCLOUD_API_KEY (fallback: OPENAI_API_KEY).+llm, emb = create_client(+ llm="atlascloud",+ embedder="openai:text-embedding-3-small",+)+# Or override the model: create_client(llm="atlascloud:moonshotai/kimi-k3", ...)+# Avoid glm-5.x here: it rejects the forced tool_choice that extraction uses.+```+### Local vLLM```python@@ -104,6 +121,7 @@ print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")| **Anthropic** | `he config llm -p anthropic -k sk-ant-xxx` + `he config embedder -p openai -k sk-xxx` || **DeepSeek** | `he config llm -p deepseek -k sk-xxx` + `he config embedder -p openai -k sk-xxx` || **OrcaRouter** | `he config init -p orcarouter -k sk-orca-xxx` |+| **Atlas Cloud** | `he config llm -p atlascloud -k xxx` + `he config embedder -p openai -k sk-xxx` || **vLLM** | `he config init` → select "local vLLM" || **Mixed** (LLM=Bailian, Embedder=vLLM) | `he config llm -p bailian -k sk-xxx` + `he config embedder -p vllm -u http://localhost:8001/v1 -k dummy` |diff --git a/docs/zh/cli/commands/config.md b/docs/zh/cli/commands/config.mdindex f1ce8e2..837662f 100644--- a/docs/zh/cli/commands/config.md+++ b/docs/zh/cli/commands/config.md@@ -30,6 +30,7 @@ he config [COMMAND] [OPTIONS]- **DeepSeek preset**: `deepseek-v4-flash`(仅 LLM —— 无嵌入预设)- **Anthropic preset**: `claude-opus-4-8`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器)- **OrcaRouter preset**: `orcarouter/auto`(OpenAI 兼容网关;密钥 `ORCAROUTER_API_KEY`)+- **Atlas Cloud preset**: `deepseek-ai/deepseek-v4-flash`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器;密钥 `ATLASCLOUD_API_KEY`)- **Google Gemini preset**: `gemini-3.8-flash`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器;别名 `gemini`)```bash@@ -40,7 +41,7 @@ he config init [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `google` / `orcarouter` / `deepseek` / `bailian` / `vllm`) |+| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `google` / `orcarouter` / `atlascloud` / `deepseek` / `bailian` / `vllm`) || `--api-key` | `-k` | LLM 和嵌入模型的 API 密钥 || `--base-url` | `-u` | 自定义 API 基础 URL(可选) |@@ -66,6 +67,10 @@ he config embedder -p openai -k sk-your-openai-key# OrcaRouter(OpenAI 兼容网关)he config init -p orcarouter -k or-your-orcarouter-key+# Atlas Cloud(仅 LLM —— 请搭配 OpenAI 兼容嵌入器)+he config llm -p atlascloud -k your-atlascloud-key+he config embedder -p openai -k sk-your-openai-key+# Google Gemini(仅 LLM —— 请搭配 OpenAI 兼容嵌入器)he config llm -p google -k your-google-api-keyhe config embedder -p openai -k sk-your-openai-key@@ -123,7 +128,7 @@ he config llm [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`orcarouter`、`deepseek`、`bailian`、`vllm`) |+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`orcarouter`、`atlascloud`、`deepseek`、`bailian`、`vllm`) || `--api-key` | `-k` | LLM API 密钥 || `--model` | `-m` | LLM 模型名称 || `--base-url` | `-u` | 自定义 API 基础 URL |@@ -166,7 +171,7 @@ he config embedder [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`orcarouter`、`deepseek`、`bailian`、`vllm`) |+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`orcarouter`、`atlascloud`、`deepseek`、`bailian`、`vllm`) || `--api-key` | `-k` | 嵌入模型 API 密钥 || `--model` | `-m` | 嵌入模型名称 || `--base-url` | `-u` | 自定义 API 基础 URL |diff --git a/docs/zh/concepts/provider-system.md b/docs/zh/concepts/provider-system.mdindex bbcdc44..6de2305 100644--- a/docs/zh/concepts/provider-system.md+++ b/docs/zh/concepts/provider-system.md@@ -1,6 +1,6 @@# Provider 系统-Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**Google Gemini**、**阿里云百炼**、**DeepSeek**、**OrcaRouter**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。+Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**Google Gemini**、**阿里云百炼**、**DeepSeek**、**OrcaRouter**、**Atlas Cloud**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。---@@ -15,6 +15,7 @@ Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**Google G| **Google Gemini** | gemini-3.8-flash / gemini-2.5-flash / gemini-2.5-pro | ✅(工具调用) | ✅ | 仅 LLM——本仓库无成熟嵌入路径(请搭配 OpenAI 兼容嵌入器)。需 `hyperextract[google]`。密钥:`GOOGLE_API_KEY` 或 `GEMINI_API_KEY`。别名:`gemini` || **DeepSeek** | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI 兼容。V4 模型默认开启"thinking"模式,Hyper-Extract 会自动关闭以保证结构化抽取可用。仅 LLM——无嵌入接口。密钥:`DEEPSEEK_API_KEY` || **OrcaRouter** | `orcarouter/auto`、`openai/gpt-4o-mini`、`anthropic/claude-haiku-4-5`、`deepseek/...`、`gemini/...` | ✅ | ✅ | OpenAI 兼容网关,用同一端点和密钥路由 OpenAI、Anthropic、Google、DeepSeek、Qwen、MiniMax、xAI 等 150+ 模型。密钥:`ORCAROUTER_API_KEY` |+| **Atlas Cloud** | `deepseek-ai/deepseek-v4-flash`、`deepseek-ai/deepseek-v4-pro`、`moonshotai/kimi-k3`、`qwen/qwen3.5-plus`、`openai/gpt-5.5`、`anthropic/claude-sonnet-4.6` | ✅ | ✅ | OpenAI 兼容网关,模型 id 带厂商前缀,覆盖 DeepSeek、智谱、月之暗面、Qwen、MiniMax、OpenAI、Anthropic、Google 等。仅 LLM —— 无嵌入 API。`glm-5.x` 不接受结构化抽取使用的强制 `tool_choice`,请换其他模型。密钥:`ATLASCLOUD_API_KEY` || **阿里云百炼** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | 直接使用,无需修改 || **阿里云百炼** | qwen-max / deepseek-v3 | ❌ | ❌ | 仅支持 `json_object`,不兼容 function calling 结构化输出 |@@ -78,6 +79,15 @@ llm, emb = create_client(# 密钥:ORCAROUTER_API_KEY(回退:OPENAI_API_KEY)。llm, emb = create_client("orcarouter")+# Atlas Cloud —— OpenAI 兼容网关,模型 id 带厂商前缀+# (deepseek-ai/...、moonshotai/...、qwen/...、openai/...、anthropic/...)。+# 仅 LLM —— 请搭配 OpenAI 兼容嵌入器。+# 密钥:ATLASCLOUD_API_KEY。可用 "atlascloud:moonshotai/kimi-k3" 覆盖模型。+llm, emb = create_client(+ llm="atlascloud",+ embedder="openai:text-embedding-3-small",+)+# 本地 vLLMllm, emb = create_client(llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",diff --git a/hyperextract/cli/commands/config.py b/hyperextract/cli/commands/config.pyindex c10e4b9..11b6b43 100644--- a/hyperextract/cli/commands/config.py+++ b/hyperextract/cli/commands/config.py@@ -160,7 +160,7 @@ def llm(None,"--provider","-p",- help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, atlascloud, vllm",),api_key: str | None = typer.Option(None,@@ -221,7 +221,7 @@ def embedder(None,"--provider","-p",- help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, atlascloud, vllm",),api_key: str | None = typer.Option(None,@@ -284,7 +284,7 @@ def init(None,"--provider","-p",- help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, atlascloud, vllm",),api_key: str | None = typer.Option(None,@@ -386,6 +386,7 @@ def init(("orcarouter", "OrcaRouter", "https://api.orcarouter.ai/v1"),("anthropic", "Anthropic (Claude)", "native SDK"),("google", "Google Gemini", "native SDK"),+ ("atlascloud", "Atlas Cloud", "https://api.atlascloud.ai/v1"),("vllm", "本地 vLLM", "自定义地址"),("custom", "其他 OpenAI 兼容接口", "自定义地址"),]diff --git a/hyperextract/utils/client.py b/hyperextract/utils/client.pyindex 745575d..ac38a02 100644--- a/hyperextract/utils/client.py+++ b/hyperextract/utils/client.py@@ -63,6 +63,17 @@ PROVIDER_PRESETS: dict[str, dict[str, str | None]] = {"default_llm": "orcarouter/auto","default_embedder": "openai/text-embedding-3-small",},+ # Atlas Cloud. OpenAI-compatible aggregator serving DeepSeek, Z.ai, Moonshot,+ # Qwen, MiniMax, OpenAI, Anthropic and Google models under vendor-prefixed+ # ids such as "deepseek-ai/deepseek-v4-flash". Forced tool_choice (which+ # method="function_calling" relies on) works for these models without+ # disabling thinking, except glm-5.x, which answers 400. Atlas Cloud has no+ # embeddings API — pair it with an OpenAI-compatible embedder.+ "atlascloud": {+ "base_url": "https://api.atlascloud.ai/v1",+ "default_llm": "deepseek-ai/deepseek-v4-flash",+ "default_embedder": None,+ },# Anthropic (Claude). Uses the native ChatAnthropic client, so base_url is# left empty (the SDK targets api.anthropic.com by default). Anthropic has# no embeddings API, hence default_embedder is None — pair it with an@@ -113,6 +124,7 @@ PROVIDER_API_KEY_ENV: dict[str, tuple[str, ...]] = {"gemini": ("GOOGLE_API_KEY", "GEMINI_API_KEY"),"deepseek": ("DEEPSEEK_API_KEY",),"orcarouter": ("ORCAROUTER_API_KEY",),+ "atlascloud": ("ATLASCLOUD_API_KEY",),}diff --git a/tests/cli/test_config.py b/tests/cli/test_config.pyindex 75124e7..1e6b7ad 100644--- a/tests/cli/test_config.py+++ b/tests/cli/test_config.py@@ -307,3 +307,35 @@ def test_legacy_broken_google_embedder_still_fails_create_embedder():{"provider": "google", "model": "text-embedding-3-small"},api_key=_FAKE_API_KEY,)+++def test_atlascloud_is_a_library_preset_with_its_own_key_env():+ """The CLI reads Atlas Cloud from the library tables, not a copy."""+ from hyperextract.cli import config as cli_config++ assert "atlascloud" in cli_config.PROVIDER_PRESETS+ assert cli_config.PROVIDER_API_KEY_ENV["atlascloud"] == ("ATLASCLOUD_API_KEY",)+++def test_get_llm_config_reads_atlascloud_env_key(tmp_path, monkeypatch):+ """Empty toml api_key must resolve ATLASCLOUD_API_KEY, ahead of OPENAI_API_KEY."""+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-must-not-win")+ monkeypatch.setenv("ATLASCLOUD_API_KEY", "apikey-atlas-from-env")++ cm = ConfigManager(tmp_path / "config.toml")+ cm.set_llm(provider="atlascloud", model="deepseek-ai/deepseek-v4-flash", api_key="")+ cfg = cm.get_llm_config()++ assert cfg.api_key == "apikey-atlas-from-env"+ assert cfg.base_url == "https://api.atlascloud.ai/v1"+++def test_interactive_init_lists_atlascloud():+ """he config init provider list includes Atlas Cloud."""+ import inspect++ from hyperextract.cli.commands.config import init++ assert '"atlascloud"' in inspect.getsource(init)+diff --git a/tests/utils/test_client.py b/tests/utils/test_client.pyindex bd55c2a..bb8f7e7 100644--- a/tests/utils/test_client.py+++ b/tests/utils/test_client.py@@ -134,6 +134,24 @@ class TestCreateLLM:)assert llm.extra_body == {"thinking": {"type": "enabled"}}+ def test_create_llm_atlascloud(self):+ """Create LLM with atlascloud preset (OpenAI-compatible gateway)."""+ llm = create_llm("atlascloud", api_key="apikey-test")+ assert llm.model_name == "deepseek-ai/deepseek-v4-flash"+ assert llm.openai_api_base == "https://api.atlascloud.ai/v1"++ def test_create_llm_atlascloud_model_override(self):+ """A vendor-prefixed Atlas Cloud model id after the colon is kept whole."""+ llm = create_llm("atlascloud:moonshotai/kimi-k3", api_key="apikey-test")+ assert llm.model_name == "moonshotai/kimi-k3"+ assert llm.openai_api_base == "https://api.atlascloud.ai/v1"++ def test_create_llm_atlascloud_env_key(self, monkeypatch):+ """Atlas Cloud key is read from ATLASCLOUD_API_KEY when api_key is omitted."""+ monkeypatch.setenv("ATLASCLOUD_API_KEY", "apikey-from-env")+ llm = create_llm("atlascloud")+ assert llm.openai_api_key.get_secret_value() == "apikey-from-env"+def test_create_llm_orcarouter(self):"""Create LLM with orcarouter preset (OpenAI-compatible gateway)."""llm = create_llm("orcarouter", api_key="sk-test")@@ -598,6 +616,14 @@ class TestProviderPresets:assert preset["default_llm"] == "deepseek-v4-flash"assert preset["default_embedder"] is None+ def test_atlascloud_provider(self):+ """Atlas Cloud has its own preset (OpenAI-compatible, LLM only)."""+ assert "atlascloud" in PROVIDER_PRESETS+ preset = PROVIDER_PRESETS["atlascloud"]+ assert preset["base_url"] == "https://api.atlascloud.ai/v1"+ assert preset["default_llm"] == "deepseek-ai/deepseek-v4-flash"+ assert preset["default_embedder"] is None+def test_orcarouter_provider(self):"""OrcaRouter has its own preset (OpenAI-compatible, named models)."""assert "orcarouter" in PROVIDER_PRESETS