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: isolate per-chunk extraction failures in graph-family AutoTypes

yifanfeng972e8c7736d095
diff --git a/hyperextract/types/base.py b/hyperextract/types/base.py
index d89d3bf..52711fb 100644
--- a/hyperextract/types/base.py
+++ b/hyperextract/types/base.py
@@ -251,13 +251,9 @@ class BaseAutoType(ABC, Generic[T]):
if len(text) <= self.chunk_size:
logger.debug("stage=extract_single_chunk chunk_text_preview=%s", text[:200])
- try:
- extracted_data = self.data_extractor.invoke({"source_text": text})
- except Exception as e:
- # LLM returned unparseable output (e.g. prose instead of JSON).
- # Log and treat as an empty result instead of crashing the run.
- logger.warning("stage=extract_single_chunk_failed error=%s", e)
- extracted_data = None
+ extracted_data = self._invoke_safe(
+ self.data_extractor, {"source_text": text}, stage="extract"
+ )
logger.debug(
"stage=extract_single_chunk_result chunk=0 result_summary=%s",
self._summarize_extracted(extracted_data),
@@ -279,22 +275,9 @@ class BaseAutoType(ABC, Generic[T]):
self.max_workers,
len(inputs),
)
- # return_exceptions keeps one bad chunk from aborting the whole batch;
- # failures are logged and nulled (then filtered) below.
- extracted_data_list = self.data_extractor.batch(
- inputs,
- config={"max_concurrency": self.max_workers},
- return_exceptions=True,
+ extracted_data_list = self._batch_safe(
+ self.data_extractor, inputs, stage="extract"
)
- cleaned = []
- for i, r in enumerate(extracted_data_list):
- if isinstance(r, Exception):
- logger.warning(
- "stage=chunk_extract_failed chunk_index=%d error=%s", i, r
- )
- r = None
- cleaned.append(r)
- extracted_data_list = cleaned
logger.debug(
"stage=llm_batch_complete results=%d", len(extracted_data_list)
)
@@ -346,6 +329,54 @@ class BaseAutoType(ABC, Generic[T]):
return [r for r in results if r is not None]
return results
+ def _invoke_safe(self, extractor, input: dict, *, stage: str):
+ """invoke() with provider failures logged and nulled instead of raised.
+
+ One bad chunk (rate limit, timeout, unparseable output) must not abort
+ the whole run — failures degrade to None, matching _extract_data's
+ contract. Logs the stage and exception only, never the source text.
+
+ Args:
+ extractor: Runnable with an ``invoke`` method.
+ input: Input dict for the extractor.
+ stage: Stage label used in log lines (e.g. ``"one_stage"``).
+
+ Returns:
+ The extractor result, or None if it raised.
+ """
+ try:
+ return extractor.invoke(input)
+ except Exception as e:
+ logger.warning("stage=%s_single_extract_failed error=%s", stage, e)
+ return None
+
+ def _batch_safe(self, extractor, inputs: list[dict], *, stage: str) -> list:
+ """batch() with return_exceptions=True; per-chunk failures logged and nulled.
+
+ Args:
+ extractor: Runnable with a ``batch`` method.
+ inputs: List of input dicts, one per chunk.
+ stage: Stage label used in log lines (e.g. ``"two_stage_nodes"``).
+
+ Returns:
+ List aligned with ``inputs``; failed chunks are None.
+ """
+ raw = extractor.batch(
+ inputs,
+ config={"max_concurrency": self.max_workers},
+ return_exceptions=True,
+ )
+ results: list = []
+ for i, r in enumerate(raw):
+ if isinstance(r, Exception):
+ logger.warning(
+ "stage=%s_chunk_extract_failed chunk_index=%d error=%s", stage, i, r
+ )
+ results.append(None)
+ else:
+ results.append(r)
+ return results
+
def _summarize_extracted(self, data: T) -> str:
"""Return a concise summary of extracted data for debug logging."""
try:
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index 8995e43..7697068 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -483,8 +483,13 @@ class AutoGraph(
if len(text) <= self.chunk_size:
logger.debug("stage=one_stage_single_invoke")
- graph = self.data_extractor.invoke({"source_text": text})
- graph_list = [graph]
+ graph = self._invoke_safe(
+ self.data_extractor, {"source_text": text}, stage="one_stage"
+ )
+ graph_list = self._filter_none_results(
+ [graph],
+ default_factory=lambda: self.graph_schema(nodes=[], edges=[]),
+ )
else:
chunks = self.text_splitter.split_text(text)
logger.debug("stage=one_stage_split num_chunks=%d", len(chunks))
@@ -492,8 +497,8 @@ class AutoGraph(
logger.debug(
"stage=one_stage_batch_start max_concurrency=%d", self.max_workers
)
- graph_list = self.data_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
+ graph_list = self._batch_safe(
+ self.data_extractor, inputs, stage="one_stage"
)
graph_list = self._filter_none_results(
graph_list,
@@ -537,9 +542,9 @@ class AutoGraph(
chunks = self.text_splitter.split_text(text)
logger.debug("stage=two_stage_chunks num_chunks=%d", len(chunks))
- # 2. Batch Extract Nodes (returns List[NodeListSchema])
+ # 2. Batch Extract Nodes (returns List[NodeListSchema] + per-chunk failure mask)
logger.debug("stage=two_stage_node_extraction_start")
- chunk_node_lists = self._extract_nodes_batch(chunks)
+ chunk_node_lists, node_failed = self._extract_nodes_batch(chunks)
total_nodes = sum(len(nl.items) for nl in chunk_node_lists)
logger.debug(
"stage=two_stage_node_extraction_complete chunks=%d total_nodes=%d",
@@ -547,9 +552,25 @@ class AutoGraph(
total_nodes,
)
- # 3. Batch Extract Edges (Context-aware, returns List[EdgeListSchema])
+ # 3. Batch Extract Edges (Context-aware, returns List[EdgeListSchema]).
+ # Chunks whose node extraction failed are skipped — do not prompt the
+ # LLM with an empty node list. Results are padded back to the full
+ # chunk length because merge_batch_data zips the node/edge lists.
logger.debug("stage=two_stage_edge_extraction_start")
- chunk_edge_lists = self._extract_edges_batch(chunks, chunk_node_lists)
+ edge_indices = [i for i, failed in enumerate(node_failed) if not failed]
+ edge_results = (
+ self._extract_edges_batch(
+ [chunks[i] for i in edge_indices],
+ [chunk_node_lists[i] for i in edge_indices],
+ )
+ if edge_indices
+ else []
+ )
+ pending_edges = iter(edge_results)
+ chunk_edge_lists = [
+ next(pending_edges) if not failed else self.edge_list_schema(items=[])
+ for failed in node_failed
+ ]
total_edges = sum(len(el.items) for el in chunk_edge_lists)
logger.debug(
"stage=two_stage_edge_extraction_complete chunks=%d total_edges=%d",
@@ -575,23 +596,24 @@ class AutoGraph(
def _extract_nodes_batch(
self, chunks: list[str]
- ) -> list[NodeListSchema[NodeSchema]]:
+ ) -> tuple[list[NodeListSchema[NodeSchema]], list[bool]]:
"""Batch extract nodes from multiple text chunks.
Args:
chunks: List of text chunks.
Returns:
- List of NodeListSchema objects with extracted nodes.
+ Tuple of (node list schemas aligned with chunks, per-chunk failure
+ mask where True marks a chunk whose node extraction failed).
"""
inputs = [{"source_text": chunk} for chunk in chunks]
- results = self.node_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
- return self._filter_none_results(
+ results = self._batch_safe(self.node_extractor, inputs, stage="two_stage_nodes")
+ node_failed = [r is None for r in results]
+ node_lists = self._filter_none_results(
results,
default_factory=lambda: self.node_list_schema(items=[]),
)
+ return node_lists, node_failed
def _extract_edges_batch(
self, chunks: list[str], node_lists: list[NodeListSchema[NodeSchema]]
@@ -616,9 +638,7 @@ class AutoGraph(
inputs.append({"source_text": chunk, "known_nodes": known_nodes})
- results = self.edge_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
+ results = self._batch_safe(self.edge_extractor, inputs, stage="two_stage_edges")
return self._filter_none_results(
results,
default_factory=lambda: self.edge_list_schema(items=[]),
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index d4bfe22..959a665 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -455,13 +455,18 @@ class AutoHypergraph(
"""
# Extract from single chunk or multiple chunks
if len(text) <= self.chunk_size:
- graph = self.data_extractor.invoke({"source_text": text})
- graph_list = [graph]
+ graph = self._invoke_safe(
+ self.data_extractor, {"source_text": text}, stage="one_stage"
+ )
+ graph_list = self._filter_none_results(
+ [graph],
+ default_factory=lambda: self.graph_schema(nodes=[], edges=[]),
+ )
else:
chunks = self.text_splitter.split_text(text)
inputs = [{"source_text": chunk} for chunk in chunks]
- graph_list = self.data_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
+ graph_list = self._batch_safe(
+ self.data_extractor, inputs, stage="one_stage"
)
graph_list = self._filter_none_results(
graph_list,
@@ -489,11 +494,27 @@ class AutoHypergraph(
if self.verbose:
logger.info(f"Extracting from {len(chunks)} chunks...")
- # 2. Batch Extract Nodes
- chunk_node_lists = self._extract_nodes_batch(chunks)
-
- # 3. Batch Extract Hyperedges (Context-aware)
- chunk_edge_lists = self._extract_edges_batch(chunks, chunk_node_lists)
+ # 2. Batch Extract Nodes (returns node lists + per-chunk failure mask)
+ chunk_node_lists, node_failed = self._extract_nodes_batch(chunks)
+
+ # 3. Batch Extract Hyperedges (Context-aware). Chunks whose node
+ # extraction failed are skipped — do not prompt the LLM with an empty
+ # node list. Results are padded back to the full chunk length because
+ # merge_batch_data zips the node/edge lists.
+ edge_indices = [i for i, failed in enumerate(node_failed) if not failed]
+ edge_results = (
+ self._extract_edges_batch(
+ [chunks[i] for i in edge_indices],
+ [chunk_node_lists[i] for i in edge_indices],
+ )
+ if edge_indices
+ else []
+ )
+ pending_edges = iter(edge_results)
+ chunk_edge_lists = [
+ next(pending_edges) if not failed else self.edge_list_schema(items=[])
+ for failed in node_failed
+ ]
# 4. Construct Partial Graphs (Tuple format for merge optimization)
partial_hypergraphs = (
@@ -506,16 +527,21 @@ class AutoHypergraph(
def _extract_nodes_batch(
self, chunks: list[str]
- ) -> list[NodeListSchema[NodeSchema]]:
- """Batch extract nodes from multiple text chunks."""
+ ) -> tuple[list[NodeListSchema[NodeSchema]], list[bool]]:
+ """Batch extract nodes from multiple text chunks.
+
+ Returns:
+ Tuple of (node list schemas aligned with chunks, per-chunk failure
+ mask where True marks a chunk whose node extraction failed).
+ """
inputs = [{"source_text": chunk} for chunk in chunks]
- results = self.node_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
- return self._filter_none_results(
+ results = self._batch_safe(self.node_extractor, inputs, stage="two_stage_nodes")
+ node_failed = [r is None for r in results]
+ node_lists = self._filter_none_results(
results,
default_factory=lambda: self.node_list_schema(items=[]),
)
+ return node_lists, node_failed
def _extract_edges_batch(
self, chunks: list[str], node_lists: list[NodeListSchema[NodeSchema]]
@@ -532,9 +558,7 @@ class AutoHypergraph(
inputs.append({"source_text": chunk, "known_nodes": known_nodes})
- results = self.edge_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
+ results = self._batch_safe(self.edge_extractor, inputs, stage="two_stage_edges")
return self._filter_none_results(
results,
default_factory=lambda: self.edge_list_schema(items=[]),
diff --git a/hyperextract/types/spatial_graph.py b/hyperextract/types/spatial_graph.py
index 70e410c..4c34125 100644
--- a/hyperextract/types/spatial_graph.py
+++ b/hyperextract/types/spatial_graph.py
@@ -271,9 +271,7 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
}
)
- results = self.edge_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
+ results = self._batch_safe(self.edge_extractor, inputs, stage="two_stage_edges")
return self._filter_none_results(
results,
default_factory=lambda: self.edge_list_schema(items=[]),
@@ -287,8 +285,11 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
"source_text": text,
"observation_location": self.observation_location,
}
- graph = self.data_extractor.invoke(inp)
- graph_list = [graph]
+ graph = self._invoke_safe(self.data_extractor, inp, stage="one_stage")
+ graph_list = self._filter_none_results(
+ [graph],
+ default_factory=lambda: self.graph_schema(nodes=[], edges=[]),
+ )
else:
chunks = self.text_splitter.split_text(text)
inputs = [
@@ -298,8 +299,8 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
}
for chunk in chunks
]
- graph_list = self.data_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
+ graph_list = self._batch_safe(
+ self.data_extractor, inputs, stage="one_stage"
)
graph_list = self._filter_none_results(
graph_list,
diff --git a/hyperextract/types/spatio_temporal_graph.py b/hyperextract/types/spatio_temporal_graph.py
index 7473a08..6fca415 100644
--- a/hyperextract/types/spatio_temporal_graph.py
+++ b/hyperextract/types/spatio_temporal_graph.py
@@ -288,9 +288,7 @@ class AutoSpatioTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
}
)
- results = self.edge_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
+ results = self._batch_safe(self.edge_extractor, inputs, stage="two_stage_edges")
return self._filter_none_results(
results,
default_factory=lambda: self.edge_list_schema(items=[]),
@@ -305,8 +303,11 @@ class AutoSpatioTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
"observation_time": self.observation_time,
"observation_location": self.observation_location,
}
- graph = self.data_extractor.invoke(inp)
- graph_list = [graph]
+ graph = self._invoke_safe(self.data_extractor, inp, stage="one_stage")
+ graph_list = self._filter_none_results(
+ [graph],
+ default_factory=lambda: self.graph_schema(nodes=[], edges=[]),
+ )
else:
chunks = self.text_splitter.split_text(text)
inputs = [
@@ -317,8 +318,8 @@ class AutoSpatioTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
}
for chunk in chunks
]
- graph_list = self.data_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
+ graph_list = self._batch_safe(
+ self.data_extractor, inputs, stage="one_stage"
)
graph_list = self._filter_none_results(
graph_list,
diff --git a/hyperextract/types/temporal_graph.py b/hyperextract/types/temporal_graph.py
index 96134dd..b5bd97f 100644
--- a/hyperextract/types/temporal_graph.py
+++ b/hyperextract/types/temporal_graph.py
@@ -288,9 +288,7 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
}
)
- results = self.edge_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
- )
+ results = self._batch_safe(self.edge_extractor, inputs, stage="two_stage_edges")
return self._filter_none_results(
results,
default_factory=lambda: self.edge_list_schema(items=[]),
@@ -301,16 +299,19 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
if len(text) <= self.chunk_size:
inp = {"source_text": text, "observation_time": self.observation_time}
- graph = self.data_extractor.invoke(inp)
- graph_list = [graph]
+ graph = self._invoke_safe(self.data_extractor, inp, stage="one_stage")
+ graph_list = self._filter_none_results(
+ [graph],
+ default_factory=lambda: self.graph_schema(nodes=[], edges=[]),
+ )
else:
chunks = self.text_splitter.split_text(text)
inputs = [
{"source_text": chunk, "observation_time": self.observation_time}
for chunk in chunks
]
- graph_list = self.data_extractor.batch(
- inputs, config={"max_concurrency": self.max_workers}
+ graph_list = self._batch_safe(
+ self.data_extractor, inputs, stage="one_stage"
)
graph_list = self._filter_none_results(
graph_list,
diff --git a/tests/types/test_graph_failure_isolation.py b/tests/types/test_graph_failure_isolation.py
new file mode 100644
index 0000000..de47880
--- /dev/null
+++ b/tests/types/test_graph_failure_isolation.py
@@ -0,0 +1,332 @@
+"""Graph-family extraction isolates per-chunk LLM failures (issue #78).
+
+BaseAutoType already treats one bad chunk as a partial result; the graph-family
+overrides (one-stage invoke/batch, two-stage node/edge batches) previously let
+a single provider error (rate limit, timeout, unparseable output) abort the
+whole run and discard every other chunk's data. These tests pin the contract:
+
+- one-stage single/batch paths survive chunk failures (empty result, no raise)
+- two-stage skips edge extraction for chunks whose node extraction failed
+ (no wasted LLM call with an empty node list) while keeping merge alignment
+- observation time/location injection keeps working for the spatiotemporal
+ subclasses alongside the isolation
+"""
+
+
+
+from pydantic import BaseModel, Field
+
+from hyperextract.types import AutoGraph, AutoHypergraph, AutoTemporalGraph
+from tests.mocks import MockChatModel, MockEmbeddings
+
+
+class Entity(BaseModel):
+ """Simple node schema for testing."""
+
+ name: str
+ type: str = "ENTITY"
+ properties: dict = Field(default_factory=dict)
+
+
+class Relation(BaseModel):
+ """Simple edge schema for testing."""
+
+ source: str
+ target: str
+ relation_type: str
+
+
+class HyperRelation(BaseModel):
+ """Simple hyperedge schema for testing."""
+
+ participants: list[str] = Field(default_factory=list)
+ relation_type: str = "related"
+
+
+LONG_TEXT = "sentence about entities. " * 100 # forces multi-chunk at small chunk_size
+
+
+class _FlakyBatch:
+ """Extractor stub that fails odd-index chunks.
+
+ Mirrors the Runnable.batch contract: with return_exceptions=True failures
+ come back as exceptions in the list; without it the first failure raises.
+ """
+
+ def __init__(self, ok_factory):
+ self.ok_factory = ok_factory
+ self.batch_sizes = [] # number of inputs per batch() call
+
+ def invoke(self, _input, config=None):
+ return self.ok_factory(0)
+
+ def batch(self, inputs, config=None, return_exceptions=False, **kwargs):
+ self.batch_sizes.append(len(inputs))
+ results = []
+ for i in range(len(inputs)):
+ if i % 2 == 1:
+ err = RuntimeError(f"429 rate limit on chunk {i}")
+ if return_exceptions:
+ results.append(err)
+ else:
+ raise err
+ else:
+ results.append(self.ok_factory(i))
+ return results
+
+
+class _InvokeFails:
+ """Extractor stub whose invoke() always raises (unparseable LLM output)."""
+
+ def invoke(self, _input, config=None):
+ raise ValueError("Invalid JSON: expected value at line 1 column 1")
+
+ def batch(self, inputs, config=None, return_exceptions=False, **kwargs):
+ raise AssertionError("batch() not expected on the single-chunk path")
+
+
+class _RecordingEdgeExtractor:
+ """Edge-extractor stub recording every batch input it is given."""
+
+ def __init__(self, empty_factory):
+ self.seen_inputs = []
+ self.empty_factory = empty_factory # returns an empty EdgeListSchema
+
+ def invoke(self, _input, config=None):
+ raise AssertionError("invoke() not expected in two-stage edge extraction")
+
+ def batch(self, inputs, config=None, return_exceptions=False, **kwargs):
+ self.seen_inputs.extend(inputs)
+ return [self.empty_factory() for _ in inputs]
+
+
+def _graph(extraction_mode="one_stage", chunk_size=64):
+ g = 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=MockChatModel(),
+ embedder=MockEmbeddings(),
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=16,
+ )
+ return g
+
+
+def _hypergraph(extraction_mode="one_stage", chunk_size=64):
+ h = AutoHypergraph(
+ node_schema=Entity,
+ edge_schema=HyperRelation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.relation_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=16,
+ )
+ return h
+
+
+class TestOneStageIsolation:
+ """One-stage extraction survives per-chunk provider failures."""
+
+ def test_multi_chunk_batch_failure_keeps_good_chunks(self):
+ g = _graph()
+ g.data_extractor = _FlakyBatch(
+ lambda i: g.graph_schema(nodes=[Entity(name=f"N{i}")], edges=[])
+ )
+
+ result = g.parse(LONG_TEXT)
+
+ names = {n.name for n in result.nodes}
+ # Even-index chunks must survive; odd ones failed with a 429.
+ assert "N0" in names
+ assert "N2" in names
+ assert all(not n.name.endswith(("1", "3", "5", "7", "9")) for n in result.nodes)
+
+ def test_single_chunk_invoke_failure_yields_empty_result(self):
+ g = _graph(chunk_size=100_000) # short text -> single invoke() path
+ g.data_extractor = _InvokeFails()
+
+ result = g.parse("a short biography text")
+
+ assert result.empty()
+
+
+class TestTwoStageIsolation:
+ """Two-stage extraction isolates node/edge batch failures."""
+
+ def test_node_failure_skips_edge_llm_call(self):
+ g = _graph(extraction_mode="two_stage")
+ g.node_extractor = _FlakyBatch(
+ lambda i: g.node_list_schema(items=[Entity(name=f"N{i}")])
+ )
+ edge_stub = _RecordingEdgeExtractor(lambda: g.edge_list_schema(items=[]))
+ g.edge_extractor = edge_stub
+
+ result = g.parse(LONG_TEXT)
+
+ node_batches = g.node_extractor.batch_sizes
+ assert node_batches and node_batches[0] >= 2 # multi-chunk run
+
+ # Chunks are len(chunks); failed (odd) ones must not reach the LLM.
+ num_chunks = node_batches[0]
+ expected_edge_inputs = (num_chunks + 1) // 2 # even indices only
+ assert len(edge_stub.seen_inputs) == expected_edge_inputs
+
+ # Nodes from the successful chunks are still merged in.
+ names = {n.name for n in result.nodes}
+ assert "N0" in names
+
+ def test_edge_batch_failure_degrades_to_nodes_only(self):
+ g = _graph(extraction_mode="two_stage")
+ g.node_extractor = _FlakyBatch(
+ lambda i: g.node_list_schema(items=[Entity(name=f"N{i}")])
+ )
+ g.edge_extractor = _FlakyBatch(lambda i: g.edge_list_schema(items=[]))
+
+ result = g.parse(LONG_TEXT)
+
+ # Edges all failed (odd) or were empty (even), but nodes survive.
+ names = {n.name for n in result.nodes}
+ assert "N0" in names and "N2" in names
+
+
+class TestHypergraphIsolation:
+ """AutoHypergraph mirrors the graph-family isolation contract."""
+
+ def test_one_stage_batch_failure_keeps_good_chunks(self):
+ h = _hypergraph()
+ h.data_extractor = _FlakyBatch(
+ lambda i: h.graph_schema(
+ nodes=[Entity(name=f"H{i}")],
+ edges=[HyperRelation(participants=[f"H{i}"], relation_type="rel")],
+ )
+ )
+
+ result = h.parse(LONG_TEXT)
+
+ names = {n.name for n in result.nodes}
+ assert "H0" in names and "H2" in names
+
+ def test_two_stage_node_failure_skips_edge_llm_call(self):
+ h = _hypergraph(extraction_mode="two_stage")
+ h.node_extractor = _FlakyBatch(
+ lambda i: h.node_list_schema(items=[Entity(name=f"H{i}")])
+ )
+ edge_stub = _RecordingEdgeExtractor(lambda: h.edge_list_schema(items=[]))
+ h.edge_extractor = edge_stub
+
+ result = h.parse(LONG_TEXT)
+
+ num_chunks = h.node_extractor.batch_sizes[0]
+ expected_edge_inputs = (num_chunks + 1) // 2
+ assert len(edge_stub.seen_inputs) == expected_edge_inputs
+ assert "H0" in {n.name for n in result.nodes}
+
+
+class TestTemporalInjectionWithIsolation:
+ """Spatiotemporal subclasses keep observation_time injection while isolating."""
+
+ def _temporal_graph(self, extraction_mode="two_stage", chunk_size=64):
+ g = AutoTemporalGraph(
+ 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}",
+ time_in_edge_extractor=lambda x: "",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ observation_time="2026-09-01",
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=16,
+ )
+ return g
+
+ def test_two_stage_edge_inputs_keep_observation_time(self):
+ g = self._temporal_graph()
+ g.node_extractor = _FlakyBatch(
+ lambda i: g.node_list_schema(items=[Entity(name=f"T{i}")])
+ )
+ edge_stub = _RecordingEdgeExtractor(lambda: g.edge_list_schema(items=[]))
+ g.edge_extractor = edge_stub
+
+ g.parse(LONG_TEXT)
+
+ assert edge_stub.seen_inputs
+ assert all(
+ inp.get("observation_time") == "2026-09-01" for inp in edge_stub.seen_inputs
+ )
+
+ def test_one_stage_failure_survives_with_injection(self):
+ g = self._temporal_graph(extraction_mode="one_stage")
+
+ recorded = {}
+
+ class _Probe:
+ def invoke(self, inp, config=None):
+ recorded.update(inp)
+ raise ValueError("429")
+
+ def batch(self, inputs, config=None, return_exceptions=False, **kwargs):
+ recorded.update(inputs[0])
+ if return_exceptions:
+ return [ValueError("429")] * len(inputs)
+ raise ValueError("429")
+
+ g.data_extractor = _Probe()
+
+ result = g.parse(LONG_TEXT)
+
+ # Injection still happens on the failed call, and the run survives.
+ assert recorded.get("observation_time") == "2026-09-01"
+ assert result.empty()
+
+
+class TestFailureLogging:
+ """Failure logs carry chunk_index and never echo source text."""
+
+ def test_batch_failure_logs_chunk_index_not_source_text(self):
+ import logging
+
+ class LogCapture(logging.Handler):
+ def __init__(self):
+ super().__init__()
+ self.messages = []
+
+ def emit(self, record):
+ self.messages.append(self.format(record))
+
+ handler = LogCapture()
+ handler.setLevel(logging.WARNING)
+ handler.setFormatter(logging.Formatter("%(message)s"))
+ # _batch_safe lives in base.py, so records come from that logger.
+ logger = logging.getLogger("hyperextract.types.base")
+ logger.addHandler(handler)
+ logger.setLevel(logging.WARNING)
+
+ try:
+ g = _graph()
+ g.data_extractor = _FlakyBatch(
+ lambda i: g.graph_schema(nodes=[Entity(name=f"N{i}")], edges=[])
+ )
+
+ g.parse(LONG_TEXT)
+ finally:
+ logger.removeHandler(handler)
+
+ # Failures identify the chunk (stub exception message carries the index,
+ # structlog renders it via positional_args)...
+ assert any(
+ "chunk_extract_failed" in m and "429 rate limit on chunk 1" in m
+ for m in handler.messages
+ )
+ # ...and never echo user content.
+ assert all("sentence about entities" not in m for m in handler.messages)
diff --git a/uv.lock b/uv.lock
index 109915d..551686b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -956,7 +956,7 @@ requires-dist = [
{ name = "langchain-community", specifier = ">=0.4.1" },
{ name = "langchain-google-genai", marker = "extra == 'google'", specifier = ">=2.1.0" },
{ name = "langchain-openai", specifier = ">=1.1.7" },
- { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.2.0,<2" },
+ { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.2.0,<3" },
{ name = "ontomem", specifier = ">=0.2.3" },
{ name = "ontosight", specifier = ">=0.1.8" },
{ name = "python-dotenv", specifier = ">=1.2.1" },