Skip to content

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

Add comprehensive tests for AutoSet, AutoSpatialGraph, AutoSpatioTemporalGraph, and AutoTemporalGraph

yifanfeng97d2a3160c018c
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..6eb0a63
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,83 @@
+"""Pytest configuration: Auto-detect environment (Real API vs Mock) and inject fixtures."""
+
+import os
+from pathlib import Path
+
+import pytest
+from dotenv import load_dotenv
+
+
+# Load .env file if it exists
+def _load_env():
+ """Load environment variables from .env file."""
+ env_path = Path(__file__).parent.parent / ".env"
+ if env_path.exists():
+ load_dotenv(env_path)
+ # Also check for .env in current working directory
+ load_dotenv()
+
+
+_load_env()
+
+
+def _has_openai_key() -> bool:
+ """Check if OpenAI API key is available in environment."""
+ api_key = os.getenv("OPENAI_API_KEY", "").strip()
+ return bool(api_key and api_key != "sk-")
+
+
[email protected](scope="session")
+def is_real_env() -> bool:
+ """Fixture indicating whether tests should use real API or mock."""
+ has_key = _has_openai_key()
+ if has_key:
+ print("\n\n[PYTEST CONFIG] 🔌 Real OpenAI API detected - Using REAL LLM & Embeddings")
+ else:
+ print("\n\n[PYTEST CONFIG] 🎭 No API key found - Using MOCK LLM & Embeddings")
+ return has_key
+
+
[email protected](scope="session")
+def llm_client(is_real_env):
+ """
+ Fixture that provides LLM client (Real or Mock).
+
+ Auto-switches based on whether OPENAI_API_KEY is set.
+ """
+ if is_real_env:
+ try:
+ from langchain_openai import ChatOpenAI
+
+ return ChatOpenAI(model="gpt-4o-mini", temperature=0)
+ except ImportError:
+ pytest.fail(
+ "OPENAI_API_KEY detected but 'langchain-openai' package not installed. "
+ "Install with: pip install langchain-openai"
+ )
+ else:
+ from tests.mocks import MockChatModel
+
+ return MockChatModel()
+
+
[email protected](scope="session")
+def embedder(is_real_env):
+ """
+ Fixture that provides Embeddings client (Real or Mock).
+
+ Auto-switches based on whether OPENAI_API_KEY is set.
+ """
+ if is_real_env:
+ try:
+ from langchain_openai import OpenAIEmbeddings
+
+ return OpenAIEmbeddings(model="text-embedding-3-small")
+ except ImportError:
+ pytest.fail(
+ "OPENAI_API_KEY detected but 'langchain-openai' package not installed. "
+ "Install with: pip install langchain-openai"
+ )
+ else:
+ from tests.mocks import MockEmbeddings
+
+ return MockEmbeddings()
diff --git a/tests/mocks.py b/tests/mocks.py
new file mode 100644
index 0000000..cffc1a3
--- /dev/null
+++ b/tests/mocks.py
@@ -0,0 +1,130 @@
+"""Mock implementations for LLM and Embeddings for testing without API keys."""
+
+from typing import Any, List, Optional, Type, get_origin, get_args
+from pydantic import BaseModel, create_model
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import BaseMessage, AIMessage
+from langchain_core.embeddings import Embeddings
+from langchain_core.runnables import RunnableSerializable, RunnableConfig
+
+
+class MockEmbeddings(Embeddings):
+ """Mock Embeddings that returns deterministic vectors based on string hash."""
+
+ def __init__(self, dim: int = 768):
+ self.dim = dim
+
+ def embed_documents(self, texts: List[str]) -> List[List[float]]:
+ """Return deterministic embedding vectors based on text hash."""
+ return [self._hash_to_vector(text) for text in texts]
+
+ def embed_query(self, text: str) -> List[float]:
+ """Return deterministic embedding vector for query."""
+ return self._hash_to_vector(text)
+
+ def _hash_to_vector(self, text: str) -> List[float]:
+ """Convert text to deterministic vector of given dimension."""
+ hash_val = hash(text)
+ # Create deterministic values based on hash
+ return [(hash_val + i) % 1000 / 1000.0 for i in range(self.dim)]
+
+
+class MockStructuredRunnable(RunnableSerializable):
+ """
+ Mock Runnable that simulates with_structured_output behavior.
+ Generates dummy data matching the given Pydantic schema.
+ """
+
+ schema: Type[BaseModel]
+
+ class Config:
+ arbitrary_types_allowed = True
+
+ def invoke(
+ self, input: Any, config: Optional[RunnableConfig] = None
+ ) -> BaseModel:
+ """Generate and return a mock instance of the schema."""
+ return self._generate_mock_instance(self.schema)
+
+ def batch(
+ self,
+ inputs: List[Any],
+ config: Optional[RunnableConfig] = None,
+ **kwargs: Any,
+ ) -> List[BaseModel]:
+ """Generate mock instances for batch input."""
+ return [self.invoke(inp, config) for inp in inputs]
+
+ def _generate_mock_instance(self, model_cls: Type[BaseModel]) -> BaseModel:
+ """Recursively generate mock instance matching schema."""
+ data = {}
+
+ for field_name, field_info in model_cls.model_fields.items():
+ field_type = field_info.annotation
+
+ # Handle Optional types
+ origin = get_origin(field_type)
+ if origin is Optional.__class__ or (
+ hasattr(field_type, "__args__") and type(None) in get_args(field_type)
+ ):
+ # Extract the actual type from Optional
+ args = get_args(field_type)
+ field_type = args[0] if args else str
+
+ origin = get_origin(field_type)
+
+ # Handle List types
+ if origin is list:
+ args = get_args(field_type)
+ if args and issubclass(args[0], BaseModel):
+ # List of Pydantic models
+ data[field_name] = [self._generate_mock_instance(args[0])]
+ else:
+ # List of primitives or empty
+ data[field_name] = []
+
+ # Handle Pydantic model fields
+ elif isinstance(field_type, type) and issubclass(field_type, BaseModel):
+ data[field_name] = self._generate_mock_instance(field_type)
+
+ # Handle primitive types
+ elif field_type == str:
+ data[field_name] = f"mock_{field_name}"
+ elif field_type == int:
+ data[field_name] = 1
+ elif field_type == float:
+ data[field_name] = 1.0
+ elif field_type == bool:
+ data[field_name] = True
+ else:
+ # Default to None for unknown types
+ data[field_name] = None
+
+ return model_cls(**data)
+
+
+class MockChatModel(BaseChatModel):
+ """Mock Chat Model for testing without API calls."""
+
+ @property
+ def _llm_type(self) -> str:
+ return "mock-chat-model"
+
+ def _generate(
+ self,
+ messages: List[BaseMessage],
+ stop: Optional[List[str]] = None,
+ run_manager: Any = None,
+ **kwargs: Any,
+ ) -> Any:
+ """Generate mock response."""
+ # Return a simple mock message
+ return type("ChatResult", (), {"generations": [type("Generation", (), {"message": AIMessage(content="mock response")})]})()
+
+ def with_structured_output(self, schema: Type[BaseModel], **kwargs: Any) -> RunnableSerializable:
+ """
+ Return a MockStructuredRunnable that generates mock data matching the schema.
+ This simulates LangChain's with_structured_output behavior.
+ """
+ runnable = MockStructuredRunnable(schema=schema)
+ return runnable
diff --git a/tests/types/__init__.py b/tests/types/__init__.py
new file mode 100644
index 0000000..ee4509f
--- /dev/null
+++ b/tests/types/__init__.py
@@ -0,0 +1 @@
+"""Test suite for Hyper-Extract types module."""
diff --git a/tests/types/test_graph.py b/tests/types/test_graph.py
new file mode 100644
index 0000000..19ed957
--- /dev/null
+++ b/tests/types/test_graph.py
@@ -0,0 +1,271 @@
+"""Tests for AutoGraph - basic graph extraction pattern."""
+
+import pytest
+from pydantic import BaseModel, Field
+from typing import Tuple
+from ontomem.merger import MergeStrategy
+from hyperextract.types.graph import AutoGraph
+
+
+class Entity(BaseModel):
+ """Test schema for graph nodes."""
+
+ name: str = Field(default="", description="Entity name")
+ entity_type: str = Field(default="unknown", description="Type of entity")
+
+
+class Relation(BaseModel):
+ """Test schema for graph edges."""
+
+ source: str = Field(default="", description="Source entity name")
+ target: str = Field(default="", description="Target entity name")
+ relation_type: str = Field(default="", description="Type of relation")
+
+
+class TestAutoGraphBasics:
+ """Test basic AutoGraph initialization."""
+
+ def test_initialization_one_stage(self, llm_client, embedder):
+ """Test AutoGraph initialization in one-stage mode."""
+ kg = 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,
+ extraction_mode="one_stage",
+ )
+
+ assert kg.extraction_mode == "one_stage"
+ assert kg.node_schema == Entity
+ assert kg.edge_schema == Relation
+ assert kg.empty() is True
+
+ def test_initialization_two_stage(self, llm_client, embedder):
+ """Test AutoGraph initialization in two-stage mode."""
+ kg = 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,
+ extraction_mode="two_stage",
+ )
+
+ assert kg.extraction_mode == "two_stage"
+ assert kg.empty() is True
+
+ def test_custom_prompts(self, llm_client, embedder):
+ """Test that custom prompts are stored."""
+ custom_prompt = "Custom extraction prompt"
+ node_prompt = "Custom node prompt"
+ edge_prompt = "Custom edge prompt"
+
+ kg = 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,
+ prompt=custom_prompt,
+ prompt_for_node_extraction=node_prompt,
+ prompt_for_edge_extraction=edge_prompt,
+ )
+
+ assert custom_prompt in kg.prompt
+ assert node_prompt in kg.node_prompt
+ assert edge_prompt in kg.edge_prompt
+
+
+class TestAutoGraphExtraction:
+ """Test graph extraction operations."""
+
+ def test_feed_text_one_stage(self, llm_client, embedder):
+ """Test feeding text in one-stage mode."""
+ kg = 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,
+ extraction_mode="one_stage",
+ )
+
+ kg.feed_text("Alice knows Bob. Bob knows Charlie.")
+
+ assert not kg.empty()
+ assert len(kg.data.nodes) > 0
+
+ def test_feed_text_two_stage(self, llm_client, embedder):
+ """Test feeding text in two-stage mode."""
+ kg = 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,
+ extraction_mode="two_stage",
+ )
+
+ kg.feed_text("Alice is an engineer. Bob is a designer. They work together.")
+
+ assert not kg.empty()
+ assert hasattr(kg.data, "nodes")
+ assert hasattr(kg.data, "edges")
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test extract() creates new instance."""
+ kg1 = 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,
+ )
+
+ kg2 = kg1.extract("""CEO Sarah leads Engineering where Bob manages Backend Systems.
+ Bob oversees both Database Architecture (led by Alice) and API Development (led by Tom).
+ Alice collaborates with Tom on performance optimization.""")
+
+ assert kg1 is not kg2
+ assert kg1.empty() is True
+ # kg2 may or may not be empty depending on extraction results
+
+
+class TestAutoGraphProperties:
+ """Test graph data properties."""
+
+ def test_nodes_property(self, llm_client, embedder):
+ """Test accessing nodes from graph."""
+ kg = 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,
+ )
+
+ kg.feed_text("""
+ Engineering Director Michael manages Sarah (Backend Lead) and James (Frontend Lead).
+ Sarah collaborates with DevOps engineer David on infrastructure.
+ James works with UI designer Lisa on frontend components.
+ Chief Architect Elena mentors the entire team on best practices.
+ """)
+
+ nodes = kg.data.nodes
+ assert isinstance(nodes, list)
+ assert all(isinstance(n, Entity) for n in nodes)
+
+ def test_edges_property(self, llm_client, embedder):
+ """Test accessing edges from graph."""
+ kg = 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,
+ )
+
+ kg.feed_text("""
+ CEO John directs CTO Lisa and CFO David.
+ Lisa manages the core engineering team and reports to John.
+ David oversees financial planning and coordinates with John on budgets.
+ Senior Architect Elena advises Lisa on technical decisions.
+ """)
+
+ edges = kg.data.edges
+ assert isinstance(edges, list)
+ assert all(isinstance(e, Relation) for e in edges)
+
+
+class TestAutoGraphDeduplication:
+ """Test graph deduplication logic."""
+
+ def test_node_deduplication_by_key(self, llm_client, embedder):
+ """Test that nodes with same key are deduplicated."""
+ kg = 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,
+ )
+
+ # Manually create nodes
+ e1 = Entity(name="Alice", entity_type="person")
+ e2 = Entity(name="Alice", entity_type="person") # Same key
+ e3 = Entity(name="Bob", entity_type="person")
+
+ # Add them manually to test deduplication
+ kg._node_memory.add([e1, e2, e3])
+
+ # After deduplication via key, should have 2 nodes
+ assert kg._node_memory.size == 2
+
+ def test_edge_deduplication_by_key(self, llm_client, embedder):
+ """Test that edges with same key are deduplicated."""
+ kg = 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,
+ )
+
+ r1 = Relation(source="Alice", target="Bob", relation_type="knows")
+ r2 = Relation(source="Alice", target="Bob", relation_type="knows") # Same key
+ r3 = Relation(source="Bob", target="Charlie", relation_type="knows")
+
+ # Add them manually to test deduplication
+ kg._edge_memory.add([r1, r2, r3])
+
+ # After deduplication via key, should have 2 edges
+ assert kg._edge_memory.size == 2
+
+
+class TestAutoGraphSchemaValidation:
+ """Test schema validation."""
+
+ def test_edge_key_extractor_receives_relation_object(self, llm_client, embedder):
+ """Test that edge_key_extractor receives Relation objects."""
+ called_with = []
+
+ def capture_edge_key(rel: Relation):
+ called_with.append(rel)
+ return f"{rel.source}-{rel.relation_type}-{rel.target}"
+
+ kg = AutoGraph(
+ node_schema=Entity,
+ edge_schema=Relation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=capture_edge_key,
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ rel = Relation(source="A", target="B", relation_type="test")
+ capture_edge_key(rel)
+
+ assert len(called_with) > 0
+ assert called_with[-1].source == "A"
diff --git a/tests/types/test_hypergraph.py b/tests/types/test_hypergraph.py
new file mode 100644
index 0000000..a71cd90
--- /dev/null
+++ b/tests/types/test_hypergraph.py
@@ -0,0 +1,269 @@
+"""Tests for AutoHypergraph - hypergraph extraction pattern."""
+
+import pytest
+from pydantic import BaseModel, Field
+from typing import List, Tuple
+from ontomem.merger import MergeStrategy
+from hyperextract.types.hypergraph import AutoHypergraph
+
+
+class Person(BaseModel):
+ """Test schema for hypergraph nodes."""
+
+ name: str = Field(default="", description="Person's name")
+
+
+class Event(BaseModel):
+ """Test schema for hyperedges."""
+
+ event_type: str = Field(default="", description="Type of event")
+ participants: List[str] = Field(default_factory=list, description="Names of participants")
+
+
+class TestAutoHypergraphBasics:
+ """Test basic AutoHypergraph functionality."""
+
+ def test_initialization(self, llm_client, embedder):
+ """Test AutoHypergraph initialization."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode="two_stage",
+ )
+
+ assert hg.node_schema == Person
+ assert hg.edge_schema == Event
+ assert hg.extraction_mode == "two_stage"
+ assert hg.empty() is True
+
+ def test_default_extraction_mode_is_two_stage(self, llm_client, embedder):
+ """Test that default extraction mode is two_stage."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ assert hg.extraction_mode == "two_stage"
+
+
+class TestAutoHypergraphKeyGeneration:
+ """Test key generation and deduplication logic."""
+
+ def test_edge_key_with_sorted_participants(self, llm_client, embedder):
+ """Test that edge keys are the same for same participants regardless of order."""
+ # Define key extractor with sorting
+ def edge_key(event: Event) -> str:
+ sorted_participants = "-".join(sorted(event.participants))
+ return f"{event.event_type}_{sorted_participants}"
+
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=edge_key,
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Two events with same type and participants but different order
+ e1 = Event(event_type="meeting", participants=["Alice", "Bob", "Charlie"])
+ e2 = Event(event_type="meeting", participants=["Charlie", "Alice", "Bob"])
+
+ key1 = edge_key(e1)
+ key2 = edge_key(e2)
+
+ assert key1 == key2
+ assert key1 == "meeting_Alice-Bob-Charlie"
+
+ def test_hyperedge_participants_extractor(self, llm_client, embedder):
+ """Test that nodes_in_edge_extractor returns all participants."""
+ def participants_extractor(event: Event) -> Tuple[str, ...]:
+ return tuple(event.participants)
+
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=participants_extractor,
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ event = Event(event_type="party", participants=["Alice", "Bob", "Dave"])
+ participants = participants_extractor(event)
+
+ assert len(participants) == 3
+ assert "Alice" in participants
+ assert "Bob" in participants
+ assert "Dave" in participants
+
+
+class TestAutoHypergraphExtraction:
+ """Test hypergraph extraction."""
+
+ def test_feed_text_populates_hypergraph(self, llm_client, embedder):
+ """Test feeding text extracts nodes and hyperedges."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ hg.feed_text("Alice, Bob, and Charlie had a meeting. They collaborated on a project.")
+
+ assert not hg.empty()
+ assert len(hg.data.nodes) > 0
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test extract() creates new instance."""
+ hg1 = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ hg2 = hg1.extract("""Annual planning conference brings together CEO, CFO, CTO,
+ VP Marketing, and VP Sales to discuss Q2 revenue targets and product roadmap priorities.""")
+
+ assert hg1 is not hg2
+ assert hg1.empty() is True
+ assert hg2.empty() is False
+
+
+class TestAutoHypergraphDeduplication:
+ """Test hyperedge deduplication."""
+
+ def test_hyperedge_deduplication_ignores_participant_order(self, llm_client, embedder):
+ """Test that hyperedges with same participants in different order are deduplicated."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Create events with same event_type and participants but different order
+ e1 = Event(event_type="team_meeting", participants=["Alex", "Bailey", "Casey"])
+ e2 = Event(event_type="team_meeting", participants=["Casey", "Alex", "Bailey"])
+ e3 = Event(event_type="conference", participants=["Alex", "Bailey", "Casey"])
+
+ # Manually add to edge memory to test deduplication
+ hg._edge_memory.add([e1, e2])
+
+ # Should deduplicate e1 and e2 to 1 edge
+ assert hg._edge_memory.size == 1
+
+ # Adding e3 should increase count (different event_type)
+ hg._edge_memory.add([e3])
+ assert hg._edge_memory.size == 2
+
+ def test_multiple_hyperedges_with_different_participants(self, llm_client, embedder):
+ """Test that hyperedges with different participants are kept separate."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ e1 = Event(event_type="meeting", participants=["Alice", "Bob"])
+ e2 = Event(event_type="meeting", participants=["Alice", "Charlie"])
+
+ hg._edge_memory.add([e1, e2])
+
+ # Should have 2 different edges
+ assert hg._edge_memory.size == 2
+
+
+class TestAutoHypergraphProperties:
+ """Test hypergraph data properties."""
+
+ def test_nodes_property(self, llm_client, embedder):
+ """Test accessing nodes from hypergraph."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ hg.feed_text("""
+ Monthly Sync Meeting:
+ CEO John, CTO Lisa, and Product Manager Sarah discussed Q2 roadmap.
+ John, Lisa, and CFO David negotiated on budget allocation for infrastructure.
+ Lisa, Sarah, and QA Lead Tom reviewed test coverage requirements.
+ """)
+
+ nodes = hg.data.nodes
+ assert isinstance(nodes, list)
+ assert all(isinstance(n, Person) for n in nodes)
+
+ def test_edges_property(self, llm_client, embedder):
+ """Test accessing edges from hypergraph."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ hg.feed_text("""
+ Leadership Retreat Decisions:
+ Board Members Alice, Bob, and Charlie approved the new strategic plan.
+ Executives Alice, David, and Eve formed the new innovation committee.
+ Department heads Frank, Grace, and Henry committed to cross-team collaboration.
+ """)
+
+ edges = hg.data.edges
+ assert isinstance(edges, list)
+ assert all(isinstance(e, Event) for e in edges)
+
+ def test_edge_has_multiple_participants(self, llm_client, embedder):
+ """Test that hyperedges contain multiple participants."""
+ hg = AutoHypergraph(
+ node_schema=Person,
+ edge_schema=Event,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.event_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ event = Event(event_type="workshop", participants=["Person1", "Person2", "Person3", "Person4"])
+ hg._edge_memory.add([event])
+
+ assert len(hg.data.edges) > 0
+ assert len(hg.data.edges[0].participants) >= 2
diff --git a/tests/types/test_list.py b/tests/types/test_list.py
new file mode 100644
index 0000000..752fa32
--- /dev/null
+++ b/tests/types/test_list.py
@@ -0,0 +1,220 @@
+"""Tests for AutoList - list extraction pattern."""
+
+import pytest
+from pydantic import BaseModel, Field
+from hyperextract.types.list import AutoList
+
+
+class Task(BaseModel):
+ """Test schema for list items."""
+
+ title: str = Field(default="", description="Task title")
+ priority: int = Field(default=1)
+ done: bool = Field(default=False)
+
+
+class Person(BaseModel):
+ """Test schema for people."""
+
+ name: str = Field(default="", description="Person's name")
+ age: int = Field(default=0)
+
+
+class TestAutoListBasics:
+ """Test basic AutoList functionality."""
+
+ def test_initialization(self, llm_client, embedder):
+ """Test AutoList initialization."""
+ task_list = AutoList(
+ item_schema=Task, llm_client=llm_client, embedder=embedder
+ )
+
+ assert task_list.item_schema == Task
+ assert task_list.empty()
+ assert len(task_list) == 0
+
+ def test_properties(self, llm_client, embedder):
+ """Test AutoList properties."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ # Check items property
+ assert task_list.items == []
+ assert isinstance(task_list.items, list)
+
+
+class TestAutoListFeed:
+ """Test feeding text to AutoList."""
+
+ def test_feed_text_populates_list(self, llm_client, embedder):
+ """Test feeding text extracts items into list."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ task_list.feed_text("Buy milk and walk the dog")
+
+ assert not task_list.empty()
+ assert len(task_list) > 0
+ assert isinstance(task_list[0], Task)
+
+ def test_feed_text_appends(self, llm_client, embedder):
+ """Test that feed_text appends, not replaces."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ # Manually set initial items
+ task_list._data.items = [Task(title="Item 1", priority=1)]
+ initial_len = len(task_list)
+
+ # Feed more text (in mock mode, this adds mock items)
+ task_list.feed_text("""
+ Q1 2024 Sprint Tasks:
+ 1. Implement user authentication (High priority)
+ 2. Optimize database queries (Medium priority)
+ 3. Write API documentation (Low priority)
+ 4. Security audit review (Critical priority)
+ 5. Deploy staging environment (High priority)
+ """)
+
+ # Should have more items
+ assert len(task_list) >= initial_len
+
+
+class TestAutoListIndexing:
+ """Test indexing and slicing operations."""
+
+ def test_integer_indexing(self, llm_client, embedder):
+ """Test integer indexing returns single item."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ t1 = Task(title="First", priority=1)
+ t2 = Task(title="Second", priority=2)
+ t3 = Task(title="Third", priority=3)
+ task_list._data.items = [t1, t2, t3]
+
+ assert task_list[0] == t1
+ assert task_list[1] == t2
+ assert task_list[-1] == t3
+
+ def test_out_of_bounds_indexing(self, llm_client, embedder):
+ """Test IndexError for out of bounds access."""
+ task_list = AutoList(Task, llm_client, embedder)
+ task_list._data.items = [Task(title="Only", priority=1)]
+
+ with pytest.raises(IndexError):
+ _ = task_list[10]
+
+ def test_slice_returns_new_list(self, llm_client, embedder):
+ """Test slicing returns new AutoList instance."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ t1 = Task(title="First", priority=1)
+ t2 = Task(title="Second", priority=2)
+ t3 = Task(title="Third", priority=3)
+ task_list._data.items = [t1, t2, t3]
+
+ # Test slice
+ sliced = task_list[0:2]
+
+ assert isinstance(sliced, AutoList)
+ assert sliced.item_schema == Task
+ assert len(sliced) == 2
+ assert sliced[0] == t1
+ assert sliced[1] == t2
+
+ def test_slice_with_step(self, llm_client, embedder):
+ """Test slicing with step."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ items = [Task(title=f"Item {i}", priority=i) for i in range(5)]
+ task_list._data.items = items
+
+ sliced = task_list[::2]
+ assert len(sliced) == 3
+
+
+class TestAutoListSetItem:
+ """Test item assignment."""
+
+ def test_setitem_updates_item(self, llm_client, embedder):
+ """Test __setitem__ replaces item at index."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ t1 = Task(title="First")
+ t2 = Task(title="Second")
+ task_list._data.items = [t1, t2]
+
+ new_item = Task(title="Updated")
+ task_list[0] = new_item
+
+ assert task_list[0].title == "Updated"
+ assert task_list[1] == t2
+
+ def test_setitem_invalid_schema(self, llm_client, embedder):
+ """Test that setting wrong schema raises error."""
+ task_list = AutoList(Task, llm_client, embedder)
+ task_list._data.items = [Task(title="Item")]
+
+ with pytest.raises(TypeError):
+ task_list[0] = Person(name="Not a Task")
+
+
+class TestAutoListAddition:
+ """Test list concatenation."""
+
+ def test_list_plus_list(self, llm_client, embedder):
+ """Test AutoList + AutoList merges both lists."""
+ list1 = AutoList(Task, llm_client, embedder)
+ list1._data.items = [Task(title="A", priority=1)]
+
+ list2 = AutoList(Task, llm_client, embedder)
+ list2._data.items = [Task(title="B", priority=2)]
+
+ result = list1 + list2
+
+ assert isinstance(result, AutoList)
+ assert len(result) == 2
+ assert result[0].title == "A"
+ assert result[1].title == "B"
+
+ def test_list_plus_model(self, llm_client, embedder):
+ """Test AutoList + AutoModel appends model."""
+ from hyperextract.types.model import AutoModel
+
+ list_obj = AutoList(Task, llm_client, embedder)
+ list_obj._data.items = [Task(title="Existing", priority=1)]
+
+ model = AutoModel(Task, llm_client, embedder)
+ model._data = Task(title="New Item", priority=2)
+
+ result = list_obj + model
+
+ assert isinstance(result, AutoList)
+ assert len(result) == 2
+ assert result[1].title == "New Item"
+
+
+class TestAutoListDeletion:
+ """Test item deletion."""
+
+ def test_delitem(self, llm_client, embedder):
+ """Test __delitem__ removes item at index."""
+ task_list = AutoList(Task, llm_client, embedder)
+
+ items = [Task(title=f"Item {i}") for i in range(3)]
+ task_list._data.items = items
+
+ del task_list[1]
+
+ assert len(task_list) == 2
+ assert task_list[0].title == "Item 0"
+ assert task_list[1].title == "Item 2"
+
+
+class TestAutoListLen:
+ """Test length operations."""
+
+ def test_len(self, llm_client, embedder):
+ """Test __len__ returns list length."""
+ task_list = AutoList(Task, llm_client, embedder)
+ assert len(task_list) == 0
+
+ task_list._data.items = [Task(title=str(i)) for i in range(5)]
+ assert len(task_list) == 5
diff --git a/tests/types/test_model.py b/tests/types/test_model.py
new file mode 100644
index 0000000..6786bca
--- /dev/null
+++ b/tests/types/test_model.py
@@ -0,0 +1,223 @@
+"""Tests for AutoModel - single object extraction pattern."""
+
+import pytest
+from pydantic import BaseModel, Field
+from datetime import datetime
+from hyperextract.types.model import AutoModel
+from ontomem.merger import MergeStrategy
+
+
+class Person(BaseModel):
+ """Test schema for AutoModel tests."""
+
+ name: str | None = Field(default=None, description="Person's name")
+ age: int | None = Field(default=None, description="Person's age")
+ profession: str | None = Field(default=None, description="Person's profession")
+
+
+class Article(BaseModel):
+ """Test schema for article summary."""
+
+ title: str = Field(default="", description="Article title")
+ author: str = Field(default="", description="Article author")
+ summary: str = Field(default="", description="Article summary")
+
+
+class TestAutoModelBasics:
+ """Test basic AutoModel functionality."""
+
+ def test_initialization(self, llm_client, embedder):
+ """Test AutoModel initialization."""
+ model = AutoModel(
+ data_schema=Person,
+ llm_client=llm_client,
+ embedder=embedder,
+ strategy_or_merger=MergeStrategy.MERGE_FIELD,
+ )
+
+ assert model.data_schema == Person
+ # Note: empty() may return False if default values are present
+ assert isinstance(model.data, Person)
+
+ def test_properties(self, llm_client, embedder):
+ """Test AutoModel properties."""
+ model = AutoModel(Person, llm_client, embedder)
+
+ # Check metadata
+ assert "created_at" in model.metadata
+ assert "updated_at" in model.metadata
+ assert isinstance(model.metadata["created_at"], datetime)
+
+ def test_empty_check(self, llm_client, embedder):
+ """Test empty() method for detecting uninitialized data."""
+ model = AutoModel(Person, llm_client, embedder)
+ # Initially, model may or may not be empty depending on default values
+ initial_state = model.empty()
+
+ # Explicitly set non-default values
+ model._data.name = "John Doe"
+ # After setting explicit data, should not be empty
+ assert model.empty() is False
+
+
+class TestAutoModelExtraction:
+ """Test extraction and data management."""
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test that extract() returns a new instance."""
+ model1 = AutoModel(Person, llm_client, embedder)
+ model2 = model1.extract("""Dr. James Wilson, 47 years old, served as Chief Technology Officer
+ at Innovate Systems for 12 years before joining CloudFirst as VP of Engineering.""")
+
+ # Should be different instances
+ assert model1 is not model2
+ # Original should still be empty
+ assert model1.empty() is True
+ # New should have data
+ assert not model2.empty()
+
+ def test_feed_text_updates_in_place(self, llm_client, embedder):
+ """Test that feed_text() updates current instance."""
+ model = AutoModel(Person, llm_client, embedder)
+ original_id = id(model)
+
+ result = model.feed_text("""
+ Dr. Sarah Chen is a 42-year-old data scientist at Tech Labs.
+ She specializes in machine learning and supervises 8 engineers.
+ Sarah earned her PhD from Stanford in 2008.
+ """)
+
+ # Should return self
+ assert id(result) == original_id
+ # Should not be empty
+ assert not model.empty()
+
+ def test_feed_text_chaining(self, llm_client, embedder):
+ """Test that feed_text() supports method chaining."""
+ model = AutoModel(Person, llm_client, embedder)
+
+ result = model.feed_text(
+ "Alexandra Martinez is a 35-year-old software architect"
+ ).feed_text(
+ "She works at TechCorp and has 12 years of experience in distributed systems"
+ )
+
+ assert result is model
+ assert not model.empty()
+
+
+class TestAutoModelClear:
+ """Test clearing operations."""
+
+ def test_clear_resets_data(self, llm_client, embedder):
+ """Test clear() resets all data."""
+ model = AutoModel(Person, llm_client, embedder)
+ model.feed_text("""
+ Prof. Michael Johnson is a 56-year-old cloud architect.
+ He has 20 years of experience in distributed systems.
+ Michael leads the infrastructure team.
+ """)
+ assert not model.empty()
+
+ model.clear()
+ assert model.empty() is True
+
+ def test_clear_updates_metadata(self, llm_client, embedder):
+ """Test that clear() updates metadata."""
+ model = AutoModel(Person, llm_client, embedder)
+ old_time = model.metadata["updated_at"]
+
+ model.feed_text("""
+ Emma Rodriguez is a 38-year-old product manager at StartupCorp.
+ She specializes in B2B SaaS products and leads cross-functional teams.
+ Emma worked at Microsoft for 10 years before joining StartupCorp.
+ """)
+ model.clear()
+
+ # Updated time should be newer
+ assert model.metadata["updated_at"] >= old_time
+
+
+class TestAutoModelOperators:
+ """Test operator overloading."""
+
+ def test_model_plus_model_creates_list(self, llm_client, embedder):
+ """Test AutoModel + AutoModel creates AutoList."""
+ from hyperextract.types.list import AutoList
+
+ model1 = AutoModel(Person, llm_client, embedder)
+ model1._data = Person(name="Alice", age=30, profession="Engineer")
+
+ model2 = AutoModel(Person, llm_client, embedder)
+ model2._data = Person(name="Bob", age=25, profession="Designer")
+
+ result = model1 + model2
+
+ assert isinstance(result, AutoList)
+ assert result.item_schema == Person
+ assert len(result) == 2
+
+ def test_model_plus_model_same_schema_required(self, llm_client, embedder):
+ """Test that + operator requires same schema."""
+ model1 = AutoModel(Person, llm_client, embedder)
+
+ article_model = AutoModel(Article, llm_client, embedder)
+
+ with pytest.raises(TypeError, match="different schemas"):
+ model1 + article_model
+
+ def test_model_plus_list_creates_list(self, llm_client, embedder):
+ """Test AutoModel + AutoList prepends model to list."""
+ from hyperextract.types.list import AutoList
+
+ model = AutoModel(Person, llm_client, embedder)
+ model._data = Person(name="Charlie", age=35)
+
+ auto_list = AutoList(Person, llm_client, embedder)
+ person1 = Person(name="Alice", age=30)
+ person2 = Person(name="Bob", age=25)
+ auto_list._data.items = [person1, person2]
+
+ result = model + auto_list
+
+ assert isinstance(result, AutoList)
+ assert len(result) == 3
+ # Model should be prepended
+ assert result[0].name == "Charlie"
+ assert result[1].name == "Alice"
+ assert result[2].name == "Bob"
+
+
+class TestAutoModelMerging:
+ """Test merge batch data functionality."""
+
+ def test_merge_batch_multiple_items(self, llm_client, embedder):
+ """Test merging multiple extracted items."""
+ # Use MERGE_FIELD strategy to test deterministic field-level merging
+ # without depending on LLM (works with or without API key)
+ model = AutoModel(Person, llm_client, embedder, strategy_or_merger=MergeStrategy.MERGE_FIELD)
+
+ # Create mock items to merge
+ item1 = Person(name="John", age=30, profession="Engineer")
+ item2 = Person(name="Jane", age=28, profession="Doctor")
+
+ # Merge strategy: MERGE_FIELD merges non-null fields
+ result = model.merge_batch_data([item1, item2])
+
+ # Result should be a valid Person with one of the merged data
+ assert isinstance(result, Person)
+ # Should have a name (from one of the items)
+ assert result.name in ["John", "Jane"]
+ # Should have age and profession (from merged data)
+ assert result.age is not None
+ assert result.profession is not None
+
+ def test_merge_batch_empty_list(self, llm_client, embedder):
+ """Test merging empty list."""
+ model = AutoModel(Person, llm_client, embedder)
+
+ result = model.merge_batch_data([])
+
+ # Should return empty instance
+ assert isinstance(result, Person)
+ assert result.model_dump(exclude_unset=True) == {}
diff --git a/tests/types/test_set.py b/tests/types/test_set.py
new file mode 100644
index 0000000..efdff72
--- /dev/null
+++ b/tests/types/test_set.py
@@ -0,0 +1,316 @@
+"""Tests for AutoSet - set extraction pattern with deduplication."""
+
+import pytest
+from pydantic import BaseModel, Field
+from ontomem.merger import MergeStrategy
+from hyperextract.types.set import AutoSet
+
+
+class BookEntry(BaseModel):
+ """Test schema for book entries."""
+
+ title: str = Field(description="Book title (unique key)")
+ author: str | None = Field(None, description="Book author")
+ year: int | None = Field(None, description="Publication year")
+
+
+class TestAutoSetBasics:
+ """Test basic AutoSet functionality."""
+
+ def test_initialization(self, llm_client, embedder):
+ """Test AutoSet initialization."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ strategy_or_merger=MergeStrategy.MERGE_FIELD,
+ )
+
+ assert books.item_schema == BookEntry
+ assert books.empty()
+ assert len(books) == 0
+ assert books.keys == []
+
+ def test_key_extractor_validation(self, llm_client, embedder):
+ """Test that key_extractor is properly stored."""
+ key_func = lambda x: x.title
+
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=key_func,
+ )
+
+ assert books.key_extractor == key_func
+
+
+class TestAutoSetDeduplication:
+ """Test deduplication core functionality."""
+
+ def test_add_deduplicates_same_key(self, llm_client, embedder):
+ """Test that adding items with same key deduplicates."""
+ # Use MERGE_FIELD strategy to test deterministic deduplication
+ # without depending on LLM (works with or without API key)
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ strategy_or_merger=MergeStrategy.MERGE_FIELD,
+ )
+
+ b1 = BookEntry(title="Python Basics", author="John", year=2020)
+ books.add(b1)
+ assert len(books) == 1
+
+ # Add same book with different author info
+ b2 = BookEntry(title="Python Basics", author="John Smith", year=2021)
+ books.add(b2)
+
+ # Should still be 1 item (deduplicated with MERGE_FIELD strategy)
+ # MERGE_FIELD merges non-null fields, so both books merge into one
+ assert len(books) == 1
+
+ def test_add_keeps_distinct_keys(self, llm_client, embedder):
+ """Test that distinct keys are kept."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.add(BookEntry(title="Python Basics"))
+ books.add(BookEntry(title="Web Development"))
+ books.add(BookEntry(title="Data Science"))
+
+ assert len(books) == 3
+ assert "Python Basics" in books
+ assert "Web Development" in books
+ assert "Data Science" in books
+
+ def test_keys_property(self, llm_client, embedder):
+ """Test keys property returns all unique keys."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.add(BookEntry(title="Advanced Python"))
+ books.add(BookEntry(title="Web Frameworks"))
+ books.add(BookEntry(title="ML Fundamentals"))
+
+ keys = books.keys
+ assert len(keys) == 3
+ assert "Advanced Python" in keys
+ assert "Web Frameworks" in keys
+ assert "ML Fundamentals" in keys
+
+
+class TestAutoSetOperations:
+ """Test set-like operations."""
+
+ def test_contains_operator(self, llm_client, embedder):
+ """Test 'in' operator (contains)."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.add(BookEntry(title="Python Pro"))
+
+ assert "Python Pro" in books
+ assert "Java Expert" not in books
+
+ def test_contains_method(self, llm_client, embedder):
+ """Test contains method."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.add(BookEntry(title="Go Guide"))
+
+ assert books.contains("Go Guide") is True
+ assert books.contains("Rust Book") is False
+
+ def test_get_method(self, llm_client, embedder):
+ """Test get method retrieves items by key."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ book = BookEntry(title="TypeScript Handbook", author="Microsoft", year=2022)
+ books.add(book)
+
+ retrieved = books.get("TypeScript Handbook")
+ assert retrieved is not None
+ assert retrieved.title == "TypeScript Handbook"
+
+ def test_get_with_default(self, llm_client, embedder):
+ """Test get with default value."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ result = books.get("Nonexistent Book", default=None)
+ assert result is None
+
+
+class TestAutoSetRemoval:
+ """Test removal operations."""
+
+ def test_remove_removes_by_key(self, llm_client, embedder):
+ """Test remove method by key."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ book = BookEntry(title="Remove This")
+ books.add(book)
+ assert len(books) == 1
+
+ removed = books.remove("Remove This")
+ assert removed is not None
+ assert removed.title == "Remove This"
+ assert len(books) == 0
+ assert "Remove This" not in books
+
+ def test_remove_nonexistent(self, llm_client, embedder):
+ """Test removing non-existent key returns None."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ result = books.remove("Nonexistent")
+ assert result is None
+
+
+class TestAutoSetIteration:
+ """Test iteration operations."""
+
+ def test_iter_over_items(self, llm_client, embedder):
+ """Test iterating over set items."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ titles = ["Book A", "Book B", "Book C"]
+ for title in titles:
+ books.add(BookEntry(title=title))
+
+ collected = [b.title for b in books]
+ assert len(collected) == 3
+ assert set(collected) == set(titles)
+
+ def test_len_operator(self, llm_client, embedder):
+ """Test len() operator."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ assert len(books) == 0
+
+ for i in range(5):
+ books.add(BookEntry(title=f"Book_{i}"))
+
+ assert len(books) == 5
+
+
+class TestAutoSetFeedText:
+ """Test feed_text extraction."""
+
+ def test_feed_text_populates_set(self, llm_client, embedder):
+ """Test feeding text extracts and deduplicates."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.feed_text("Some text about popular books and authors")
+
+ # In mock mode, should have mock items
+ assert not books.empty()
+ assert len(books) > 0
+
+ def test_feed_text_maintains_uniqueness(self, llm_client, embedder):
+ """Test that feed_text maintains deduplication."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ # Manually add some books
+ books.add(BookEntry(title="Python Guide"))
+ books.add(BookEntry(title="Java Basics"))
+ initial_size = len(books)
+
+ # Feed text (in mock mode, generates mock data that might have same title)
+ books.feed_text("More information about programming books")
+
+ # Size should be >= initial (due to mock data being indeterminate)
+ assert len(books) >= initial_size
+
+
+class TestAutoSetRepr:
+ """Test string representations."""
+
+ def test_repr(self, llm_client, embedder):
+ """Test __repr__ method."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ repr_str = repr(books)
+ assert "AutoSet" in repr_str
+ assert "BookEntry" in repr_str
+ assert "0" in repr_str
+
+ def test_str(self, llm_client, embedder):
+ """Test __str__ method."""
+ books = AutoSet(
+ item_schema=BookEntry,
+ llm_client=llm_client,
+ embedder=embedder,
+ key_extractor=lambda x: x.title,
+ )
+
+ books.add(BookEntry(title="Book One"))
+ books.add(BookEntry(title="Book Two"))
+
+ str_repr = str(books)
+ assert "AutoSet" in str_repr
+ assert "2" in str_repr
diff --git a/tests/types/test_spatial_graph.py b/tests/types/test_spatial_graph.py
new file mode 100644
index 0000000..8b60736
--- /dev/null
+++ b/tests/types/test_spatial_graph.py
@@ -0,0 +1,235 @@
+"""Tests for AutoSpatialGraph - spatial graph extraction with location-aware deduplication."""
+
+import pytest
+from pydantic import BaseModel, Field
+from typing import Optional, Tuple
+from ontomem.merger import MergeStrategy
+from hyperextract.types.spatial_graph import AutoSpatialGraph
+
+
+class Entity(BaseModel):
+ """Test schema for spatial graph nodes."""
+
+ name: str = Field(default="", description="Entity name")
+
+
+class SpatialEdge(BaseModel):
+ """Test schema for spatial edges."""
+
+ src: str = Field(default="", description="Source entity")
+ dst: str = Field(default="", description="Target entity")
+ rel: str = Field(default="", description="Relationship type")
+ place: Optional[str] = Field(default=None, description="Location of relationship")
+
+
+class TestAutoSpatialGraphBasics:
+ """Test basic AutoSpatialGraph functionality."""
+
+ def test_initialization_with_default_location(self, llm_client, embedder):
+ """Test AutoSpatialGraph initialization with default observation_location."""
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Should have default observation_location
+ assert kg.observation_location is not None
+ assert kg.observation_location == "Unknown Location"
+
+ def test_initialization_with_custom_location(self, llm_client, embedder):
+ """Test AutoSpatialGraph initialization with custom observation_location."""
+ custom_location = "Paris, France"
+
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_location=custom_location,
+ )
+
+ assert kg.observation_location == custom_location
+
+
+class TestAutoSpatialGraphLocationInjection:
+ """Test that observation_location is properly injected into prompts."""
+
+ def test_observation_location_in_edge_prompt(self, llm_client, embedder):
+ """Test that observation_location is included in edge extraction prompt."""
+ observation_location = "Tokyo"
+
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_location=observation_location,
+ )
+
+ # The observation_location should be stored
+ assert kg.observation_location == observation_location
+ # And should be in prompts
+ assert "location" in kg.edge_prompt.lower() or "place" in kg.edge_prompt.lower()
+
+ def test_observation_location_in_graph_prompt(self, llm_client, embedder):
+ """Test that observation_location is in the full graph extraction prompt."""
+ observation_location = "New York City"
+
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_location=observation_location,
+ )
+
+ assert kg.observation_location == observation_location
+
+
+class TestAutoSpatialGraphKeyGeneration:
+ """Test spatial edge key generation."""
+
+ def test_edge_key_includes_location(self, llm_client, embedder):
+ """Test that edge keys differentiate based on location."""
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # The internal edge_key_extractor should combine base key and location
+ edge1 = SpatialEdge(src="Shop", dst="Customer", rel="at", place="London")
+ edge2 = SpatialEdge(src="Shop", dst="Customer", rel="at", place="Tokyo")
+ edge3 = SpatialEdge(src="Shop", dst="Customer", rel="at")
+
+ # Adding edges with different locations should create different keys
+ kg._edge_memory.add([edge1, edge2, edge3])
+
+ # Should have at least 2 unique edges (different locations)
+ assert kg._edge_memory.size >= 2
+
+
+class TestAutoSpatialGraphExtraction:
+ """Test spatial graph extraction."""
+
+ def test_feed_text_two_stage(self, llm_client, embedder):
+ """Test feeding text in two-stage extraction mode."""
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode="two_stage",
+ )
+
+ kg.feed_text("The library is located next to the museum. They are in downtown.")
+
+ assert not kg.empty()
+ assert len(kg.data.nodes) > 0
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test extract() creates new instance."""
+ kg1 = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ kg2 = kg1.extract("""Company headquarters in San Francisco connects to regional centers:
+ New York for East Coast operations, Chicago for Midwest, and Denver for Mountain region.
+ Each regional center manages local office branches.""")
+
+ assert kg1 is not kg2
+ assert kg1.empty() is True
+ assert kg2.empty() is False
+
+
+class TestAutoSpatialGraphPrompts:
+ """Test spatial prompt construction."""
+
+ def test_node_prompt_excludes_locations(self, llm_client, embedder):
+ """Test that node extraction prompt instructs NOT to extract locations."""
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Node prompt should warn not to extract locations
+ assert "location" in kg.node_prompt.lower() or "spatial" in kg.node_prompt.lower()
+
+ def test_edge_prompt_includes_spatial_rules(self, llm_client, embedder):
+ """Test that edge prompt includes spatial resolution rules."""
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Edge prompt should contain spatial/location rules
+ assert "location" in kg.edge_prompt.lower() or "observation" in kg.edge_prompt.lower()
+
+
+class TestAutoSpatialGraphLocationContext:
+ """Test location context handling."""
+
+ def test_custom_location_context(self, llm_client, embedder):
+ """Test that custom location context is used."""
+ locations = ["Office A", "Conference Room B", "Parking Lot"]
+
+ for location in locations:
+ kg = AutoSpatialGraph(
+ node_schema=Entity,
+ edge_schema=SpatialEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_location=location,
+ )
+
+ assert kg.observation_location == location
diff --git a/tests/types/test_spatio_temporal_graph.py b/tests/types/test_spatio_temporal_graph.py
new file mode 100644
index 0000000..204506c
--- /dev/null
+++ b/tests/types/test_spatio_temporal_graph.py
@@ -0,0 +1,288 @@
+"""Tests for AutoSpatioTemporalGraph - spatio-temporal graph extraction."""
+
+import pytest
+from pydantic import BaseModel, Field
+from typing import Optional, Tuple
+from ontomem.merger import MergeStrategy
+from hyperextract.types.spatio_temporal_graph import AutoSpatioTemporalGraph
+
+
+class Entity(BaseModel):
+ """Test schema for spatio-temporal graph nodes."""
+
+ name: str = Field(default="", description="Entity name")
+
+
+class STEdge(BaseModel):
+ """Test schema for spatio-temporal edges."""
+
+ src: str = Field(default="", description="Source entity")
+ dst: str = Field(default="", description="Target entity")
+ rel: str = Field(default="", description="Relationship type")
+ time: Optional[str] = Field(default=None, description="Time of relationship")
+ place: Optional[str] = Field(default=None, description="Location of relationship")
+
+
+class TestAutoSpatioTemporalGraphBasics:
+ """Test basic AutoSpatioTemporalGraph functionality."""
+
+ def test_initialization_with_defaults(self, llm_client, embedder):
+ """Test AutoSpatioTemporalGraph initialization with defaults."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Should have default observation_time and observation_location
+ assert kg.observation_time is not None
+ assert kg.observation_location is not None
+
+ def test_initialization_with_custom_context(self, llm_client, embedder):
+ """Test AutoSpatioTemporalGraph with custom time and location."""
+ custom_time = "2024-06-15"
+ custom_location = "Singapore"
+
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_time=custom_time,
+ observation_location=custom_location,
+ )
+
+ assert kg.observation_time == custom_time
+ assert kg.observation_location == custom_location
+
+
+class TestAutoSpatioTemporalGraphContextInjection:
+ """Test that both time and location contexts are injected."""
+
+ def test_both_contexts_in_prompts(self, llm_client, embedder):
+ """Test that both observation_time and observation_location are in prompts."""
+ custom_time = "2024-01-01"
+ custom_location = "Berlin"
+
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_time=custom_time,
+ observation_location=custom_location,
+ )
+
+ # Both contexts should be stored
+ assert kg.observation_time == custom_time
+ assert kg.observation_location == custom_location
+ # Prompts should reference spatio-temporal concepts
+ assert ("time" in kg.edge_prompt.lower() and "location" in kg.edge_prompt.lower()) \
+ or "spatio" in kg.edge_prompt.lower()
+
+
+class TestAutoSpatioTemporalGraphKeyGeneration:
+ """Test composite key generation combining time and location."""
+
+ def test_edge_key_combines_time_and_location(self, llm_client, embedder):
+ """Test that edge keys combine both time and location."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Create edges: same relation at different times and places
+ e1 = STEdge(src="Alice", dst="Bob", rel="meet", time="2023-06-15", place="London")
+ e2 = STEdge(src="Alice", dst="Bob", rel="meet", time="2023-06-15", place="Paris")
+ e3 = STEdge(src="Alice", dst="Bob", rel="meet", time="2023-07-15", place="London")
+ e4 = STEdge(src="Alice", dst="Bob", rel="meet", time="2023-07-15", place="Paris")
+ e5 = STEdge(src="Alice", dst="Bob", rel="meet") # No time or place
+
+ kg._edge_memory.add([e1, e2, e3, e4, e5])
+
+ # All 5 should be unique (different combinations of time and location)
+ assert kg._edge_memory.size >= 3 # At least 3 different combinations
+
+
+class TestAutoSpatioTemporalGraphExtraction:
+ """Test spatio-temporal graph extraction."""
+
+ def test_feed_text_two_stage(self, llm_client, embedder):
+ """Test feeding text in two-stage extraction mode."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode="two_stage",
+ )
+
+ kg.feed_text("In 2023, Alice and Bob met at the conference in Barcelona.")
+
+ assert not kg.empty()
+ assert len(kg.data.nodes) > 0
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test extract() creates new instance."""
+ kg1 = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ kg2 = kg1.extract("""Tech conference tour 2024: January workshop in San Francisco,
+ March seminar in New York, June training in London, September workshop in Tokyo.
+ Each event has 200+ attendees sharing innovations and networking.""")
+
+ assert kg1 is not kg2
+ assert kg1.empty() is True
+ assert kg2.empty() is False
+
+
+class TestAutoSpatioTemporalGraphPrompts:
+ """Test spatio-temporal prompt construction."""
+
+ def test_edge_prompt_includes_temporal_rules(self, llm_client, embedder):
+ """Test that edge prompt includes temporal extraction rules."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Edge prompt should contain both temporal and spatial rules
+ edge_prompt_lower = kg.edge_prompt.lower()
+ assert "time" in edge_prompt_lower or "date" in edge_prompt_lower or "observation" in edge_prompt_lower
+
+ def test_edge_prompt_includes_spatial_rules(self, llm_client, embedder):
+ """Test that edge prompt includes spatial extraction rules."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Edge prompt should contain spatial rules
+ edge_prompt_lower = kg.edge_prompt.lower()
+ assert "location" in edge_prompt_lower or "place" in edge_prompt_lower or "observation" in edge_prompt_lower
+
+ def test_node_prompt_excludes_temporal_spatial_markers(self, llm_client, embedder):
+ """Test that node extraction prompt excludes dates and locations."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Node prompt should warn against extracting dates/times and locations
+ node_prompt_lower = kg.node_prompt.lower()
+ assert "exclude" in node_prompt_lower or "never" in node_prompt_lower or "not" in node_prompt_lower
+
+
+class TestAutoSpatioTemporalGraphConsistency:
+ """Test spatio-temporal graph consistency."""
+
+ def test_all_dimensions_in_edge(self, llm_client, embedder):
+ """Test that edges can have all spatio-temporal dimensions."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Add nodes
+ kg._node_memory.add([Entity(name="Alice"), Entity(name="Bob")])
+
+ # Edge with all dimensions
+ full_edge = STEdge(src="Alice", dst="Bob", rel="meet", time="2024-06-15", place="Summit")
+ kg._edge_memory.add([full_edge])
+
+ assert kg._edge_memory.size > 0
+ edge_data = kg._edge_memory.items[0]
+ assert edge_data.time == "2024-06-15"
+ assert edge_data.place == "Summit"
+
+ def test_partial_dimensions(self, llm_client, embedder):
+ """Test edges with partial spatio-temporal information."""
+ kg = AutoSpatioTemporalGraph(
+ node_schema=Entity,
+ edge_schema=STEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.time or "",
+ location_in_edge_extractor=lambda x: x.place or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Add nodes
+ kg._node_memory.add([Entity(name="Alice"), Entity(name="Bob")])
+
+ # Edges with partial information
+ time_only = STEdge(src="Alice", dst="Bob", rel="call", time="2024-06-15")
+ place_only = STEdge(src="Alice", dst="Bob", rel="visit", place="Office")
+ neither = STEdge(src="Alice", dst="Bob", rel="know")
+
+ kg._edge_memory.add([time_only, place_only, neither])
+
+ # All should be added (different combinations)
+ assert kg._edge_memory.size >= 2
diff --git a/tests/types/test_temporal_graph.py b/tests/types/test_temporal_graph.py
new file mode 100644
index 0000000..81d556c
--- /dev/null
+++ b/tests/types/test_temporal_graph.py
@@ -0,0 +1,243 @@
+"""Tests for AutoTemporalGraph - temporal graph extraction with time-aware deduplication."""
+
+import pytest
+from pydantic import BaseModel, Field
+from typing import Optional, Tuple
+from datetime import datetime, timedelta
+from ontomem.merger import MergeStrategy
+from hyperextract.types.temporal_graph import AutoTemporalGraph
+
+
+class Entity(BaseModel):
+ """Test schema for temporal graph nodes."""
+
+ name: str = Field(default="", description="Entity name")
+
+
+class TemporalEdge(BaseModel):
+ """Test schema for temporal edges."""
+
+ src: str = Field(default="", description="Source entity")
+ dst: str = Field(default="", description="Target entity")
+ rel: str = Field(default="", description="Relationship type")
+ year: Optional[str] = Field(default=None, description="Year of relationship")
+
+
+class TestAutoTemporalGraphBasics:
+ """Test basic AutoTemporalGraph functionality."""
+
+ def test_initialization_with_default_time(self, llm_client, embedder):
+ """Test AutoTemporalGraph initialization with default observation_time."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Should have default observation_time (today)
+ assert kg.observation_time is not None
+ assert len(kg.observation_time) == 10 # YYYY-MM-DD format
+
+ def test_initialization_with_custom_time(self, llm_client, embedder):
+ """Test AutoTemporalGraph initialization with custom observation_time."""
+ custom_time = "2024-06-15"
+
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_time=custom_time,
+ )
+
+ assert kg.observation_time == custom_time
+
+
+class TestAutoTemporalGraphTimeInjection:
+ """Test that observation_time is properly injected into prompts."""
+
+ def test_observation_time_in_edge_prompt(self, llm_client, embedder):
+ """Test that observation_time is included in edge extraction prompt."""
+ observation_time = "2023-01-01"
+
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_time=observation_time,
+ )
+
+ # The observation_time should be in the prompt template
+ assert observation_time == kg.observation_time
+ assert "{observation_time}" in kg.edge_prompt or observation_time in kg.prompt
+
+ def test_observation_time_in_graph_prompt(self, llm_client, embedder):
+ """Test that observation_time is in the full graph extraction prompt."""
+ observation_time = "2024-12-25"
+
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ observation_time=observation_time,
+ )
+
+ assert observation_time == kg.observation_time
+
+
+class TestAutoTemporalGraphKeyGeneration:
+ """Test temporal edge key generation."""
+
+ def test_edge_key_includes_time(self, llm_client, embedder):
+ """Test that edge keys differentiate based on time."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # The internal edge_key_extractor should combine base key and time
+ # Testing the logic of what the actual implementation does
+
+ edge1 = TemporalEdge(src="Alice", dst="Bob", rel="friend", year="2020")
+ edge2 = TemporalEdge(src="Alice", dst="Bob", rel="friend", year="2021")
+ edge3 = TemporalEdge(src="Alice", dst="Bob", rel="friend")
+
+ # Due to the composite key logic, edges with different years should have different keys
+ # And edge without time should be different from edges with time
+
+ # We can test this by adding them to the edge memory
+ kg._edge_memory.add([edge1, edge2, edge3])
+
+ # Should have 3 unique edges (all different times)
+ assert kg._edge_memory.size >= 2 # At least different from no-time case
+
+
+class TestAutoTemporalGraphExtraction:
+ """Test temporal graph extraction."""
+
+ def test_feed_text_two_stage(self, llm_client, embedder):
+ """Test feeding text in two-stage extraction mode."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode="two_stage",
+ )
+
+ kg.feed_text("In 2020, Alice collaborated with Bob on a research project.")
+
+ assert not kg.empty()
+ assert len(kg.data.nodes) > 0
+
+ def test_extract_creates_new_instance(self, llm_client, embedder):
+ """Test extract() creates new instance."""
+ kg1 = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ kg2 = kg1.extract("""ProjectX timeline: Q1 2023 requirements gathering with stakeholders,
+ Q2 2023 architecture design phase, Q3 2023 development sprint cycles,
+ Q4 2023 beta testing and Q1 2024 production launch.""")
+
+ assert kg1 is not kg2
+ assert kg1.empty() is True
+ assert kg2.empty() is False
+
+
+class TestAutoTemporalGraphPrompts:
+ """Test temporal prompt construction."""
+
+ def test_node_prompt_excludes_dates(self, llm_client, embedder):
+ """Test that node extraction prompt instructs NOT to extract dates."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Node prompt should warn not to extract dates
+ assert "date" in kg.node_prompt.lower() or "time" in kg.node_prompt.lower()
+
+ def test_edge_prompt_includes_relative_time_rules(self, llm_client, embedder):
+ """Test that edge prompt includes relative time resolution rules."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Edge prompt should contain rules about relative time
+ assert "relative time" in kg.edge_prompt.lower() or "observation" in kg.edge_prompt.lower()
+
+
+class TestAutoTemporalGraphConsistency:
+ """Test consistency between nodes and edges."""
+
+ def test_temporal_edge_participants_are_validated(self, llm_client, embedder):
+ """Test that temporal edges reference existing nodes."""
+ kg = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=TemporalEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.src}-{x.rel}-{x.dst}",
+ time_in_edge_extractor=lambda x: x.year or "",
+ nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ llm_client=llm_client,
+ embedder=embedder,
+ )
+
+ # Create nodes
+ kg._node_memory.add([Entity(name="Alice"), Entity(name="Bob")])
+
+ # Create valid edges (participants exist)
+ valid_edge = TemporalEdge(src="Alice", dst="Bob", rel="knows", year="2022")
+ kg._edge_memory.add([valid_edge])
+
+ assert kg._edge_memory.size > 0