Skip to content

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

feat: add template validator with machine-readable diagnostics

Frankie-Xu419b9d843ed7
diff --git a/hyperextract/utils/template_engine/__init__.py b/hyperextract/utils/template_engine/__init__.py
index f2f9fab..8c40c81 100644
--- a/hyperextract/utils/template_engine/__init__.py
+++ b/hyperextract/utils/template_engine/__init__.py
@@ -10,6 +10,7 @@ Main Components:
- SchemaParser: Parses output schemas based on template type
- GuidelineParser: Parses prompts based on template type
- parse_identifiers: Parses identifier extractors from config
+- validate_template: Semantic checks with machine-readable diagnostics
"""
from .factory import TemplateFactory
@@ -20,12 +21,22 @@ from .parsers import (
localize_template,
)
from .template import Template
+from .validator import (
+ Diagnostic,
+ ValidationResult,
+ validate_template,
+ validate_template_dir,
+)
__all__ = [
+ "Diagnostic",
"Gallery",
"Template",
"TemplateCfg",
"TemplateFactory",
+ "ValidationResult",
"load_template",
"localize_template",
+ "validate_template",
+ "validate_template_dir",
]
diff --git a/hyperextract/utils/template_engine/validator.py b/hyperextract/utils/template_engine/validator.py
new file mode 100644
index 0000000..e4e1550
--- /dev/null
+++ b/hyperextract/utils/template_engine/validator.py
@@ -0,0 +1,835 @@
+"""Semantic validator for Hyper-Extract YAML templates.
+
+``load_template()`` only checks Pydantic shape. This module applies the checks
+documented in ``hyperextract-skills/yaml-validator/`` so authors can catch
+identifier, display, and spatiotemporal mistakes before extraction.
+
+The runtime loader is intentionally left unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import ValidationError
+
+from .gallery import Gallery
+from .parsers.loader import TemplateCfg, localize_template
+from .parsers.schemas.base import FieldSchema
+from .parsers.schemas.graph import (
+ GraphDisplaySchema,
+ GraphIdentifiersSchema,
+ GraphOutputSchema,
+)
+from .parsers.schemas.naive import (
+ NaiveDisplaySchema,
+ NaiveIdentifierSchema,
+ NaiveOutputSchema,
+)
+
+Severity = Literal["error", "warning"]
+
+HE_T001 = "HE-T001" # YAML syntax
+HE_T002 = "HE-T002" # TemplateCfg / schema
+HE_T003 = "HE-T003" # identifier field reference
+HE_T004 = "HE-T004" # relation_members type mismatch
+HE_T005 = "HE-T005" # display placeholder
+HE_T006 = "HE-T006" # missing time_field / location_field
+HE_T007 = "HE-T007" # bilingual completeness
+HE_T008 = "HE-T008" # field count > DESIGN_GUIDE limit
+HE_T009 = "HE-T009" # Gallery domain/name collision
+
+GRAPH_TYPES = frozenset(
+ {
+ "graph",
+ "hypergraph",
+ "temporal_graph",
+ "spatial_graph",
+ "spatio_temporal_graph",
+ }
+)
+BINARY_GRAPH_TYPES = frozenset(
+ {"graph", "temporal_graph", "spatial_graph", "spatio_temporal_graph"}
+)
+TEMPORAL_TYPES = frozenset({"temporal_graph", "spatio_temporal_graph"})
+SPATIAL_TYPES = frozenset({"spatial_graph", "spatio_temporal_graph"})
+RECORD_TYPES = frozenset({"model", "list", "set"})
+
+FIELD_COUNT_LIMIT = 5
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+_LANG_KEY_RE = re.compile(r"^[a-z]{2}(?:-[A-Za-z]+)?$")
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+ """A single validator finding."""
+
+ code: str
+ severity: Severity
+ path: str
+ message: str
+
+ def to_dict(self) -> dict[str, str]:
+ return {
+ "code": self.code,
+ "severity": self.severity,
+ "path": self.path,
+ "message": self.message,
+ }
+
+
+@dataclass
+class ValidationResult:
+ """Outcome of validating one template file."""
+
+ file: str
+ diagnostics: list[Diagnostic] = field(default_factory=list)
+
+ @property
+ def ok(self) -> bool:
+ return not any(d.severity == "error" for d in self.diagnostics)
+
+ @property
+ def error_count(self) -> int:
+ return sum(1 for d in self.diagnostics if d.severity == "error")
+
+ @property
+ def warning_count(self) -> int:
+ return sum(1 for d in self.diagnostics if d.severity == "warning")
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "file": self.file,
+ "diagnostics": [d.to_dict() for d in self.diagnostics],
+ "ok": self.ok,
+ }
+
+
+def _presets_dir() -> Path:
+ return Path(__file__).resolve().parent.parent.parent / "templates" / "presets"
+
+
+def iter_template_files(path: str | Path) -> list[Path]:
+ """Return YAML template files under ``path`` (file or directory), sorted."""
+ root = Path(path)
+ if root.is_file():
+ return [root]
+ files = [
+ p
+ for p in root.rglob("*")
+ if p.is_file() and p.suffix.lower() in {".yaml", ".yml"}
+ ]
+ return sorted(files)
+
+
+def validate_template_dir(directory: str | Path) -> list[ValidationResult]:
+ """Validate every YAML file under ``directory``."""
+ return [validate_template(p) for p in iter_template_files(directory)]
+
+
+def validate_template(path: str | Path) -> ValidationResult:
+ """Validate one template YAML file.
+
+ Returns a :class:`ValidationResult`. ``ok`` is True when there are no
+ error-severity diagnostics (warnings do not fail the result).
+ """
+ file_path = Path(path)
+ result = ValidationResult(file=str(file_path))
+
+ if not file_path.exists():
+ result.diagnostics.append(
+ Diagnostic(
+ HE_T001,
+ "error",
+ "",
+ f"File not found: {file_path}",
+ )
+ )
+ return result
+
+ raw, load_diags = _load_yaml(file_path)
+ result.diagnostics.extend(load_diags)
+ if raw is None:
+ return result
+
+ config, schema_diags = _parse_config(raw)
+ result.diagnostics.extend(schema_diags)
+ if config is None:
+ return result
+
+ result.diagnostics.extend(_check_localize(config))
+ result.diagnostics.extend(_check_output_shape(config))
+ result.diagnostics.extend(_check_identifiers(config))
+ result.diagnostics.extend(_check_spatiotemporal(config))
+ result.diagnostics.extend(_check_display(config))
+ result.diagnostics.extend(_check_bilingual(config))
+ result.diagnostics.extend(_check_field_count(config))
+ result.diagnostics.extend(_check_gallery_collision(file_path, config))
+ return result
+
+
+def _load_yaml(path: Path) -> tuple[dict[str, Any] | None, list[Diagnostic]]:
+ try:
+ with open(path, encoding="utf-8") as handle:
+ raw = yaml.safe_load(handle)
+ except yaml.YAMLError as exc:
+ loc = ""
+ mark = getattr(exc, "problem_mark", None)
+ if mark is not None:
+ loc = f"line {mark.line + 1}"
+ return None, [
+ Diagnostic(HE_T001, "error", loc, f"YAML is not parseable: {exc}")
+ ]
+ except OSError as exc:
+ return None, [Diagnostic(HE_T001, "error", "", f"Cannot read file: {exc}")]
+
+ if raw is None:
+ return None, [Diagnostic(HE_T002, "error", "", "Template YAML is empty")]
+ if not isinstance(raw, dict):
+ return None, [
+ Diagnostic(
+ HE_T002,
+ "error",
+ "",
+ "Template YAML must be a mapping of keys to values",
+ )
+ ]
+ return raw, []
+
+
+def _parse_config(
+ raw: dict[str, Any],
+) -> tuple[TemplateCfg | None, list[Diagnostic]]:
+ try:
+ return TemplateCfg(**raw), []
+ except ValidationError as exc:
+ diags = []
+ for err in exc.errors():
+ loc = ".".join(str(part) for part in err.get("loc", ()))
+ diags.append(
+ Diagnostic(HE_T002, "error", loc, err.get("msg", "Invalid template"))
+ )
+ if not diags:
+ diags.append(Diagnostic(HE_T002, "error", "", "Invalid template schema"))
+ return None, diags
+ except (TypeError, ValueError) as exc:
+ return None, [Diagnostic(HE_T002, "error", "", str(exc))]
+
+
+def _check_localize(config: TemplateCfg) -> list[Diagnostic]:
+ languages = (
+ config.language if isinstance(config.language, list) else [config.language]
+ )
+ diags: list[Diagnostic] = []
+ for lang in languages:
+ try:
+ localize_template(config, lang)
+ except Exception as exc:
+ diags.append(
+ Diagnostic(
+ HE_T002,
+ "error",
+ "language",
+ f"Template is not valid for language {lang!r}: {exc}",
+ )
+ )
+ return diags
+
+
+def _check_output_shape(config: TemplateCfg) -> list[Diagnostic]:
+ if config.type in GRAPH_TYPES and not isinstance(config.output, GraphOutputSchema):
+ return [
+ Diagnostic(
+ HE_T002,
+ "error",
+ "output",
+ f"{config.type} templates require output.entities and output.relations",
+ )
+ ]
+ if config.type in RECORD_TYPES and not isinstance(config.output, NaiveOutputSchema):
+ return [
+ Diagnostic(
+ HE_T002,
+ "error",
+ "output",
+ f"{config.type} templates require output.fields",
+ )
+ ]
+ return []
+
+
+def _field_map(schema: NaiveOutputSchema) -> dict[str, FieldSchema]:
+ return {item.name: item for item in schema.fields}
+
+
+def _field_refs(spec: str | None, *, placeholders_only: bool = False) -> list[str]:
+ """Return field names referenced by an identifier or display string.
+
+ Identifiers treat a bare name (``name``) as a field. Display strings only
+ contribute ``{placeholder}`` matches; a constant label with no braces is
+ allowed.
+ """
+ if not spec:
+ return []
+ if "{" in spec:
+ return _PLACEHOLDER_RE.findall(spec)
+ if placeholders_only:
+ return []
+ return [spec]
+
+
+def _missing_fields(
+ spec: str,
+ available: set[str],
+ *,
+ placeholders_only: bool = False,
+) -> list[str]:
+ return [
+ name
+ for name in _field_refs(spec, placeholders_only=placeholders_only)
+ if name not in available
+ ]
+
+
+def _entity_relation_fields(
+ config: TemplateCfg,
+) -> tuple[set[str], set[str]] | None:
+ if not isinstance(config.output, GraphOutputSchema):
+ return None
+ return (
+ set(_field_map(config.output.entities)),
+ set(_field_map(config.output.relations)),
+ )
+
+
+def _record_fields(config: TemplateCfg) -> set[str]:
+ if not isinstance(config.output, NaiveOutputSchema):
+ return set()
+ return set(_field_map(config.output))
+
+
+def _check_identifiers(config: TemplateCfg) -> list[Diagnostic]:
+ if config.type in RECORD_TYPES:
+ return _check_record_identifiers(config)
+ if config.type in GRAPH_TYPES:
+ return _check_graph_identifiers(config)
+ return []
+
+
+def _check_record_identifiers(config: TemplateCfg) -> list[Diagnostic]:
+ if config.type != "set":
+ return []
+
+ diags: list[Diagnostic] = []
+ identifiers = config.identifiers
+ item_id = getattr(identifiers, "item_id", None) if identifiers else None
+ if not item_id:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.item_id",
+ "set templates require identifiers.item_id",
+ )
+ )
+ return diags
+
+ available = _record_fields(config)
+ missing = _missing_fields(item_id, available)
+ for name in missing:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.item_id",
+ f"Field {name!r} is not defined in output.fields",
+ )
+ )
+ return diags
+
+
+def _check_graph_identifiers(config: TemplateCfg) -> list[Diagnostic]:
+ diags: list[Diagnostic] = []
+ identifiers = config.identifiers
+ if identifiers is None:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers",
+ f"{config.type} templates require an identifiers section",
+ )
+ )
+ return diags
+
+ if isinstance(identifiers, NaiveIdentifierSchema):
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers",
+ f"{config.type} templates require entity_id, relation_id, "
+ "and relation_members (not item_id)",
+ )
+ )
+ return diags
+
+ fields = _entity_relation_fields(config)
+ if fields is None:
+ return diags
+ entity_fields, relation_fields = fields
+
+ entity_id = getattr(identifiers, "entity_id", None)
+ relation_id = getattr(identifiers, "relation_id", None)
+ relation_members = getattr(identifiers, "relation_members", None)
+
+ if not entity_id:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.entity_id",
+ "entity_id is required for graph templates",
+ )
+ )
+ else:
+ for name in _missing_fields(entity_id, entity_fields):
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.entity_id",
+ f"Field {name!r} is not defined in output.entities",
+ )
+ )
+
+ if not relation_id:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_id",
+ "relation_id is required for graph templates",
+ )
+ )
+ else:
+ for name in _missing_fields(relation_id, relation_fields):
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_id",
+ f"Field {name!r} is not defined in output.relations",
+ )
+ )
+
+ diags.extend(
+ _check_relation_members(config.type, relation_members, relation_fields, config)
+ )
+ return diags
+
+
+def _check_relation_members(
+ autotype: str,
+ members: Any,
+ relation_fields: set[str],
+ config: TemplateCfg,
+) -> list[Diagnostic]:
+ diags: list[Diagnostic] = []
+ if members is None:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_members",
+ "relation_members is required for graph templates",
+ )
+ )
+ return diags
+
+ if autotype in BINARY_GRAPH_TYPES:
+ if not isinstance(members, dict):
+ diags.append(
+ Diagnostic(
+ HE_T004,
+ "error",
+ "identifiers.relation_members",
+ f"{autotype} requires relation_members to be a dict "
+ "mapping roles to edge field names",
+ )
+ )
+ return diags
+ if not members:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_members",
+ "relation_members dict must map at least one edge field",
+ )
+ )
+ return diags
+ for role, field_name in members.items():
+ if field_name not in relation_fields:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ f"identifiers.relation_members.{role}",
+ f"Field {field_name!r} is not defined in output.relations",
+ )
+ )
+ return diags
+
+ if autotype == "hypergraph":
+ if isinstance(members, dict):
+ diags.append(
+ Diagnostic(
+ HE_T004,
+ "error",
+ "identifiers.relation_members",
+ "hypergraph requires relation_members to be a string "
+ "or a list of field names, not a dict",
+ )
+ )
+ return diags
+ if isinstance(members, str):
+ names = [members] if members else []
+ elif isinstance(members, list):
+ names = list(members)
+ else:
+ diags.append(
+ Diagnostic(
+ HE_T004,
+ "error",
+ "identifiers.relation_members",
+ "hypergraph requires relation_members to be a string or list",
+ )
+ )
+ return diags
+ if not names:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_members",
+ "relation_members must name at least one relation field",
+ )
+ )
+ return diags
+
+ relation_schema = (
+ _field_map(config.output.relations)
+ if isinstance(config.output, GraphOutputSchema)
+ else {}
+ )
+ for name in names:
+ if name not in relation_fields:
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.relation_members",
+ f"Field {name!r} is not defined in output.relations",
+ )
+ )
+ continue
+ field_schema = relation_schema.get(name)
+ if field_schema is not None and field_schema.type != "list":
+ diags.append(
+ Diagnostic(
+ HE_T004,
+ "error",
+ "identifiers.relation_members",
+ f"Hypergraph member field {name!r} must have type: list",
+ )
+ )
+ return diags
+
+ return diags
+
+
+def _check_spatiotemporal(config: TemplateCfg) -> list[Diagnostic]:
+ if config.type not in TEMPORAL_TYPES | SPATIAL_TYPES:
+ return []
+ if not isinstance(config.identifiers, GraphIdentifiersSchema):
+ # Missing/wrong identifiers already reported as HE-T003.
+ return []
+
+ diags: list[Diagnostic] = []
+ fields = _entity_relation_fields(config)
+ relation_fields = fields[1] if fields else set()
+
+ if config.type in TEMPORAL_TYPES:
+ time_field = config.identifiers.time_field
+ if not time_field:
+ diags.append(
+ Diagnostic(
+ HE_T006,
+ "error",
+ "identifiers.time_field",
+ f"{config.type} requires identifiers.time_field",
+ )
+ )
+ else:
+ for name in _missing_fields(time_field, relation_fields):
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.time_field",
+ f"Field {name!r} is not defined in output.relations",
+ )
+ )
+
+ if config.type in SPATIAL_TYPES:
+ location_field = config.identifiers.location_field
+ if not location_field:
+ diags.append(
+ Diagnostic(
+ HE_T006,
+ "error",
+ "identifiers.location_field",
+ f"{config.type} requires identifiers.location_field",
+ )
+ )
+ else:
+ for name in _missing_fields(location_field, relation_fields):
+ diags.append(
+ Diagnostic(
+ HE_T003,
+ "error",
+ "identifiers.location_field",
+ f"Field {name!r} is not defined in output.relations",
+ )
+ )
+ return diags
+
+
+def _check_display(config: TemplateCfg) -> list[Diagnostic]:
+ display = config.display
+ diags: list[Diagnostic] = []
+
+ if isinstance(display, NaiveDisplaySchema):
+ available = _record_fields(config)
+ for name in _missing_fields(display.label, available, placeholders_only=True):
+ diags.append(
+ Diagnostic(
+ HE_T005,
+ "error",
+ "display.label",
+ f"Placeholder {{{name}}} is not defined in output.fields",
+ )
+ )
+ return diags
+
+ if not isinstance(display, GraphDisplaySchema):
+ return diags
+
+ fields = _entity_relation_fields(config)
+ if fields is None:
+ return diags
+ entity_fields, relation_fields = fields
+
+ for name in _missing_fields(
+ display.entity_label, entity_fields, placeholders_only=True
+ ):
+ diags.append(
+ Diagnostic(
+ HE_T005,
+ "error",
+ "display.entity_label",
+ f"Placeholder {{{name}}} is not defined in output.entities",
+ )
+ )
+ for name in _missing_fields(
+ display.relation_label, relation_fields, placeholders_only=True
+ ):
+ diags.append(
+ Diagnostic(
+ HE_T005,
+ "error",
+ "display.relation_label",
+ f"Placeholder {{{name}}} is not defined in output.relations",
+ )
+ )
+ return diags
+
+
+def _declared_languages(config: TemplateCfg) -> list[str]:
+ if isinstance(config.language, list):
+ return [str(lang) for lang in config.language]
+ return [str(config.language)]
+
+
+def _is_lang_dict(value: object) -> bool:
+ if not isinstance(value, dict) or not value:
+ return False
+ return all(isinstance(key, str) and _LANG_KEY_RE.match(key) for key in value)
+
+
+def _walk_bilingual(value: Any, path: str, langs: list[str]) -> list[Diagnostic]:
+ diags: list[Diagnostic] = []
+ if _is_lang_dict(value):
+ for lang in langs:
+ entry = value.get(lang)
+ missing = lang not in value or entry is None or entry == "" or entry == []
+ if missing:
+ diags.append(
+ Diagnostic(
+ HE_T007,
+ "warning",
+ f"{path}.{lang}" if path else lang,
+ f"Missing {lang!r} text on a bilingual field",
+ )
+ )
+ return diags
+ if isinstance(value, dict):
+ for key, child in value.items():
+ child_path = f"{path}.{key}" if path else str(key)
+ diags.extend(_walk_bilingual(child, child_path, langs))
+ elif isinstance(value, list):
+ for index, child in enumerate(value):
+ diags.extend(_walk_bilingual(child, f"{path}[{index}]", langs))
+ return diags
+
+
+def _check_bilingual(config: TemplateCfg) -> list[Diagnostic]:
+ langs = _declared_languages(config)
+ payload = {
+ "description": config.description,
+ "output": config.output.model_dump(),
+ "guideline": config.guideline.model_dump(),
+ }
+ return _walk_bilingual(payload, "", langs)
+
+
+def _check_field_count(config: TemplateCfg) -> list[Diagnostic]:
+ 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 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
+
+
+def _is_under_presets(path: Path) -> bool:
+ try:
+ path.resolve().relative_to(_presets_dir().resolve())
+ return True
+ except ValueError:
+ return False
+
+
+def _domain_for(path: Path) -> str:
+ presets = _presets_dir()
+ try:
+ relative = path.resolve().relative_to(presets.resolve())
+ if relative.parts:
+ return relative.parts[0]
+ except ValueError:
+ pass
+ return path.parent.name
+
+
+@lru_cache(maxsize=1)
+def _preset_key_index() -> dict[str, tuple[Path, ...]]:
+ presets = _presets_dir()
+ index: dict[str, list[Path]] = {}
+ if not presets.is_dir():
+ return {}
+ for file_path in presets.rglob("*.yaml"):
+ try:
+ with open(file_path, encoding="utf-8") as handle:
+ raw = yaml.safe_load(handle)
+ except (OSError, yaml.YAMLError):
+ continue
+ if not isinstance(raw, dict) or "name" not in raw:
+ continue
+ domain = file_path.parent.relative_to(presets).parts[0]
+ index.setdefault(f"{domain}/{raw['name']}", []).append(file_path)
+ return {key: tuple(paths) for key, paths in index.items()}
+
+
+def _preset_files_for_key(key: str) -> list[Path]:
+ return list(_preset_key_index().get(key, ()))
+
+
+def _check_gallery_collision(path: Path, config: TemplateCfg) -> list[Diagnostic]:
+ domain = _domain_for(path)
+ if not domain:
+ return []
+ key = f"{domain}/{config.name}"
+ if _is_under_presets(path):
+ others = [
+ other
+ for other in _preset_files_for_key(key)
+ if other.resolve() != path.resolve()
+ ]
+ if not others:
+ return []
+ return [
+ Diagnostic(
+ HE_T009,
+ "warning",
+ "name",
+ f"Gallery key {key!r} is used by another preset: {others[0]}",
+ )
+ ]
+
+ if key in Gallery.list():
+ return [
+ Diagnostic(
+ HE_T009,
+ "warning",
+ "name",
+ f"Gallery already has a template named {key!r}",
+ )
+ ]
+ return []
+
+
+__all__ = [
+ "BINARY_GRAPH_TYPES",
+ "FIELD_COUNT_LIMIT",
+ "GRAPH_TYPES",
+ "HE_T001",
+ "HE_T002",
+ "HE_T003",
+ "HE_T004",
+ "HE_T005",
+ "HE_T006",
+ "HE_T007",
+ "HE_T008",
+ "HE_T009",
+ "Diagnostic",
+ "ValidationResult",
+ "iter_template_files",
+ "validate_template",
+ "validate_template_dir",
+]
diff --git a/tests/template_engine/test_validator.py b/tests/template_engine/test_validator.py
new file mode 100644
index 0000000..099f125
--- /dev/null
+++ b/tests/template_engine/test_validator.py
@@ -0,0 +1,370 @@
+"""Unit tests for the template semantic validator."""
+
+from pathlib import Path
+from textwrap import dedent
+
+from hyperextract.utils.template_engine import (
+ validate_template,
+ validate_template_dir,
+)
+from hyperextract.utils.template_engine.validator import (
+ HE_T001,
+ HE_T002,
+ HE_T003,
+ HE_T004,
+ HE_T005,
+ HE_T006,
+ HE_T007,
+ HE_T008,
+ HE_T009,
+)
+
+PRESETS_DIR = (
+ Path(__file__).resolve().parents[2] / "hyperextract" / "templates" / "presets"
+)
+
+VALID_GRAPH = """
+language: en
+name: ValidGraph
+type: graph
+tags: [test]
+description: A valid graph template
+output:
+ description: graph output
+ entities:
+ description: entities
+ fields:
+ - name: name
+ type: str
+ description: entity name
+ - name: type
+ type: str
+ description: entity type
+ relations:
+ description: relations
+ fields:
+ - name: source
+ type: str
+ description: source entity
+ - name: target
+ type: str
+ description: target entity
+ - name: type
+ type: str
+ description: relation type
+guideline:
+ target: Extract entities and relations
+ rules_for_entities: Keep names stable
+ rules_for_relations: Only explicit links
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+display:
+ entity_label: '{name}'
+ relation_label: '{type}'
+"""
+
+VALID_HYPERGRAPH = """
+language: en
+name: ValidHypergraph
+type: hypergraph
+tags: [test]
+description: A valid hypergraph template
+output:
+ description: hypergraph output
+ entities:
+ description: entities
+ fields:
+ - name: name
+ type: str
+ description: entity name
+ relations:
+ description: relations
+ fields:
+ - name: name
+ type: str
+ description: hyperedge name
+ - name: participants
+ type: list
+ description: participating entities
+guideline:
+ target: Extract hyperedges
+ rules_for_entities: Keep names stable
+ rules_for_relations: Group co-participants
+identifiers:
+ entity_id: name
+ relation_id: '{name}'
+ relation_members: participants
+display:
+ entity_label: '{name}'
+ relation_label: '{name}'
+"""
+
+VALID_SET = """
+language: en
+name: ValidSet
+type: set
+tags: [test]
+description: A valid set template
+output:
+ description: set output
+ fields:
+ - name: name
+ type: str
+ description: item name
+guideline:
+ target: Extract items
+ rules: Keep names stable
+identifiers:
+ item_id: name
+display:
+ label: '{name}'
+"""
+
+
+def _write(tmp_path: Path, content: str, name: str = "template.yaml") -> Path:
+ path = tmp_path / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(dedent(content).lstrip(), encoding="utf-8")
+ return path
+
+
+def _codes(result) -> list[str]:
+ return [d.code for d in result.diagnostics]
+
+
+def _by_code(result, code: str):
+ return [d for d in result.diagnostics if d.code == code]
+
+
+class TestValidTemplates:
+ def test_valid_graph_has_no_diagnostics(self, tmp_path):
+ path = _write(tmp_path, VALID_GRAPH)
+ result = validate_template(path)
+ assert result.ok
+ assert result.diagnostics == []
+ assert result.to_dict()["ok"] is True
+ assert result.to_dict()["file"] == str(path)
+
+ def test_valid_hypergraph_has_no_diagnostics(self, tmp_path):
+ result = validate_template(_write(tmp_path, VALID_HYPERGRAPH))
+ assert result.ok
+ assert result.diagnostics == []
+
+ def test_valid_set_has_no_diagnostics(self, tmp_path):
+ result = validate_template(_write(tmp_path, VALID_SET))
+ assert result.ok
+ assert result.diagnostics == []
+
+
+class TestStructureErrors:
+ def test_invalid_yaml(self, tmp_path):
+ path = _write(tmp_path, "name: [\n")
+ result = validate_template(path)
+ assert not result.ok
+ assert HE_T001 in _codes(result)
+
+ def test_invalid_schema_type(self, tmp_path):
+ path = _write(tmp_path, VALID_GRAPH.replace("type: graph", "type: graphh"))
+ result = validate_template(path)
+ assert not result.ok
+ assert HE_T002 in _codes(result)
+
+ def test_missing_file(self, tmp_path):
+ result = validate_template(tmp_path / "missing.yaml")
+ assert not result.ok
+ assert HE_T001 in _codes(result)
+
+
+class TestIdentifierErrors:
+ def test_missing_entity_field(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace("entity_id: name", "entity_id: nickname")
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ diags = _by_code(result, HE_T003)
+ assert diags
+ assert diags[0].path == "identifiers.entity_id"
+ assert "nickname" in diags[0].message
+
+ def test_relation_members_dict_value_must_be_edge_field(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace(
+ " source: source\n target: target",
+ " source: src\n target: target",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ diags = _by_code(result, HE_T003)
+ assert any(d.path == "identifiers.relation_members.source" for d in diags)
+
+ def test_graph_members_must_be_dict(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace(
+ " relation_members:\n source: source\n target: target",
+ " relation_members: participants",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ assert HE_T004 in _codes(result)
+
+ def test_hypergraph_members_must_not_be_dict(self, tmp_path):
+ yaml_text = VALID_HYPERGRAPH.replace(
+ " relation_members: participants",
+ " relation_members:\n source: source\n target: target",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ assert HE_T004 in _codes(result)
+
+ def test_hypergraph_member_field_must_be_list_type(self, tmp_path):
+ yaml_text = VALID_HYPERGRAPH.replace(
+ " - name: participants\n type: list",
+ " - name: participants\n type: str",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ assert HE_T004 in _codes(result)
+
+
+class TestDisplayErrors:
+ def test_entity_label_unknown_placeholder(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace(
+ " entity_label: '{name}'",
+ " entity_label: '{title}'",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ diags = _by_code(result, HE_T005)
+ assert diags
+ assert diags[0].path == "display.entity_label"
+ assert "title" in diags[0].message
+
+ def test_constant_display_label_is_allowed(self, tmp_path):
+ yaml_text = VALID_SET.replace(" label: '{name}'", " label: '出院指导'")
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert result.ok
+ assert HE_T005 not in _codes(result)
+
+
+class TestSpatiotemporalErrors:
+ def test_temporal_graph_requires_time_field(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace("type: graph", "type: temporal_graph")
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ diags = _by_code(result, HE_T006)
+ assert any(d.path == "identifiers.time_field" for d in diags)
+
+ def test_spatial_graph_requires_location_field(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace("type: graph", "type: spatial_graph")
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ diags = _by_code(result, HE_T006)
+ assert any(d.path == "identifiers.location_field" for d in diags)
+
+ def test_spatio_temporal_requires_both(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace("type: graph", "type: spatio_temporal_graph")
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert not result.ok
+ paths = {d.path for d in _by_code(result, HE_T006)}
+ assert "identifiers.time_field" in paths
+ assert "identifiers.location_field" in paths
+
+
+class TestWarningsDoNotFail:
+ def test_bilingual_gap_is_warning(self, tmp_path):
+ yaml_text = VALID_GRAPH.replace(
+ "language: en\nname: ValidGraph",
+ "language: [zh, en]\nname: ValidGraph",
+ ).replace(
+ "description: A valid graph template",
+ "description:\n en: A valid graph template",
+ )
+ result = validate_template(_write(tmp_path, yaml_text))
+ assert result.ok
+ assert result.error_count == 0
+ assert HE_T007 in _codes(result)
+ assert all(d.severity == "warning" for d in _by_code(result, HE_T007))
+
+ def test_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(4)
+ )
+ yaml_text = VALID_GRAPH.replace(
+ " - name: type\n type: str\n description: entity type",
+ " - name: type\n type: str\n description: entity type\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.entities.fields"
+
+ def test_gallery_name_collision_is_warning(self, tmp_path):
+ path = _write(
+ tmp_path / "general",
+ VALID_GRAPH.replace("name: ValidGraph", "name: graph"),
+ name="dup.yaml",
+ )
+ result = validate_template(path)
+ assert result.ok
+ diags = _by_code(result, HE_T009)
+ assert diags
+ assert "general/graph" in diags[0].message
+
+
+class TestJsonShape:
+ def test_to_dict_is_stable(self, tmp_path):
+ result = validate_template(
+ _write(
+ tmp_path,
+ VALID_GRAPH.replace("entity_id: name", "entity_id: missing"),
+ )
+ )
+ payload = result.to_dict()
+ assert set(payload) == {"file", "diagnostics", "ok"}
+ assert payload["ok"] is False
+ assert payload["diagnostics"]
+ item = payload["diagnostics"][0]
+ assert set(item) == {"code", "severity", "path", "message"}
+
+
+# Bundled presets that currently fail error-level checks. Do not "fix" them in
+# this change — record and keep the allowlist tight so new errors still fail.
+KNOWN_PRESET_ERRORS = {
+ "general/workflow_graph.yaml": {HE_T006},
+}
+
+
+class TestPresetBootstrap:
+ def test_bundled_presets_have_no_unexpected_errors(self):
+ results = validate_template_dir(PRESETS_DIR)
+ assert results, "expected bundled presets"
+
+ unexpected = []
+ seen_known = set()
+ for item in results:
+ relative = str(Path(item.file).relative_to(PRESETS_DIR)).replace("\\", "/")
+ error_codes = {
+ d.code for d in item.diagnostics if d.severity == "error"
+ }
+ allowed = KNOWN_PRESET_ERRORS.get(relative, set())
+ extra = error_codes - allowed
+ missing = allowed - error_codes
+ if extra or missing:
+ unexpected.append((relative, sorted(error_codes), sorted(allowed)))
+ if relative in KNOWN_PRESET_ERRORS:
+ seen_known.add(relative)
+
+ assert unexpected == []
+ assert seen_known == set(KNOWN_PRESET_ERRORS)
+
+ collisions = [
+ item.file
+ for item in results
+ if any(d.code == HE_T009 for d in item.diagnostics)
+ ]
+ assert collisions == []