Skip to content

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.example
index 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-here
diff --git a/README.md b/README.md
index 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 Start
diff --git a/README_ZH.md b/README_ZH.md
index 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.py
index 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.py
index 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 ""
+
@dataclass
class 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.py
index 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 ChatOpenAI
return 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.py
new file mode 100644
index 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"