Skip to content

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.md
index 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 vLLM
llm, 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.md
index 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.py
index 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.py
index 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():