Skip to content

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

docs: catch MCP exports, orcarouter, HE-T008, and document type

Frankie-Xu4e595f053480
diff --git a/docs/en/cli/commands/config.md b/docs/en/cli/commands/config.md
index d395839..d0f076c 100644
--- a/docs/en/cli/commands/config.md
+++ b/docs/en/cli/commands/config.md
@@ -29,6 +29,7 @@ Initialize configuration. This is the **lazy one-step setup** — if you pass `-
- **Bailian preset**: `qwen3.6-plus` + `text-embedding-v4`
- **DeepSeek preset**: `deepseek-v4-flash` (LLM only — no embedder preset)
- **Anthropic preset**: `claude-opus-4-8` (LLM only — no embedder preset, pair with an OpenAI-compatible embedder)
+- **OrcaRouter preset**: `orcarouter/auto` (OpenAI-compatible gateway; key `ORCAROUTER_API_KEY`)
```bash
he config init [OPTIONS]
@@ -38,7 +39,7 @@ he config init [OPTIONS]
| Option | Short | Description |
|--------|-------|-------------|
-| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `deepseek` / `bailian` / `vllm`) |
+| `--provider` | `-p` | Provider preset (`openai` / `anthropic` / `orcarouter` / `deepseek` / `bailian` / `vllm`) |
| `--api-key` | `-k` | API key for both LLM and embedder |
| `--base-url` | `-u` | Custom API base URL (optional) |
@@ -60,6 +61,9 @@ he config embedder -p openai -k sk-your-openai-key
# Anthropic (LLM only — pair with an OpenAI-compatible embedder)
he config llm -p anthropic -k sk-your-anthropic-key
he config embedder -p openai -k sk-your-openai-key
+
+# OrcaRouter (OpenAI-compatible gateway)
+he config init -p orcarouter -k or-your-orcarouter-key
```
This saves the preset's default model and API URL automatically.
@@ -114,7 +118,7 @@ he config llm [OPTIONS]
| Option | Short | Description |
|--------|-------|-------------|
-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `deepseek`, `bailian`, `vllm`) |
+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `orcarouter`, `deepseek`, `bailian`, `vllm`) |
| `--api-key` | `-k` | LLM API key |
| `--model` | `-m` | LLM model name |
| `--base-url` | `-u` | Custom API base URL |
@@ -157,7 +161,7 @@ he config embedder [OPTIONS]
| Option | Short | Description |
|--------|-------|-------------|
-| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `deepseek`, `bailian`, `vllm`) |
+| `--provider` | `-p` | Provider preset (e.g. `openai`, `anthropic`, `orcarouter`, `deepseek`, `bailian`, `vllm`) |
| `--api-key` | `-k` | Embedder API key |
| `--model` | `-m` | Embedder model name |
| `--base-url` | `-u` | Custom API base URL |
diff --git a/docs/en/cli/commands/template.md b/docs/en/cli/commands/template.md
index 30a5e02..03d7b7e 100644
--- a/docs/en/cli/commands/template.md
+++ b/docs/en/cli/commands/template.md
@@ -44,7 +44,7 @@ Checks follow `hyperextract-skills/yaml-validator/` and `templates/DESIGN_GUIDE.
| `HE-T005` | Display `{field}` placeholders exist on the corresponding schema | error |
| `HE-T006` | Temporal types define `time_field`; spatial types define `location_field` | error |
| `HE-T007` | Declared languages are present on bilingual dict fields | warning |
-| `HE-T008` | Entity or relation field count exceeds the DESIGN_GUIDE limit of 5 | warning |
+| `HE-T008` | Field count exceeds the DESIGN_GUIDE limit of 5 (graph entity/relation, or `model`/`list`/`set` `output.fields`) | warning |
| `HE-T009` | `domain/name` collides with a Gallery preset | warning |
Exit code **1** if any **error** is reported; **0** if the template is clean or has warnings only.
diff --git a/docs/en/mcp.md b/docs/en/mcp.md
index 13978db..533c711 100644
--- a/docs/en/mcp.md
+++ b/docs/en/mcp.md
@@ -46,10 +46,12 @@ Point your MCP client at the `he-mcp` command. For a Claude Desktop–style conf
| `search` | Semantic retrieval over a KA | ✓ | embedder |
| `ask` | RAG question-answering over a KA | ✓ | ✓ |
| `export_obsidian` | Export a KA to an Obsidian vault | — | embedder |
+| `export_graphml` | Export a KA to GraphML (same as `he export graphml`) | — | embedder |
+| `export_csv` | Export a KA to CSV tables (same as `he export csv`) | — | embedder |
All tools take a `ka_path` (a directory created by `he parse`). `search`/`ask` require an index — build it with [`he build-index`](cli/commands/build-index.md).
-> `export_obsidian` requires the Obsidian export feature (see [`he export obsidian`](cli/commands/export.md)). If it is unavailable, the tool returns an explanatory message instead of failing.
+> `export_obsidian` requires the Obsidian export feature (see [`he export obsidian`](cli/commands/export.md)). If it is unavailable, the tool returns an explanatory message instead of failing. `export_graphml` / `export_csv` use the same exporters as the CLI (see [`he export`](cli/commands/export.md)).
---
diff --git a/docs/zh/cli/commands/config.md b/docs/zh/cli/commands/config.md
index 992047b..81e4af0 100644
--- a/docs/zh/cli/commands/config.md
+++ b/docs/zh/cli/commands/config.md
@@ -29,6 +29,7 @@ he config [COMMAND] [OPTIONS]
- **百炼 preset**: `qwen3.6-plus` + `text-embedding-v4`
- **DeepSeek preset**: `deepseek-v4-flash`(仅 LLM —— 无嵌入预设)
- **Anthropic preset**: `claude-opus-4-8`(仅 LLM —— 无嵌入预设,请搭配 OpenAI 兼容嵌入器)
+- **OrcaRouter preset**: `orcarouter/auto`(OpenAI 兼容网关;密钥 `ORCAROUTER_API_KEY`)
```bash
he config init [OPTIONS]
@@ -38,7 +39,7 @@ he config init [OPTIONS]
| 选项 | 简写 | 描述 |
|--------|-------|-------------|
-| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `deepseek` / `bailian` / `vllm`) |
+| `--provider` | `-p` | 提供商 preset (`openai` / `anthropic` / `orcarouter` / `deepseek` / `bailian` / `vllm`) |
| `--api-key` | `-k` | LLM 和嵌入模型的 API 密钥 |
| `--base-url` | `-u` | 自定义 API 基础 URL(可选) |
@@ -60,6 +61,9 @@ he config embedder -p openai -k sk-your-openai-key
# Anthropic(仅 LLM —— 请搭配 OpenAI 兼容嵌入器)
he config llm -p anthropic -k sk-your-anthropic-key
he config embedder -p openai -k sk-your-openai-key
+
+# OrcaRouter(OpenAI 兼容网关)
+he config init -p orcarouter -k or-your-orcarouter-key
```
执行后会自动保存对应 preset 的默认模型和 API 地址。
@@ -114,7 +118,7 @@ he config llm [OPTIONS]
| 选项 | 简写 | 描述 |
|--------|-------|-------------|
-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`deepseek`、`bailian`、`vllm`) |
+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`orcarouter`、`deepseek`、`bailian`、`vllm`) |
| `--api-key` | `-k` | LLM API 密钥 |
| `--model` | `-m` | LLM 模型名称 |
| `--base-url` | `-u` | 自定义 API 基础 URL |
@@ -157,7 +161,7 @@ he config embedder [OPTIONS]
| 选项 | 简写 | 描述 |
|--------|-------|-------------|
-| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`deepseek`、`bailian`、`vllm`) |
+| `--provider` | `-p` | 提供商 preset(如 `openai`、`anthropic`、`orcarouter`、`deepseek`、`bailian`、`vllm`) |
| `--api-key` | `-k` | 嵌入模型 API 密钥 |
| `--model` | `-m` | 嵌入模型名称 |
| `--base-url` | `-u` | 自定义 API 基础 URL |
diff --git a/docs/zh/cli/commands/template.md b/docs/zh/cli/commands/template.md
index f35e1a8..42cb996 100644
--- a/docs/zh/cli/commands/template.md
+++ b/docs/zh/cli/commands/template.md
@@ -44,7 +44,7 @@ he template validate PATH [--json] [--all]
| `HE-T005` | display 中的 `{field}` 占位符在对应 schema 中存在 | error |
| `HE-T006` | 时序类型定义 `time_field`;空间类型定义 `location_field` | error |
| `HE-T007` | 已声明的语言在双语字典字段中齐全 | warning |
-| `HE-T008` | 实体或关系字段数超过 DESIGN_GUIDE 上限 5 | warning |
+| `HE-T008` | 字段数超过 DESIGN_GUIDE 上限 5(图的实体/关系,或 `model`/`list`/`set` 的 `output.fields`) | warning |
| `HE-T009` | `domain/name` 与 Gallery 中已有 preset 冲突 | warning |
存在任何 **error** 时退出码为 **1**;全部通过或仅有 warning 时为 **0**。
diff --git a/docs/zh/concepts/provider-system.md b/docs/zh/concepts/provider-system.md
index 9dfb9bf..d9e152f 100644
--- a/docs/zh/concepts/provider-system.md
+++ b/docs/zh/concepts/provider-system.md
@@ -1,6 +1,6 @@
# Provider 系统
-Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**阿里云百炼**、**DeepSeek**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。
+Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**阿里云百炼**、**DeepSeek**、**OrcaRouter**、**本地 vLLM**。统一使用 `create_client()` 接口,仅需修改第一行。
---
@@ -13,6 +13,7 @@ Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**阿里
| **OpenAI** | gpt-4o / gpt-4o-mini / gpt-5 | ✅ | ✅ | 官方原生支持,推荐 |
| **Anthropic** | claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 | ✅(工具调用) | ✅ | 仅 LLM——无嵌入接口(请搭配 OpenAI 兼容嵌入器)。需 `hyperextract[anthropic]` |
| **DeepSeek** | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI 兼容。V4 模型默认开启"thinking"模式,Hyper-Extract 会自动关闭以保证结构化抽取可用。仅 LLM——无嵌入接口。密钥:`DEEPSEEK_API_KEY` |
+| **OrcaRouter** | `orcarouter/auto`、`openai/gpt-4o-mini`、`anthropic/claude-haiku-4-5`、`deepseek/...`、`gemini/...` | ✅ | ✅ | OpenAI 兼容网关,用同一端点和密钥路由 OpenAI、Anthropic、Google、DeepSeek、Qwen、MiniMax、xAI 等 150+ 模型。密钥:`ORCAROUTER_API_KEY` |
| **阿里云百炼** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | 直接使用,无需修改 |
| **阿里云百炼** | qwen-max / deepseek-v3 | ❌ | ❌ | 仅支持 `json_object`,不兼容 function calling 结构化输出 |
@@ -60,6 +61,13 @@ llm, emb = create_client(
embedder="openai:text-embedding-3-small", # 或 vllm:bge-m3@localhost:8001/v1
)
+# OrcaRouter —— OpenAI 兼容网关,用一把密钥路由 150+ 模型(OpenAI、
+# Anthropic、Google、DeepSeek、Qwen、MiniMax、xAI)。默认模型
+# "orcarouter/auto" 会选合适的上游;可用 "openai:gpt-4o-mini" 或
+# "anthropic:claude-haiku-4-5" 等命名空间 id 覆盖。
+# 密钥:ORCAROUTER_API_KEY(回退:OPENAI_API_KEY)。
+llm, emb = create_client("orcarouter")
+
# 本地 vLLM
llm, emb = create_client(
llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",
diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md
index ea9157f..9d01ae3 100644
--- a/docs/zh/mcp.md
+++ b/docs/zh/mcp.md
@@ -46,10 +46,12 @@ python -m hyperextract.mcp_server
| `search` | KA 语义检索 | ✓ | 嵌入器 |
| `ask` | KA 上的 RAG 问答 | ✓ | ✓ |
| `export_obsidian` | 将 KA 导出为 Obsidian 知识库 | — | 嵌入器 |
+| `export_graphml` | 将 KA 导出为 GraphML(同 `he export graphml`) | — | 嵌入器 |
+| `export_csv` | 将 KA 导出为 CSV 表(同 `he export csv`) | — | 嵌入器 |
所有工具都接受一个 `ka_path`(由 `he parse` 创建的目录)。`search`/`ask` 需要索引——用 [`he build-index`](cli/commands/build-index.md) 构建。
-> `export_obsidian` 依赖 Obsidian 导出功能(见 [`he export obsidian`](cli/commands/export.md))。若不可用,该工具会返回说明信息而不会报错。
+> `export_obsidian` 依赖 Obsidian 导出功能(见 [`he export obsidian`](cli/commands/export.md))。若不可用,该工具会返回说明信息而不会报错。`export_graphml` / `export_csv` 使用与 CLI 相同的导出器(见 [`he export`](cli/commands/export.md))。
---
diff --git a/examples/README.md b/examples/README.md
index 2374ee0..91eba2d 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -18,6 +18,12 @@ python providers/bailian_demo.py
# DeepSeek
python providers/deepseek_demo.py
+# Anthropic
+python providers/anthropic_demo.py
+
+# OrcaRouter
+python providers/orcarouter_demo.py
+
# Local vLLM
python providers/vllm_demo.py
```
@@ -43,6 +49,8 @@ examples/
│ ├── openai_demo.py # OpenAI setup
│ ├── bailian_demo.py # Bailian (Alibaba Cloud) setup
│ ├── deepseek_demo.py # DeepSeek setup
+│ ├── anthropic_demo.py # Anthropic setup
+│ ├── orcarouter_demo.py # OrcaRouter setup
│ └── vllm_demo.py # Local vLLM setup
├── en/ # English demos
│ ├── tesla.md # Tesla biography data
diff --git a/examples/README_ZH.md b/examples/README_ZH.md
index 77abe9d..856ebc4 100644
--- a/examples/README_ZH.md
+++ b/examples/README_ZH.md
@@ -18,6 +18,12 @@ python providers/bailian_demo.py
# DeepSeek
python providers/deepseek_demo.py
+# Anthropic
+python providers/anthropic_demo.py
+
+# OrcaRouter
+python providers/orcarouter_demo.py
+
# 本地 vLLM
python providers/vllm_demo.py
```
@@ -44,6 +50,8 @@ examples/
│ ├── openai_demo.py # OpenAI 配置
│ ├── bailian_demo.py # 百炼(阿里云)配置
│ ├── deepseek_demo.py # DeepSeek 配置
+│ ├── anthropic_demo.py # Anthropic 配置
+│ ├── orcarouter_demo.py # OrcaRouter 配置
│ └── vllm_demo.py # 本地 vLLM 配置
├── en/ # 英文演示
│ ├── tesla.md # 特斯拉传记数据
diff --git a/examples/providers/anthropic_demo.py b/examples/providers/anthropic_demo.py
new file mode 100644
index 0000000..3a37fa4
--- /dev/null
+++ b/examples/providers/anthropic_demo.py
@@ -0,0 +1,34 @@
+"""
+Anthropic Provider Demo
+
+Extract entities and relationships using the Anthropic Messages API.
+Anthropic has no embeddings API, so pair it with an OpenAI-compatible
+embedder. No real key is required to read this file.
+
+Usage:
+ ANTHROPIC_API_KEY=sk-ant-xxx OPENAI_API_KEY=sk-xxx python examples/providers/anthropic_demo.py
+"""
+
+from hyperextract import create_client, AutoGraph
+
+# Anthropic for LLM, OpenAI for embeddings (Anthropic has no embeddings API)
+llm, emb = create_client(
+ llm="anthropic", # default: claude-opus-4-8
+ embedder="openai:text-embedding-3-small",
+)
+
+graph = AutoGraph(
+ instruction="Extract people and their relationships",
+ llm_client=llm,
+ embedder=emb,
+ node_key_extractor=lambda n: n.name,
+ edge_key_extractor=lambda e: (e.source, e.target, e.type),
+ nodes_in_edge_extractor=lambda e: (e.source, e.target),
+)
+
+text = "Zhang San founded ByteDance. Li Si serves as CEO."
+graph.parse(text)
+
+print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")
+for n in graph.nodes:
+ print(f" - {n.name} ({n.type})")
diff --git a/examples/providers/orcarouter_demo.py b/examples/providers/orcarouter_demo.py
new file mode 100644
index 0000000..cef0d6e
--- /dev/null
+++ b/examples/providers/orcarouter_demo.py
@@ -0,0 +1,32 @@
+"""
+OrcaRouter Provider Demo
+
+Extract entities and relationships via the OrcaRouter OpenAI-compatible
+gateway (150+ upstream models behind one key). No real key is required
+to read this file; set ORCAROUTER_API_KEY before running.
+
+Usage:
+ ORCAROUTER_API_KEY=or-xxx python examples/providers/orcarouter_demo.py
+"""
+
+from hyperextract import create_client, AutoGraph
+
+# Default model is orcarouter/auto. Override with a namespaced id such as
+# llm="orcarouter:openai/gpt-4o-mini" when you want a specific upstream.
+llm, emb = create_client("orcarouter")
+
+graph = AutoGraph(
+ instruction="Extract people and their relationships",
+ llm_client=llm,
+ embedder=emb,
+ node_key_extractor=lambda n: n.name,
+ edge_key_extractor=lambda e: (e.source, e.target, e.type),
+ nodes_in_edge_extractor=lambda e: (e.source, e.target),
+)
+
+text = "Zhang San founded ByteDance. Li Si serves as CEO."
+graph.parse(text)
+
+print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")
+for n in graph.nodes:
+ print(f" - {n.name} ({n.type})")
diff --git a/hyperextract-skills/yaml-validator/references/rules-errors.md b/hyperextract-skills/yaml-validator/references/rules-errors.md
index f762ffd..d988965 100644
--- a/hyperextract-skills/yaml-validator/references/rules-errors.md
+++ b/hyperextract-skills/yaml-validator/references/rules-errors.md
@@ -26,7 +26,7 @@ output:
```
ERROR: type value 'graphh' is not valid
-Valid values: model, list, set, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph
+Valid values: model, list, set, document, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph
Fix: Correct to 'graph'
```