Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
Add OrcaRouter as a named provider preset
Marc-oss-hub115b4cfe7570
diff --git a/docs/en/concepts/provider-system.md b/docs/en/concepts/provider-system.mdindex 8d8ff9f..d0a871e 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**, 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**, **Alibaba Bailian**, **DeepSeek**, **OrcaRouter**, and **local vLLM**. All use the same `create_client()` interface — only the first line changes.---@@ -13,6 +13,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]` || **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 || **Alibaba Bailian** | qwen-max / deepseek-v3 | ❌ | ❌ | Only `json_object`; `json_schema` not supported |@@ -62,6 +63,13 @@ llm, emb = create_client(embedder="openai:text-embedding-3-small", # or vllm:bge-m3@localhost:8001/v1)+# OrcaRouter — OpenAI-compatible gateway routing 150+ models (OpenAI,+# Anthropic, Google, DeepSeek, Qwen, MiniMax, xAI) behind one key. The default+# "orcarouter/auto" model routes to a suitable upstream; override with+# namespaced ids like "openai:gpt-4o-mini" or "anthropic:claude-haiku-4-5".+# Key: ORCAROUTER_API_KEY (fallback: OPENAI_API_KEY).+llm, emb = create_client("orcarouter")+# 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 b838045..480f7cb 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), or local vLLM deployments.+Configure Hyper-Extract to work with OpenAI, Bailian (Alibaba Cloud), DeepSeek, OrcaRouter, or local vLLM deployments.---@@ -52,6 +52,18 @@ llm, emb = create_client()```+### OrcaRouter++```python+from hyperextract import create_client, AutoGraph++# OrcaRouter is an OpenAI-compatible gateway routing 150+ models (OpenAI,+# Anthropic, Google, DeepSeek, Qwen, MiniMax, xAI) behind one endpoint and key.+# Key: ORCAROUTER_API_KEY (fallback: OPENAI_API_KEY).+llm, emb = create_client("orcarouter")+# Or override the model: create_client("orcarouter:openai/gpt-4o-mini", ...)+```+### Local vLLM```python@@ -91,6 +103,7 @@ print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")| **Bailian** | `he config init -p bailian -k sk-xxx` || **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` || **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/hyperextract/utils/client.py b/hyperextract/utils/client.pyindex dc0354c..ad77c40 100644--- a/hyperextract/utils/client.py+++ b/hyperextract/utils/client.py@@ -54,6 +54,15 @@ PROVIDER_PRESETS: dict[str, dict[str, str | None]] = {"default_llm": "deepseek-v4-flash","default_embedder": None,},+ # OrcaRouter. OpenAI-compatible model routing gateway exposing 150+ models+ # from OpenAI, Anthropic, Google, DeepSeek, Qwen, MiniMax, xAI and others+ # behind a single endpoint and API key. Namespaced model ids such as+ # "orcarouter/auto" route to a matching upstream.+ "orcarouter": {+ "base_url": "https://api.orcarouter.ai/v1",+ "default_llm": "orcarouter/auto",+ "default_embedder": "openai/text-embedding-3-small",+ },# 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@@ -79,6 +88,7 @@ PROVIDER_API_KEY_ENV: dict[str, tuple[str, ...]] = {"anthropic": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),"claude": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"),"deepseek": ("DEEPSEEK_API_KEY",),+ "orcarouter": ("ORCAROUTER_API_KEY",),}@@ -379,7 +389,7 @@ def create_llm(chat_kwargs: dict[str, Any] = {"model": config["model"],- "api_key": config["api_key"] or os.environ.get("OPENAI_API_KEY", ""),+ "api_key": config["api_key"] or _env_api_key(provider),"base_url": config.get("base_url") or None,"temperature": config.get("temperature", 0),}@@ -424,7 +434,7 @@ def create_embedder(if uses_custom:return CompatibleEmbeddings(model=config["model"],- api_key=config["api_key"] or os.environ.get("OPENAI_API_KEY", ""),+ api_key=config["api_key"] or _env_api_key(config.get("provider", "")),base_url=base_url,**kwargs,)@@ -433,7 +443,7 @@ def create_embedder(return OpenAIEmbeddings(model=config["model"],- api_key=config["api_key"] or os.environ.get("OPENAI_API_KEY", ""),+ api_key=config["api_key"] or _env_api_key(config.get("provider", "")),**kwargs,)diff --git a/tests/utils/test_client.py b/tests/utils/test_client.pyindex 12db895..8fbea76 100644--- a/tests/utils/test_client.py+++ b/tests/utils/test_client.py@@ -56,6 +56,20 @@ class TestParseClientSpec:result = _parse_client_spec("bailian", api_key="sk-test", default_kind="embedder")assert result["model"] == "text-embedding-v4" # default_embedder preset+ def test_provider_orcarouter(self):+ """OrcaRouter preset defaults (OpenAI-compatible gateway)."""+ result = _parse_client_spec("orcarouter", api_key="sk-test")+ assert result["provider"] == "orcarouter"+ assert result["model"] == "orcarouter/auto" # default_llm preset+ assert result["base_url"] == "https://api.orcarouter.ai/v1"++ def test_provider_orcarouter_embedder(self):+ """OrcaRouter embedder default uses the namespaced embedder model."""+ result = _parse_client_spec(+ "orcarouter", api_key="sk-test", default_kind="embedder"+ )+ assert result["model"] == "openai/text-embedding-3-small"+def test_dict_input(self):"""Dict input is passed through with api_key fallback."""result = _parse_client_spec(@@ -116,6 +130,18 @@ class TestCreateLLM:)assert llm.extra_body == {"thinking": {"type": "enabled"}}+ def test_create_llm_orcarouter(self):+ """Create LLM with orcarouter preset (OpenAI-compatible gateway)."""+ llm = create_llm("orcarouter", api_key="sk-test")+ assert llm.model_name == "orcarouter/auto"+ assert llm.openai_api_base == "https://api.orcarouter.ai/v1"++ def test_create_llm_orcarouter_env_key(self, monkeypatch):+ """OrcaRouter key is read from ORCAROUTER_API_KEY when api_key is omitted."""+ monkeypatch.setenv("ORCAROUTER_API_KEY", "sk-orca-test")+ llm = create_llm("orcarouter")+ assert llm.openai_api_key.get_secret_value() == "sk-orca-test"+def test_create_llm_custom_model(self):"""Override model via string shorthand."""llm = create_llm("bailian:qwen-plus", api_key="sk-test")@@ -156,6 +182,18 @@ class TestCreateEmbedder:assert isinstance(emb, CompatibleEmbeddings)assert emb._model == "bge-m3"+ def test_create_embedder_orcarouter(self):+ """OrcaRouter embedder uses CompatibleEmbeddings (custom base_url)."""+ emb = create_embedder("orcarouter", api_key="sk-test")+ assert isinstance(emb, CompatibleEmbeddings)+ assert emb._model == "openai/text-embedding-3-small"++ def test_create_embedder_orcarouter_env_key(self, monkeypatch):+ """OrcaRouter embedder reads ORCAROUTER_API_KEY when api_key is omitted."""+ monkeypatch.setenv("ORCAROUTER_API_KEY", "sk-orca-test")+ emb = create_embedder("orcarouter")+ assert emb._client.api_key == "sk-orca-test"+# =============================================================================# create_client (unified API)@@ -491,6 +529,14 @@ class TestProviderPresets:assert preset["default_llm"] == "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+ preset = PROVIDER_PRESETS["orcarouter"]+ assert preset["base_url"] == "https://api.orcarouter.ai/v1"+ assert preset["default_llm"] == "orcarouter/auto"+ assert preset["default_embedder"] == "openai/text-embedding-3-small"+def test_all_presets_have_base_url_or_none(self):"""Every preset has either a base_url or None (for vLLM)."""for name, preset in PROVIDER_PRESETS.items():