Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
docs: link HE-T rules to yaml-validator and DESIGN_GUIDE sections
Frankie-Xu1f3ef1e66cb2
diff --git a/hyperextract/utils/template_engine/validator.py b/hyperextract/utils/template_engine/validator.pyindex e4e1550..e008433 100644--- a/hyperextract/utils/template_engine/validator.py+++ b/hyperextract/utils/template_engine/validator.py@@ -4,6 +4,11 @@documented in ``hyperextract-skills/yaml-validator/`` so authors can catchidentifier, display, and spatiotemporal mistakes before extraction.+Each ``HE-T*`` rule points at the matching skill file and+``hyperextract/templates/DESIGN_GUIDE.md`` section. Lookup of fixes:+``hyperextract-skills/yaml-validator/references/rules-errors.md`` and+DESIGN_GUIDE Part 5 Common Errors.+The runtime loader is intentionally left unchanged."""@@ -133,10 +138,15 @@ def validate_template_dir(directory: str | Path) -> list[ValidationResult]:def validate_template(path: str | Path) -> ValidationResult:- """Validate one template YAML file.+ """Validate one template YAML file (HE-T001 through HE-T009).Returns a :class:`ValidationResult`. ``ok`` is True when there are noerror-severity diagnostics (warnings do not fail the result).++ See also:+ hyperextract-skills/yaml-validator/SKILL.md+ hyperextract-skills/yaml-validator/references/rules-errors.md+ hyperextract/templates/DESIGN_GUIDE.md (Part 5 Validation, Common Errors)"""file_path = Path(path)result = ValidationResult(file=str(file_path))@@ -174,6 +184,12 @@ def validate_template(path: str | Path) -> ValidationResult:def _load_yaml(path: Path) -> tuple[dict[str, Any] | None, list[Diagnostic]]:+ """Parse YAML text (HE-T001).++ See also:+ hyperextract-skills/yaml-validator/references/rules-syntax.md+ hyperextract/templates/DESIGN_GUIDE.md (Part 5 Validation)+ """try:with open(path, encoding="utf-8") as handle:raw = yaml.safe_load(handle)@@ -205,6 +221,12 @@ def _load_yaml(path: Path) -> tuple[dict[str, Any] | None, list[Diagnostic]]:def _parse_config(raw: dict[str, Any],) -> tuple[TemplateCfg | None, list[Diagnostic]]:+ """Match the document to ``TemplateCfg`` (HE-T002).++ See also:+ hyperextract-skills/yaml-validator/references/rules-types.md+ hyperextract/templates/DESIGN_GUIDE.md (Part 2 Type-Specific Design)+ """try:return TemplateCfg(**raw), []except ValidationError as exc:@@ -242,6 +264,12 @@ def _check_localize(config: TemplateCfg) -> list[Diagnostic]:def _check_output_shape(config: TemplateCfg) -> list[Diagnostic]:+ """Require type-specific output keys (HE-T002).++ See also:+ hyperextract-skills/yaml-validator/references/rules-types.md+ hyperextract/templates/DESIGN_GUIDE.md (Part 2 Type-Specific Design)+ """if config.type in GRAPH_TYPES and not isinstance(config.output, GraphOutputSchema):return [Diagnostic(@@ -314,6 +342,12 @@ def _record_fields(config: TemplateCfg) -> set[str]:def _check_identifiers(config: TemplateCfg) -> list[Diagnostic]:+ """Check identifier field references (HE-T003).++ See also:+ hyperextract-skills/yaml-validator/references/rules-identifiers.md+ hyperextract/templates/DESIGN_GUIDE.md (Part 3 Identifiers Configuration)+ """if config.type in RECORD_TYPES:return _check_record_identifiers(config)if config.type in GRAPH_TYPES:@@ -440,6 +474,18 @@ def _check_relation_members(relation_fields: set[str],config: TemplateCfg,) -> list[Diagnostic]:+ """Check ``relation_members`` shape vs AutoType (HE-T004).++ Binary graph types require a dict whose values name edge-schema fields+ (direction preserved). Hypergraph requires a string or list of list-typed+ relation fields, not a dict.++ See also:+ hyperextract-skills/yaml-validator/references/rules-identifiers.md+ (Binary Relations, Hypergraph)+ hyperextract/templates/DESIGN_GUIDE.md+ (Part 2 graph vs hypergraph)+ """diags: list[Diagnostic] = []if members is None:diags.append(@@ -555,6 +601,14 @@ def _check_relation_members(def _check_spatiotemporal(config: TemplateCfg) -> list[Diagnostic]:+ """Require ``time_field`` / ``location_field`` (HE-T006).++ See also:+ hyperextract-skills/yaml-validator/references/rules-identifiers.md+ (Temporal Graph, Spatial Graph)+ hyperextract/templates/DESIGN_GUIDE.md+ (Part 2 temporal_graph / spatial_graph)+ """if config.type not in TEMPORAL_TYPES | SPATIAL_TYPES:return []if not isinstance(config.identifiers, GraphIdentifiersSchema):@@ -612,6 +666,12 @@ def _check_spatiotemporal(config: TemplateCfg) -> list[Diagnostic]:def _check_display(config: TemplateCfg) -> list[Diagnostic]:+ """Check display ``{placeholder}`` names (HE-T005).++ See also:+ hyperextract-skills/yaml-validator/SKILL.md (Field validation)+ hyperextract/templates/DESIGN_GUIDE.md (Part 3 Display Configuration)+ """display = config.displaydiags: list[Diagnostic] = []@@ -700,6 +760,11 @@ def _walk_bilingual(value: Any, path: str, langs: list[str]) -> list[Diagnostic]def _check_bilingual(config: TemplateCfg) -> list[Diagnostic]:+ """Warn when declared languages are missing on bilingual fields (HE-T007).++ See also:+ hyperextract/templates/DESIGN_GUIDE.md (Part 4 Multi-language Rules)+ """langs = _declared_languages(config)payload = {"description": config.description,@@ -710,6 +775,13 @@ 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).++ 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] = []@@ -781,6 +853,11 @@ def _preset_files_for_key(key: str) -> list[Path]:def _check_gallery_collision(path: Path, config: TemplateCfg) -> list[Diagnostic]:+ """Warn when ``domain/name`` collides with a Gallery preset (HE-T009).++ See also:+ hyperextract/templates/DESIGN_GUIDE.md (Appendix Template Directory Structure)+ """domain = _domain_for(path)if not domain:return []