Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: add Anthropic (Claude) LLM provider
Oguz Vuruskanera41c515777f1
diff --git a/.env.example b/.env.exampleindex 2fc8dcd..dce16dd 100644--- a/.env.example+++ b/.env.example@@ -1,5 +1,9 @@-# OpenAI API Key (Required)+# OpenAI API Key (Required for OpenAI-compatible providers and embeddings)OPENAI_API_KEY=sk-your-api-key-here# Base URL (Optional, configure when using proxy)OPENAI_BASE_URL=https://api.openai.com/v1++# Anthropic / Claude API Key (Optional, required when using the anthropic provider)+# CLAUDE_API_KEY is also accepted as an alias.+ANTHROPIC_API_KEY=sk-ant-your-api-key-herediff --git a/README.md b/README.mdindex f6a90ab..d5a501f 100644--- a/README.md+++ b/README.md@@ -98,11 +98,19 @@ Hyper-Extract relies on the LLM's structured output capability (`json_schema` or| Platform | Verified Models ||----------|-----------------|| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-5 |+| **Anthropic** | claude-sonnet-4-6, claude-opus-4-1, claude-haiku-4-5 || **阿里云百炼** | qwen-plus, qwen-turbo, deepseek-r1 || **Local vLLM** | Qwen3.5-9B (GPTQ-Marlin) |**Embedding models** (semantic search) work with any OpenAI-compatible endpoint: `text-embedding-3-small`, `text-embedding-v4` (Bailian), `bge-m3` (local vLLM).+> **Anthropic note:** Claude is used for the **LLM** (set `ANTHROPIC_API_KEY`). Anthropic has no embeddings API, so pair it with an OpenAI-compatible embedder:+> ```python+> from hyperextract import create_client+> llm, emb = create_client(llm="anthropic", embedder="openai:text-embedding-3-small")+> ```+> Requires the extra: `pip install 'hyperextract[anthropic]'`.+> 📖 Full guide: [Provider System & Local Model Support](https://yifanfeng97.github.io/Hyper-Extract/latest/concepts/provider-system/)## ⚡ 30-Second Quick Startdiff --git a/README_ZH.md b/README_ZH.mdindex a08f684..30d9784 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -98,11 +98,19 @@ Hyper-Extract 依赖大语言模型的结构化输出能力(`json_schema` 或| 平台 | 已验证模型 ||----------|-----------------|| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-5 |+| **Anthropic** | claude-sonnet-4-6, claude-opus-4-1, claude-haiku-4-5 || **阿里云百炼** | qwen-plus, qwen-turbo, deepseek-r1 || **本地 vLLM** | Qwen3.5-9B (GPTQ-Marlin) |**嵌入模型**(语义搜索)支持任意 OpenAI 兼容端点:`text-embedding-3-small`、`text-embedding-v4`(百炼)、`bge-m3`(本地 vLLM)。+> **Anthropic 说明:** Claude 仅用于 **LLM**(设置 `ANTHROPIC_API_KEY`)。Anthropic 没有嵌入接口,请搭配 OpenAI 兼容的嵌入模型使用:+> ```python+> from hyperextract import create_client+> llm, emb = create_client(llm="anthropic", embedder="openai:text-embedding-3-small")+> ```+> 需安装额外依赖:`pip install 'hyperextract[anthropic]'`。+> 📖 完整指南:[Provider 系统与本地模型支持](https://yifanfeng97.github.io/Hyper-Extract/latest/zh/concepts/provider-system/)## ⚡ 30 秒快速上手diff --git a/hyperextract/cli/commands/config.py b/hyperextract/cli/commands/config.pyindex da550b8..04c21cc 100644--- a/hyperextract/cli/commands/config.py+++ b/hyperextract/cli/commands/config.py@@ -85,6 +85,9 @@ def config_callback(console.print(" [green]OPENAI_API_KEY[/green] - OpenAI API key (used if not set in config)")+ console.print(+ " [green]ANTHROPIC_API_KEY[/green] - Anthropic/Claude API key (or CLAUDE_API_KEY)"+ )console.print(" [green]OPENAI_BASE_URL[/green] - Custom API base URL (optional)")console.print()@@ -148,7 +151,7 @@ def llm(None,"--provider","-p",- help="Provider preset: openai, bailian, vllm",+ help="Provider preset: openai, anthropic, bailian, vllm",),api_key: Optional[str] = typer.Option(None,@@ -209,7 +212,7 @@ def embedder(None,"--provider","-p",- help="Provider preset: openai, bailian, vllm",+ help="Provider preset: openai, anthropic, bailian, vllm",),api_key: Optional[str] = typer.Option(None,@@ -272,7 +275,7 @@ def init(None,"--provider","-p",- help="Provider preset: openai, bailian, vllm",+ help="Provider preset: openai, anthropic, bailian, vllm",),api_key: Optional[str] = typer.Option(None,diff --git a/hyperextract/cli/config.py b/hyperextract/cli/config.pyindex a171925..a5a275e 100644--- a/hyperextract/cli/config.py+++ b/hyperextract/cli/config.py@@ -29,8 +29,37 @@ PROVIDER_PRESETS: Dict[str, Dict[str, str | None]] = {"default_llm": None,"default_embedder": None,},+ # Anthropic (Claude): native client, no base_url, no embeddings API.+ "anthropic": {+ "base_url": "",+ "default_llm": "claude-sonnet-4-6",+ "default_embedder": None,+ },+ "claude": {+ "base_url": "",+ "default_llm": "claude-sonnet-4-6",+ "default_embedder": None,+ },}+# Environment variables checked (in order) for each provider's API key.+PROVIDER_API_KEY_ENV: Dict[str, tuple] = {+ "anthropic": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),+ "claude": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),+}+++def _env_api_key(provider: str) -> str:+ """Return the first non-empty API key from the provider's env vars.++ Falls back to OPENAI_API_KEY for OpenAI-compatible providers.+ """+ for var in PROVIDER_API_KEY_ENV.get(provider, ("OPENAI_API_KEY",)):+ value = os.environ.get(var, "")+ if value:+ return value+ return ""+@dataclassclass LLMConfig:@@ -135,7 +164,7 @@ class ConfigManager:config = LLMConfig(provider=self.llm.provider,model=self.llm.model,- api_key=self.llm.api_key or os.environ.get("OPENAI_API_KEY", ""),+ api_key=self.llm.api_key or _env_api_key(self.llm.provider),base_url=self._resolve_base_url(self.llm.provider,self.llm.base_url or os.environ.get("OPENAI_BASE_URL", ""),@@ -148,7 +177,7 @@ class ConfigManager:config = EmbedderConfig(provider=self.embedder.provider,model=self.embedder.model,- api_key=self.embedder.api_key or os.environ.get("OPENAI_API_KEY", ""),+ api_key=self.embedder.api_key or _env_api_key(self.embedder.provider),base_url=self._resolve_base_url(self.embedder.provider,self.embedder.base_url or os.environ.get("OPENAI_BASE_URL", ""),diff --git a/hyperextract/utils/client.py b/hyperextract/utils/client.pyindex cc41c60..9b2510b 100644--- a/hyperextract/utils/client.py+++ b/hyperextract/utils/client.py@@ -44,8 +44,44 @@ PROVIDER_PRESETS: Dict[str, Dict[str, str | None]] = {"default_llm": None,"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+ # OpenAI-compatible embedder.+ "anthropic": {+ "base_url": "",+ "default_llm": "claude-sonnet-4-6",+ "default_embedder": None,+ },+ "claude": {+ "base_url": "",+ "default_llm": "claude-sonnet-4-6",+ "default_embedder": None,+ },}+# Providers handled by the native langchain-anthropic client rather than the+# OpenAI-compatible path.+ANTHROPIC_PROVIDERS = ("anthropic", "claude")++# 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"),+}+++def _env_api_key(provider: str) -> str:+ """Return the first non-empty API key from the provider's env vars.++ Falls back to OPENAI_API_KEY for OpenAI-compatible providers.+ """+ for var in PROVIDER_API_KEY_ENV.get(provider, ("OPENAI_API_KEY",)):+ value = os.environ.get(var, "")+ if value:+ return value+ return ""+class CompatibleEmbeddings(Embeddings):"""Embeddings for OpenAI-compatible providers that only accept string input.@@ -274,6 +310,33 @@ def create_llm(config = _parse_client_spec(spec, api_key=api_key, default_kind="llm")config.update(kwargs)+ provider = config.get("provider", "")++ if provider in ANTHROPIC_PROVIDERS:+ try:+ from langchain_anthropic import ChatAnthropic+ except ImportError as e:+ raise ImportError(+ "The Anthropic provider requires 'langchain-anthropic'. "+ "Install it with: pip install 'hyperextract[anthropic]'"+ ) from e++ resolved_key = config["api_key"] or _env_api_key(provider)+ if not resolved_key:+ raise ValueError(+ "No Anthropic API key found. Set ANTHROPIC_API_KEY (or CLAUDE_API_KEY), "+ "or pass api_key=..."+ )++ return ChatAnthropic(+ model=config["model"],+ api_key=resolved_key,+ temperature=config.get("temperature", 0),+ # Anthropic requires max_tokens; default low (1024) truncates large+ # structured extractions, so use a more generous default.+ max_tokens=config.get("max_tokens", 4096),+ )+from langchain_openai import ChatOpenAIreturn ChatOpenAI(@@ -306,6 +369,14 @@ def create_embedder("""config = _parse_client_spec(spec, api_key=api_key, default_kind="embedder")+ if config.get("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."+ )+base_url = config.get("base_url", "")uses_custom = bool(base_url and base_url.rstrip("/") != OPENAI_API_URL)diff --git a/tests/utils/test_anthropic.py b/tests/utils/test_anthropic.pynew file mode 100644index 0000000..37a5589--- /dev/null+++ b/tests/utils/test_anthropic.py@@ -0,0 +1,144 @@+"""Tests for the Anthropic (Claude) provider integration."""++from unittest.mock import patch++import pytest++from hyperextract.utils.client import (+ ANTHROPIC_PROVIDERS,+ PROVIDER_PRESETS,+ _env_api_key,+ _parse_client_spec,+ create_embedder,+ create_llm,+)+++# ---------------------------------------------------------------------------+# Presets+# ---------------------------------------------------------------------------+++class TestAnthropicPresets:+ def test_anthropic_preset(self):+ preset = PROVIDER_PRESETS["anthropic"]+ assert preset["base_url"] == "" # native client, no base_url needed+ assert preset["default_llm"]+ assert preset["default_embedder"] is None # no embeddings API++ def test_claude_alias_matches_anthropic(self):+ assert PROVIDER_PRESETS["claude"] == PROVIDER_PRESETS["anthropic"]++ def test_providers_constant(self):+ assert "anthropic" in ANTHROPIC_PROVIDERS+ assert "claude" in ANTHROPIC_PROVIDERS+++# ---------------------------------------------------------------------------+# Spec parsing+# ---------------------------------------------------------------------------+++class TestParseAnthropicSpec:+ def test_default_model(self):+ result = _parse_client_spec("anthropic", default_kind="llm")+ assert result["provider"] == "anthropic"+ assert result["model"] == PROVIDER_PRESETS["anthropic"]["default_llm"]++ def test_explicit_model(self):+ result = _parse_client_spec("anthropic:claude-opus-4-1", default_kind="llm")+ assert result["provider"] == "anthropic"+ assert result["model"] == "claude-opus-4-1"+++# ---------------------------------------------------------------------------+# API key env resolution+# ---------------------------------------------------------------------------+++class TestEnvApiKey:+ def test_anthropic_uses_anthropic_key(self, monkeypatch):+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-xyz")+ assert _env_api_key("anthropic") == "sk-ant-xyz"++ def test_anthropic_falls_back_to_claude_key(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.setenv("CLAUDE_API_KEY", "sk-claude")+ assert _env_api_key("claude") == "sk-claude"++ def test_openai_default(self, monkeypatch):+ monkeypatch.setenv("OPENAI_API_KEY", "sk-oai")+ assert _env_api_key("openai") == "sk-oai"+++# ---------------------------------------------------------------------------+# create_llm — Anthropic branch+# ---------------------------------------------------------------------------+++class TestCreateLLMAnthropic:+ def test_builds_chatanthropic(self):+ with patch("langchain_anthropic.ChatAnthropic") as MockChat:+ create_llm("anthropic:claude-sonnet-4-6", api_key="sk-ant-1")+ MockChat.assert_called_once()+ kwargs = MockChat.call_args.kwargs+ assert kwargs["model"] == "claude-sonnet-4-6"+ assert kwargs["api_key"] == "sk-ant-1"+ assert kwargs["temperature"] == 0+ assert kwargs["max_tokens"] == 4096++ def test_env_key_fallback(self, monkeypatch):+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-env")+ with patch("langchain_anthropic.ChatAnthropic") as MockChat:+ create_llm("anthropic")+ assert MockChat.call_args.kwargs["api_key"] == "sk-env"++ def test_missing_key_raises(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.delenv("CLAUDE_API_KEY", raising=False)+ with patch("langchain_anthropic.ChatAnthropic"):+ with pytest.raises(ValueError, match="Anthropic API key"):+ create_llm("anthropic")++ def test_temperature_and_max_tokens_forwarded(self):+ with patch("langchain_anthropic.ChatAnthropic") as MockChat:+ create_llm("anthropic", api_key="k", temperature=0.7, max_tokens=8192)+ kwargs = MockChat.call_args.kwargs+ assert kwargs["temperature"] == 0.7+ assert kwargs["max_tokens"] == 8192+++# ---------------------------------------------------------------------------+# create_embedder — Anthropic guard+# ---------------------------------------------------------------------------+++class TestCreateEmbedderAnthropicGuard:+ def test_anthropic_embedder_raises(self):+ with pytest.raises(ValueError, match="embeddings"):+ create_embedder("anthropic", api_key="sk-ant")++ def test_claude_embedder_raises(self):+ with pytest.raises(ValueError, match="embeddings"):+ create_embedder("claude", api_key="sk-ant")+++# ---------------------------------------------------------------------------+# ConfigManager integration+# ---------------------------------------------------------------------------+++class TestConfigManagerAnthropic:+ def test_resolves_without_base_url_error(self, tmp_path, monkeypatch):+ from hyperextract.cli.config import ConfigManager++ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-cfg")++ cm = ConfigManager(tmp_path / "config.toml")+ cm.set_llm(provider="anthropic", model="claude-sonnet-4-6", api_key="")+ cfg = cm.get_llm_config()++ assert cfg.provider == "anthropic"+ assert cfg.base_url == "" # must not raise (unlike vllm)+ assert cfg.api_key == "sk-ant-cfg"