Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: encode N-ary GraphML edges as GraphML 1.0 hyperedges
Frankie-Xu04b217faa7c9
diff --git a/docs/en/cli/commands/export.md b/docs/en/cli/commands/export.mdindex 874eba1..eae88f8 100644--- a/docs/en/cli/commands/export.md+++ b/docs/en/cli/commands/export.md@@ -125,9 +125,9 @@ Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported; the comm## he export graphml-Export a pairwise knowledge graph to [GraphML](http://graphml.graphdrawing.org/) — an XML graph format that Gephi, yEd, and other desktop tools can open.+Export a knowledge graph to [GraphML](http://graphml.graphdrawing.org/) — an XML graph format that Gephi, yEd, and other desktop tools can open.-Hypergraphs have no single GraphML encoding for N-ary edges. `he export graphml` reports a clear error for hypergraph KAs and suggests [`he export csv`](#he-export-csv).+Binary (2-endpoint) edges are written as ordinary `<edge source="…" target="…">` elements. Edges with **three or more** endpoints are written as GraphML 1.0 `<hyperedge>` elements with `<endpoint node="…"/>` children, in extractor order.### Synopsis@@ -149,11 +149,12 @@ he export graphml KA_PATH -o FILE.graphml### Description-- **Directed.** The document uses `graph edgedefault="directed"`. An edge `B → A` is written as `source="B"` `target="A"`; endpoints are never sorted.+- **Directed pairwise edges.** The document uses `graph edgedefault="directed"`. An edge `B → A` is written as `source="B"` `target="A"`; endpoints are never sorted.+- **N-ary hyperedges.** An edge with 3+ incident nodes becomes `<hyperedge>` plus `<endpoint node="…"/>` in the same order `incident_nodes_extractor` returns. Endpoints are never sorted.- **Attributes.** Scalar fields from each node's / edge's `model_dump()` (`str` / `int` / `float` / `bool`) become GraphML `<data>` keys. Nested values are stringified. XML special characters (`& < > " '`) are escaped.-- **Dangling edges.** An edge whose source or target node is missing is skipped (with a warning), not treated as a crash.+- **Dangling edges.** An edge whose source or target node is missing (or a hyperedge with any missing endpoint) is skipped (with a warning), not treated as a crash.-Supported Auto-Types: `AutoGraph` and its temporal/spatial subclasses. `AutoHypergraph` is rejected. Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported.+Supported Auto-Types: `AutoGraph`, `AutoHypergraph`, and temporal/spatial subclasses. Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported.### Examplesdiff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.mdindex e33eebb..5ad6c54 100644--- a/docs/zh/cli/commands/export.md+++ b/docs/zh/cli/commands/export.md@@ -125,9 +125,9 @@ Serbian-American inventor and electrical engineer## he export graphml-将二元知识图谱导出为 [GraphML](http://graphml.graphdrawing.org/)——Gephi、yEd 等桌面工具可打开的 XML 图谱格式。+将知识图谱导出为 [GraphML](http://graphml.graphdrawing.org/)——Gephi、yEd 等桌面工具可打开的 XML 图谱格式。-超图的 N 元边没有单一的 GraphML 编码。对超图 KA 运行 `he export graphml` 会给出明确错误,并建议使用 [`he export csv`](#he-export-csv)。+二元(2 端点)边写成普通的 `<edge source="…" target="…">`。**三个及以上**端点的边写成 GraphML 1.0 的 `<hyperedge>`,子元素为 `<endpoint node="…"/>`,顺序与抽取器返回顺序一致。### 用法@@ -149,11 +149,12 @@ he export graphml KA_PATH -o FILE.graphml### 说明-- **有向。** 文档使用 `graph edgedefault="directed"`。边 `B → A` 写作 `source="B"` `target="A"`;端点不会被排序。+- **有向二元边。** 文档使用 `graph edgedefault="directed"`。边 `B → A` 写作 `source="B"` `target="A"`;端点不会被排序。+- **N 元超边。** 3 个及以上端点的边写成 `<hyperedge>`,并按 `incident_nodes_extractor` 的返回顺序写出 `<endpoint node="…"/>`。端点不会被排序。- **属性。** 节点 / 边 `model_dump()` 中的标量字段(`str` / `int` / `float` / `bool`)成为 GraphML `<data>` 键。嵌套值转为字符串。XML 特殊字符(`& < > " '`)会被转义。-- **悬空边。** 源或目标节点缺失的边会被跳过(并记录 warning),不会导致崩溃。+- **悬空边。** 源或目标节点缺失的二元边(或任一端点缺失的超边)会被跳过(并记录 warning),不会导致崩溃。-支持的 Auto-Type:`AutoGraph` 及其时空子类。`AutoHypergraph` 会被拒绝。非图谱类型(`AutoList`、`AutoSet`、`AutoModel`)不支持。+支持的 Auto-Type:`AutoGraph`、`AutoHypergraph` 及其时空子类。非图谱类型(`AutoList`、`AutoSet`、`AutoModel`)不支持。### 示例diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.pyindex 75e3108..e9590f5 100644--- a/hyperextract/cli/cli.py+++ b/hyperextract/cli/cli.py@@ -581,10 +581,10 @@ def export_graphml_cmd(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),output: str = typer.Option(..., "--output", "-o", help="Output GraphML file"),):- """Export a pairwise graph Knowledge Abstract to GraphML.+ """Export a knowledge graph to GraphML.- Hypergraphs are not encoded as GraphML (no single N-ary standard).- Use `he export csv` for hypergraphs.+ Binary edges are written as `<edge source target>`. Edges with three+ or more endpoints are written as GraphML 1.0 `<hyperedge>` elements."""from hyperextract.utils.exporters import GraphMLHypergraphError, export_to_graphml@@ -592,13 +592,6 @@ def export_graphml_cmd(ka, _path, template = _load_graph_ka_for_export(ka_path)- if _is_hypergraph_ka(ka):- console.print(- "[red]Error:[/red] GraphML export supports pairwise graphs only. "- "Use [bold]he export csv[/bold] for hypergraphs."- )- raise typer.Exit(1)-output_path = Path(output)console.print(f"[blue]Knowledge Abstract:[/blue] {ka_path}")console.print(f"[blue]Template:[/blue] {template}")diff --git a/hyperextract/utils/exporters/graphml.py b/hyperextract/utils/exporters/graphml.pyindex 1c6cdaa..776cc1f 100644--- a/hyperextract/utils/exporters/graphml.py+++ b/hyperextract/utils/exporters/graphml.py@@ -1,12 +1,12 @@-"""GraphML exporter for pairwise (binary) graphs.+"""GraphML exporter for pairwise graphs and GraphML 1.0 hyperedges.-Produces a directed GraphML 1.0 document that Gephi, yEd, and other-desktop tools can open. N-ary hyperedges have no single GraphML encoding;-callers should use :func:`hyperextract.utils.exporters.export_to_csv`-with ``hypergraph=True`` instead.+Produces a GraphML 1.0 document that Gephi, yEd, and other desktop tools+can open. Binary edges are written as ``<edge source target>``. Edges with+three or more endpoints are written as ``<hyperedge>`` with+``<endpoint node="..."/>`` children, in ``incident_nodes_extractor`` order.-Endpoint order is preserved: ``source`` is the first incident node and-``target`` is the second. Endpoints are never sorted.+Endpoint order is preserved: for pairwise edges, ``source`` is the first+incident node and ``target`` is the second. Endpoints are never sorted."""from collections.abc import Callable, Sequence@@ -31,9 +31,17 @@ logger = get_logger(__name__)GRAPHML_NS = "http://graphml.graphdrawing.org/xmlns"+_ScalarFields = dict[str, str | int | float | bool]+_PairwiseRow = tuple[str, str, str, _ScalarFields]+_HyperedgeRow = tuple[str, list[str], _ScalarFields]+class GraphMLHypergraphError(ValueError):- """Raised when GraphML export is asked to encode an N-ary edge."""+ """Raised when GraphML export cannot encode an edge.++ N-ary edges are encoded as GraphML 1.0 ``<hyperedge>`` elements; this+ exception is kept for callers that still catch it.+ """def export_to_graphml(@@ -45,24 +53,23 @@ def export_to_graphml(file_path: str | Path,edge_id_extractor: Callable[[Any], str] | None = None,) -> Path:- """Export a pairwise graph to a GraphML file.+ """Export a graph to a GraphML file.Args:nodes: Node/entity models to export.- edges: Pairwise edge models to export.+ edges: Edge models to export (pairwise or N-ary).node_id_extractor: Maps a node to its unique key (matches edge endpoints).- incident_nodes_extractor: Maps an edge to ``(source, target)`` node- keys. Must return exactly two endpoints; N-ary edges raise- :class:`GraphMLHypergraphError`.+ incident_nodes_extractor: Maps an edge to incident node keys in order.+ Two endpoints become ``<edge source target>``; three or more+ become ``<hyperedge>`` with ``<endpoint>`` children.file_path: Destination ``.graphml`` file.- edge_id_extractor: Optional edge -> GraphML edge id. Defaults to+ edge_id_extractor: Optional edge -> GraphML id. Defaults to``e0``, ``e1``, ...Returns:The written file :class:`~pathlib.Path`.Raises:- GraphMLHypergraphError: If any edge has more than two incident nodes.IsADirectoryError: If ``file_path`` exists and is a directory."""dest = Path(file_path)@@ -75,7 +82,7 @@ def export_to_graphml(by_id = resolve_nodes(nodes, node_id_extractor)node_keys: dict[str, str] = {}- node_rows: list[tuple[str, dict[str, str | int | float | bool]]] = []+ node_rows: list[tuple[str, _ScalarFields]] = []for node_id, node in by_id.items():fields = scalar_fields(node)for name, value in fields.items():@@ -84,53 +91,68 @@ def export_to_graphml()node_rows.append((node_id, fields))- pairwise: list[tuple[str, str, str, dict[str, str | int | float | bool]]] = []+ pairwise: list[_PairwiseRow] = []+ hyperedges: list[_HyperedgeRow] = []edge_keys: dict[str, str] = {}+ hyperedge_keys: dict[str, str] = {}skipped = 0for index, edge in enumerate(edges):members = incident_ids(edge, incident_nodes_extractor)if members is None:skipped += 1continue- if len(members) > 2:- raise GraphMLHypergraphError(- "GraphML export supports pairwise graphs only; this edge has "- f"{len(members)} incident nodes. Use CSV export for hypergraphs "- "(he export csv / export_to_csv(..., hypergraph=True))."- )- if len(members) != 2:- skipped += 1- logger.warning(- "export.graphml: skipping non-pairwise edge members=%s",- members,- )+ if len(members) == 2:+ source, target = members[0], members[1]+ if source not in by_id or target not in by_id:+ skipped += 1+ logger.warning(+ "export.graphml: skipping edge with missing endpoint "+ "source=%s target=%s",+ source,+ target,+ )+ continue+ edge_id = _edge_id(edge, index, edge_id_extractor)+ fields = scalar_fields(edge)+ for name, value in fields.items():+ edge_keys[name] = merge_graphml_type(+ edge_keys.get(name), graphml_attr_type(value)+ )+ pairwise.append((edge_id, source, target, fields))continue- source, target = members[0], members[1]- if source not in by_id or target not in by_id:- skipped += 1- logger.warning(- "export.graphml: skipping edge with missing endpoint "- "source=%s target=%s",- source,- target,- )+ if len(members) >= 3:+ missing = [member for member in members if member not in by_id]+ if missing:+ skipped += 1+ logger.warning(+ "export.graphml: skipping hyperedge with missing endpoint(s) %s",+ missing,+ )+ continue+ edge_id = _edge_id(edge, index, edge_id_extractor)+ fields = scalar_fields(edge)+ for name, value in fields.items():+ hyperedge_keys[name] = merge_graphml_type(+ hyperedge_keys.get(name), graphml_attr_type(value)+ )+ hyperedges.append((edge_id, members, fields))continue+ skipped += 1+ logger.warning(+ "export.graphml: skipping non-pairwise edge members=%s",+ members,+ )- edge_id = _edge_id(edge, index, edge_id_extractor)- fields = scalar_fields(edge)- for name, value in fields.items():- edge_keys[name] = merge_graphml_type(- edge_keys.get(name), graphml_attr_type(value)- )- pairwise.append((edge_id, source, target, fields))-- xml = _render_graphml(node_keys, edge_keys, node_rows, pairwise)+ xml = _render_graphml(+ node_keys, edge_keys, hyperedge_keys, node_rows, pairwise, hyperedges+ )dest.write_text(xml, encoding="utf-8")logger.info(- "graphml: exported nodes=%d edges=%d skipped_edges=%d path=%s",+ "graphml: exported nodes=%d edges=%d hyperedges=%d skipped_edges=%d path=%s",len(node_rows),len(pairwise),+ len(hyperedges),skipped,dest,)@@ -160,8 +182,10 @@ def _key_id(prefix: str, name: str) -> str:def _render_graphml(node_keys: dict[str, str],edge_keys: dict[str, str],- node_rows: list[tuple[str, dict[str, str | int | float | bool]]],- edges: list[tuple[str, str, str, dict[str, str | int | float | bool]]],+ hyperedge_keys: dict[str, str],+ node_rows: list[tuple[str, _ScalarFields]],+ edges: list[_PairwiseRow],+ hyperedges: list[_HyperedgeRow],) -> str:lines = ['<?xml version="1.0" encoding="UTF-8"?>',@@ -183,6 +207,14 @@ def _render_graphml(f' <key id="{xml_escape(kid)}" for="edge" 'f'attr.name="{xml_escape(name)}" attr.type="{attr_type}"/>')+ hyperedge_key_ids: dict[str, str] = {}+ for name, attr_type in hyperedge_keys.items():+ kid = _key_id("h", name)+ hyperedge_key_ids[name] = kid+ lines.append(+ f' <key id="{xml_escape(kid)}" for="hyperedge" '+ f'attr.name="{xml_escape(name)}" attr.type="{attr_type}"/>'+ )lines.append(' <graph id="G" edgedefault="directed">')for node_id, fields in node_rows:@@ -216,6 +248,18 @@ def _render_graphml(else:lines.append(f" <edge {attrs}/>")+ for edge_id, members, fields in hyperedges:+ lines.append(f' <hyperedge id="{xml_escape(edge_id)}">')+ for member in members:+ lines.append(f' <endpoint node="{xml_escape(member)}"/>')+ for name, value in fields.items():+ kid = hyperedge_key_ids[name]+ lines.append(+ f' <data key="{xml_escape(kid)}">'+ f"{xml_escape(graphml_attr_value(value))}</data>"+ )+ lines.append(" </hyperedge>")+lines.append(" </graph>")lines.append("</graphml>")lines.append("")diff --git a/tests/utils/test_exporters.py b/tests/utils/test_exporters.pyindex 499a256..4e54e67 100644--- a/tests/utils/test_exporters.py+++ b/tests/utils/test_exporters.py@@ -17,7 +17,6 @@ from typer.testing import CliRunnerfrom hyperextract.cli.cli import appfrom hyperextract.utils.exporters import (HYPEREDGE_MEMBER_SEP,- GraphMLHypergraphError,export_to_csv,export_to_graphml,)@@ -178,17 +177,33 @@ class TestGraphMLPairwise:]assert node_ids == ["Apple"]- def test_nary_edge_raises(self, tmp_path):+ def test_nary_edge_writes_hyperedge(self, tmp_path):nodes = [Entity(name="A"), Entity(name="B"), Entity(name="C")]- edges = [Event(label="meeting", participants=["A", "B", "C"])]- with pytest.raises(GraphMLHypergraphError, match="pairwise"):- export_to_graphml(- nodes,- edges,- node_id_extractor=lambda n: n.name,- incident_nodes_extractor=lambda e: tuple(e.participants),- file_path=tmp_path / "g.graphml",+ edges = [Event(label="meeting", participants=["C", "A", "B"])]+ path = export_to_graphml(+ nodes,+ edges,+ node_id_extractor=lambda n: n.name,+ incident_nodes_extractor=lambda e: tuple(e.participants),+ file_path=tmp_path / "g.graphml",+ )+ xml = path.read_text(encoding="utf-8")+ assert "hyperedge" in xml+ assert f'xmlns="{GRAPHML_NS}"' in xml++ root, graph, ns = _parse_graphml(path)+ assert root.tag == f"{{{GRAPHML_NS}}}graphml" or root.get("xmlns") == GRAPHML_NS+ hyperedges = graph.findall("g:hyperedge", ns) or graph.findall("hyperedge")+ assert len(hyperedges) == 1+ endpoints = [+ ep.get("node")+ for ep in (+ hyperedges[0].findall("g:endpoint", ns)+ or hyperedges[0].findall("endpoint"))+ ]+ assert endpoints == ["C", "A", "B"]+ assert _edge_endpoints(graph, ns) == []# ---------------------------------------------------------------------------@@ -353,7 +368,7 @@ class TestCLIExport:_root, graph, ns = _parse_graphml(out)assert _edge_endpoints(graph, ns) == [("B", "A")]- def test_graphml_rejects_hypergraph(self, tmp_path):+ def test_graphml_exports_hypergraph(self, tmp_path):ka_dir = _ka_dir(tmp_path)fake = FakeGraphKA([Entity(name="A"), Entity(name="B"), Entity(name="C")],@@ -371,9 +386,10 @@ class TestCLIExport:result = runner.invoke(app, ["export", "graphml", str(ka_dir), "-o", str(out)])- assert result.exit_code == 1- assert "csv" in result.output.lower()- assert not out.exists()+ assert result.exit_code == 0, result.output+ xml = out.read_text(encoding="utf-8")+ assert "hyperedge" in xml+ assert f'xmlns="{GRAPHML_NS}"' in xmldef test_csv_writes_tables(self, tmp_path):ka_dir = _ka_dir(tmp_path)