Skip to content

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

Warn HE-T008 for model/list/set field counts and refresh DESIGN_GUIDE appendix

Frankie-Xu1207231821da
diff --git a/hyperextract/templates/DESIGN_GUIDE.md b/hyperextract/templates/DESIGN_GUIDE.md
index 40084fd..8e8fb8b 100644
--- a/hyperextract/templates/DESIGN_GUIDE.md
+++ b/hyperextract/templates/DESIGN_GUIDE.md
@@ -707,6 +707,7 @@ identifiers:
Need single object → model
Need list → list
Need deduplication → set
+Need chunked documents without LLM extraction → document # method/chunk_rag
Need binary relations → graph
Need multi-party relations → hypergraph
Need time → temporal_graph
@@ -719,7 +720,8 @@ Need both → spatio_temporal_graph
```
templates/
├── presets/
-│ ├── general/ # 13 templates (8 base + 5 domain-specific)
+│ ├── general/ # 12 templates
+│ ├── education/ # 2 templates
│ ├── finance/ # 5 templates
│ ├── medicine/ # 5 templates
│ ├── tcm/ # 5 templates
@@ -731,6 +733,22 @@ templates/
└── README_ZH.md # 中文目录
```
+### Validator codes (HE-T001–009)
+
+Run `he template validate`. Implementation: `hyperextract/utils/template_engine/validator.py`.
+
+| Code | Severity | Check |
+|------|----------|--------|
+| HE-T001 | error | YAML is parseable |
+| HE-T002 | error | Document matches `TemplateCfg` |
+| HE-T003 | error | Identifier fields exist on the relevant output schema |
+| HE-T004 | error | `relation_members` type matches AutoType |
+| HE-T005 | error | Display `{field}` placeholders exist on the corresponding schema |
+| HE-T006 | error | Temporal types define `time_field`; spatial types define `location_field` |
+| HE-T007 | warning | Declared languages are present on bilingual dict fields |
+| HE-T008 | warning | Field count exceeds the Part 4 limit of 5 (graph entity/relation, or `model`/`list`/`set` `output.fields`) |
+| HE-T009 | warning | `domain/name` collides with a Gallery preset |
+
---
## License
diff --git a/hyperextract/templates/DESIGN_GUIDE_zh.md b/hyperextract/templates/DESIGN_GUIDE_zh.md
index bffcbaf..114a8f7 100644
--- a/hyperextract/templates/DESIGN_GUIDE_zh.md
+++ b/hyperextract/templates/DESIGN_GUIDE_zh.md
@@ -707,6 +707,7 @@ identifiers:
需要单个对象 → model
需要列表 → list
需要去重 → set
+需要切分文档、不做 LLM 抽取 → document # method/chunk_rag
需要二元关系 → graph
需要多方关系 → hypergraph
需要时间 → temporal_graph
@@ -719,7 +720,8 @@ identifiers:
```
templates/
├── presets/
-│ ├── general/ # 13 个模板(8 个基础 + 5 个领域专用)
+│ ├── general/ # 12 个模板
+│ ├── education/ # 2 个模板
│ ├── finance/ # 5 个模板
│ ├── medicine/ # 5 个模板
│ ├── tcm/ # 5 个模板
@@ -731,6 +733,22 @@ templates/
└── README_ZH.md # 中文目录
```
+### 校验码(HE-T001–009)
+
+运行 `he template validate`。实现:`hyperextract/utils/template_engine/validator.py`。
+
+| 代码 | 级别 | 检查 |
+|------|------|------|
+| HE-T001 | error | YAML 可解析 |
+| HE-T002 | error | 文档符合 `TemplateCfg` |
+| HE-T003 | error | 标识字段存在于对应输出 schema |
+| HE-T004 | error | `relation_members` 类型与 AutoType 匹配 |
+| HE-T005 | error | Display `{field}` 占位符存在于对应 schema |
+| HE-T006 | error | 时间类型定义 `time_field`;空间类型定义 `location_field` |
+| HE-T007 | warning | 声明的语言出现在双语 dict 字段上 |
+| HE-T008 | warning | 字段数超过第四部分上限 5(图实体/关系,或 `model`/`list`/`set` 的 `output.fields`) |
+| HE-T009 | warning | `domain/name` 与 Gallery 预设冲突 |
+
---
## 许可证
diff --git a/hyperextract/utils/template_engine/validator.py b/hyperextract/utils/template_engine/validator.py
index 42a6809..027cebf 100644
--- a/hyperextract/utils/template_engine/validator.py
+++ b/hyperextract/utils/template_engine/validator.py
@@ -789,38 +789,54 @@ def _check_bilingual(config: TemplateCfg) -> list[Diagnostic]:
def _check_field_count(config: TemplateCfg) -> list[Diagnostic]:
- """Warn when entity/relation field count exceeds the DESIGN_GUIDE limit (HE-T008).
+ """Warn when field count exceeds the DESIGN_GUIDE Part 4 limit (HE-T008).
+
+ Graph types check entity and relation schemas. Naive types
+ (``model`` / ``list`` / ``set``) check ``output.fields``. The cap is
+ ``FIELD_COUNT_LIMIT`` (Part 4: max 5 fields per component).
See also:
hyperextract-skills/yaml-validator/SKILL.md (Validation Levels)
hyperextract/templates/DESIGN_GUIDE.md
(Quick Reference Field Count Guidelines, Part 4 Field Count Optimization)
"""
- if not isinstance(config.output, GraphOutputSchema):
- return []
diags: list[Diagnostic] = []
- entity_count = len(config.output.entities.fields)
- relation_count = len(config.output.relations.fields)
- if entity_count > FIELD_COUNT_LIMIT:
- diags.append(
- Diagnostic(
- HE_T008,
- "warning",
- "output.entities.fields",
- f"Entity schema has {entity_count} fields "
- f"(DESIGN_GUIDE limit is {FIELD_COUNT_LIMIT})",
+ if isinstance(config.output, GraphOutputSchema):
+ entity_count = len(config.output.entities.fields)
+ relation_count = len(config.output.relations.fields)
+ if entity_count > FIELD_COUNT_LIMIT:
+ diags.append(
+ Diagnostic(
+ HE_T008,
+ "warning",
+ "output.entities.fields",
+ f"Entity schema has {entity_count} fields "
+ f"(DESIGN_GUIDE limit is {FIELD_COUNT_LIMIT})",
+ )
)
- )
- if relation_count > FIELD_COUNT_LIMIT:
- diags.append(
- Diagnostic(
- HE_T008,
- "warning",
- "output.relations.fields",
- f"Relation schema has {relation_count} fields "
- f"(DESIGN_GUIDE limit is {FIELD_COUNT_LIMIT})",
+ if relation_count > FIELD_COUNT_LIMIT:
+ diags.append(
+ Diagnostic(
+ HE_T008,
+ "warning",
+ "output.relations.fields",
+ f"Relation schema has {relation_count} fields "
+ f"(DESIGN_GUIDE limit is {FIELD_COUNT_LIMIT})",
+ )
+ )
+ return diags
+ if config.type in RECORD_TYPES and isinstance(config.output, NaiveOutputSchema):
+ count = len(config.output.fields)
+ if count > FIELD_COUNT_LIMIT:
+ diags.append(
+ Diagnostic(
+ HE_T008,
+ "warning",
+ "output.fields",
+ f"{config.type} schema has {count} fields "
+ f"(DESIGN_GUIDE limit is {FIELD_COUNT_LIMIT})",
+ )
)
- )
return diags
diff --git a/tests/template_engine/test_validator.py b/tests/template_engine/test_validator.py
index d614e2d..c1f5313 100644
--- a/tests/template_engine/test_validator.py
+++ b/tests/template_engine/test_validator.py
@@ -317,6 +317,24 @@ class TestWarningsDoNotFail:
assert diags[0].severity == "warning"
assert diags[0].path == "output.entities.fields"
+ def test_model_field_count_over_limit_is_warning(self, tmp_path):
+ extra_fields = "\n".join(
+ f" - name: extra_{i}\n type: str\n description: extra"
+ for i in range(5)
+ )
+ yaml_text = VALID_SET.replace("type: set", "type: model").replace(
+ " - name: name\n type: str\n description: item name",
+ " - name: name\n type: str\n description: item name\n"
+ + extra_fields,
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert result.ok
+ diags = _by_code(result, HE_T008)
+ assert diags
+ assert diags[0].severity == "warning"
+ assert diags[0].path == "output.fields"
+ assert "model" in diags[0].message
+
def test_gallery_name_collision_is_warning(self, tmp_path):
path = _write(
tmp_path / "general",