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.pyindex c59905e..fe84b82 100644--- a/hyperextract/cli/cli.py+++ b/hyperextract/cli/cli.py@@ -12,7 +12,7 @@ from rich.text import Textfrom hyperextract.utils.logging import configure_logging, get_loggerfrom hyperextract.utils.template_engine import Gallery, Template-from .commands import config_app, list_app+from .commands import config_app, list_app, template_appfrom .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__.pyindex 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_appfrom .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.pynew file mode 100644index 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.pynew file mode 100644index 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}