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.mdindex 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?"# Visualizehe 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.mdindex 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.pyindex 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.pyindex 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.pyindex 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__.pyindex 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_levelfrom .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.pynew file mode 100644index 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 rootdiff --git a/tests/types/test_obsidian_export.py b/tests/types/test_obsidian_export.pynew file mode 100644index 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 sourcediff --git a/tests/utils/test_obsidian.py b/tests/utils/test_obsidian.pynew file mode 100644index 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