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.mdindex 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 guidediff --git a/docs/en/cli/commands/template.md b/docs/en/cli/commands/template.mdnew file mode 100644index 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.mdindex 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.mdindex 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+```+```pythonfrom 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 Typesdiff --git a/docs/zh/cli/commands/list.md b/docs/zh/cli/commands/list.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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+```+```pythonfrom 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.ymlindex 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