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.pyindex 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__.pynew file mode 100644index 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.pynew file mode 100644index 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 = (+ ("&", "&"),+ ("<", "<"),+ (">", ">"),+ ('"', """),+ ("'", "'"),+)+++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.pynew file mode 100644index 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 namesdiff --git a/hyperextract/utils/exporters/graphml.py b/hyperextract/utils/exporters/graphml.pynew file mode 100644index 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.pynew file mode 100644index 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 "&" in xml+ assert "<" in xml+ assert ">" in xml+ assert """ in xml+ assert "'" 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()