Skip to content

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

fix: persist temporal/spatial observation context in metadata

Frankie-Xu5a8256201af7
diff --git a/hyperextract/methods/typical/atom.py b/hyperextract/methods/typical/atom.py
index 991ef9b..09b801d 100644
--- a/hyperextract/methods/typical/atom.py
+++ b/hyperextract/methods/typical/atom.py
@@ -396,6 +396,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
max_workers=max_workers,
verbose=verbose,
)
+ self.metadata["observation_time"] = self.observation_time
# ==================== Extraction Pipeline ====================
diff --git a/hyperextract/types/base.py b/hyperextract/types/base.py
index ae64cb4..275bbb5 100644
--- a/hyperextract/types/base.py
+++ b/hyperextract/types/base.py
@@ -739,6 +739,16 @@ class BaseAutoType(ABC, Generic[T]):
pass
self.metadata.update(params)
+ self._restore_observation_context()
+
+ def _restore_observation_context(self) -> None:
+ """Copy persisted observation fields back onto instance attributes."""
+ if "observation_time" in self.metadata and hasattr(self, "observation_time"):
+ self.observation_time = self.metadata["observation_time"]
+ if "observation_location" in self.metadata and hasattr(
+ self, "observation_location"
+ ):
+ self.observation_location = self.metadata["observation_location"]
@abstractmethod
def dump_index(self, folder_path: str | Path) -> None:
diff --git a/hyperextract/types/spatial_graph.py b/hyperextract/types/spatial_graph.py
index b351631..20576e7 100644
--- a/hyperextract/types/spatial_graph.py
+++ b/hyperextract/types/spatial_graph.py
@@ -245,6 +245,7 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
edge_fields_for_index=edge_fields_for_index,
**kwargs,
)
+ self.metadata["observation_location"] = self.observation_location
# ==============================================================================
# Override Extraction Methods to Dynamically Inject Observation Location
diff --git a/hyperextract/types/spatio_temporal_graph.py b/hyperextract/types/spatio_temporal_graph.py
index 08b09f8..8776c07 100644
--- a/hyperextract/types/spatio_temporal_graph.py
+++ b/hyperextract/types/spatio_temporal_graph.py
@@ -261,6 +261,8 @@ class AutoSpatioTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
edge_fields_for_index=edge_fields_for_index,
**kwargs,
)
+ self.metadata["observation_time"] = self.observation_time
+ self.metadata["observation_location"] = self.observation_location
# ==============================================================================
# Override Extraction Methods to Dynamically Inject Context
diff --git a/hyperextract/types/temporal_graph.py b/hyperextract/types/temporal_graph.py
index cce4ac0..e138a5c 100644
--- a/hyperextract/types/temporal_graph.py
+++ b/hyperextract/types/temporal_graph.py
@@ -262,6 +262,7 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
edge_fields_for_index=edge_fields_for_index,
**kwargs,
)
+ self.metadata["observation_time"] = self.observation_time
# ==============================================================================
# Override Extraction Methods to Dynamically Inject Observation Date
diff --git a/tests/types/test_observation_roundtrip.py b/tests/types/test_observation_roundtrip.py
new file mode 100644
index 0000000..cf57333
--- /dev/null
+++ b/tests/types/test_observation_roundtrip.py
@@ -0,0 +1,171 @@
+"""Observation time/location must survive dump/load (not just live on the instance)."""
+
+import json
+
+from pydantic import BaseModel, Field
+
+from hyperextract.methods.typical.atom import Atom
+from hyperextract.types import (
+ AutoSpatialGraph,
+ AutoSpatioTemporalGraph,
+ AutoTemporalGraph,
+)
+from tests.mocks import MockChatModel, MockEmbeddings
+
+
+class Entity(BaseModel):
+ name: str
+ type: str = "ENTITY"
+ properties: dict = Field(default_factory=dict)
+
+
+class Relation(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+
+
+OBS_TIME = "2020-01-01"
+OBS_LOCATION = "Beijing"
+
+
+class _RecordingExtractor:
+ """Edge-extractor stub that records batch inputs."""
+
+ def __init__(self, empty_factory):
+ self.seen_inputs: list[dict] = []
+ self.empty_factory = empty_factory
+
+ def batch(self, inputs, config=None, return_exceptions=False, **kwargs):
+ self.seen_inputs.extend(inputs)
+ return [self.empty_factory() for _ in inputs]
+
+
+def _assert_edge_inputs_carry(loaded, **expected):
+ recorder = _RecordingExtractor(lambda: loaded.edge_list_schema(items=[]))
+ loaded.edge_extractor = recorder
+ nodes = loaded.node_list_schema(items=[Entity(name="Alice")])
+ loaded._extract_edges_batch(["Alice met Bob yesterday."], [nodes])
+ assert recorder.seen_inputs
+ for key, value in expected.items():
+ assert all(inp.get(key) == value for inp in recorder.seen_inputs)
+
+
+def _graph_kwargs():
+ return dict(
+ 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=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+
+
+def _assert_not_in_data_json(folder):
+ data = json.loads((folder / "data.json").read_text(encoding="utf-8"))
+ blob = json.dumps(data)
+ assert "observation_time" not in blob
+ assert "observation_location" not in blob
+
+
+def test_temporal_graph_observation_time_roundtrip(tmp_path):
+ original = AutoTemporalGraph(
+ **_graph_kwargs(),
+ time_in_edge_extractor=lambda x: "",
+ observation_time=OBS_TIME,
+ )
+ dest = tmp_path / "temporal"
+ original.dump(dest)
+
+ meta = json.loads((dest / "metadata.json").read_text(encoding="utf-8"))
+ assert meta["observation_time"] == OBS_TIME
+ _assert_not_in_data_json(dest)
+
+ loaded = AutoTemporalGraph(
+ **_graph_kwargs(),
+ time_in_edge_extractor=lambda x: "",
+ )
+ loaded.load(dest)
+
+ assert loaded.observation_time == OBS_TIME
+ assert loaded.metadata["observation_time"] == OBS_TIME
+ _assert_edge_inputs_carry(loaded, observation_time=OBS_TIME)
+
+
+def test_spatial_graph_observation_location_roundtrip(tmp_path):
+ original = AutoSpatialGraph(
+ **_graph_kwargs(),
+ location_in_edge_extractor=lambda x: "",
+ observation_location=OBS_LOCATION,
+ )
+ dest = tmp_path / "spatial"
+ original.dump(dest)
+
+ meta = json.loads((dest / "metadata.json").read_text(encoding="utf-8"))
+ assert meta["observation_location"] == OBS_LOCATION
+ _assert_not_in_data_json(dest)
+
+ loaded = AutoSpatialGraph(
+ **_graph_kwargs(),
+ location_in_edge_extractor=lambda x: "",
+ )
+ loaded.load(dest)
+
+ assert loaded.observation_location == OBS_LOCATION
+ assert loaded.metadata["observation_location"] == OBS_LOCATION
+ _assert_edge_inputs_carry(loaded, observation_location=OBS_LOCATION)
+
+
+def test_spatio_temporal_graph_observation_roundtrip(tmp_path):
+ original = AutoSpatioTemporalGraph(
+ **_graph_kwargs(),
+ time_in_edge_extractor=lambda x: "",
+ location_in_edge_extractor=lambda x: "",
+ observation_time=OBS_TIME,
+ observation_location=OBS_LOCATION,
+ )
+ dest = tmp_path / "st"
+ original.dump(dest)
+
+ meta = json.loads((dest / "metadata.json").read_text(encoding="utf-8"))
+ assert meta["observation_time"] == OBS_TIME
+ assert meta["observation_location"] == OBS_LOCATION
+ _assert_not_in_data_json(dest)
+
+ loaded = AutoSpatioTemporalGraph(
+ **_graph_kwargs(),
+ time_in_edge_extractor=lambda x: "",
+ location_in_edge_extractor=lambda x: "",
+ )
+ loaded.load(dest)
+
+ assert loaded.observation_time == OBS_TIME
+ assert loaded.observation_location == OBS_LOCATION
+ _assert_edge_inputs_carry(
+ loaded, observation_time=OBS_TIME, observation_location=OBS_LOCATION
+ )
+
+
+def test_atom_observation_time_roundtrip(tmp_path):
+ original = Atom(
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ observation_time=OBS_TIME,
+ )
+ dest = tmp_path / "atom"
+ original.dump(dest)
+
+ meta = json.loads((dest / "metadata.json").read_text(encoding="utf-8"))
+ assert meta["observation_time"] == OBS_TIME
+ _assert_not_in_data_json(dest)
+
+ loaded = Atom(
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+ loaded.load(dest)
+
+ assert loaded.observation_time == OBS_TIME
+ assert loaded.metadata["observation_time"] == OBS_TIME