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: 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.md
index 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.
### Examples
diff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.md
index 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.py
index 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.py
index 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 = 0
for index, edge in enumerate(edges):
members = incident_ids(edge, incident_nodes_extractor)
if members is None:
skipped += 1
continue
- 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.py
index 499a256..4e54e67 100644
--- a/tests/utils/test_exporters.py
+++ b/tests/utils/test_exporters.py
@@ -17,7 +17,6 @@ from typer.testing import CliRunner
from hyperextract.cli.cli import app
from 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 xml
def test_csv_writes_tables(self, tmp_path):
ka_dir = _ka_dir(tmp_path)