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 Obsidian vault export for knowledge graphs

Oguz Vuruskanera78df3af3ff5
diff --git a/README.md b/README.md
index f6a90ab..aca224d 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ Hyper-Extract is an intelligent, LLM-powered knowledge extraction and evolution
| 🧠 **10+ Extraction Engines** | GraphRAG, LightRAG, Hyper-RAG, KG-Gen, and more — ready to use |
| 📝 **80+ YAML Templates** | Zero-code extraction across Finance, Legal, Medical, TCM, Industry, and General domains |
| 🔄 **Incremental Evolution** | Feed new documents anytime to expand and refine your knowledge base |
+| 📤 **Obsidian Export** | Turn any extracted graph into an Obsidian vault — Markdown notes linked by `[[wikilinks]]` |
## 🎯 What Can You Do With It?
@@ -122,6 +123,9 @@ he search ./output/ "What are Tesla's major achievements?"
# Visualize
he show ./output/
+
+# Export to an Obsidian vault (Markdown notes + [[wikilinks]])
+he export ./output/ -o ./vault/
```
<details>
diff --git a/README_ZH.md b/README_ZH.md
index a08f684..9d86928 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -45,6 +45,7 @@ Hyper-Extract 是一个智能的、由大语言模型(LLM)驱动的知识提
| 🧠 **10+ 提取引擎** | GraphRAG、LightRAG、Hyper-RAG、KG-Gen 等开箱即用 |
| 📝 **80+ YAML 模板** | 零代码提取,覆盖金融、法律、医疗、中医、工业、通用 6 大领域 |
| 🔄 **增量演进** | 随时喂入新文档,自动扩展和精炼知识库 |
+| 📤 **Obsidian 导出** | 将提取的图谱导出为 Obsidian 知识库——以 `[[双向链接]]` 关联的 Markdown 笔记 |
## 🎯 它能做什么?
@@ -122,6 +123,9 @@ he search ./output/ "苏轼有哪些重要的作品?"
# 可视化
he show ./output/
+
+# 导出为 Obsidian 知识库(Markdown 笔记 + [[双向链接]])
+he export ./output/ -o ./vault/
```
<details>
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index fd68607..e460d7e 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -136,6 +136,7 @@ def main(
("he talk <ka_path> [-i]", "Chat with KA"),
("he search <ka_path> <query>", "Semantic search"),
("he show <ka_path>", "Visualize KA"),
+ ("he export <ka_path> -o <vault>", "Export to Obsidian vault"),
],
),
]
@@ -439,6 +440,88 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")
console.print(f"[dim] he talk {ka_path} -i # Interactive chat[/dim]")
[email protected](name="export")
+def export(
+ ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),
+ output: str = typer.Option(..., "--output", "-o", help="Output vault directory"),
+ fmt: str = typer.Option(
+ "obsidian", "--format", "-F", help="Export format (obsidian)"
+ ),
+ name: Optional[str] = typer.Option(
+ None, "--name", help="Vault name used for the index note"
+ ),
+ no_index: bool = typer.Option(
+ False, "--no-index", help="Skip writing the index/map-of-content note"
+ ),
+ force: bool = typer.Option(
+ False, "--force", "-f", help="Write into an existing, non-empty directory"
+ ),
+):
+ """Export a Knowledge Abstract to an Obsidian vault (Markdown + wikilinks)."""
+ logger.info("command=export ka_path=%s output=%s format=%s", ka_path, output, fmt)
+
+ if fmt != "obsidian":
+ console.print(
+ f"[red]Error:[/red] Unsupported format '{fmt}'. Supported: obsidian."
+ )
+ raise typer.Exit(1)
+
+ path = validate_ka_with_data(ka_path)
+ template, lang = get_template_from_ka(path)
+
+ output_path = Path(output)
+ if output_path.exists() and any(output_path.iterdir()) 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)
+
+ console.print(f"[blue]Knowledge Abstract:[/blue] {ka_path}")
+ console.print(f"[blue]Template:[/blue] {template}")
+ console.print(f"[blue]Output vault:[/blue] {output}")
+ console.print()
+
+ validate_config()
+
+ vault_name = name or output_path.name or "Knowledge Vault"
+
+ 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] Obsidian export is only supported for graph-type "
+ "Knowledge Abstracts (graph, hypergraph, temporal/spatial graphs)."
+ )
+ raise typer.Exit(1)
+
+ with console.status("[bold blue]Exporting to Obsidian vault..."):
+ try:
+ ka.export_obsidian(
+ output_path,
+ vault_name=vault_name,
+ include_index=not no_index,
+ overwrite=force,
+ )
+ except Exception as e:
+ console.print(f"[red]Error during export:[/red] {e}")
+ raise typer.Exit(1)
+
+ note_count = len(list(output_path.glob("*.md")))
+ console.print()
+ console.print(
+ f"[bold green]Success![/bold green] Exported {note_count} notes to {output_path}"
+ )
+ console.print()
+ console.print("[dim]Open the folder as a vault in Obsidian to explore it.[/dim]")
+
+
@app.command(name="info")
def info(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")):
"""View Knowledge Abstract information and statistics."""
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index aab2345..5e9c447 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -1045,3 +1045,55 @@ class AutoGraph(
on_search=search_callback,
on_chat=chat_callback,
)
+
+ # ==================== Obsidian Export ====================
+
+ def export_obsidian(
+ self,
+ folder_path: str | Path,
+ *,
+ node_label_extractor: Callable[[NodeSchema], str] = None,
+ edge_label_extractor: Callable[[EdgeSchema], str] = None,
+ vault_name: str = "Knowledge Vault",
+ include_index: bool = True,
+ overwrite: bool = False,
+ ) -> Path:
+ """Export the graph as an Obsidian vault.
+
+ Writes one Markdown note per node (fields stored as YAML front-matter)
+ and renders every edge as an internal ``[[wikilink]]`` under its source
+ note. The resulting folder can be opened directly in Obsidian, where the
+ graph view reflects the extracted knowledge structure.
+
+ Args:
+ folder_path: Destination vault directory.
+ node_label_extractor: Optional node -> display title. Defaults to the
+ one from ``__init__``, then common fields, then the node id.
+ edge_label_extractor: Optional edge -> relationship label. Defaults to
+ the one from ``__init__``, then common fields, then "related to".
+ vault_name: Title used for the generated index note.
+ include_index: Whether to write an index/map-of-content note.
+ overwrite: Allow writing into an existing, non-empty directory.
+
+ Returns:
+ The vault directory :class:`~pathlib.Path`.
+ """
+ from hyperextract.utils.obsidian import export_to_obsidian
+
+ if node_label_extractor is None:
+ node_label_extractor = self._node_label_extractor
+ if edge_label_extractor is None:
+ edge_label_extractor = self._edge_label_extractor
+
+ return export_to_obsidian(
+ nodes=self.nodes,
+ edges=self.edges,
+ node_id_extractor=self.node_key_extractor,
+ incident_nodes_extractor=self.nodes_in_edge_extractor,
+ folder_path=folder_path,
+ node_label_extractor=node_label_extractor,
+ edge_label_extractor=edge_label_extractor,
+ vault_name=vault_name,
+ include_index=include_index,
+ overwrite=overwrite,
+ )
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index 53dea78..1cc94f1 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -933,3 +933,55 @@ class AutoHypergraph(
on_search=search_callback,
on_chat=chat_callback,
)
+
+ # ==================== Obsidian Export ====================
+
+ def export_obsidian(
+ self,
+ folder_path: str | Path,
+ *,
+ node_label_extractor: Callable[[NodeSchema], str] = None,
+ edge_label_extractor: Callable[[EdgeSchema], str] = None,
+ vault_name: str = "Knowledge Vault",
+ include_index: bool = True,
+ overwrite: bool = False,
+ ) -> Path:
+ """Export the hypergraph as an Obsidian vault.
+
+ Writes one Markdown note per node (fields stored as YAML front-matter).
+ Each N-ary hyperedge is rendered under its first incident node, linking
+ out to the remaining members via ``[[wikilinks]]``, so the relationship
+ is browsable in Obsidian's graph view.
+
+ Args:
+ folder_path: Destination vault directory.
+ node_label_extractor: Optional node -> display title. Defaults to the
+ one from ``__init__``, then common fields, then the node id.
+ edge_label_extractor: Optional edge -> relationship label. Defaults to
+ the one from ``__init__``, then common fields, then "related to".
+ vault_name: Title used for the generated index note.
+ include_index: Whether to write an index/map-of-content note.
+ overwrite: Allow writing into an existing, non-empty directory.
+
+ Returns:
+ The vault directory :class:`~pathlib.Path`.
+ """
+ from hyperextract.utils.obsidian import export_to_obsidian
+
+ if node_label_extractor is None:
+ node_label_extractor = self._node_label_extractor
+ if edge_label_extractor is None:
+ edge_label_extractor = self._edge_label_extractor
+
+ return export_to_obsidian(
+ nodes=self.nodes,
+ edges=self.edges,
+ node_id_extractor=self.node_key_extractor,
+ incident_nodes_extractor=self.nodes_in_edge_extractor,
+ folder_path=folder_path,
+ node_label_extractor=node_label_extractor,
+ edge_label_extractor=edge_label_extractor,
+ vault_name=vault_name,
+ include_index=include_index,
+ overwrite=overwrite,
+ )
diff --git a/hyperextract/utils/__init__.py b/hyperextract/utils/__init__.py
index 6516179..f6a1b54 100644
--- a/hyperextract/utils/__init__.py
+++ b/hyperextract/utils/__init__.py
@@ -2,10 +2,13 @@
from .logging import get_logger, configure_logging, set_log_level
from .client import get_client
+from .obsidian import export_to_obsidian, sanitize_filename
__all__ = [
"get_logger",
"configure_logging",
"set_log_level",
"get_client",
+ "export_to_obsidian",
+ "sanitize_filename",
]
diff --git a/hyperextract/utils/obsidian.py b/hyperextract/utils/obsidian.py
new file mode 100644
index 0000000..805cf4e
--- /dev/null
+++ b/hyperextract/utils/obsidian.py
@@ -0,0 +1,457 @@
+"""Obsidian vault exporter.
+
+Converts an extracted Knowledge Abstract into an `Obsidian
+<https://obsidian.md>`_ vault: a folder of Markdown notes where each node
+becomes a note and each edge becomes an internal ``[[wikilink]]``. Opening the
+resulting folder as a vault in Obsidian renders the extracted knowledge in its
+interactive graph view, fully browsable and editable.
+
+The core :func:`export_to_obsidian` function is decoupled from the AutoType
+classes (mirroring how :mod:`ontosight` powers ``AutoGraph.show``). It works on
+plain lists of Pydantic node/edge models plus a few extractor callables, so it
+supports the entire graph family (``AutoGraph`` and its temporal/spatial
+subclasses) as well as ``AutoHypergraph`` (N-ary edges).
+
+Only the Python standard library is used; no extra dependency is introduced.
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+from pydantic import BaseModel
+
+from hyperextract.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+# Characters Obsidian/most filesystems disallow (or treat specially) in note
+# file names. ``[`` / ``]`` / ``#`` / ``^`` / ``|`` break wikilink parsing.
+_ILLEGAL_FILENAME_CHARS = re.compile(r'[\\/:*?"<>|\[\]#^]')
+_WHITESPACE = re.compile(r"\s+")
+
+# Conservative "safe to emit unquoted" YAML plain-scalar charset.
+_SAFE_PLAIN = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9 _./()\-]*$")
+_NUMERIC = re.compile(r"^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$")
+_YAML_RESERVED = {"", "~", "true", "false", "yes", "no", "on", "off", "null", "none"}
+
+# Field names checked (in order) when guessing a node title / type, or an edge
+# label / description, for models with arbitrary schemas.
+_TITLE_FIELDS = ("name", "title", "label", "term", "id")
+_TYPE_FIELDS = ("type", "category", "kind", "group", "label")
+_EDGE_LABEL_FIELDS = ("relation_type", "type", "label", "name", "relation", "predicate")
+_DESCRIPTION_FIELDS = ("description", "desc", "summary", "detail", "details", "note")
+
+
+# ----------------------------------------------------------------------------
+# YAML front-matter emission (minimal, dependency-free)
+# ----------------------------------------------------------------------------
+
+
+def _needs_quote(text: str) -> bool:
+ """Return True if a string must be quoted to be a valid YAML plain scalar."""
+ if text.strip() != text: # leading/trailing whitespace
+ return True
+ if text.lower() in _YAML_RESERVED:
+ return True
+ if _NUMERIC.match(text):
+ return True
+ return not _SAFE_PLAIN.match(text)
+
+
+def _yaml_scalar(value: Any) -> str:
+ """Serialize a scalar value to a YAML representation."""
+ if value is None:
+ return "null"
+ if isinstance(value, bool):
+ return "true" if value else "false"
+ if isinstance(value, int):
+ return str(value)
+ if isinstance(value, float):
+ return repr(value)
+ text = str(value)
+ if _needs_quote(text):
+ # A JSON-encoded string is also a valid YAML double-quoted scalar and
+ # handles all escaping (quotes, newlines, unicode) for us.
+ return json.dumps(text, ensure_ascii=False)
+ return text
+
+
+def _is_scalar(value: Any) -> bool:
+ return not isinstance(value, (dict, list, tuple))
+
+
+def _emit_kv(key: str, value: Any, indent: int) -> List[str]:
+ """Emit ``key: value`` as YAML block-style lines."""
+ pad = " " * indent
+ key_str = _yaml_scalar(key)
+
+ if isinstance(value, dict):
+ if not value:
+ return [f"{pad}{key_str}: {{}}"]
+ lines = [f"{pad}{key_str}:"]
+ for sub_key, sub_value in value.items():
+ lines.extend(_emit_kv(str(sub_key), sub_value, indent + 1))
+ return lines
+
+ if isinstance(value, (list, tuple)):
+ if not value:
+ return [f"{pad}{key_str}: []"]
+ if all(_is_scalar(item) for item in value):
+ lines = [f"{pad}{key_str}:"]
+ item_pad = " " * (indent + 1)
+ lines.extend(f"{item_pad}- {_yaml_scalar(item)}" for item in value)
+ return lines
+ # Mixed/nested list: fall back to a JSON flow sequence (valid YAML).
+ return [
+ f"{pad}{key_str}: {json.dumps(list(value), ensure_ascii=False, default=str)}"
+ ]
+
+ return [f"{pad}{key_str}: {_yaml_scalar(value)}"]
+
+
+def _render_frontmatter(mapping: Dict[str, Any]) -> str:
+ """Render a mapping as a YAML front-matter block (with ``---`` fences)."""
+ lines = ["---"]
+ for key, value in mapping.items():
+ lines.extend(_emit_kv(str(key), value, 0))
+ lines.append("---")
+ return "\n".join(lines)
+
+
+# ----------------------------------------------------------------------------
+# Field / filename helpers
+# ----------------------------------------------------------------------------
+
+
+def _first_field(model: BaseModel, candidates: Sequence[str]) -> Optional[str]:
+ """Return the first present, non-empty candidate field as a string."""
+ model_fields = type(model).model_fields
+ for field in candidates:
+ if field in model_fields:
+ value = getattr(model, field, None)
+ if value not in (None, "", [], {}):
+ return str(value)
+ return None
+
+
+def _safe_call(func: Optional[Callable], arg: Any) -> Optional[str]:
+ """Call ``func(arg)`` defensively, returning a string or None."""
+ if func is None:
+ return None
+ try:
+ result = func(arg)
+ except Exception as exc: # noqa: BLE001 - extractor is user-supplied
+ logger.debug("obsidian: extractor raised %s", exc)
+ return None
+ if result in (None, ""):
+ return None
+ return str(result)
+
+
+def sanitize_filename(name: str, fallback: str = "untitled") -> str:
+ """Turn an arbitrary title into an Obsidian-safe note filename stem."""
+ cleaned = _ILLEGAL_FILENAME_CHARS.sub(" ", str(name))
+ cleaned = _WHITESPACE.sub(" ", cleaned).strip()
+ cleaned = cleaned.strip(".") # trailing dots are problematic on Windows
+ if not cleaned:
+ return fallback
+ # Keep note names reasonable for the filesystem.
+ return cleaned[:120].strip()
+
+
+def _wikilink(stem: str, display: Optional[str] = None) -> str:
+ """Build an Obsidian wikilink targeting ``stem`` with optional display text."""
+ if display and display != stem:
+ return f"[[{stem}|{display}]]"
+ return f"[[{stem}]]"
+
+
+# ----------------------------------------------------------------------------
+# Internal node bookkeeping
+# ----------------------------------------------------------------------------
+
+
+class _NoteEntry:
+ """Resolved metadata for a single node note."""
+
+ __slots__ = ("node_id", "title", "stem", "model")
+
+ def __init__(self, node_id: str, title: str, stem: str, model: BaseModel):
+ self.node_id = node_id
+ self.title = title
+ self.stem = stem
+ self.model = model
+
+
+def _resolve_notes(
+ nodes: Sequence[BaseModel],
+ node_id_extractor: Callable[[Any], str],
+ node_label_extractor: Optional[Callable[[Any], str]],
+ reserved_stems: set,
+) -> Tuple[List[_NoteEntry], Dict[str, _NoteEntry]]:
+ """Resolve titles and unique, collision-free filename stems for all nodes."""
+ used_stems = set(reserved_stems)
+ entries: List[_NoteEntry] = []
+ by_id: Dict[str, _NoteEntry] = {}
+
+ for index, node in enumerate(nodes):
+ try:
+ node_id = str(node_id_extractor(node))
+ except Exception as exc: # noqa: BLE001
+ logger.debug("obsidian: node_id_extractor raised %s; skipping node", exc)
+ continue
+
+ if node_id in by_id:
+ # Defensive: ids should already be deduplicated upstream.
+ logger.debug("obsidian: duplicate node id %r; keeping first", node_id)
+ continue
+
+ title = (
+ _safe_call(node_label_extractor, node)
+ or _first_field(node, _TITLE_FIELDS)
+ or node_id
+ )
+
+ base_stem = sanitize_filename(title, fallback=f"node-{index}")
+ stem = base_stem
+ suffix = 2
+ while stem.lower() in used_stems:
+ stem = f"{base_stem} ({suffix})"
+ suffix += 1
+ used_stems.add(stem.lower())
+
+ entry = _NoteEntry(node_id=node_id, title=title, stem=stem, model=node)
+ entries.append(entry)
+ by_id[node_id] = entry
+
+ return entries, by_id
+
+
+def _incident_ids(
+ edge: Any, incident_nodes_extractor: Callable[[Any], Sequence[str]]
+) -> List[str]:
+ """Normalize an edge's incident node keys to a list of strings."""
+ try:
+ raw = incident_nodes_extractor(edge)
+ except Exception as exc: # noqa: BLE001
+ logger.debug("obsidian: incident_nodes_extractor raised %s; skipping edge", exc)
+ return []
+ 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)]
+
+
+def _build_relationships(
+ edges: Sequence[BaseModel],
+ incident_nodes_extractor: Callable[[Any], Sequence[str]],
+ edge_label_extractor: Optional[Callable[[Any], str]],
+ by_id: Dict[str, _NoteEntry],
+) -> Tuple[Dict[str, List[str]], int]:
+ """Group edges into per-source-note relationship lines.
+
+ Returns a mapping ``{source_node_id: [markdown bullet, ...]}`` and the count
+ of edges that were skipped because no incident node was known.
+ """
+ relationships: Dict[str, List[str]] = {}
+ skipped = 0
+
+ for edge in edges:
+ members = [
+ nid for nid in _incident_ids(edge, incident_nodes_extractor) if nid in by_id
+ ]
+ if not members:
+ skipped += 1
+ continue
+
+ source_id = members[0]
+ target_ids = members[1:]
+
+ label = (
+ _safe_call(edge_label_extractor, edge)
+ or _first_field(edge, _EDGE_LABEL_FIELDS)
+ or "related to"
+ )
+ description = _first_field(edge, _DESCRIPTION_FIELDS)
+
+ if target_ids:
+ targets = ", ".join(
+ _wikilink(by_id[tid].stem, by_id[tid].title) for tid in target_ids
+ )
+ line = f"- **{label}** → {targets}"
+ else:
+ # Self-contained edge (e.g. a single-member hyperedge): note it.
+ line = f"- **{label}** (self)"
+
+ if description:
+ line += f" — {description}"
+
+ relationships.setdefault(source_id, []).append(line)
+
+ return relationships, skipped
+
+
+# ----------------------------------------------------------------------------
+# Note rendering
+# ----------------------------------------------------------------------------
+
+
+def _build_frontmatter(entry: _NoteEntry) -> Dict[str, Any]:
+ """Build the YAML front-matter mapping for a node note."""
+ data: Dict[str, Any] = dict(entry.model.model_dump())
+
+ # Ensure the original id / title remain resolvable as aliases, so wikilinks
+ # written against either still point at this note.
+ extra_aliases = [
+ value for value in (entry.node_id, entry.title) if value and value != entry.stem
+ ]
+ if extra_aliases:
+ existing = data.get("aliases")
+ if isinstance(existing, list):
+ merged = list(existing)
+ elif existing:
+ merged = [existing]
+ else:
+ merged = []
+ for alias in extra_aliases:
+ if alias not in merged:
+ merged.append(alias)
+ data["aliases"] = merged
+
+ return data
+
+
+def _render_note(entry: _NoteEntry, relationship_lines: List[str]) -> str:
+ """Render a single node note's full Markdown content."""
+ parts = [_render_frontmatter(_build_frontmatter(entry)), "", f"# {entry.title}", ""]
+
+ description = _first_field(entry.model, _DESCRIPTION_FIELDS)
+ if description:
+ parts.extend([description, ""])
+
+ if relationship_lines:
+ parts.append("## Relationships")
+ parts.append("")
+ parts.extend(relationship_lines)
+ parts.append("")
+
+ return "\n".join(parts).rstrip() + "\n"
+
+
+def _render_index(entries: List[_NoteEntry], vault_name: str, edge_count: int) -> str:
+ """Render the vault index / map-of-content note."""
+ parts = [
+ _render_frontmatter({"tags": ["index"], "title": vault_name}),
+ "",
+ f"# {vault_name}",
+ "",
+ f"> {len(entries)} notes · {edge_count} relationships",
+ "",
+ ]
+
+ # Group notes by a guessed "type" field for a tidy table of contents.
+ groups: Dict[str, List[_NoteEntry]] = {}
+ for entry in entries:
+ group = _first_field(entry.model, _TYPE_FIELDS) or "Notes"
+ groups.setdefault(group, []).append(entry)
+
+ for group in sorted(groups):
+ parts.append(f"## {group}")
+ parts.append("")
+ for entry in sorted(groups[group], key=lambda e: e.title.lower()):
+ parts.append(f"- {_wikilink(entry.stem, entry.title)}")
+ parts.append("")
+
+ return "\n".join(parts).rstrip() + "\n"
+
+
+# ----------------------------------------------------------------------------
+# Public API
+# ----------------------------------------------------------------------------
+
+
+def export_to_obsidian(
+ nodes: Sequence[BaseModel],
+ edges: Sequence[BaseModel],
+ *,
+ node_id_extractor: Callable[[Any], str],
+ incident_nodes_extractor: Callable[[Any], Sequence[str]],
+ folder_path: str | Path,
+ node_label_extractor: Optional[Callable[[Any], str]] = None,
+ edge_label_extractor: Optional[Callable[[Any], str]] = None,
+ vault_name: str = "Knowledge Vault",
+ include_index: bool = True,
+ overwrite: bool = False,
+) -> Path:
+ """Export graph-structured knowledge to an Obsidian vault.
+
+ Each node is written as a Markdown note whose YAML front-matter holds the
+ node's fields; each edge is rendered under its source note as a
+ ``[[wikilink]]`` to the target note(s). For N-ary (hyper)edges the first
+ incident node is treated as the source and the rest as targets.
+
+ Args:
+ nodes: Node/entity models to export.
+ edges: Edge/relationship models to export.
+ node_id_extractor: Maps a node to its unique key (matches edge endpoints).
+ incident_nodes_extractor: Maps an edge to the node keys it connects
+ (a 2-tuple for pairwise graphs, an N-tuple for hypergraphs).
+ folder_path: Destination vault directory.
+ node_label_extractor: Optional node -> display title. Falls back to common
+ fields (name/title/...) then the node id.
+ edge_label_extractor: Optional edge -> relationship label. Falls back to
+ common fields (relation_type/type/...) then "related to".
+ vault_name: Title used for the generated index note.
+ include_index: Whether to write an index/map-of-content note.
+ overwrite: Allow writing into an existing, non-empty directory.
+
+ Returns:
+ The vault directory :class:`~pathlib.Path`.
+
+ Raises:
+ FileExistsError: If ``folder_path`` exists, is non-empty and ``overwrite``
+ is False.
+ """
+ root = Path(folder_path)
+ 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)
+
+ reserved_stems: set = set()
+ index_stem = None
+ if include_index:
+ index_stem = sanitize_filename(vault_name, fallback="Index")
+ reserved_stems.add(index_stem.lower())
+
+ entries, by_id = _resolve_notes(
+ nodes, node_id_extractor, node_label_extractor, reserved_stems
+ )
+ relationships, skipped_edges = _build_relationships(
+ edges, incident_nodes_extractor, edge_label_extractor, by_id
+ )
+
+ for entry in entries:
+ content = _render_note(entry, relationships.get(entry.node_id, []))
+ (root / f"{entry.stem}.md").write_text(content, encoding="utf-8")
+
+ if include_index and index_stem is not None:
+ index_content = _render_index(entries, vault_name, len(edges))
+ (root / f"{index_stem}.md").write_text(index_content, encoding="utf-8")
+
+ logger.info(
+ "obsidian: exported vault notes=%d edges=%d skipped_edges=%d path=%s",
+ len(entries),
+ len(edges),
+ skipped_edges,
+ root,
+ )
+ return root
diff --git a/tests/types/test_obsidian_export.py b/tests/types/test_obsidian_export.py
new file mode 100644
index 0000000..ac75977
--- /dev/null
+++ b/tests/types/test_obsidian_export.py
@@ -0,0 +1,91 @@
+"""Tests for the export_obsidian() methods on graph AutoTypes.
+
+Graphs are populated directly via the OMem stores (no LLM calls needed), so
+these run deterministically under the mock fixtures.
+"""
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+from hyperextract.types import AutoGraph, AutoHypergraph, AutoTemporalGraph
+
+
+class Entity(BaseModel):
+ name: str
+ type: str = "ENTITY"
+
+
+class Relation(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+
+
+class Event(BaseModel):
+ label: str
+ participants: List[str] = Field(default_factory=list)
+
+
+def _make_graph(llm_client, embedder):
+ return AutoGraph(
+ node_schema=Entity,
+ edge_schema=Relation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.source}-{x.relation_type}-{x.target}",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+
+class TestAutoGraphExportObsidian:
+ def test_export_creates_vault(self, tmp_path, llm_client, embedder):
+ graph = _make_graph(llm_client, embedder)
+ graph._node_memory.add(
+ [Entity(name="Apple", type="ORG"), Entity(name="Steve Jobs", type="PERSON")]
+ )
+ graph._edge_memory.add(
+ [Relation(source="Apple", target="Steve Jobs", relation_type="founded_by")]
+ )
+
+ vault = graph.export_obsidian(tmp_path / "vault", vault_name="MyKB")
+
+ assert vault == tmp_path / "vault"
+ assert (vault / "Apple.md").exists()
+ assert (vault / "Steve Jobs.md").exists()
+ assert (vault / "MyKB.md").exists()
+ assert "[[Steve Jobs]]" in (vault / "Apple.md").read_text(encoding="utf-8")
+
+ def test_empty_graph_exports_index_only(self, tmp_path, llm_client, embedder):
+ graph = _make_graph(llm_client, embedder)
+ vault = graph.export_obsidian(tmp_path / "vault", vault_name="Empty")
+ assert (vault / "Empty.md").exists()
+ assert len(list(vault.glob("*.md"))) == 1
+
+ def test_temporal_graph_inherits_method(self, llm_client, embedder):
+ # AutoTemporalGraph subclasses AutoGraph, so it inherits export_obsidian.
+ assert hasattr(AutoTemporalGraph, "export_obsidian")
+
+
+class TestAutoHypergraphExportObsidian:
+ def test_export_nary_edge(self, tmp_path, llm_client, embedder):
+ hg = AutoHypergraph(
+ node_schema=Entity,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.label}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ edge_label_extractor=lambda x: x.label,
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+ hg._node_memory.add([Entity(name="A"), Entity(name="B"), Entity(name="C")])
+ hg._edge_memory.add([Event(label="meeting", participants=["A", "B", "C"])])
+
+ vault = hg.export_obsidian(tmp_path / "vault")
+
+ source = (vault / "A.md").read_text(encoding="utf-8")
+ assert "meeting" in source
+ assert "[[B]]" in source
+ assert "[[C]]" in source
diff --git a/tests/utils/test_obsidian.py b/tests/utils/test_obsidian.py
new file mode 100644
index 0000000..e24f0d1
--- /dev/null
+++ b/tests/utils/test_obsidian.py
@@ -0,0 +1,305 @@
+"""Unit tests for the Obsidian vault exporter (hyperextract.utils.obsidian).
+
+These tests exercise the exporter directly with plain Pydantic models and
+lambda extractors — no LLM/embedder is involved, so they are fast and fully
+deterministic.
+"""
+
+from typing import List, Optional
+
+import pytest
+from pydantic import BaseModel, Field
+
+from hyperextract.utils.obsidian import (
+ export_to_obsidian,
+ sanitize_filename,
+ _render_frontmatter,
+)
+
+
+# ---------------------------------------------------------------------------
+# Schemas + helpers
+# ---------------------------------------------------------------------------
+
+
+class Entity(BaseModel):
+ name: str
+ type: str = "ENTITY"
+ description: Optional[str] = None
+ properties: dict = Field(default_factory=dict)
+
+
+class Relation(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+ description: Optional[str] = None
+
+
+class Event(BaseModel):
+ """N-ary hyperedge schema."""
+
+ label: str
+ participants: List[str]
+
+
+def export_graph(folder, nodes, edges, **kwargs):
+ return export_to_obsidian(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: (e.source, e.target),
+ folder_path=folder,
+ **kwargs,
+ )
+
+
+# ---------------------------------------------------------------------------
+# sanitize_filename
+# ---------------------------------------------------------------------------
+
+
+class TestSanitizeFilename:
+ def test_keeps_plain_names(self):
+ assert sanitize_filename("Steve Jobs") == "Steve Jobs"
+
+ def test_replaces_illegal_chars(self):
+ result = sanitize_filename('A/B:C*?"<>|[]#^')
+ for bad in '\\/:*?"<>|[]#^':
+ assert bad not in result
+
+ def test_collapses_whitespace(self):
+ assert sanitize_filename("a b\tc") == "a b c"
+
+ def test_empty_uses_fallback(self):
+ assert sanitize_filename("///", fallback="x") == "x"
+ assert sanitize_filename("", fallback="x") == "x"
+
+ def test_strips_trailing_dots(self):
+ assert sanitize_filename("name...") == "name"
+
+ def test_truncates_long_names(self):
+ assert len(sanitize_filename("z" * 500)) <= 120
+
+
+# ---------------------------------------------------------------------------
+# Front-matter rendering
+# ---------------------------------------------------------------------------
+
+
+class TestFrontmatter:
+ def test_has_fences(self):
+ out = _render_frontmatter({"name": "Apple"})
+ assert out.startswith("---\n")
+ assert out.endswith("\n---")
+
+ def test_yaml_roundtrip_preserves_structure(self):
+ yaml = pytest.importorskip("yaml")
+ data = {
+ "name": "Apple: the fruit", # colon -> must be quoted
+ "count": 3,
+ "ratio": 1.5,
+ "active": True,
+ "missing": None,
+ "tags": ["a", "b c", "needs: quote"],
+ "nested": {"founded": 1976, "ceo": "Tim Cook"},
+ "mixed": [{"k": 1}, "v"],
+ "unicode": "苹果",
+ }
+ rendered = _render_frontmatter(data)
+ body = rendered.strip().strip("-").strip()
+ loaded = yaml.safe_load(body)
+ assert loaded == data
+
+ def test_reserved_words_quoted(self):
+ yaml = pytest.importorskip("yaml")
+ data = {"a": "yes", "b": "null", "c": "true"}
+ loaded = yaml.safe_load(_render_frontmatter(data).strip().strip("-").strip())
+ # Without quoting these would parse as bool/None instead of strings.
+ assert loaded == data
+
+
+# ---------------------------------------------------------------------------
+# export_to_obsidian — structure
+# ---------------------------------------------------------------------------
+
+
+class TestExportStructure:
+ def test_creates_note_per_node_plus_index(self, tmp_path):
+ nodes = [
+ Entity(name="Apple", type="ORG"),
+ Entity(name="Steve Jobs", type="PERSON"),
+ ]
+ edges = [
+ Relation(source="Apple", target="Steve Jobs", relation_type="founded_by")
+ ]
+
+ export_graph(tmp_path / "vault", nodes, edges, vault_name="TestVault")
+
+ vault = tmp_path / "vault"
+ assert (vault / "Apple.md").exists()
+ assert (vault / "Steve Jobs.md").exists()
+ assert (vault / "TestVault.md").exists() # index
+ assert len(list(vault.glob("*.md"))) == 3
+
+ def test_note_has_frontmatter_and_heading(self, tmp_path):
+ export_graph(tmp_path / "v", [Entity(name="Apple", type="ORG")], [])
+ content = (tmp_path / "v" / "Apple.md").read_text(encoding="utf-8")
+ assert content.startswith("---\n")
+ assert "name: Apple" in content
+ assert "type: ORG" in content
+ assert "# Apple" in content
+
+ def test_description_rendered_in_body(self, tmp_path):
+ node = Entity(name="Apple", description="A tech company.")
+ export_graph(tmp_path / "v", [node], [])
+ content = (tmp_path / "v" / "Apple.md").read_text(encoding="utf-8")
+ assert "A tech company." in content
+
+ def test_no_index_when_disabled(self, tmp_path):
+ export_graph(
+ tmp_path / "v",
+ [Entity(name="Apple")],
+ [],
+ vault_name="TestVault",
+ include_index=False,
+ )
+ assert not (tmp_path / "v" / "TestVault.md").exists()
+ assert (tmp_path / "v" / "Apple.md").exists()
+
+
+# ---------------------------------------------------------------------------
+# export_to_obsidian — edges / wikilinks
+# ---------------------------------------------------------------------------
+
+
+class TestExportEdges:
+ def test_edge_renders_wikilink_under_source(self, tmp_path):
+ nodes = [Entity(name="Apple"), Entity(name="Steve Jobs")]
+ edges = [
+ Relation(
+ source="Apple",
+ target="Steve Jobs",
+ relation_type="founded_by",
+ description="in 1976",
+ )
+ ]
+ export_graph(tmp_path / "v", nodes, edges)
+
+ source = (tmp_path / "v" / "Apple.md").read_text(encoding="utf-8")
+ assert "## Relationships" in source
+ assert "[[Steve Jobs]]" in source
+ assert "founded_by" in source
+ assert "in 1976" in source
+
+ def test_unknown_endpoints_are_skipped(self, tmp_path):
+ nodes = [Entity(name="Apple")]
+ edges = [Relation(source="Apple", target="Ghost", relation_type="x")]
+ # Should not raise; Apple note has no resolvable relationship target.
+ export_graph(tmp_path / "v", nodes, edges)
+ source = (tmp_path / "v" / "Apple.md").read_text(encoding="utf-8")
+ assert "[[Ghost]]" not in source
+
+ def test_custom_edge_label_extractor(self, tmp_path):
+ nodes = [Entity(name="A"), Entity(name="B")]
+ edges = [Relation(source="A", target="B", relation_type="r")]
+ export_to_obsidian(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: (e.source, e.target),
+ folder_path=tmp_path / "v",
+ edge_label_extractor=lambda e: "LINKS-TO",
+ )
+ assert "LINKS-TO" in (tmp_path / "v" / "A.md").read_text(encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# export_to_obsidian — naming / aliases / collisions
+# ---------------------------------------------------------------------------
+
+
+class TestExportNaming:
+ def test_illegal_chars_in_node_name(self, tmp_path):
+ nodes = [Entity(name="A/B:C")]
+ export_graph(tmp_path / "v", nodes, [])
+ files = list((tmp_path / "v").glob("*.md"))
+ node_files = [f for f in files if f.stem != "Knowledge Vault"]
+ assert len(node_files) == 1
+ for bad in '\\/:*?"<>|':
+ assert bad not in node_files[0].name
+
+ def test_label_extractor_adds_alias_for_id(self, tmp_path):
+ nodes = [Entity(name="apple_inc")]
+ export_to_obsidian(
+ nodes,
+ [],
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: (e.source, e.target),
+ folder_path=tmp_path / "v",
+ node_label_extractor=lambda n: "Apple Inc",
+ )
+ content = (tmp_path / "v" / "Apple Inc.md").read_text(encoding="utf-8")
+ assert "aliases:" in content
+ assert "apple_inc" in content
+
+ def test_colliding_titles_get_unique_files(self, tmp_path):
+ # Two distinct ids whose titles sanitize to the same stem.
+ nodes = [Entity(name="A:B"), Entity(name="A/B")]
+ export_graph(tmp_path / "v", nodes, [], include_index=False)
+ node_files = sorted(f.name for f in (tmp_path / "v").glob("*.md"))
+ assert len(node_files) == 2
+ assert node_files[0] != node_files[1]
+
+ def test_wikilink_uses_sanitized_stem(self, tmp_path):
+ nodes = [Entity(name="Apple"), Entity(name="Steve/Jobs")]
+ edges = [Relation(source="Apple", target="Steve/Jobs", relation_type="x")]
+ export_graph(tmp_path / "v", nodes, edges)
+ source = (tmp_path / "v" / "Apple.md").read_text(encoding="utf-8")
+ # Link target is the sanitized stem; display keeps original via alias pipe.
+ assert "[[Steve Jobs|Steve/Jobs]]" in source
+
+
+# ---------------------------------------------------------------------------
+# export_to_obsidian — overwrite guard
+# ---------------------------------------------------------------------------
+
+
+class TestOverwriteGuard:
+ def test_raises_on_nonempty_dir(self, tmp_path):
+ dest = tmp_path / "v"
+ dest.mkdir()
+ (dest / "existing.md").write_text("keep me", encoding="utf-8")
+ with pytest.raises(FileExistsError):
+ export_graph(dest, [Entity(name="Apple")], [])
+
+ def test_overwrite_allows_nonempty_dir(self, tmp_path):
+ dest = tmp_path / "v"
+ dest.mkdir()
+ (dest / "existing.md").write_text("keep me", encoding="utf-8")
+ export_graph(dest, [Entity(name="Apple")], [], overwrite=True)
+ assert (dest / "Apple.md").exists()
+
+
+# ---------------------------------------------------------------------------
+# export_to_obsidian — hypergraph (N-ary edges)
+# ---------------------------------------------------------------------------
+
+
+class TestHypergraphExport:
+ def test_nary_edge_links_all_members(self, tmp_path):
+ nodes = [Entity(name="A"), Entity(name="B"), Entity(name="C")]
+ edges = [Event(label="meeting", participants=["A", "B", "C"])]
+ export_to_obsidian(
+ nodes,
+ edges,
+ node_id_extractor=lambda n: n.name,
+ incident_nodes_extractor=lambda e: tuple(e.participants),
+ edge_label_extractor=lambda e: e.label,
+ folder_path=tmp_path / "v",
+ )
+ # First member is the source; remaining are linked targets.
+ source = (tmp_path / "v" / "A.md").read_text(encoding="utf-8")
+ assert "meeting" in source
+ assert "[[B]]" in source
+ assert "[[C]]" in source