Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

10.8 KB
Raw Blame
"""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