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: add GraphML and CSV exporters for graph knowledge abstracts

Frankie-Xu7185d9669570
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index fe84b82..a629da2 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -140,6 +140,14 @@ def main(
"he export obsidian <ka_path> -o <vault>",
"Export to Obsidian vault",
),
+ (
+ "he export graphml <ka_path> -o <file>",
+ "Export pairwise graph to GraphML",
+ ),
+ (
+ "he export csv <ka_path> -o <dir>",
+ "Export nodes/edges as CSV tables",
+ ),
],
),
]
@@ -522,6 +530,154 @@ def export_obsidian_cmd(
console.print("[dim]Open the folder as a vault in Obsidian to explore it.[/dim]")
+def _load_graph_ka_for_export(ka_path: str):
+ """Load a graph-family KA for GraphML / CSV export."""
+ path = validate_ka_with_data(ka_path)
+ template, lang = get_template_from_ka(path)
+
+ validate_config()
+
+ with console.status("[bold blue]Loading Knowledge Abstract..."):
+ try:
+ ka = Template.create(template, lang)
+ ka.load(path)
+ except Exception as e:
+ console.print(f"[red]Error loading Knowledge Abstract:[/red] {e}")
+ raise typer.Exit(1)
+
+ 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)."
+ )
+ raise typer.Exit(1)
+
+ return ka, path, template
+
+
+def _is_hypergraph_ka(ka) -> bool:
+ """True for AutoHypergraph; temporal/spatial graphs are pairwise."""
+ if type(ka).__name__ == "AutoHypergraph":
+ return True
+ meta = getattr(ka, "metadata", None)
+ return isinstance(meta, dict) and meta.get("type") == "hypergraph"
+
+
+@export_app.command(name="graphml")
+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.
+
+ Hypergraphs are not encoded as GraphML (no single N-ary standard).
+ Use `he export csv` for hypergraphs.
+ """
+ from hyperextract.utils.exporters import GraphMLHypergraphError, export_to_graphml
+
+ logger.info("command=export-graphml ka_path=%s output=%s", ka_path, output)
+
+ 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}")
+ console.print(f"[blue]Output file:[/blue] {output}")
+ console.print()
+
+ with console.status("[bold blue]Exporting to GraphML..."):
+ try:
+ export_to_graphml(
+ 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 GraphMLHypergraphError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+ 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 GraphML to {output_path}")
+ console.print()
+ console.print("[dim]Open the file in Gephi, yEd, or another GraphML tool.[/dim]")
+
+
+@export_app.command(name="csv")
+def export_csv_cmd(
+ ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),
+ output: str = typer.Option(..., "--output", "-o", help="Output directory"),
+ force: bool = typer.Option(
+ False, "--force", "-f", help="Write into an existing, non-empty directory"
+ ),
+):
+ """Export a Knowledge Abstract to node and edge CSV tables."""
+ from hyperextract.utils.exporters import export_to_csv
+
+ logger.info("command=export-csv ka_path=%s output=%s", ka_path, output)
+
+ output_path = Path(output)
+ nonempty = (
+ output_path.exists() and output_path.is_dir() and any(output_path.iterdir())
+ )
+ if nonempty and not force:
+ console.print(
+ "[red]Error:[/red] Output directory already exists and is not empty. "
+ "Use --force to write into it."
+ )
+ raise typer.Exit(1)
+
+ ka, _path, template = _load_graph_ka_for_export(ka_path)
+ hypergraph = _is_hypergraph_ka(ka)
+
+ console.print(f"[blue]Knowledge Abstract:[/blue] {ka_path}")
+ console.print(f"[blue]Template:[/blue] {template}")
+ console.print(f"[blue]Output directory:[/blue] {output}")
+ console.print()
+
+ with console.status("[bold blue]Exporting to CSV..."):
+ try:
+ export_to_csv(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ folder_path=output_path,
+ edge_id_extractor=getattr(ka, "edge_key_extractor", None),
+ hypergraph=hypergraph,
+ overwrite=force,
+ )
+ except FileExistsError:
+ console.print(
+ "[red]Error:[/red] Output directory already exists and is not empty. "
+ "Use --force to write into it."
+ )
+ raise typer.Exit(1)
+ except Exception as e:
+ console.print(f"[red]Error during export:[/red] {e}")
+ raise typer.Exit(1)
+
+ if hypergraph:
+ written = "nodes.csv + hyperedges.csv"
+ else:
+ written = "nodes.csv + edges.csv"
+
+ console.print()
+ console.print(f"[bold green]Success![/bold green] Wrote {written} to {output_path}")
+
+
app.add_typer(export_app, name="export")
diff --git a/hyperextract/utils/exporters/__init__.py b/hyperextract/utils/exporters/__init__.py
new file mode 100644
index 0000000..f157b45
--- /dev/null
+++ b/hyperextract/utils/exporters/__init__.py
@@ -0,0 +1,29 @@
+"""Read-only graph exporters (GraphML, CSV).
+
+These are pure functions over node/edge models, matching
+:func:`hyperextract.utils.obsidian.export_to_obsidian`. They are not methods
+on AutoType classes.
+
+Example::
+
+ from hyperextract.utils.exporters import export_to_graphml, export_to_csv
+
+ export_to_graphml(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ file_path="graph.graphml",
+ )
+"""
+
+from .common import HYPEREDGE_MEMBER_SEP
+from .csv_export import export_to_csv
+from .graphml import GraphMLHypergraphError, export_to_graphml
+
+__all__ = [
+ "HYPEREDGE_MEMBER_SEP",
+ "GraphMLHypergraphError",
+ "export_to_csv",
+ "export_to_graphml",
+]
diff --git a/hyperextract/utils/exporters/common.py b/hyperextract/utils/exporters/common.py
new file mode 100644
index 0000000..91081c1
--- /dev/null
+++ b/hyperextract/utils/exporters/common.py
@@ -0,0 +1,121 @@
+"""Shared helpers for GraphML and CSV exporters.
+
+These functions operate on plain Pydantic models plus extractor callables,
+matching :func:`hyperextract.utils.obsidian.export_to_obsidian`. They do not
+import AutoType classes.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from pydantic import BaseModel
+
+from hyperextract.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Stable delimiter for hyperedge membership in ``hyperedges.csv``.
+# Binary CSV never sorts endpoints; hyperedge members *are* sorted
+# lexicographically so the file is deterministic.
+HYPEREDGE_MEMBER_SEP = "|"
+
+_XML_ESCAPE = (
+ ("&", "&amp;"),
+ ("<", "&lt;"),
+ (">", "&gt;"),
+ ('"', "&quot;"),
+ ("'", "&apos;"),
+)
+
+
+def xml_escape(value: Any) -> str:
+ """Escape XML special characters ``& < > " '`` in document order."""
+ text = str(value)
+ for src, dst in _XML_ESCAPE:
+ text = text.replace(src, dst)
+ return text
+
+
+def scalar_fields(model: BaseModel) -> dict[str, str | int | float | bool]:
+ """Return exportable fields from ``model.model_dump()``.
+
+ ``str`` / ``int`` / ``float`` / ``bool`` are kept as-is; ``None`` is
+ omitted; every other value is coerced with ``str()``.
+ """
+ dumped = model.model_dump()
+ fields: dict[str, str | int | float | bool] = {}
+ for key, value in dumped.items():
+ if value is None:
+ continue
+ if value == [] or value == {}:
+ continue
+ if isinstance(value, (bool, int, float, str)):
+ fields[key] = value
+ else:
+ fields[key] = str(value)
+ return fields
+
+
+def graphml_attr_type(value: str | float | bool) -> str:
+ """Map a Python scalar to a GraphML ``attr.type``."""
+ if isinstance(value, bool):
+ return "boolean"
+ if isinstance(value, int):
+ return "long"
+ if isinstance(value, float):
+ return "double"
+ return "string"
+
+
+def graphml_attr_value(value: str | float | bool) -> str:
+ """Serialize a scalar for a GraphML ``<data>`` element."""
+ if isinstance(value, bool):
+ return "true" if value else "false"
+ return str(value)
+
+
+def merge_graphml_type(existing: str | None, incoming: str) -> str:
+ """Promote mixed attribute types to ``string``."""
+ if existing is None or existing == incoming:
+ return incoming
+ return "string"
+
+
+def resolve_nodes(
+ nodes: Sequence[BaseModel],
+ node_id_extractor: Callable[[Any], str],
+) -> dict[str, BaseModel]:
+ """Map node id -> model, keeping the first occurrence of each id."""
+ by_id: dict[str, BaseModel] = {}
+ for node in nodes:
+ try:
+ node_id = str(node_id_extractor(node))
+ except Exception as exc:
+ logger.debug("export: node_id_extractor raised %s; skipping node", exc)
+ continue
+ if node_id in by_id:
+ logger.debug("export: duplicate node id %r; keeping first", node_id)
+ continue
+ by_id[node_id] = node
+ return by_id
+
+
+def incident_ids(
+ edge: Any, incident_nodes_extractor: Callable[[Any], Sequence[str]]
+) -> list[str] | None:
+ """Normalize an edge's incident node keys.
+
+ Returns ``None`` when the extractor fails (caller should skip the edge).
+ """
+ try:
+ raw = incident_nodes_extractor(edge)
+ except Exception as exc:
+ logger.debug("export: incident_nodes_extractor raised %s; skipping edge", exc)
+ return None
+ if raw is None:
+ return []
+ if isinstance(raw, (str, bytes)):
+ return [str(raw)]
+ if isinstance(raw, (list, tuple, set)):
+ return [str(item) for item in raw if item is not None]
+ return [str(raw)]
diff --git a/hyperextract/utils/exporters/csv_export.py b/hyperextract/utils/exporters/csv_export.py
new file mode 100644
index 0000000..25aa448
--- /dev/null
+++ b/hyperextract/utils/exporters/csv_export.py
@@ -0,0 +1,241 @@
+"""CSV exporters for pairwise graphs and hypergraphs.
+
+Writes spreadsheet-friendly tables using the stdlib :mod:`csv` module
+(correct quoting for commas, quotes, and newlines).
+
+This module is named ``csv_export`` so it does not shadow the stdlib
+:mod:`csv` package. Import from :mod:`hyperextract.utils.exporters`.
+
+Pairwise graphs
+ ``nodes.csv`` (``id`` + schema scalars) and ``edges.csv``
+ (``source``, ``target`` + edge scalars). Endpoint order is preserved;
+ endpoints are never sorted.
+
+Hypergraphs
+ ``nodes.csv`` and ``hyperedges.csv``. ``hyperedges.csv`` has an ``id``
+ column plus a ``members`` column. Members are joined with
+ :data:`HYPEREDGE_MEMBER_SEP` (``|``) and **sorted lexicographically** so
+ the file is deterministic. This is the opposite of binary CSV, which
+ must not sort endpoints.
+"""
+
+import csv
+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 (
+ HYPEREDGE_MEMBER_SEP,
+ incident_ids,
+ resolve_nodes,
+ scalar_fields,
+)
+
+logger = get_logger(__name__)
+
+
+def export_to_csv(
+ nodes: Sequence[BaseModel],
+ edges: Sequence[BaseModel],
+ *,
+ node_id_extractor: Callable[[Any], str],
+ incident_nodes_extractor: Callable[[Any], Sequence[str]],
+ folder_path: str | Path,
+ edge_id_extractor: Callable[[Any], str] | None = None,
+ hypergraph: bool = False,
+ overwrite: bool = False,
+) -> Path:
+ """Export nodes and edges to CSV files in ``folder_path``.
+
+ Args:
+ nodes: Node/entity models to export.
+ edges: Edge/hyperedge models to export.
+ node_id_extractor: Maps a node to its unique key.
+ incident_nodes_extractor: Maps an edge to incident node keys
+ (a 2-tuple for pairwise graphs, an N-tuple for hypergraphs).
+ folder_path: Destination directory.
+ edge_id_extractor: Optional edge -> id (used for ``hyperedges.csv``
+ and ignored for pairwise ``edges.csv``). Defaults to ``e0``,
+ ``e1``, ...
+ hypergraph: If True, write ``hyperedges.csv`` instead of
+ ``edges.csv``. Hyperedge members are sorted; binary endpoints
+ are not.
+ overwrite: Allow writing into an existing, non-empty directory.
+
+ Returns:
+ The output directory :class:`~pathlib.Path`.
+
+ Raises:
+ FileExistsError: If ``folder_path`` exists, is non-empty, and
+ ``overwrite`` is False.
+ NotADirectoryError: If ``folder_path`` exists and is a file.
+ """
+ root = Path(folder_path)
+ if root.exists() and root.is_file():
+ raise NotADirectoryError(
+ f"Destination '{root}' is a file; pass a directory for CSV export."
+ )
+ if root.exists() and root.is_dir() and any(root.iterdir()) and not overwrite:
+ raise FileExistsError(
+ f"Destination '{root}' already exists and is not empty. "
+ f"Pass overwrite=True to write into it."
+ )
+ root.mkdir(parents=True, exist_ok=True)
+
+ by_id = resolve_nodes(nodes, node_id_extractor)
+ node_rows = _node_rows(by_id)
+ _write_csv(root / "nodes.csv", ["id"], node_rows)
+
+ if hypergraph:
+ edge_rows, skipped = _hyperedge_rows(
+ edges, incident_nodes_extractor, by_id, edge_id_extractor
+ )
+ _write_csv(root / "hyperedges.csv", ["id", "members"], edge_rows)
+ edge_count = len(edge_rows)
+ kind = "hypergraph"
+ else:
+ edge_rows, skipped = _pairwise_edge_rows(edges, incident_nodes_extractor, by_id)
+ _write_csv(root / "edges.csv", ["source", "target"], edge_rows)
+ edge_count = len(edge_rows)
+ kind = "graph"
+
+ logger.info(
+ "csv: exported kind=%s nodes=%d edges=%d skipped_edges=%d path=%s",
+ kind,
+ len(node_rows),
+ edge_count,
+ skipped,
+ root,
+ )
+ return root
+
+
+def _node_rows(by_id: dict[str, BaseModel]) -> list[dict[str, Any]]:
+ rows: list[dict[str, Any]] = []
+ for node_id, node in by_id.items():
+ row: dict[str, Any] = {"id": node_id}
+ for key, value in scalar_fields(node).items():
+ if key == "id":
+ continue
+ row[key] = value
+ rows.append(row)
+ return rows
+
+
+def _pairwise_edge_rows(
+ edges: Sequence[BaseModel],
+ incident_nodes_extractor: Callable[[Any], Sequence[str]],
+ by_id: dict[str, BaseModel],
+) -> tuple[list[dict[str, Any]], int]:
+ rows: list[dict[str, Any]] = []
+ skipped = 0
+ for edge in edges:
+ members = incident_ids(edge, incident_nodes_extractor)
+ if members is None or len(members) != 2:
+ skipped += 1
+ if members is not None and len(members) > 2:
+ logger.warning(
+ "export.csv: skipping non-pairwise edge members=%s "
+ "(pass hypergraph=True for N-ary edges)",
+ members,
+ )
+ continue
+ source, target = members[0], members[1]
+ if source not in by_id or target not in by_id:
+ skipped += 1
+ logger.warning(
+ "export.csv: skipping edge with missing endpoint source=%s target=%s",
+ source,
+ target,
+ )
+ continue
+ row: dict[str, Any] = {"source": source, "target": target}
+ for key, value in scalar_fields(edge).items():
+ if key in {"source", "target"}:
+ continue
+ row[key] = value
+ rows.append(row)
+ return rows, skipped
+
+
+def _hyperedge_rows(
+ edges: Sequence[BaseModel],
+ incident_nodes_extractor: Callable[[Any], Sequence[str]],
+ by_id: dict[str, BaseModel],
+ edge_id_extractor: Callable[[Any], str] | None,
+) -> tuple[list[dict[str, Any]], int]:
+ rows: list[dict[str, Any]] = []
+ skipped = 0
+ for index, edge in enumerate(edges):
+ members = incident_ids(edge, incident_nodes_extractor)
+ if members is None:
+ skipped += 1
+ continue
+ known = [mid for mid in members if mid in by_id]
+ missing = [mid for mid in members if mid not in by_id]
+ if missing:
+ skipped += 1
+ logger.warning(
+ "export.csv: skipping hyperedge with missing members %s",
+ missing,
+ )
+ continue
+ if not known:
+ skipped += 1
+ continue
+ edge_id = _edge_id(edge, index, edge_id_extractor)
+ # Sorted for stable output; binary CSV must not sort endpoints.
+ members_cell = HYPEREDGE_MEMBER_SEP.join(sorted(known))
+ row: dict[str, Any] = {"id": edge_id, "members": members_cell}
+ dumped = edge.model_dump()
+ for key, value in scalar_fields(edge).items():
+ if key in {"id", "members"}:
+ continue
+ # Membership lists are represented by the members column.
+ if isinstance(dumped.get(key), (list, tuple, set, dict)):
+ continue
+ row[key] = value
+ rows.append(row)
+ return rows, skipped
+
+
+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.csv: edge_id_extractor raised %s", exc)
+ return f"e{index}"
+ if value in (None, ""):
+ return f"e{index}"
+ return str(value)
+
+
+def _write_csv(path: Path, primary: Sequence[str], rows: list[dict[str, Any]]) -> None:
+ fieldnames = _fieldnames(primary, rows)
+ with path.open("w", encoding="utf-8", newline="") as handle:
+ writer = csv.DictWriter(
+ handle,
+ fieldnames=fieldnames,
+ quoting=csv.QUOTE_MINIMAL,
+ extrasaction="ignore",
+ )
+ writer.writeheader()
+ for row in rows:
+ writer.writerow({key: row.get(key, "") for key in fieldnames})
+
+
+def _fieldnames(primary: Sequence[str], rows: list[dict[str, Any]]) -> list[str]:
+ names = list(primary)
+ seen = set(primary)
+ for row in rows:
+ for key in row:
+ if key not in seen:
+ names.append(key)
+ seen.add(key)
+ return names
diff --git a/hyperextract/utils/exporters/graphml.py b/hyperextract/utils/exporters/graphml.py
new file mode 100644
index 0000000..1c6cdaa
--- /dev/null
+++ b/hyperextract/utils/exporters/graphml.py
@@ -0,0 +1,222 @@
+"""GraphML exporter for pairwise (binary) graphs.
+
+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.
+
+Endpoint order is preserved: ``source`` is the first incident node and
+``target`` is the second. Endpoints are never sorted.
+"""
+
+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 (
+ graphml_attr_type,
+ graphml_attr_value,
+ incident_ids,
+ merge_graphml_type,
+ resolve_nodes,
+ scalar_fields,
+ xml_escape,
+)
+
+logger = get_logger(__name__)
+
+GRAPHML_NS = "http://graphml.graphdrawing.org/xmlns"
+
+
+class GraphMLHypergraphError(ValueError):
+ """Raised when GraphML export is asked to encode an N-ary edge."""
+
+
+def export_to_graphml(
+ 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 pairwise graph to a GraphML file.
+
+ Args:
+ nodes: Node/entity models to export.
+ edges: Pairwise edge models to export.
+ 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`.
+ file_path: Destination ``.graphml`` file.
+ edge_id_extractor: Optional edge -> GraphML edge 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)
+ if dest.exists() and dest.is_dir():
+ raise IsADirectoryError(
+ f"Destination '{dest}' is a directory; pass a GraphML file path."
+ )
+ dest.parent.mkdir(parents=True, exist_ok=True)
+
+ by_id = resolve_nodes(nodes, node_id_extractor)
+
+ node_keys: dict[str, str] = {}
+ node_rows: list[tuple[str, dict[str, str | int | float | bool]]] = []
+ for node_id, node in by_id.items():
+ fields = scalar_fields(node)
+ for name, value in fields.items():
+ node_keys[name] = merge_graphml_type(
+ node_keys.get(name), graphml_attr_type(value)
+ )
+ node_rows.append((node_id, fields))
+
+ pairwise: list[tuple[str, str, str, dict[str, str | int | float | bool]]] = []
+ edge_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,
+ )
+ 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,
+ )
+ 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))
+
+ xml = _render_graphml(node_keys, edge_keys, node_rows, pairwise)
+ dest.write_text(xml, encoding="utf-8")
+
+ logger.info(
+ "graphml: exported nodes=%d edges=%d skipped_edges=%d path=%s",
+ len(node_rows),
+ len(pairwise),
+ skipped,
+ dest,
+ )
+ return dest
+
+
+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.graphml: edge_id_extractor raised %s", exc)
+ return f"e{index}"
+ if value in (None, ""):
+ return f"e{index}"
+ return str(value)
+
+
+def _key_id(prefix: str, name: str) -> str:
+ safe = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in name)
+ if not safe or safe[0].isdigit():
+ safe = f"_{safe}"
+ return f"{prefix}_{safe}"
+
+
+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]]],
+) -> str:
+ lines = [
+ '<?xml version="1.0" encoding="UTF-8"?>',
+ f'<graphml xmlns="{GRAPHML_NS}">',
+ ]
+ node_key_ids: dict[str, str] = {}
+ for name, attr_type in node_keys.items():
+ kid = _key_id("n", name)
+ node_key_ids[name] = kid
+ lines.append(
+ f' <key id="{xml_escape(kid)}" for="node" '
+ f'attr.name="{xml_escape(name)}" attr.type="{attr_type}"/>'
+ )
+ edge_key_ids: dict[str, str] = {}
+ for name, attr_type in edge_keys.items():
+ kid = _key_id("e", name)
+ edge_key_ids[name] = kid
+ lines.append(
+ f' <key id="{xml_escape(kid)}" for="edge" '
+ f'attr.name="{xml_escape(name)}" attr.type="{attr_type}"/>'
+ )
+
+ lines.append(' <graph id="G" edgedefault="directed">')
+ for node_id, fields in node_rows:
+ if fields:
+ lines.append(f' <node id="{xml_escape(node_id)}">')
+ for name, value in fields.items():
+ kid = node_key_ids[name]
+ lines.append(
+ f' <data key="{xml_escape(kid)}">'
+ f"{xml_escape(graphml_attr_value(value))}</data>"
+ )
+ lines.append(" </node>")
+ else:
+ lines.append(f' <node id="{xml_escape(node_id)}"/>')
+
+ for edge_id, source, target, fields in edges:
+ attrs = (
+ f'id="{xml_escape(edge_id)}" '
+ f'source="{xml_escape(source)}" '
+ f'target="{xml_escape(target)}"'
+ )
+ if fields:
+ lines.append(f" <edge {attrs}>")
+ for name, value in fields.items():
+ kid = edge_key_ids[name]
+ lines.append(
+ f' <data key="{xml_escape(kid)}">'
+ f"{xml_escape(graphml_attr_value(value))}</data>"
+ )
+ lines.append(" </edge>")
+ else:
+ lines.append(f" <edge {attrs}/>")
+
+ lines.append(" </graph>")
+ lines.append("</graphml>")
+ lines.append("")
+ return "\n".join(lines)
diff --git a/tests/utils/test_exporters.py b/tests/utils/test_exporters.py
new file mode 100644
index 0000000..499a256
--- /dev/null
+++ b/tests/utils/test_exporters.py
@@ -0,0 +1,470 @@
+"""Unit tests for GraphML and CSV exporters (hyperextract.utils.exporters).
+
+Pure-function tests use Pydantic fixtures and extractors — no LLM. CLI tests
+mock ``Template.create`` / ``load`` against a dumped KA directory.
+"""
+
+import csv
+import json
+import xml.etree.ElementTree as ET
+from typing import List, Optional
+from unittest.mock import patch
+
+import pytest
+from pydantic import BaseModel, Field
+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,
+)
+from hyperextract.utils.exporters.graphml import GRAPHML_NS
+
+runner = CliRunner()
+
+
+class Entity(BaseModel):
+ name: str
+ type: str = "ENTITY"
+ note: Optional[str] = None
+ score: Optional[int] = None
+ active: bool = True
+ properties: dict = Field(default_factory=dict)
+
+
+class Relation(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+ description: Optional[str] = None
+ weight: Optional[float] = None
+
+
+class Event(BaseModel):
+ label: str
+ participants: List[str]
+
+
+def _export_graphml(path, nodes, edges, **kwargs):
+ return export_to_graphml(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: (e.source, e.target),
+ file_path=path,
+ **kwargs,
+ )
+
+
+def _export_csv(folder, nodes, edges, **kwargs):
+ return export_to_csv(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: (e.source, e.target),
+ folder_path=folder,
+ **kwargs,
+ )
+
+
+def _parse_graphml(path):
+ tree = ET.parse(path)
+ root = tree.getroot()
+ ns = {"g": GRAPHML_NS}
+ graph = root.find("g:graph", ns)
+ if graph is None:
+ graph = root.find("graph")
+ return root, graph, ns
+
+
+def _edge_endpoints(graph, ns):
+ edges = graph.findall("g:edge", ns) or graph.findall("edge")
+ return [(e.get("source"), e.get("target")) for e in edges]
+
+
+def _node_data(root, graph, ns, node_id):
+ keys = {}
+ for key in root.findall("g:key", ns) or root.findall("key"):
+ if key.get("for") == "node":
+ keys[key.get("id")] = key.get("attr.name")
+ for node in graph.findall("g:node", ns) or graph.findall("node"):
+ if node.get("id") != node_id:
+ continue
+ data = {}
+ for data_el in node.findall("g:data", ns) or node.findall("data"):
+ name = keys.get(data_el.get("key"), data_el.get("key"))
+ data[name] = data_el.text
+ return data
+ return None
+
+
+# ---------------------------------------------------------------------------
+# GraphML — pairwise direction, attributes, escaping
+# ---------------------------------------------------------------------------
+
+
+class TestGraphMLPairwise:
+ def test_preserves_direction_b_to_a(self, tmp_path):
+ nodes = [Entity(name="A"), Entity(name="B")]
+ edges = [Relation(source="B", target="A", relation_type="leads_to")]
+ path = _export_graphml(tmp_path / "g.graphml", nodes, edges)
+
+ xml = path.read_text(encoding="utf-8")
+ assert 'edgedefault="directed"' in xml
+
+ _root, graph, ns = _parse_graphml(path)
+ endpoints = _edge_endpoints(graph, ns)
+ assert endpoints == [("B", "A")]
+ assert ("A", "B") not in endpoints
+
+ def test_custom_fields_appear_as_data_keys(self, tmp_path):
+ nodes = [
+ Entity(name="Apple", type="ORG", score=7, active=True),
+ Entity(name="Jobs", type="PERSON", note="founder"),
+ ]
+ edges = [
+ Relation(
+ source="Apple",
+ target="Jobs",
+ relation_type="founded_by",
+ weight=1.5,
+ )
+ ]
+ path = _export_graphml(tmp_path / "g.graphml", nodes, edges)
+ xml = path.read_text(encoding="utf-8")
+ assert 'attr.name="type"' in xml
+ assert 'attr.name="score"' in xml
+ assert 'attr.name="active"' in xml
+ assert 'attr.name="weight"' in xml
+ assert 'attr.name="relation_type"' in xml
+
+ root, graph, ns = _parse_graphml(path)
+ apple = _node_data(root, graph, ns, "Apple")
+ assert apple["type"] == "ORG"
+ assert apple["score"] == "7"
+ assert apple["active"] == "true"
+ jobs = _node_data(root, graph, ns, "Jobs")
+ assert jobs["note"] == "founder"
+
+ def test_xml_special_characters_escaped(self, tmp_path):
+ nasty = "A&B<C>\"'"
+ nodes = [Entity(name=nasty, note='x & y <z> "q" \''), Entity(name="Z")]
+ edges = [Relation(source=nasty, target="Z", relation_type="mentions")]
+ path = _export_graphml(tmp_path / "g.graphml", nodes, edges)
+ xml = path.read_text(encoding="utf-8")
+
+ assert "&amp;" in xml
+ assert "&lt;" in xml
+ assert "&gt;" in xml
+ assert "&quot;" in xml
+ assert "&apos;" in xml
+
+ ET.parse(path)
+ _root, graph, ns = _parse_graphml(path)
+ endpoints = _edge_endpoints(graph, ns)
+ assert endpoints == [(nasty, "Z")]
+
+ def test_missing_endpoint_is_skipped(self, tmp_path):
+ nodes = [Entity(name="Apple")]
+ edges = [Relation(source="Apple", target="Ghost", relation_type="x")]
+ path = _export_graphml(tmp_path / "g.graphml", nodes, edges)
+ _root, graph, ns = _parse_graphml(path)
+ assert _edge_endpoints(graph, ns) == []
+ node_ids = [
+ n.get("id") for n in (graph.findall("g:node", ns) or graph.findall("node"))
+ ]
+ assert node_ids == ["Apple"]
+
+ def test_nary_edge_raises(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",
+ )
+
+
+# ---------------------------------------------------------------------------
+# CSV — round-trip, quoting, direction, dangling, hypergraph
+# ---------------------------------------------------------------------------
+
+
+class TestCSVPairwise:
+ def test_round_trip_and_quoting(self, tmp_path):
+ nodes = [
+ Entity(name="Apple, Inc.", type="ORG", note='He said "hi"'),
+ Entity(name="Jobs", type="PERSON", note="line1\nline2"),
+ ]
+ edges = [
+ Relation(
+ source="Apple, Inc.",
+ target="Jobs",
+ relation_type="founded_by",
+ description="a, b",
+ )
+ ]
+ folder = _export_csv(tmp_path / "csv", nodes, edges)
+
+ with (folder / "nodes.csv").open(encoding="utf-8", newline="") as handle:
+ node_rows = list(csv.DictReader(handle))
+ with (folder / "edges.csv").open(encoding="utf-8", newline="") as handle:
+ edge_rows = list(csv.DictReader(handle))
+
+ assert [row["id"] for row in node_rows] == ["Apple, Inc.", "Jobs"]
+ assert node_rows[0]["name"] == "Apple, Inc."
+ assert node_rows[0]["note"] == 'He said "hi"'
+ assert node_rows[1]["note"] == "line1\nline2"
+
+ assert edge_rows[0]["source"] == "Apple, Inc."
+ assert edge_rows[0]["target"] == "Jobs"
+ assert edge_rows[0]["description"] == "a, b"
+ header = (folder / "nodes.csv").read_text(encoding="utf-8").splitlines()[0]
+ assert header.startswith("id,")
+
+ def test_preserves_direction_b_to_a(self, tmp_path):
+ nodes = [Entity(name="A"), Entity(name="B")]
+ edges = [Relation(source="B", target="A", relation_type="leads_to")]
+ folder = _export_csv(tmp_path / "csv", nodes, edges)
+ with (folder / "edges.csv").open(encoding="utf-8", newline="") as handle:
+ rows = list(csv.DictReader(handle))
+ assert rows[0]["source"] == "B"
+ assert rows[0]["target"] == "A"
+
+ def test_missing_endpoint_is_skipped(self, tmp_path):
+ nodes = [Entity(name="Apple")]
+ edges = [Relation(source="Apple", target="Ghost", relation_type="x")]
+ folder = _export_csv(tmp_path / "csv", nodes, edges)
+ with (folder / "edges.csv").open(encoding="utf-8", newline="") as handle:
+ rows = list(csv.DictReader(handle))
+ assert rows == []
+ with (folder / "nodes.csv").open(encoding="utf-8", newline="") as handle:
+ assert [r["id"] for r in csv.DictReader(handle)] == ["Apple"]
+
+ def test_raises_on_nonempty_dir(self, tmp_path):
+ dest = tmp_path / "csv"
+ dest.mkdir()
+ (dest / "keep.txt").write_text("keep", encoding="utf-8")
+ with pytest.raises(FileExistsError):
+ _export_csv(dest, [Entity(name="Apple")], [])
+
+ def test_overwrite_allows_nonempty_dir(self, tmp_path):
+ dest = tmp_path / "csv"
+ dest.mkdir()
+ (dest / "keep.txt").write_text("keep", encoding="utf-8")
+ _export_csv(dest, [Entity(name="Apple")], [], overwrite=True)
+ assert (dest / "nodes.csv").exists()
+ assert (dest / "keep.txt").exists()
+
+
+class TestCSVHypergraph:
+ def test_members_sorted_stable_delimiter(self, tmp_path):
+ nodes = [Entity(name="A"), Entity(name="B"), Entity(name="C")]
+ edges = [Event(label="meeting", participants=["C", "A", "B"])]
+ folder = export_to_csv(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: tuple(e.participants),
+ folder_path=tmp_path / "csv",
+ edge_id_extractor=lambda e: e.label,
+ hypergraph=True,
+ )
+ assert (folder / "hyperedges.csv").exists()
+ assert not (folder / "edges.csv").exists()
+ with (folder / "hyperedges.csv").open(encoding="utf-8", newline="") as handle:
+ rows = list(csv.DictReader(handle))
+ assert rows[0]["id"] == "meeting"
+ assert rows[0]["members"] == HYPEREDGE_MEMBER_SEP.join(["A", "B", "C"])
+ assert rows[0]["label"] == "meeting"
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+class FakeGraphKA:
+ def __init__(self, nodes, edges, hypergraph=False):
+ self.nodes = nodes
+ self.edges = edges
+ self.node_key_extractor = lambda n: n.name
+ if hypergraph:
+ self.nodes_in_edge_extractor = lambda e: tuple(e.participants)
+ self.edge_key_extractor = lambda e: e.label
+ self.metadata = {"type": "hypergraph"}
+ else:
+ self.nodes_in_edge_extractor = lambda e: (e.source, e.target)
+ self.edge_key_extractor = lambda e: (
+ f"{e.source}-{e.relation_type}-{e.target}"
+ )
+ self.metadata = {"type": "graph"}
+
+ def export_obsidian(self, *args, **kwargs):
+ return None
+
+ def load(self, path):
+ return None
+
+
+class FakeListKA:
+ def load(self, path):
+ return None
+
+
+def _ka_dir(tmp_path):
+ ka = tmp_path / "ka"
+ ka.mkdir()
+ (ka / "data.json").write_text(
+ json.dumps({"nodes": [], "edges": []}), encoding="utf-8"
+ )
+ (ka / "metadata.json").write_text(
+ json.dumps({"template": "general/biography_graph", "lang": "en"}),
+ encoding="utf-8",
+ )
+ return ka
+
+
+class TestCLIExport:
+ def test_graphml_writes_directed_edge(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ fake = FakeGraphKA(
+ [Entity(name="A"), Entity(name="B")],
+ [Relation(source="B", target="A", relation_type="leads_to")],
+ )
+ out = tmp_path / "out.graphml"
+ 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", "graphml", str(ka_dir), "-o", str(out)]
+ )
+ assert result.exit_code == 0, result.output
+ _root, graph, ns = _parse_graphml(out)
+ assert _edge_endpoints(graph, ns) == [("B", "A")]
+
+ def test_graphml_rejects_hypergraph(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ fake = FakeGraphKA(
+ [Entity(name="A"), Entity(name="B"), Entity(name="C")],
+ [Event(label="meeting", participants=["A", "B", "C"])],
+ hypergraph=True,
+ )
+ out = tmp_path / "out.graphml"
+ 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", "graphml", str(ka_dir), "-o", str(out)]
+ )
+ assert result.exit_code == 1
+ assert "csv" in result.output.lower()
+ assert not out.exists()
+
+ def test_csv_writes_tables(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ fake = FakeGraphKA(
+ [Entity(name="A"), Entity(name="B")],
+ [Relation(source="B", target="A", relation_type="leads_to")],
+ )
+ out = tmp_path / "csv_out"
+ 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", "csv", str(ka_dir), "-o", str(out)])
+ assert result.exit_code == 0, result.output
+ with (out / "edges.csv").open(encoding="utf-8", newline="") as handle:
+ rows = list(csv.DictReader(handle))
+ assert rows[0]["source"] == "B"
+ assert rows[0]["target"] == "A"
+
+ def test_csv_hypergraph_writes_hyperedges(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 / "csv_out"
+ 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", "csv", str(ka_dir), "-o", str(out)])
+ assert result.exit_code == 0, result.output
+ assert (out / "hyperedges.csv").exists()
+ assert not (out / "edges.csv").exists()
+
+ def test_csv_requires_force_for_nonempty_dir(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ dest = tmp_path / "csv_out"
+ dest.mkdir()
+ (dest / "existing.txt").write_text("x", 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", "csv", str(ka_dir), "-o", str(dest)])
+ assert result.exit_code == 1
+ assert "--force" in result.output or "not empty" in result.output
+
+ def test_csv_force_writes_nonempty_dir(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ dest = tmp_path / "csv_out"
+ dest.mkdir()
+ (dest / "existing.txt").write_text("x", 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", "csv", str(ka_dir), "-o", str(dest), "--force"]
+ )
+ assert result.exit_code == 0, result.output
+ assert (dest / "nodes.csv").exists()
+
+ def test_rejects_non_graph_ka(self, tmp_path):
+ ka_dir = _ka_dir(tmp_path)
+ fake = FakeListKA()
+ 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", "graphml", str(ka_dir), "-o", str(tmp_path / "g.graphml")],
+ )
+ assert result.exit_code == 1
+ assert "graph" in result.output.lower()