Skip to content

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

8.7 KB
Raw Blame
"""Unit tests for template parsers - identifiers."""

import pytest
from pydantic import BaseModel

from hyperextract.utils.template_engine.parsers import parse_identifiers
from hyperextract.utils.template_engine.parsers.identifiers import (
    validate_identifiers_fields,
)
from hyperextract.utils.template_engine.parsers.schemas import (
    GraphIdentifiersSchema,
)


class Entity(BaseModel):
    name: str


class Relation(BaseModel):
    source: str
    target: str
    type: str


class CustomRelation(BaseModel):
    """Relation whose endpoint fields are not named source/target."""

    subject: str
    object: str
    type: str


class NumericRelation(BaseModel):
    source: int
    target: int
    type: str


class HyperRelation(BaseModel):
    name: str
    participants: list[str]


class NestedHyperRelation(BaseModel):
    name: str
    group_a: list[str]
    group_b: list[str]


def _graph_members_extractor(relation_members):
    """Build the members extractor via the public parse_identifiers API."""
    identifiers = GraphIdentifiersSchema(
        entity_id="name",
        relation_id="{type}",
        relation_members=relation_members,
    )
    _, _, members_extractor = parse_identifiers(identifiers, "graph")
    return members_extractor


class TestGraphRelationMembers:
    """Dict-based relation_members for binary graph types."""

    def test_default_source_target_mapping(self):
        """Standard {source: source, target: target} mapping works."""
        extractor = _graph_members_extractor({"source": "source", "target": "target"})
        edge = Relation(source="A", target="B", type="knows")

        assert extractor(edge) == ("A", "B")

    def test_direction_is_preserved(self):
        """Directed edges must keep (source, target) order, not sorted order."""
        extractor = _graph_members_extractor({"source": "source", "target": "target"})
        edge = Relation(source="B", target="A", type="manages")

        assert extractor(edge) == ("B", "A")

    def test_custom_field_mapping(self):
        """Dict values map to custom edge field names, per documented contract."""
        extractor = _graph_members_extractor({"source": "subject", "target": "object"})
        edge = CustomRelation(subject="Alice", object="Bob", type="mentors")

        assert extractor(edge) == ("Alice", "Bob")

    def test_custom_field_mapping_preserves_direction(self):
        """Custom-mapped endpoints also keep source -> target order."""
        extractor = _graph_members_extractor({"source": "subject", "target": "object"})
        edge = CustomRelation(subject="Zoe", object="Adam", type="mentors")

        assert extractor(edge) == ("Zoe", "Adam")

    def test_missing_mapped_field_raises(self):
        """Mapping to a field absent from the edge schema raises AttributeError."""
        extractor = _graph_members_extractor({"source": "src", "target": "dst"})
        edge = Relation(source="A", target="B", type="knows")

        with pytest.raises(AttributeError, match="src"):
            extractor(edge)

    def test_non_string_values_coerced_to_str(self):
        """Endpoint values are coerced to strings for key comparison."""
        extractor = _graph_members_extractor({"source": "source", "target": "target"})
        edge = NumericRelation(source=2, target=1, type="links")

        assert extractor(edge) == ("2", "1")


class TestHypergraphRelationMembers:
    """String and list relation_members for hypergraph types."""

    def test_string_members_returns_sorted_participants(self):
        """Unordered hyperedge participants are sorted for a stable key."""
        identifiers = GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{name}",
            relation_members="participants",
        )
        _, _, extractor = parse_identifiers(identifiers, "hypergraph")
        edge = HyperRelation(name="meeting", participants=["Carol", "Alice", "Bob"])

        assert extractor(edge) == ("Alice", "Bob", "Carol")

    def test_list_members_returns_sorted_groups(self):
        """Nested hyperedge groups are each sorted for a stable key."""
        identifiers = GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{name}",
            relation_members=["group_a", "group_b"],
        )
        _, _, extractor = parse_identifiers(identifiers, "hypergraph")
        edge = NestedHyperRelation(name="match", group_a=["Y", "X"], group_b=["B", "A"])

        assert extractor(edge) == (("X", "Y"), ("A", "B"))


class TestValidateHypergraphMembers:
    """Hypergraph relation_members (string / list) must be field-checked too."""

    @staticmethod
    def _identifiers(members):
        return GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{name}|{type}",
            relation_members=members,
        )

    @staticmethod
    def _declared(relations):
        return {"entities": {"name"}, "relations": set(relations)}

    def test_string_members_must_be_declared(self):
        with pytest.raises(ValueError, match="attendees"):
            validate_identifiers_fields(
                self._identifiers("attendees"),
                "hypergraph",
                self._declared(["name", "type", "participants"]),
            )

    def test_list_members_must_be_declared(self):
        with pytest.raises(ValueError, match="group_b"):
            validate_identifiers_fields(
                self._identifiers(["group_a", "group_b"]),
                "hypergraph",
                self._declared(["name", "type", "group_a"]),
            )

    def test_declared_string_members_accepted(self):
        validate_identifiers_fields(
            self._identifiers("participants"),
            "hypergraph",
            self._declared(["name", "type", "participants"]),
        )

    def test_declared_list_members_accepted(self):
        validate_identifiers_fields(
            self._identifiers(["group_a", "group_b"]),
            "hypergraph",
            self._declared(["name", "type", "group_a", "group_b"]),
        )
class TestValidateIdentifiersFields:
    """Load-time field check: time/location live on relations (HE-T006)."""

    @staticmethod
    def _declared(entities, relations):
        return {"entities": set(entities), "relations": set(relations)}

    def test_relation_level_time_field_accepted(self):
        """Every shipped temporal preset declares `time` under relations."""
        identifiers = GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{source}|{type}|{target}|{time}",
            relation_members={"source": "source", "target": "target"},
            time_field="time",
        )

        validate_identifiers_fields(
            identifiers,
            "temporal_graph",
            self._declared(["name"], ["source", "target", "type", "time"]),
        )

    def test_relation_level_location_field_accepted(self):
        identifiers = GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{source}|{target}",
            relation_members={"source": "source", "target": "target"},
            location_field="location",
        )

        validate_identifiers_fields(
            identifiers,
            "spatial_graph",
            self._declared(["name"], ["source", "target", "location"]),
        )

    def test_undeclared_time_field_still_rejected(self):
        identifiers = GraphIdentifiersSchema(
            entity_id="name",
            relation_id="{source}|{target}",
            relation_members={"source": "source", "target": "target"},
            time_field="when",
        )

        with pytest.raises(ValueError, match="when"):
            validate_identifiers_fields(
                identifiers,
                "temporal_graph",
                self._declared(["name"], ["source", "target"]),
            )


class TestGraphTemplateWithNaiveIdentifiers:
    """A graph-family template carrying item_id must fail with a diagnosis."""

    def test_naive_identifiers_rejected_with_guidance(self):
        from hyperextract.utils.template_engine.parsers.schemas import (
            NaiveIdentifierSchema,
        )

        with pytest.raises(ValueError, match="not item_id"):
            validate_identifiers_fields(
                NaiveIdentifierSchema(item_id="name"),
                "graph",
                {"entities": {"name"}, "relations": {"source", "target"}},
            )

    def test_graph_identifiers_still_accepted(self):
        validate_identifiers_fields(
            GraphIdentifiersSchema(
                entity_id="name",
                relation_id="{source}|{target}",
                relation_members={"source": "source", "target": "target"},
            ),
            "graph",
            {"entities": {"name"}, "relations": {"source", "target"}},
        )