Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: wire unused google extra to native Gemini create_llm
Frankie-Xu27af05262a86
diff --git a/docs/en/cli/commands/config.md b/docs/en/cli/commands/config.mdindex d395839..a4b1911 100644--- a/docs/en/cli/commands/config.md+++ b/docs/en/cli/commands/config.md@@ -29,6 +29,7 @@ Initialize configuration. This is the **lazy one-step setup** — if you pass `-- **Bailian preset**: `qwen3.6-plus` + `text-embedding-v4`- **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)+- **Google Gemini preset**: `gemini-3.8-flash` (LLM only — no embedder preset, pair with an OpenAI-compatible embedder; alias `gemini`)```bashhe config init [OPTIONS]@@ -38,7 +39,7 @@ he config init [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `deepseek` / `bailian` / `vllm`) |+| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `google` / `deepseek` / `bailian` / `vllm`) || `--api-key` | `-k` | API key for both LLM and embedder || `--base-url` | `-u` | Custom API base URL (optional) |@@ -60,6 +61,10 @@ he config embedder -p openai -k sk-your-openai-key# Anthropic (LLM only — pair with an OpenAI-compatible embedder)he config llm -p anthropic -k sk-your-anthropic-keyhe 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-key+he config embedder -p openai -k sk-your-openai-key```This saves the preset's default model and API URL automatically.@@ -114,7 +119,7 @@ he config llm [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `deepseek`, `bailian`, `vllm`) |+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `deepseek`, `bailian`, `vllm`) || `--api-key` | `-k` | LLM API key || `--model` | `-m` | LLM model name || `--base-url` | `-u` | Custom API base URL |@@ -157,7 +162,7 @@ he config embedder [OPTIONS]| Option | Short | Description ||--------|-------|-------------|-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `deepseek`, `bailian`, `vllm`) |+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `google`, `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 dbb5ac4..404b307 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**, **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**, and **local vLLM**. All use the same `create_client()` interface — only the first line changes.---@@ -12,6 +12,7 @@ Hyper-Extract supports these ways to connect to LLMs: **OpenAI**, **Anthropic**,|----------|-------|:----------------:|:----------:|-------|| **OpenAI** | gpt-4o / gpt-4o-mini / gpt-5 | ✅ | ✅ | Native support, recommended || **Anthropic** | claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 | ✅ (tool calling) | ✅ | LLM only — no embeddings API (pair with an OpenAI-compatible embedder). Needs `hyperextract[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` || **Alibaba Bailian** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | Works out of the box |@@ -54,6 +55,15 @@ llm, emb = create_client(embedder="openai:text-embedding-3-small",)+# Google Gemini — native ChatGoogleGenerativeAI (not the OrcaRouter gemini/...+# gateway). LLM only; pair with an OpenAI-compatible embedder.+# Keys: GOOGLE_API_KEY (or GEMINI_API_KEY). Alias: "gemini".+# Extra: pip install 'hyperextract[google]'.+llm, emb = create_client(+ llm="google", # default model: gemini-3.8-flash (override with "google:<model>")+ embedder="openai:text-embedding-3-small",+)+# DeepSeek — OpenAI-compatible, but no embeddings API. The V4 models# default to "thinking" mode, which Hyper-Extract auto-disables so that# tool-calling (function_calling) structured extraction works out of the box.diff --git a/docs/zh/cli/commands/config.md b/docs/zh/cli/commands/config.mdindex 992047b..341223d 100644--- a/docs/zh/cli/commands/config.md+++ b/docs/zh/cli/commands/config.md@@ -29,6 +29,7 @@ he config [COMMAND] [OPTIONS]- **百炼 preset**: `qwen3.6-plus` + `text-embedding-v4`- **DeepSeek preset**: `deepseek-v4-flash`(仅 LLM —— 无嵌入预设)- **Anthropic preset**: `claude-opus-4-8`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器)+- **Google Gemini preset**: `gemini-3.8-flash`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器;别名 `gemini`)```bashhe config init [OPTIONS]@@ -38,7 +39,7 @@ he config init [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `deepseek` / `bailian` / `vllm`) |+| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `google` / `deepseek` / `bailian` / `vllm`) || `--api-key` | `-k` | LLM 和嵌入模型的 API 密钥 || `--base-url` | `-u` | 自定义 API 基础 URL(可选) |@@ -60,6 +61,10 @@ he config embedder -p openai -k sk-your-openai-key# Anthropic(仅 LLM —— 请搭配 OpenAI 兼容嵌入器)he config llm -p anthropic -k sk-your-anthropic-keyhe config embedder -p openai -k sk-your-openai-key++# Google Gemini(仅 LLM —— 请搭配 OpenAI 兼容嵌入器)+he config llm -p google -k your-google-api-key+he config embedder -p openai -k sk-your-openai-key```执行后会自动保存对应 preset 的默认模型和 API 地址。@@ -114,7 +119,7 @@ he config llm [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`deepseek`、`bailian`、`vllm`) |+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`deepseek`、`bailian`、`vllm`) || `--api-key` | `-k` | LLM API 密钥 || `--model` | `-m` | LLM 模型名称 || `--base-url` | `-u` | 自定义 API 基础 URL |@@ -157,7 +162,7 @@ he config embedder [OPTIONS]| 选项 | 简写 | 描述 ||--------|-------|-------------|-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`deepseek`、`bailian`、`vllm`) |+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`google`、`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 9dfb9bf..0967dd2 100644--- a/docs/zh/concepts/provider-system.md+++ b/docs/zh/concepts/provider-system.md@@ -1,6 +1,6 @@# Provider 系统-Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**阿里云百炼**、**DeepSeek**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。+Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**Google Gemini**、**阿里云百炼**、**DeepSeek**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。---@@ -12,6 +12,7 @@ Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**阿里|------|------|:--------:|:------:|------|| **OpenAI** | gpt-4o / gpt-4o-mini / gpt-5 | ✅ | ✅ | 官方原生支持,推荐 || **Anthropic** | claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 | ✅(工具调用) | ✅ | 仅 LLM——无嵌入接口(请搭配 OpenAI 兼容嵌入器)。需 `hyperextract[anthropic]` |+| **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` || **阿里云百炼** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | 直接使用,无需修改 || **阿里云百炼** | qwen-max / deepseek-v3 | ❌ | ❌ | 仅支持 `json_object`,不兼容 function calling 结构化输出 |@@ -52,6 +53,15 @@ llm, emb = create_client(embedder="openai:text-embedding-3-small",)+# Google Gemini —— 原生 ChatGoogleGenerativeAI(不是 OrcaRouter 的 gemini/... 网关)。+# 仅 LLM;请搭配 OpenAI 兼容嵌入器。+# 密钥:GOOGLE_API_KEY(或 GEMINI_API_KEY)。别名:"gemini"。+# 额外依赖:pip install 'hyperextract[google]'。+llm, emb = create_client(+ llm="google", # 默认模型:gemini-3.8-flash(用 "google:<model>" 覆盖)+ embedder="openai:text-embedding-3-small",+)+# DeepSeek —— OpenAI 兼容,但无嵌入接口。V4 模型默认开启 "thinking" 模式,# Hyper-Extract 会自动关闭以保证工具调用(function_calling)结构化抽取可用。# 密钥:DEEPSEEK_API_KEY。用 "deepseek:deepseek-v4-pro" 覆盖模型。diff --git a/hyperextract/cli/commands/config.py b/hyperextract/cli/commands/config.pyindex b716db2..07cd71c 100644--- a/hyperextract/cli/commands/config.py+++ b/hyperextract/cli/commands/config.py@@ -151,7 +151,7 @@ def llm(None,"--provider","-p",- help="Provider preset: openai, anthropic, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",),api_key: str | None = typer.Option(None,@@ -212,7 +212,7 @@ def embedder(None,"--provider","-p",- help="Provider preset: openai, anthropic, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",),api_key: str | None = typer.Option(None,@@ -275,7 +275,7 @@ def init(None,"--provider","-p",- help="Provider preset: openai, anthropic, deepseek, bailian, orcarouter, vllm",+ help="Provider preset: openai, anthropic, google, deepseek, bailian, orcarouter, vllm",),api_key: str | None = typer.Option(None,@@ -374,6 +374,7 @@ def init(("deepseek", "DeepSeek", "https://api.deepseek.com"),("orcarouter", "OrcaRouter", "https://api.orcarouter.ai/v1"),("anthropic", "Anthropic (Claude)", "native SDK"),+ ("google", "Google Gemini", "native SDK"),("vllm", "本地 vLLM", "自定义地址"),("custom", "其他 OpenAI 兼容接口", "自定义地址"),]diff --git a/hyperextract/utils/client.py b/hyperextract/utils/client.pyindex 7084f14..085ba1f 100644--- a/hyperextract/utils/client.py+++ b/hyperextract/utils/client.py@@ -77,16 +77,40 @@ PROVIDER_PRESETS: dict[str, dict[str, str | None]] = {"default_llm": "claude-opus-4-8","default_embedder": None,},+ # Google Gemini. Uses the native ChatGoogleGenerativeAI client+ # (langchain-google-genai), so base_url is empty. Gemini Developer API+ # has no mature embedder path in this repo — pair with an OpenAI-compatible+ # embedder. Default model is the current documented stable Flash id+ # (Gemini API models page, 2026-09-04): gemini-3.8-flash.+ "google": {+ "base_url": "",+ "default_llm": "gemini-3.8-flash",+ "default_embedder": None,+ },+ "gemini": {+ "base_url": "",+ "default_llm": "gemini-3.8-flash",+ "default_embedder": None,+ },}# Providers handled by the native langchain-anthropic client rather than the# OpenAI-compatible path.ANTHROPIC_PROVIDERS = ("anthropic", "claude")+# Providers handled by the native langchain-google-genai client.+GOOGLE_PROVIDERS = ("google", "gemini")++# Native (non-OpenAI-compatible) LLM providers — do not fall back to+# OPENAI_API_KEY when their own env vars are unset.+_NATIVE_LLM_PROVIDERS = ANTHROPIC_PROVIDERS + GOOGLE_PROVIDERS+# Environment variables checked (in order) for each provider's API key.PROVIDER_API_KEY_ENV: dict[str, tuple[str, ...]] = {"anthropic": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),"claude": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),+ "google": ("GOOGLE_API_KEY", "GEMINI_API_KEY"),+ "gemini": ("GOOGLE_API_KEY", "GEMINI_API_KEY"),"deepseek": ("DEEPSEEK_API_KEY",),"orcarouter": ("ORCAROUTER_API_KEY",),}@@ -101,7 +125,7 @@ def _env_api_key(provider: str) -> str:value = os.environ.get(var, "")if value:return value- if provider not in ANTHROPIC_PROVIDERS:+ if provider not in _NATIVE_LLM_PROVIDERS:return os.environ.get("OPENAI_API_KEY", "")return ""@@ -378,6 +402,28 @@ def create_llm(max_tokens=config.get("max_tokens", 4096),)+ if provider in GOOGLE_PROVIDERS:+ try:+ from langchain_google_genai import ChatGoogleGenerativeAI+ except ImportError as e:+ raise ImportError(+ "The Google / Gemini provider requires 'langchain-google-genai'. "+ "Install it with: pip install 'hyperextract[google]'"+ ) from e++ resolved_key = config["api_key"] or _env_api_key(provider)+ if not resolved_key:+ raise ValueError(+ "No Google API key found. Set GOOGLE_API_KEY (or GEMINI_API_KEY), "+ "or pass api_key=..."+ )++ return ChatGoogleGenerativeAI(+ model=config["model"],+ api_key=resolved_key,+ temperature=config.get("temperature", 0),+ )+from langchain_openai import ChatOpenAI# DeepSeek V4 models default to "thinking" mode, which rejects the@@ -422,13 +468,21 @@ def create_embedder("""config = _parse_client_spec(spec, api_key=api_key, default_kind="embedder")- if config.get("provider", "") in ANTHROPIC_PROVIDERS:+ provider = config.get("provider", "")+ if provider in ANTHROPIC_PROVIDERS:raise ValueError("Anthropic does not provide an embeddings API. Configure a separate ""OpenAI-compatible embedder, e.g. "'create_client(llm="anthropic", embedder="openai:text-embedding-3-small", ...) '"or a local vLLM/bge-m3 endpoint.")+ if provider in GOOGLE_PROVIDERS:+ raise ValueError(+ "Google / Gemini has no mature embeddings path in this repo. Configure a "+ "separate OpenAI-compatible embedder, e.g. "+ 'create_client(llm="google", embedder="openai:text-embedding-3-small", ...) '+ "or a local vLLM/bge-m3 endpoint."+ )base_url = config.get("base_url", "")uses_custom = bool(base_url and base_url.rstrip("/") != OPENAI_API_URL)diff --git a/tests/cli/test_config.py b/tests/cli/test_config.pyindex b04846c..9a90498 100644--- a/tests/cli/test_config.py+++ b/tests/cli/test_config.py@@ -146,6 +146,11 @@ def test_cli_provider_tables_are_library_presets():assert cli_config.PROVIDER_API_KEY_ENV is PROVIDER_API_KEY_ENVassert "orcarouter" in cli_config.PROVIDER_PRESETSassert cli_config.PROVIDER_API_KEY_ENV["orcarouter"] == ("ORCAROUTER_API_KEY",)+ assert "google" in cli_config.PROVIDER_PRESETS+ assert cli_config.PROVIDER_API_KEY_ENV["google"] == (+ "GOOGLE_API_KEY",+ "GEMINI_API_KEY",+ )def test_get_llm_config_reads_orcarouter_env_key(tmp_path, monkeypatch):@@ -184,3 +189,19 @@ def test_interactive_init_lists_orcarouter_and_anthropic():source = inspect.getsource(init)assert '"orcarouter"' in sourceassert '"anthropic"' in source+ assert '"google"' in source+++def test_get_llm_config_reads_google_env_key(tmp_path, monkeypatch):+ """Empty toml api_key must resolve GOOGLE_API_KEY for google."""+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.setenv("GOOGLE_API_KEY", "sk-google-from-env")++ cm = ConfigManager(tmp_path / "config.toml")+ cm.set_llm(provider="google", model="gemini-3.8-flash", api_key="")+ cfg = cm.get_llm_config()++ assert cfg.api_key == "sk-google-from-env"+ assert cfg.base_url == ""diff --git a/tests/utils/test_client.py b/tests/utils/test_client.pyindex 49b9df2..bd55c2a 100644--- a/tests/utils/test_client.py+++ b/tests/utils/test_client.py@@ -612,3 +612,91 @@ class TestProviderPresets:assert "base_url" in presetassert "default_llm" in presetassert "default_embedder" in preset++ def test_google_provider(self):+ """Native Gemini extra is wired (not OrcaRouter)."""+ assert "google" in PROVIDER_PRESETS+ preset = PROVIDER_PRESETS["google"]+ assert preset["base_url"] == ""+ assert preset["default_llm"] == "gemini-3.8-flash"+ assert preset["default_embedder"] is None+ assert PROVIDER_PRESETS["gemini"] == preset+++class TestGoogleGeminiProvider:+ """Google / Gemini native client — no live API calls."""++ def test_parse_google_defaults(self):+ result = _parse_client_spec("google", api_key="sk-google")+ assert result["provider"] == "google"+ assert result["model"] == "gemini-3.8-flash"+ assert result["base_url"] == ""++ def test_parse_gemini_alias(self):+ result = _parse_client_spec("gemini:gemini-2.5-flash", api_key="sk-google")+ assert result["provider"] == "gemini"+ assert result["model"] == "gemini-2.5-flash"++ def test_env_prefers_google_then_gemini(self, monkeypatch):+ from hyperextract.utils.client import _env_api_key++ monkeypatch.delenv("GOOGLE_API_KEY", raising=False)+ monkeypatch.setenv("GEMINI_API_KEY", "sk-gemini-only")+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-must-not-win")+ assert _env_api_key("google") == "sk-gemini-only"++ monkeypatch.setenv("GOOGLE_API_KEY", "sk-google-first")+ assert _env_api_key("gemini") == "sk-google-first"++ def test_env_does_not_fall_back_to_openai(self, monkeypatch):+ from hyperextract.utils.client import _env_api_key++ monkeypatch.delenv("GOOGLE_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-must-not-win")+ assert _env_api_key("google") == ""++ def test_create_llm_uses_chat_google(self):+ with patch("langchain_google_genai.ChatGoogleGenerativeAI") as MockChat:+ create_llm("google:gemini-3.8-flash", api_key="sk-google-1")+ MockChat.assert_called_once()+ kwargs = MockChat.call_args.kwargs+ assert kwargs["model"] == "gemini-3.8-flash"+ assert kwargs["api_key"] == "sk-google-1"+ assert kwargs["temperature"] == 0++ def test_create_llm_env_key(self, monkeypatch):+ monkeypatch.setenv("GOOGLE_API_KEY", "sk-google-env")+ with patch("langchain_google_genai.ChatGoogleGenerativeAI") as MockChat:+ create_llm("google")+ assert MockChat.call_args.kwargs["api_key"] == "sk-google-env"++ def test_create_llm_missing_key_raises(self, monkeypatch):+ monkeypatch.delenv("GOOGLE_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ with patch("langchain_google_genai.ChatGoogleGenerativeAI"):+ with pytest.raises(ValueError, match="Google API key"):+ create_llm("google")++ def test_create_llm_missing_extra_import_error(self):+ import builtins++ real_import = builtins.__import__++ def fake_import(name, *args, **kwargs):+ if name == "langchain_google_genai" or name.startswith(+ "langchain_google_genai."+ ):+ raise ImportError("simulated missing extra")+ return real_import(name, *args, **kwargs)++ with patch("builtins.__import__", side_effect=fake_import):+ with pytest.raises(ImportError, match="hyperextract\\[google\\]"):+ create_llm("google", api_key="sk-google-1")++ def test_create_embedder_raises(self):+ with pytest.raises(ValueError, match="embeddings"):+ create_embedder("google", api_key="sk-google")+ with pytest.raises(ValueError, match="embeddings"):+ create_embedder("gemini", api_key="sk-google")