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: wire he template validate CLI command

Frankie-Xu029efb3ce1f8
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index c59905e..fe84b82 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -12,7 +12,7 @@ from rich.text import Text
from hyperextract.utils.logging import configure_logging, get_logger
from hyperextract.utils.template_engine import Gallery, Template
-from .commands import config_app, list_app
+from .commands import config_app, list_app, template_app
from .config import (
load_ka_metadata,
)
@@ -38,6 +38,7 @@ app = typer.Typer(
app.add_typer(list_app, name="list")
app.add_typer(config_app, name="config")
+app.add_typer(template_app, name="template")
@app.callback()
@@ -110,6 +111,7 @@ def main(
[
("he list template", "List available templates"),
("he list method", "List extraction methods"),
+ ("he template validate <yaml>", "Validate a template YAML file"),
("he config --help", "Manage LLM/Embedder config"),
],
),
diff --git a/hyperextract/cli/commands/__init__.py b/hyperextract/cli/commands/__init__.py
index 23fc2ed..ecfe555 100644
--- a/hyperextract/cli/commands/__init__.py
+++ b/hyperextract/cli/commands/__init__.py
@@ -2,5 +2,6 @@
from .config import app as config_app
from .list import app as list_app
+from .template import app as template_app
-__all__ = ["config_app", "list_app"]
+__all__ = ["config_app", "list_app", "template_app"]
diff --git a/hyperextract/cli/commands/template.py b/hyperextract/cli/commands/template.py
new file mode 100644
index 0000000..f855c82
--- /dev/null
+++ b/hyperextract/cli/commands/template.py
@@ -0,0 +1,136 @@
+"""Template authoring commands for Hyper-Extract CLI."""
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from hyperextract.utils.logging import get_logger
+from hyperextract.utils.template_engine import (
+ ValidationResult,
+ validate_template,
+ validate_template_dir,
+)
+from hyperextract.utils.template_engine.validator import iter_template_files
+
+logger = get_logger("he.template")
+console = Console()
+
+app = typer.Typer(
+ name="template",
+ help="Template authoring tools",
+ no_args_is_help=True,
+)
+
+
+def _print_human(result: ValidationResult) -> None:
+ if result.ok and not result.diagnostics:
+ console.print(f"[bold green]OK[/bold green] {result.file}")
+ return
+ if result.ok:
+ console.print(
+ f"[bold yellow]OK[/bold yellow] {result.file} "
+ f"({result.warning_count} warning"
+ f"{'s' if result.warning_count != 1 else ''})"
+ )
+ else:
+ console.print(
+ f"[bold red]FAILED[/bold red] {result.file} "
+ f"({result.error_count} error"
+ f"{'s' if result.error_count != 1 else ''}, "
+ f"{result.warning_count} warning"
+ f"{'s' if result.warning_count != 1 else ''})"
+ )
+ for diagnostic in result.diagnostics:
+ color = "red" if diagnostic.severity == "error" else "yellow"
+ location = diagnostic.path or "-"
+ console.print(
+ f" [{color}]{diagnostic.severity:7}[/{color}] "
+ f"{diagnostic.code} {location} {diagnostic.message}"
+ )
+
+
+def _emit_json(payload: dict) -> None:
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
[email protected]("validate")
+def validate(
+ path: str = typer.Argument(
+ ...,
+ help="Template YAML file, or a directory when using --all",
+ ),
+ json_output: bool = typer.Option(
+ False,
+ "--json",
+ help="Print machine-readable JSON diagnostics",
+ ),
+ all_files: bool = typer.Option(
+ False,
+ "--all",
+ help="Validate every YAML file under a directory",
+ ),
+):
+ """Validate a template YAML file (or a directory of templates)."""
+ logger.info(
+ "command=template-validate path=%s json=%s all=%s",
+ path,
+ json_output,
+ all_files,
+ )
+ target = Path(path)
+
+ if not target.exists():
+ result = validate_template(target)
+ if json_output:
+ _emit_json(result.to_dict())
+ else:
+ console.print(f"[red]Error:[/red] {result.diagnostics[0].message}")
+ raise typer.Exit(1)
+
+ if target.is_dir() and not all_files:
+ console.print(
+ "[red]Error:[/red] PATH is a directory. Re-run with --all to validate "
+ "every YAML file under it."
+ )
+ raise typer.Exit(1)
+
+ if target.is_file() and all_files:
+ console.print(
+ "[red]Error:[/red] --all is for directories. Pass a directory path."
+ )
+ raise typer.Exit(1)
+
+ if target.is_dir():
+ files = iter_template_files(target)
+ if not files:
+ console.print(f"[red]Error:[/red] No YAML templates found in {target}")
+ raise typer.Exit(1)
+ results = validate_template_dir(target)
+ ok = all(item.ok for item in results)
+ if json_output:
+ _emit_json(
+ {
+ "results": [item.to_dict() for item in results],
+ "ok": ok,
+ }
+ )
+ else:
+ for item in results:
+ _print_human(item)
+ errors = sum(item.error_count for item in results)
+ warnings = sum(item.warning_count for item in results)
+ console.print()
+ console.print(
+ f"[dim]Validated {len(results)} template(s): "
+ f"{errors} error(s), {warnings} warning(s)[/dim]"
+ )
+ raise typer.Exit(0 if ok else 1)
+
+ result = validate_template(target)
+ if json_output:
+ _emit_json(result.to_dict())
+ else:
+ _print_human(result)
+ raise typer.Exit(0 if result.ok else 1)
diff --git a/tests/cli/test_template_validate.py b/tests/cli/test_template_validate.py
new file mode 100644
index 0000000..625dfbd
--- /dev/null
+++ b/tests/cli/test_template_validate.py
@@ -0,0 +1,146 @@
+"""Tests for the `he template validate` command."""
+
+import json
+from pathlib import Path
+from textwrap import dedent
+
+from typer.testing import CliRunner
+
+from hyperextract.cli.cli import app
+
+runner = CliRunner()
+
+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
+ 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}'
+"""
+
+
+def _write(tmp_path: Path, content: str, name: str = "template.yaml") -> Path:
+ path = tmp_path / name
+ path.write_text(dedent(content).lstrip(), encoding="utf-8")
+ return path
+
+
+class TestTemplateValidateCli:
+ def test_valid_template_exits_zero(self, tmp_path):
+ path = _write(tmp_path, VALID_GRAPH)
+ result = runner.invoke(app, ["template", "validate", str(path)])
+ assert result.exit_code == 0
+ assert "OK" in result.output
+
+ def test_identifier_error_exits_one(self, tmp_path):
+ path = _write(tmp_path, VALID_GRAPH.replace("entity_id: name", "entity_id: nope"))
+ result = runner.invoke(app, ["template", "validate", str(path)])
+ assert result.exit_code == 1
+ assert "HE-T003" in result.output
+ assert "FAILED" in result.output
+
+ def test_warning_only_exits_zero(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",
+ )
+ path = _write(tmp_path, yaml_text)
+ result = runner.invoke(app, ["template", "validate", str(path)])
+ assert result.exit_code == 0
+ assert "HE-T007" in result.output
+
+ def test_json_output_is_parseable(self, tmp_path):
+ path = _write(
+ tmp_path, VALID_GRAPH.replace("entity_id: name", "entity_id: missing")
+ )
+ result = runner.invoke(app, ["template", "validate", str(path), "--json"])
+ assert result.exit_code == 1
+ payload = json.loads(result.output)
+ assert payload["ok"] is False
+ assert payload["file"] == str(path)
+ assert isinstance(payload["diagnostics"], list)
+ item = payload["diagnostics"][0]
+ assert set(item) == {"code", "severity", "path", "message"}
+ assert item["code"] == "HE-T003"
+
+ def test_json_success_shape(self, tmp_path):
+ path = _write(tmp_path, VALID_GRAPH)
+ result = runner.invoke(app, ["template", "validate", str(path), "--json"])
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload == {"file": str(path), "diagnostics": [], "ok": True}
+
+ def test_directory_requires_all(self, tmp_path):
+ _write(tmp_path, VALID_GRAPH)
+ result = runner.invoke(app, ["template", "validate", str(tmp_path)])
+ assert result.exit_code == 1
+ assert "--all" in result.output
+
+ def test_batch_valid_directory_is_green(self, tmp_path):
+ _write(tmp_path, VALID_GRAPH, name="a.yaml")
+ _write(
+ tmp_path,
+ VALID_GRAPH.replace("name: ValidGraph", "name: Other"),
+ name="b.yaml",
+ )
+ result = runner.invoke(app, ["template", "validate", str(tmp_path), "--all"])
+ assert result.exit_code == 0, result.output
+
+ def test_batch_presets_only_known_error(self):
+ result = runner.invoke(app, ["template", "validate", str(PRESETS_DIR), "--all"])
+ # general/workflow_graph.yaml is temporal_graph without time_field.
+ assert result.exit_code == 1
+ assert "workflow_graph.yaml" in result.output
+ assert "HE-T006" in result.output
+
+ def test_batch_json_wraps_results(self, tmp_path):
+ _write(tmp_path, VALID_GRAPH, name="a.yaml")
+ _write(tmp_path, VALID_GRAPH.replace("name: ValidGraph", "name: Other"), name="b.yaml")
+ result = runner.invoke(
+ app, ["template", "validate", str(tmp_path), "--all", "--json"]
+ )
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["ok"] is True
+ assert len(payload["results"]) == 2
+ assert {item["ok"] for item in payload["results"]} == {True}