Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: add Cypher MERGE export that keeps N-ary Hyperedge nodes
Frankie-Xu9c0b918ea55b
diff --git a/docs/en/cli/commands/export.md b/docs/en/cli/commands/export.mdindex eae88f8..778c11c 100644--- a/docs/en/cli/commands/export.md+++ b/docs/en/cli/commands/export.md@@ -2,7 +2,7 @@Export a knowledge abstract to an [Obsidian](https://obsidian.md) vault — a folder of Markdown notes linked by `[[wikilinks]]`.-`export` is a command group. Formats: `obsidian`, `graphml`, `csv`.+`export` is a command group. Formats: `obsidian`, `graphml`, `cypher`, `csv`.---@@ -165,6 +165,27 @@ he export graphml ./tesla_kb/ -o ./tesla.graphml---+## he export cypher++Export a Neo4j / Memgraph-compatible Cypher MERGE script (`cypher-shell < file.cypher`). Binary edges become relationships (`:REL`, or a legal `type`/`label` ident). Edges with three or more endpoints become `(:Hyperedge)` nodes plus `(n)-[:IN]->(h)` in extractor order — never a pairwise clique. 0/1-endpoint or missing-endpoint edges are skipped with a warning.++Existing non-empty output files require `--force` / `-f`.++### Synopsis++```bash+he export cypher KA_PATH -o FILE.cypher [--force]+```++### Examples++```bash+he export cypher ./tesla_kb/ -o ./tesla.cypher+he export cypher ./tesla_kb/ -o ./tesla.cypher --force+```++---+## he export csvExport nodes and edges as CSV tables for spreadsheets and graph tools that ingest edge lists.@@ -220,7 +241,7 @@ The same capability is available on graph Auto-Types for Obsidian, and as standa```pythonka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)-from hyperextract.utils.exporters import export_to_graphml, export_to_csv+from hyperextract.utils.exporters import export_to_graphml, export_to_csv, export_to_cypherexport_to_graphml(ka.nodes,@@ -238,6 +259,14 @@ export_to_csv(folder_path="./tesla_csv/",overwrite=True,)++export_to_cypher(+ ka.nodes,+ ka.edges,+ node_id_extractor=ka.node_key_extractor,+ incident_nodes_extractor=ka.nodes_in_edge_extractor,+ file_path="./tesla.cypher",+)```---diff --git a/docs/en/cli/index.md b/docs/en/cli/index.mdindex 7b44d52..d736df5 100644--- a/docs/en/cli/index.md+++ b/docs/en/cli/index.md@@ -34,6 +34,7 @@ he --version| `he show` | Visualize knowledge graph | — || `he export obsidian` | Export to an Obsidian vault | `-o` output, `--name`, `-f` force || `he export graphml` | Export a pairwise graph to GraphML | `-o` output file |+| `he export cypher` | Export Neo4j-compatible MERGE (N-ary as Hyperedge nodes) | `-o` output file, `-f` force || `he export csv` | Export nodes/edges as CSV tables | `-o` directory, `-f` force || `he search` | Semantic search in knowledge abstract | `-n` top-k results, `--source`, `--tag` || `he talk` | Chat with knowledge abstract | `-i` interactive, `-q` query |@@ -173,6 +174,7 @@ he show ./output/- **[`he info`](commands/info.md)** — View knowledge abstract statistics- **[`he export obsidian`](commands/export.md)** — Export to an Obsidian vault- **[`he export graphml`](commands/export.md#he-export-graphml)** — Export a pairwise graph to GraphML+- **[`he export cypher`](commands/export.md#he-export-cypher)** — Export a Neo4j-compatible Cypher MERGE script- **[`he export csv`](commands/export.md#he-export-csv)** — Export nodes/edges as CSV tables### Managementdiff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.mdindex 5ad6c54..f55dff5 100644--- a/docs/zh/cli/commands/export.md+++ b/docs/zh/cli/commands/export.md@@ -2,7 +2,7 @@将知识摘要导出为 [Obsidian](https://obsidian.md) 知识库——一个由 `[[双向链接]]` 关联的 Markdown 笔记文件夹。-`export` 是一个命令组。目前支持的格式:`obsidian`、`graphml`、`csv`。+`export` 是一个命令组。目前支持的格式:`obsidian`、`graphml`、`cypher`、`csv`。---@@ -165,6 +165,27 @@ he export graphml ./tesla_kb/ -o ./tesla.graphml---+## he export cypher++导出 Neo4j / Memgraph 可用的 Cypher MERGE 脚本(`cypher-shell < file.cypher`)。二元边写成关系(`:REL`,或合法的 `type`/`label` ident)。三个及以上端点的边写成 `(:Hyperedge)` 节点,并用 `(n)-[:IN]->(h)` 按抽取器顺序连接——不会拆成两两团。0/1 个端点或缺失端点的边会跳过并记 warning。++目标文件已存在且非空时需要 `--force` / `-f`。++### 用法++```bash+he export cypher KA_PATH -o FILE.cypher [--force]+```++### 示例++```bash+he export cypher ./tesla_kb/ -o ./tesla.cypher+he export cypher ./tesla_kb/ -o ./tesla.cypher --force+```++---+## he export csv将节点和边导出为 CSV 表,便于电子表格以及读取边列表的图谱工具使用。@@ -220,7 +241,7 @@ Obsidian 导出是图谱 Auto-Type 上的方法;GraphML / CSV 是独立纯函```pythonka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)-from hyperextract.utils.exporters import export_to_graphml, export_to_csv+from hyperextract.utils.exporters import export_to_graphml, export_to_csv, export_to_cypherexport_to_graphml(ka.nodes,@@ -238,6 +259,14 @@ export_to_csv(folder_path="./tesla_csv/",overwrite=True,)++export_to_cypher(+ ka.nodes,+ ka.edges,+ node_id_extractor=ka.node_key_extractor,+ incident_nodes_extractor=ka.nodes_in_edge_extractor,+ file_path="./tesla.cypher",+)```---diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.mdindex e8b2b64..5f3718b 100644--- a/docs/zh/cli/index.md+++ b/docs/zh/cli/index.md@@ -34,6 +34,7 @@ he --version| `he show` | 可视化知识图谱 | — || `he export obsidian` | 导出为 Obsidian 知识库 | `-o` 输出, `--name`, `-f` 强制 || `he export graphml` | 将二元图导出为 GraphML | `-o` 输出文件 |+| `he export cypher` | 导出 Neo4j 兼容 MERGE(N 元边为 Hyperedge 节点) | `-o` 输出文件, `-f` 强制 || `he export csv` | 将节点/边导出为 CSV 表 | `-o` 目录, `-f` 强制 || `he search` | 知识库语义搜索 | `-n` top-k 结果数, `--source`, `--tag` || `he talk` | 与知识库对话 | `-i` 交互模式, `-q` 查询 |@@ -173,6 +174,7 @@ he show ./output/- **[`he info`](commands/info.md)** — 查看知识库统计信息- **[`he export obsidian`](commands/export.md)** — 导出为 Obsidian 知识库- **[`he export graphml`](commands/export.md#he-export-graphml)** — 将二元图导出为 GraphML+- **[`he export cypher`](commands/export.md#he-export-cypher)** — 导出 Neo4j 兼容的 Cypher MERGE 脚本- **[`he export csv`](commands/export.md#he-export-csv)** — 将节点/边导出为 CSV 表### 管理diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.pyindex 4f6d33d..348fd1f 100644--- a/hyperextract/cli/cli.py+++ b/hyperextract/cli/cli.py@@ -574,8 +574,8 @@ def _load_graph_ka_for_export(ka_path: str):if not hasattr(ka, "export_obsidian"):console.print(- "[red]Error:[/red] GraphML/CSV export is only supported for graph-type "- "Knowledge Abstracts (graph, hypergraph, temporal/spatial graphs)."+ "[red]Error:[/red] GraphML/CSV/Cypher export is only supported for "+ "graph-type Knowledge Abstracts (graph, hypergraph, temporal/spatial graphs).")raise typer.Exit(1)@@ -635,6 +635,62 @@ def export_graphml_cmd(console.print("[dim]Open the file in Gephi, yEd, or another GraphML tool.[/dim]")+@export_app.command(name="cypher")+def export_cypher_cmd(+ ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),+ output: str = typer.Option(..., "--output", "-o", help="Output Cypher file"),+ force: bool = typer.Option(+ False, "--force", "-f", help="Overwrite an existing Cypher file"+ ),+):+ """Export a knowledge graph to a Neo4j-compatible Cypher MERGE script.++ Binary edges become relationships. N-ary edges become Hyperedge nodes+ with IN membership (not a pairwise clique).+ """+ from hyperextract.utils.exporters import export_to_cypher++ logger.info("command=export-cypher ka_path=%s output=%s", ka_path, output)++ output_path = Path(output)+ existing_nonempty = (+ output_path.exists()+ and output_path.is_file()+ and output_path.stat().st_size > 0+ )+ if existing_nonempty and not force:+ console.print(+ "[red]Error:[/red] Output file already exists. "+ "Use --force / -f to overwrite it."+ )+ raise typer.Exit(1)++ ka, _path, template = _load_graph_ka_for_export(ka_path)+ console.print(f"[blue]Knowledge Abstract:[/blue] {ka_path}")+ console.print(f"[blue]Template:[/blue] {template}")+ console.print(f"[blue]Output file:[/blue] {output}")+ console.print()++ with console.status("[bold blue]Exporting to Cypher..."):+ try:+ export_to_cypher(+ ka.nodes,+ ka.edges,+ node_id_extractor=ka.node_key_extractor,+ incident_nodes_extractor=ka.nodes_in_edge_extractor,+ file_path=output_path,+ edge_id_extractor=getattr(ka, "edge_key_extractor", None),+ )+ except Exception as e:+ console.print(f"[red]Error during export:[/red] {e}")+ raise typer.Exit(1)++ console.print()+ console.print(f"[bold green]Success![/bold green] Wrote Cypher to {output_path}")+ console.print()+ console.print("[dim]Load with cypher-shell < file.cypher (Neo4j / Memgraph).[/dim]")++@export_app.command(name="csv")def export_csv_cmd(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),diff --git a/hyperextract/utils/exporters/__init__.py b/hyperextract/utils/exporters/__init__.pyindex f157b45..955a993 100644--- a/hyperextract/utils/exporters/__init__.py+++ b/hyperextract/utils/exporters/__init__.py@@ -1,4 +1,4 @@-"""Read-only graph exporters (GraphML, CSV).+"""Read-only graph exporters (GraphML, CSV, Cypher).These are pure functions over node/edge models, matching:func:`hyperextract.utils.obsidian.export_to_obsidian`. They are not methods@@ -19,11 +19,13 @@ Example::from .common import HYPEREDGE_MEMBER_SEPfrom .csv_export import export_to_csv+from .cypher import export_to_cypherfrom .graphml import GraphMLHypergraphError, export_to_graphml__all__ = ["HYPEREDGE_MEMBER_SEP","GraphMLHypergraphError","export_to_csv",+ "export_to_cypher","export_to_graphml",]diff --git a/hyperextract/utils/exporters/cypher.py b/hyperextract/utils/exporters/cypher.pynew file mode 100644index 0000000..bd68553--- /dev/null+++ b/hyperextract/utils/exporters/cypher.py@@ -0,0 +1,197 @@+"""Cypher exporter for Neo4j-compatible MERGE scripts.++Pairwise edges become relationships. N-ary edges become ``(:Hyperedge)``+nodes with ``-[:IN]->`` membership — never exploded into a pairwise clique.+Endpoint order is preserved. Stdlib only; no neo4j driver.+"""++import re+from collections.abc import Callable, Sequence+from pathlib import Path+from typing import Any++from pydantic import BaseModel++from hyperextract.utils.logging import get_logger++from .common import incident_ids, resolve_nodes, scalar_fields++logger = get_logger(__name__)++_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")+# Unquoted relationship types that would parse as Cypher keywords.+_RESERVED = frozenset(+ {+ "AND",+ "AS",+ "CONTAINS",+ "CREATE",+ "DELETE",+ "DETACH",+ "FALSE",+ "IN",+ "IS",+ "MATCH",+ "MERGE",+ "NOT",+ "NULL",+ "OR",+ "REMOVE",+ "RETURN",+ "SET",+ "TRUE",+ "WHERE",+ "WITH",+ "XOR",+ }+)+++def export_to_cypher(+ nodes: Sequence[BaseModel],+ edges: Sequence[BaseModel],+ *,+ node_id_extractor: Callable[[Any], str],+ incident_nodes_extractor: Callable[[Any], Sequence[str]],+ file_path: str | Path,+ edge_id_extractor: Callable[[Any], str] | None = None,+) -> Path:+ """Export a graph to a Cypher MERGE script.++ Args:+ nodes: Node/entity 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 incident node keys in order.+ Two endpoints become a relationship; three or more become a+ ``Hyperedge`` node plus ``IN`` membership.+ file_path: Destination ``.cypher`` file.+ edge_id_extractor: Optional edge -> Cypher id. Defaults to+ ``e0``, ``e1``, ...++ Returns:+ The written file :class:`~pathlib.Path`.++ Raises:+ IsADirectoryError: If ``file_path`` exists and is a directory.+ """+ dest = Path(file_path)+ if dest.exists() and dest.is_dir():+ raise IsADirectoryError(+ f"Destination '{dest}' is a directory; pass a Cypher file path."+ )+ dest.parent.mkdir(parents=True, exist_ok=True)++ by_id = resolve_nodes(nodes, node_id_extractor)+ lines: list[str] = []+ for node_id, node in by_id.items():+ lines.append(f"MERGE (n:Node {{id: {_cypher_str(node_id)}}})")+ assignments = _set_assignments("n", scalar_fields(node))+ if assignments:+ lines.append(f"SET {assignments}")++ skipped = 0+ pairwise = 0+ hyper = 0+ for index, edge in enumerate(edges):+ members = incident_ids(edge, incident_nodes_extractor)+ if members is None:+ skipped += 1+ continue+ if len(members) <= 1:+ skipped += 1+ logger.warning(+ "export.cypher: skipping edge with %d endpoint(s) members=%s",+ len(members),+ members,+ )+ continue+ missing = [member for member in members if member not in by_id]+ if missing:+ skipped += 1+ logger.warning(+ "export.cypher: skipping edge with missing endpoint(s) %s",+ missing,+ )+ continue+ edge_id = _edge_id(edge, index, edge_id_extractor)+ fields = scalar_fields(edge)+ if len(members) == 2:+ rel_type = _relationship_type(fields)+ source, target = members[0], members[1]+ lines.append(f"MERGE (a:Node {{id: {_cypher_str(source)}}})")+ lines.append(f"MERGE (b:Node {{id: {_cypher_str(target)}}})")+ lines.append(+ f"MERGE (a)-[r:{rel_type} {{id: {_cypher_str(edge_id)}}}]->(b)"+ )+ assignments = _set_assignments("r", fields)+ if assignments:+ lines.append(f"SET {assignments}")+ pairwise += 1+ continue+ lines.append(f"MERGE (h:Hyperedge {{id: {_cypher_str(edge_id)}}})")+ assignments = _set_assignments("h", fields)+ if assignments:+ lines.append(f"SET {assignments}")+ for member in members:+ lines.append(f"MERGE (n:Node {{id: {_cypher_str(member)}}})")+ lines.append("MERGE (n)-[:IN]->(h)")+ hyper += 1++ dest.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")+ logger.info(+ "cypher: exported nodes=%d edges=%d hyperedges=%d skipped_edges=%d path=%s",+ len(by_id),+ pairwise,+ hyper,+ skipped,+ dest,+ )+ return dest+++def _cypher_str(value: Any) -> str:+ text = str(value).replace("\\", "\\\\").replace('"', '\\"')+ return f'"{text}"'+++def _cypher_literal(value: str | float | bool) -> str:+ if isinstance(value, bool):+ return "true" if value else "false"+ if isinstance(value, (int, float)) and not isinstance(value, bool):+ return str(value)+ return _cypher_str(value)+++def _set_assignments(alias: str, fields: dict[str, str | int | float | bool]) -> str:+ parts = []+ for key, value in fields.items():+ if key == "id":+ continue+ parts.append(f"{alias}.{key} = {_cypher_literal(value)}")+ return ", ".join(parts)+++def _relationship_type(fields: dict[str, str | int | float | bool]) -> str:+ for key in ("type", "label"):+ raw = fields.get(key)+ if isinstance(raw, str) and _is_legal_ident(raw):+ return raw+ return "REL"+++def _is_legal_ident(name: str) -> bool:+ return bool(_IDENT.match(name)) and name.upper() not in _RESERVED+++def _edge_id(edge: Any, index: int, extractor: Callable[[Any], str] | None) -> str:+ if extractor is None:+ return f"e{index}"+ try:+ value = extractor(edge)+ except Exception as exc:+ logger.debug("export.cypher: edge_id_extractor raised %s", exc)+ return f"e{index}"+ if value in (None, ""):+ return f"e{index}"+ return str(value)diff --git a/tests/utils/test_exporters.py b/tests/utils/test_exporters.pyindex 4e54e67..9dd66f7 100644--- a/tests/utils/test_exporters.py+++ b/tests/utils/test_exporters.py@@ -18,6 +18,7 @@ from hyperextract.cli.cli import appfrom hyperextract.utils.exporters import (HYPEREDGE_MEMBER_SEP,export_to_csv,+ export_to_cypher,export_to_graphml,)from hyperextract.utils.exporters.graphml import GRAPHML_NS@@ -206,6 +207,102 @@ class TestGraphMLPairwise:assert _edge_endpoints(graph, ns) == []+# ---------------------------------------------------------------------------+# Cypher — pairwise REL, N-ary Hyperedge (no clique)+# ---------------------------------------------------------------------------+++class TypedRel(BaseModel):+ source: str+ target: str+ type: str+++class TestCypherExport:+ def test_pairwise_uses_rel_and_direction(self, tmp_path):+ nodes = [Entity(name="A"), Entity(name="B")]+ edges = [Relation(source="B", target="A", relation_type="leads_to")]+ path = export_to_cypher(+ nodes,+ edges,+ node_id_extractor=lambda n: n.name,+ incident_nodes_extractor=lambda e: (e.source, e.target),+ file_path=tmp_path / "g.cypher",+ )+ text = path.read_text(encoding="utf-8")+ assert 'MERGE (n:Node {id: "A"})' in text+ assert 'MERGE (n:Node {id: "B"})' in text+ assert ":REL" in text+ assert 'id: "B"' in text+ assert ']->(b)' in text+ assert text.index('MERGE (a:Node {id: "B"})') < text.index(+ 'MERGE (b:Node {id: "A"})'+ )++ def test_legal_type_becomes_rel_ident(self, tmp_path):+ nodes = [Entity(name="A"), Entity(name="B")]+ edges = [TypedRel(source="A", target="B", type="KNOWS")]+ path = export_to_cypher(+ nodes,+ edges,+ node_id_extractor=lambda n: n.name,+ incident_nodes_extractor=lambda e: (e.source, e.target),+ file_path=tmp_path / "g.cypher",+ )+ assert ":KNOWS" in path.read_text(encoding="utf-8")++ def test_nary_is_hyperedge_not_clique(self, tmp_path):+ nodes = [Entity(name="A"), Entity(name="B"), Entity(name="C")]+ edges = [Event(label="meeting", participants=["C", "A", "B"])]+ path = export_to_cypher(+ nodes,+ edges,+ node_id_extractor=lambda n: n.name,+ incident_nodes_extractor=lambda e: tuple(e.participants),+ file_path=tmp_path / "g.cypher",+ edge_id_extractor=lambda e: e.label,+ )+ text = path.read_text(encoding="utf-8")+ assert ":Hyperedge" in text+ assert "[:IN]" in text+ assert text.count("[:IN]") == 3+ in_order = [+ line+ for line in text.splitlines()+ if "[:IN]" in line or "MERGE (n:Node {id:" in line+ ]+ member_ids = [+ line.split('id: "')[1].split('"')[0]+ for line in in_order+ if "MERGE (n:Node {id:" in line+ and "Hyperedge" not in line+ and line.split('id: "')[1].split('"')[0] in {"A", "B", "C"}+ ]+ # Membership MERGEs after the Hyperedge, in extractor order C, A, B+ assert member_ids[-3:] == ["C", "A", "B"]+ assert "-[:REL]" not in text+ assert not any(+ pair in text+ for pair in (+ '(a)-[r:REL {id: "C-A"}]',+ '(a)-[r:REL {id: "A-B"}]',+ '(a)-[r:REL {id: "C-B"}]',+ )+ )++ def test_escapes_backslash_and_quote(self, tmp_path):+ nodes = [Entity(name='say "hi"\\')]+ path = export_to_cypher(+ nodes,+ [],+ node_id_extractor=lambda n: n.name,+ incident_nodes_extractor=lambda e: (),+ file_path=tmp_path / "g.cypher",+ )+ text = path.read_text(encoding="utf-8")+ assert r"say \"hi\"\\" in text++# ---------------------------------------------------------------------------# CSV — round-trip, quoting, direction, dangling, hypergraph# ---------------------------------------------------------------------------@@ -484,3 +581,46 @@ class TestCLIExport:)assert result.exit_code == 1assert "graph" in result.output.lower()++ def test_cypher_writes_hyperedge_membership(self, tmp_path):+ ka_dir = _ka_dir(tmp_path)+ fake = FakeGraphKA(+ [Entity(name="A"), Entity(name="B"), Entity(name="C")],+ [Event(label="meeting", participants=["C", "A", "B"])],+ hypergraph=True,+ )+ out = tmp_path / "out.cypher"+ with (+ patch("hyperextract.cli.cli.validate_config"),+ patch(+ "hyperextract.cli.cli.get_template_from_ka", return_value=("t", "en")+ ),+ patch("hyperextract.cli.cli.Template.create", return_value=fake),+ ):+ result = runner.invoke(+ app, ["export", "cypher", str(ka_dir), "-o", str(out)]+ )+ assert result.exit_code == 0, result.output+ text = out.read_text(encoding="utf-8")+ assert ":Hyperedge" in text+ assert "[:IN]" in text+ assert "-[:REL]->" not in text++ def test_cypher_requires_force_for_existing_file(self, tmp_path):+ ka_dir = _ka_dir(tmp_path)+ dest = tmp_path / "out.cypher"+ dest.write_text("SENTINEL", encoding="utf-8")+ fake = FakeGraphKA([Entity(name="A")], [])+ with (+ patch("hyperextract.cli.cli.validate_config"),+ patch(+ "hyperextract.cli.cli.get_template_from_ka", return_value=("t", "en")+ ),+ patch("hyperextract.cli.cli.Template.create", return_value=fake),+ ):+ result = runner.invoke(+ app, ["export", "cypher", str(ka_dir), "-o", str(dest)]+ )+ assert result.exit_code != 0+ assert "--force" in result.output or "-f" in result.output+ assert dest.read_text(encoding="utf-8") == "SENTINEL"