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: document template validation command

Frankie-Xud6f7c6460733
diff --git a/docs/en/cli/commands/list.md b/docs/en/cli/commands/list.md
index 3dac9e9..128188a 100644
--- a/docs/en/cli/commands/list.md
+++ b/docs/en/cli/commands/list.md
@@ -145,5 +145,6 @@ he list method | grep -q light_rag && echo "Available"
## See Also
- [`he parse`](parse.md) — Use templates/methods
+- [`he template validate`](template.md) — Check a template YAML file
- [Template Library](../../templates/index.md) — Detailed template documentation
- [Choosing Methods](../../concepts/methods.md) — Method selection guide
diff --git a/docs/en/cli/commands/template.md b/docs/en/cli/commands/template.md
new file mode 100644
index 0000000..30a5e02
--- /dev/null
+++ b/docs/en/cli/commands/template.md
@@ -0,0 +1,120 @@
+# he template validate
+
+Check a Hyper-Extract YAML template for structural and semantic problems before you run extraction.
+
+`load_template()` only verifies that the document matches the Pydantic `TemplateCfg` shape. Identifier fields that do not exist, display placeholders that do not match the schema, and missing time/location fields on temporal or spatial types otherwise fail later, during extraction. This command runs those checks up front.
+
+`template` is a command group; `validate` is the subcommand.
+
+---
+
+## Synopsis
+
+```bash
+he template validate PATH [--json] [--all]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `PATH` | Template YAML file, or a directory when `--all` is set |
+
+## Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--json` | | off | Print machine-readable JSON instead of Rich text |
+| `--all` | | off | Validate every `*.yaml` / `*.yml` file under a directory |
+
+---
+
+## Description
+
+The validator is a sidecar for template authors. It does **not** change runtime `load_template()` behavior.
+
+Checks follow `hyperextract-skills/yaml-validator/` and `templates/DESIGN_GUIDE.md`:
+
+| Code | Check | Severity |
+|------|--------|----------|
+| `HE-T001` | YAML is parseable | error |
+| `HE-T002` | Document matches `TemplateCfg` | error |
+| `HE-T003` | Identifier fields (`entity_id`, `relation_id`, `relation_members`, `item_id`, `time_field`, `location_field`) exist on the relevant output schema | error |
+| `HE-T004` | `relation_members` type matches AutoType (`graph` / temporal / spatial → dict; `hypergraph` → string or list). Dict **values** are edge-schema field names. Hypergraph member fields must be `type: list`. | error |
+| `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-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.
+
+---
+
+## Examples
+
+### Validate one file
+
+```bash
+he template validate ./my_template.yaml
+```
+
+### Machine-readable diagnostics
+
+```bash
+he template validate ./my_template.yaml --json
+```
+
+```json
+{
+ "file": "./my_template.yaml",
+ "diagnostics": [
+ {
+ "code": "HE-T003",
+ "severity": "error",
+ "path": "identifiers.entity_id",
+ "message": "Field 'nickname' is not defined in output.entities"
+ }
+ ],
+ "ok": false
+}
+```
+
+### Validate every bundled preset
+
+```bash
+he template validate hyperextract/templates/presets --all
+```
+
+Directory mode with `--json` wraps each file:
+
+```json
+{
+ "results": [
+ {"file": "…/base_graph.yaml", "diagnostics": [], "ok": true}
+ ],
+ "ok": true
+}
+```
+
+---
+
+## Python API
+
+The CLI is a thin wrapper around the same checks:
+
+```python
+from hyperextract.utils.template_engine import validate_template
+
+result = validate_template("my_template.yaml")
+print(result.ok, result.to_dict())
+```
+
+---
+
+## See Also
+
+- [`he list template`](list.md) — Browse bundled templates
+- [`he parse`](parse.md) — Extract with a template
+- [Creating Custom Templates](../../python/guides/custom-templates.md)
+- [Template Library](../../templates/index.md)
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index a3b3d38..32c08f0 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -40,6 +40,7 @@ he --version
| `he build-index` | Build/rebuild search index | `-f` force rebuild |
| `he clean` | Remove a KA's index (or the whole KA) | `-a` all, `-y` yes |
| `he list` | List templates and methods | `template` or `method` |
+| `he template validate` | Validate a template YAML file | `--json`, `--all` |
| `he config` | Manage configuration | `init`, `show`, `llm`, `embedder` |
---
@@ -173,6 +174,7 @@ he show ./output/
- **[`he build-index`](commands/build-index.md)** — Build search index
- **[`he clean`](commands/clean.md)** — Remove a KA's index, or the whole KA
- **[`he list`](commands/list.md)** — List available templates/methods
+- **[`he template validate`](commands/template.md)** — Validate a template YAML file
- **[`he config`](commands/config.md)** — Configuration management
---
diff --git a/docs/en/python/guides/custom-templates.md b/docs/en/python/guides/custom-templates.md
index 36fbf5b..e3d4045 100644
--- a/docs/en/python/guides/custom-templates.md
+++ b/docs/en/python/guides/custom-templates.md
@@ -105,6 +105,10 @@ display:
### 3. Validate and Use
+```bash
+he template validate ~/.hyperextract/templates/my_domain/my_template.yaml
+```
+
```python
from hyperextract import Template
@@ -115,6 +119,8 @@ ka = Template.create("my_domain/my_template", "en")
result = ka.parse("Your document text here")
```
+See [`he template validate`](../../cli/commands/template.md) for the diagnostic codes and JSON output.
+
---
## Field Types
diff --git a/docs/zh/cli/commands/list.md b/docs/zh/cli/commands/list.md
index 73a5eed..999db49 100644
--- a/docs/zh/cli/commands/list.md
+++ b/docs/zh/cli/commands/list.md
@@ -145,5 +145,6 @@ he list method | grep -q light_rag && echo "Available"
## 另请参见
- [`he parse`](parse.md) — 使用模板/方法
+- [`he template validate`](template.md) — 校验模板 YAML 文件
- [模板库](../../templates/index.md) — 详细模板文档
- [选择方法](../../concepts/methods.md) — 方法选择指南
diff --git a/docs/zh/cli/commands/template.md b/docs/zh/cli/commands/template.md
new file mode 100644
index 0000000..f35e1a8
--- /dev/null
+++ b/docs/zh/cli/commands/template.md
@@ -0,0 +1,120 @@
+# he template validate
+
+在运行抽取之前,检查 Hyper-Extract YAML 模板的结构和语义问题。
+
+`load_template()` 只验证文档是否符合 Pydantic `TemplateCfg` 形状。标识符引用了不存在的字段、display 占位符与 schema 不匹配、时序/空间类型缺少 time/location 字段时,错误会拖到抽取阶段才出现。本命令把这些检查提前到编写模板时。
+
+`template` 是命令组,`validate` 是子命令。
+
+---
+
+## 用法
+
+```bash
+he template validate PATH [--json] [--all]
+```
+
+## 参数
+
+| 参数 | 说明 |
+|----------|-------------|
+| `PATH` | 模板 YAML 文件;使用 `--all` 时可以是目录 |
+
+## 选项
+
+| 选项 | 别名 | 默认值 | 说明 |
+|--------|-------|---------|-------------|
+| `--json` | | 关闭 | 输出机器可读 JSON,而不是 Rich 文本 |
+| `--all` | | 关闭 | 校验目录下每一个 `*.yaml` / `*.yml` 文件 |
+
+---
+
+## 说明
+
+校验器是给模板作者用的旁路工具,**不会**改变运行时 `load_template()` 的行为。
+
+检查项来自 `hyperextract-skills/yaml-validator/` 与 `templates/DESIGN_GUIDE.md`:
+
+| 编码 | 检查 | 严重级别 |
+|------|--------|----------|
+| `HE-T001` | YAML 可解析 | error |
+| `HE-T002` | 文档符合 `TemplateCfg` | error |
+| `HE-T003` | 标识符字段(`entity_id`、`relation_id`、`relation_members`、`item_id`、`time_field`、`location_field`)在对应 output schema 中存在 | error |
+| `HE-T004` | `relation_members` 类型与 AutoType 匹配(`graph` / 时序 / 空间 → dict;`hypergraph` → 字符串或列表)。dict 的**值**是边 schema 的字段名。超图成员字段必须为 `type: list`。 | error |
+| `HE-T005` | display 中的 `{field}` 占位符在对应 schema 中存在 | error |
+| `HE-T006` | 时序类型定义 `time_field`;空间类型定义 `location_field` | error |
+| `HE-T007` | 已声明的语言在双语字典字段中齐全 | warning |
+| `HE-T008` | 实体或关系字段数超过 DESIGN_GUIDE 上限 5 | warning |
+| `HE-T009` | `domain/name` 与 Gallery 中已有 preset 冲突 | warning |
+
+存在任何 **error** 时退出码为 **1**;全部通过或仅有 warning 时为 **0**。
+
+---
+
+## 示例
+
+### 校验单个文件
+
+```bash
+he template validate ./my_template.yaml
+```
+
+### 机器可读诊断
+
+```bash
+he template validate ./my_template.yaml --json
+```
+
+```json
+{
+ "file": "./my_template.yaml",
+ "diagnostics": [
+ {
+ "code": "HE-T003",
+ "severity": "error",
+ "path": "identifiers.entity_id",
+ "message": "Field 'nickname' is not defined in output.entities"
+ }
+ ],
+ "ok": false
+}
+```
+
+### 校验全部内置 preset
+
+```bash
+he template validate hyperextract/templates/presets --all
+```
+
+目录模式配合 `--json` 时,每个文件包在 `results` 里:
+
+```json
+{
+ "results": [
+ {"file": "…/base_graph.yaml", "diagnostics": [], "ok": true}
+ ],
+ "ok": true
+}
+```
+
+---
+
+## Python API
+
+CLI 是同一套检查的薄封装:
+
+```python
+from hyperextract.utils.template_engine import validate_template
+
+result = validate_template("my_template.yaml")
+print(result.ok, result.to_dict())
+```
+
+---
+
+## 另请参见
+
+- [`he list template`](list.md) — 浏览内置模板
+- [`he parse`](parse.md) — 使用模板抽取
+- [创建自定义模板](../../python/guides/custom-templates.md)
+- [模板库](../../templates/index.md)
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index d2d93af..2d42a75 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -40,6 +40,7 @@ he --version
| `he build-index` | 构建/重建搜索索引 | `-f` 强制重建 |
| `he clean` | 删除 KA 的索引(或整个 KA) | `-a` all, `-y` yes |
| `he list` | 列出模板和方法 | `template` 或 `method` |
+| `he template validate` | 校验模板 YAML | `--json`、`--all` |
| `he config` | 管理配置 | `init`, `show`, `llm`, `embedder` |
---
@@ -173,6 +174,7 @@ he show ./output/
- **[`he build-index`](commands/build-index.md)** — 构建搜索索引
- **[`he clean`](commands/clean.md)** — 删除 KA 的索引,或整个 KA
- **[`he list`](commands/list.md)** — 列出可用模板/方法
+- **[`he template validate`](commands/template.md)** — 校验模板 YAML 文件
- **[`he config`](commands/config.md)** — 配置管理
---
diff --git a/docs/zh/python/guides/custom-templates.md b/docs/zh/python/guides/custom-templates.md
index 0f409f8..660b8aa 100644
--- a/docs/zh/python/guides/custom-templates.md
+++ b/docs/zh/python/guides/custom-templates.md
@@ -105,6 +105,10 @@ display:
### 3. 验证并使用
+```bash
+he template validate ~/.hyperextract/templates/my_domain/my_template.yaml
+```
+
```python
from hyperextract import Template
@@ -115,6 +119,8 @@ ka = Template.create("my_domain/my_template", "zh")
result = ka.parse("您的文档文本")
```
+诊断编码与 JSON 输出见 [`he template validate`](../../cli/commands/template.md)。
+
---
## 字段类型
diff --git a/mkdocs.yml b/mkdocs.yml
index 0639664..4591d5e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -81,6 +81,7 @@ plugins:
- cli/commands/talk.md
- cli/commands/info.md
- cli/commands/list.md
+ - cli/commands/template.md
- cli/commands/config.md
- cli/configuration.md
- MCP Server: mcp.md
@@ -175,6 +176,7 @@ plugins:
- zh/cli/commands/talk.md
- zh/cli/commands/info.md
- zh/cli/commands/list.md
+ - zh/cli/commands/template.md
- zh/cli/commands/config.md
- zh/cli/configuration.md
- MCP 服务器: zh/mcp.md