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.mdindex 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`)```bashhe 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-keyhe 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.mdindex 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.mdindex 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.mdindex 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`)```bashhe 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-keyhe 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.mdindex 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.mdindex 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")+# 本地 vLLMllm, emb = create_client(llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",diff --git a/docs/zh/mcp.md b/docs/zh/mcp.mdindex 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.mdindex 2374ee0..91eba2d 100644--- a/examples/README.md+++ b/examples/README.md@@ -18,6 +18,12 @@ python providers/bailian_demo.py# DeepSeekpython providers/deepseek_demo.py+# Anthropic+python providers/anthropic_demo.py++# OrcaRouter+python providers/orcarouter_demo.py+# Local vLLMpython 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 datadiff --git a/examples/README_ZH.md b/examples/README_ZH.mdindex 77abe9d..856ebc4 100644--- a/examples/README_ZH.md+++ b/examples/README_ZH.md@@ -18,6 +18,12 @@ python providers/bailian_demo.py# DeepSeekpython providers/deepseek_demo.py+# Anthropic+python providers/anthropic_demo.py++# OrcaRouter+python providers/orcarouter_demo.py+# 本地 vLLMpython 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.pynew file mode 100644index 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.pynew file mode 100644index 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.mdindex 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_graphFix: Correct to 'graph'```