Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

Merge branch 'main' into pr-71: resolve client.py/test_client.py conflicts

yifanfeng971f6ef987939c
diff --cc docs/en/concepts/provider-system.md
index d0a871e,6dd5a2e..dbb5ac4
--- a/docs/en/concepts/provider-system.md
+++ b/docs/en/concepts/provider-system.md
@@@ -13,11 -13,10 +13,11 @@@ Hyper-Extract supports these ways to co
| **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 |
+ | **Alibaba Bailian** | qwen-max / deepseek-v3 | ❌ | ❌ | Only `json_object`; not compatible with function-calling structured output |
- > **Bailian users**: Both qwen-max and deepseek-v3 do not support `json_schema`. If you hit `messages must contain the word 'json'` or get non-JSON output, switch to qwen-plus, qwen-turbo, or deepseek-r1. See [Issue #24](https://github.com/yifanfeng97/Hyper-Extract/issues/24).
+ > **Bailian users**: qwen-max and deepseek-v3 only support `json_object` and are not compatible with Hyper-Extract's function-calling structured output. If you hit `messages must contain the word 'json'` or get non-JSON output, switch to qwen-plus, qwen-turbo, or deepseek-r1. See [Issue #24](https://github.com/yifanfeng97/Hyper-Extract/issues/24).
### Local Deployment
diff --cc tests/utils/test_client.py
index 8fbea76,010cd93..76a27a6
--- a/tests/utils/test_client.py
+++ b/tests/utils/test_client.py
@@@ -130,18 -116,42 +130,54 @@@ 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_deepseek_reads_provider_env_key(self, monkeypatch):
+ """create_llm('deepseek') uses DEEPSEEK_API_KEY when api_key is omitted."""
+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+ monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-deepseek-test")
+ llm = create_llm("deepseek")
+ assert llm.openai_api_key.get_secret_value() == "sk-deepseek-test"
+
+ def test_create_llm_deepseek_prefers_provider_env_over_openai(self, monkeypatch):
+ """DeepSeek prefers DEEPSEEK_API_KEY when both provider and OpenAI keys are set."""
+ monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-deepseek-test")
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-test")
+ llm = create_llm("deepseek")
+ assert llm.openai_api_key.get_secret_value() == "sk-deepseek-test"
+
+ def test_create_llm_openai_still_uses_openai_env_key(self, monkeypatch):
+ """OpenAI shorthand still resolves OPENAI_API_KEY (regression)."""
+ monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-test")
+ llm = create_llm("openai:gpt-4o-mini")
+ assert llm.model_name == "gpt-4o-mini"
+ assert llm.openai_api_key.get_secret_value() == "sk-openai-test"
+
+ def test_create_llm_explicit_api_key_wins(self, monkeypatch):
+ """Explicit api_key= takes priority over provider and OpenAI env vars."""
+ monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-deepseek-test")
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-test")
+ llm = create_llm("deepseek", api_key="sk-explicit")
+ assert llm.openai_api_key.get_secret_value() == "sk-explicit"
+
+ def test_create_llm_deepseek_falls_back_to_openai_env_key(self, monkeypatch):
+ """DeepSeek still falls back to OPENAI_API_KEY when DEEPSEEK_API_KEY is unset."""
+ monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-test")
+ llm = create_llm("deepseek")
+ assert llm.openai_api_key.get_secret_value() == "sk-openai-test"
+
def test_create_llm_custom_model(self):
"""Override model via string shorthand."""
llm = create_llm("bailian:qwen-plus", api_key="sk-test")
@@@ -182,18 -192,26 +218,38 @@@ 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"
+
+ def test_create_embedder_reads_openai_env_key(self, monkeypatch):
+ """create_embedder uses _env_api_key so OPENAI_API_KEY is picked up."""
+ monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-emb")
+ emb = create_embedder("openai")
+ assert emb.openai_api_key.get_secret_value() == "sk-openai-emb"
+
+ def test_create_embedder_explicit_api_key_wins(self, monkeypatch):
+ """Explicit api_key= still wins for embedders (regression)."""
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-emb")
+ emb = create_embedder("openai", api_key="sk-explicit-emb")
+ assert emb.openai_api_key.get_secret_value() == "sk-explicit-emb"
+
+ def test_create_embedder_custom_url_reads_openai_env_key(self, monkeypatch):
+ """CompatibleEmbeddings path also resolves the env key via the factory."""
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-emb")
+ emb = create_embedder("bailian")
+ assert isinstance(emb, CompatibleEmbeddings)
+ assert emb._client.api_key == "sk-openai-emb"
+
# =============================================================================
# create_client (unified API)