Skip to content

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

feat: add debug logging to knowledge extraction pipeline

David Liaf7b48edd669
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index 3f2be56..6e0d647 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -328,6 +328,7 @@ def parse(
console.print(f"[dim]Total input: {len(combined_text)} characters[/dim]")
progress.update(task, description="Extracting knowledge...")
+ logger.debug("stage=feed_text_invoked")
ka.feed_text(combined_text)
logger.info("stage=knowledge_extracted chars=%d", len(combined_text))
else:
@@ -336,6 +337,7 @@ def parse(
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
progress.update(task, description="Extracting knowledge...")
+ logger.debug("stage=feed_text_invoked")
ka.feed_text(text)
logger.info("stage=knowledge_extracted chars=%d", len(text))
@@ -727,6 +729,7 @@ def feed(
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
progress.update(task, description="Appending knowledge...")
+ logger.debug("stage=feed_text_invoked")
ka.feed_text(text)
logger.info("stage=knowledge_appended chars=%d", len(text))
diff --git a/hyperextract/types/base.py b/hyperextract/types/base.py
index 1e1834c..84ae85b 100644
--- a/hyperextract/types/base.py
+++ b/hyperextract/types/base.py
@@ -10,6 +10,10 @@ from langchain_core.prompts import ChatPromptTemplate
from langchain_core.language_models.chat_models import BaseChatModel
from langchain_text_splitters import RecursiveCharacterTextSplitter
+from hyperextract.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
T = TypeVar("T", bound=BaseModel)
@@ -243,18 +247,25 @@ class BaseAutoType(ABC, Generic[T]):
def _extract_data(self, text: str) -> T:
"""Internal: Unified extraction logic (Chunking -> LLM -> Merge)."""
+ logger.debug("stage=extract_start input_chars=%d chunk_size=%d", len(text), self.chunk_size)
if len(text) <= self.chunk_size:
+ logger.debug("stage=extract_single_chunk")
extracted_data = self.data_extractor.invoke({"source_text": text})
extracted_data_list = [extracted_data]
else:
chunks = self.text_splitter.split_text(text)
+ logger.debug("stage=text_split num_chunks=%d", len(chunks))
inputs = [{"source_text": chunk} for chunk in chunks]
+ logger.debug("stage=llm_batch_start max_concurrency=%d", self.max_workers)
extracted_data_list = self.data_extractor.batch(
inputs, config={"max_concurrency": self.max_workers}
)
+ logger.debug("stage=llm_batch_complete results=%d", len(extracted_data_list))
+ logger.debug("stage=merge_start num_items=%d", len(extracted_data_list))
merged_data = self.merge_batch_data(extracted_data_list)
+ logger.debug("stage=extract_complete")
return merged_data
def parse(self, text: str) -> "BaseAutoType[T]":
@@ -292,10 +303,13 @@ class BaseAutoType(ABC, Generic[T]):
Returns:
Self (the current instance).
"""
+ logger.debug("stage=feed_text_start input_chars=%d", len(text))
extracted_data = self._extract_data(text)
+ logger.debug("stage=extract_done")
# Use UPDATE hook instead of manual merge+set
self._update_data_state(extracted_data)
+ logger.debug("stage=data_merged")
self.metadata["updated_at"] = datetime.now()
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index 234cbcb..6f6df5f 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -476,19 +476,26 @@ class AutoGraph(
Returns:
Raw extracted graph data.
"""
+ logger.debug("stage=one_stage_start mode=%s", self.extraction_mode)
if len(text) <= self.chunk_size:
+ logger.debug("stage=one_stage_single_invoke")
graph = self.data_extractor.invoke({"source_text": text})
graph_list = [graph]
else:
chunks = self.text_splitter.split_text(text)
+ logger.debug("stage=one_stage_split num_chunks=%d", len(chunks))
inputs = [{"source_text": chunk} for chunk in chunks]
+ 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}
)
+ logger.debug("stage=one_stage_batch_complete graphs=%d", len(graph_list))
- # Merge multiple graphs
- return self.merge_batch_data(graph_list)
+ logger.debug("stage=one_stage_merge_start")
+ result = self.merge_batch_data(graph_list)
+ logger.debug("stage=one_stage_merge_complete nodes=%d edges=%d", len(result.nodes), len(result.edges))
+ return result
def _extract_data_by_two_stage(
self, text: str
@@ -508,17 +515,26 @@ class AutoGraph(
Returns:
Extracted and validated graph.
"""
+ logger.debug("stage=two_stage_start mode=%s", self.extraction_mode)
+
# 1. Prepare chunks
if len(text) <= self.chunk_size:
chunks = [text]
else:
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])
+ logger.debug("stage=two_stage_node_extraction_start")
chunk_node_lists = 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", len(chunk_node_lists), total_nodes)
# 3. Batch Extract Edges (Context-aware, returns List[EdgeListSchema])
+ logger.debug("stage=two_stage_edge_extraction_start")
chunk_edge_lists = self._extract_edges_batch(chunks, chunk_node_lists)
+ 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", len(chunk_edge_lists), total_edges)
# 4. Construct Partial Graphs (Tuple format for merge optimization)
partial_graphs = (
@@ -527,7 +543,10 @@ class AutoGraph(
)
# 5. Global Merge (passes tuples to merge_batch_data)
- return self.merge_batch_data(partial_graphs)
+ logger.debug("stage=two_stage_merge_start")
+ result = self.merge_batch_data(partial_graphs)
+ logger.debug("stage=two_stage_merge_complete nodes=%d edges=%d", len(result.nodes), len(result.edges))
+ return result
def _extract_nodes_batch(
self, chunks: List[str]
@@ -635,6 +654,8 @@ class AutoGraph(
Returns:
Merged graph.
"""
+ logger.debug("stage=merge_batch_start input_type=%s", "tuple" if not isinstance(data_list_or_tuple[0], self.graph_schema) else "list")
+
if isinstance(data_list_or_tuple[0], self.graph_schema):
all_nodes, all_edges = [], []
@@ -659,8 +680,10 @@ class AutoGraph(
all_nodes.extend(node_list)
all_edges.extend(edge_list)
+ logger.debug("stage=merge_batch_raw total_nodes=%d total_edges=%d", len(all_nodes), len(all_edges))
merged_nodes = self.node_merger.merge(all_nodes) if all_nodes else []
merged_edges = self.edge_merger.merge(all_edges) if all_edges else []
+ logger.debug("stage=merge_batch_complete merged_nodes=%d merged_edges=%d deduped_nodes=%d deduped_edges=%d", len(merged_nodes), len(merged_edges), len(all_nodes) - len(merged_nodes), len(all_edges) - len(merged_edges))
return self.graph_schema(nodes=merged_nodes, edges=merged_edges)
# ==================== Indexing & Search & Chat ====================
diff --git a/tests/types/test_extraction_logging.py b/tests/types/test_extraction_logging.py
new file mode 100644
index 0000000..d6c7b59
--- /dev/null
+++ b/tests/types/test_extraction_logging.py
@@ -0,0 +1,168 @@
+"""Tests for debug logging during knowledge extraction."""
+
+import logging
+from unittest.mock import MagicMock
+
+import pytest
+from pydantic import BaseModel, Field
+
+from hyperextract.types.base import BaseAutoType
+from hyperextract.types.graph import AutoGraph
+
+
+class SimpleNode(BaseModel):
+ name: str = Field(description="Entity name")
+ description: str = Field(description="Entity description")
+
+
+class SimpleEdge(BaseModel):
+ source: str = Field(description="Source node key")
+ target: str = Field(description="Target node key")
+ relation: str = Field(description="Relation type")
+
+
+def _make_mock_llm_and_embedder():
+ """Create mock LLM and embedder for testing."""
+ mock_llm = MagicMock()
+ mock_llm.with_structured_output = MagicMock(return_value=mock_llm)
+ mock_llm.invoke = MagicMock()
+ mock_llm.batch = MagicMock(return_value=[])
+ mock_embedder = MagicMock()
+ mock_embedder.embed_documents = MagicMock(return_value=[])
+ mock_embedder.embed_query = MagicMock(return_value=[])
+ return mock_llm, mock_embedder
+
+
+class LogCapture(logging.Handler):
+ """Custom logging handler that captures log records."""
+
+ def __init__(self):
+ super().__init__()
+ self.messages = []
+
+ def emit(self, record):
+ self.messages.append(self.format(record))
+
+
+class TestBaseExtractionLogging:
+ """Test that BaseAutoType._extract_data emits debug logs."""
+
+ def test_extract_data_emits_debug_logs(self):
+ """_extract_data should emit debug log messages at each stage."""
+ handler = LogCapture()
+ handler.setLevel(logging.DEBUG)
+ formatter = logging.Formatter("%(message)s")
+ handler.setFormatter(formatter)
+
+ logger = logging.getLogger("hyperextract.types.base")
+ logger.addHandler(handler)
+ logger.setLevel(logging.DEBUG)
+
+ try:
+ mock_llm, mock_embedder = _make_mock_llm_and_embedder()
+
+ class TestSchema(BaseModel):
+ items: list = []
+
+ class TestAutoType(BaseAutoType):
+ def _default_prompt(self):
+ return "Extract: {source_text}"
+
+ @property
+ def data(self):
+ return TestSchema()
+
+ def empty(self):
+ return True
+
+ def _init_data_state(self):
+ pass
+
+ def _set_data_state(self, data):
+ pass
+
+ def _update_data_state(self, data):
+ pass
+
+ def _init_index_state(self):
+ pass
+
+ def merge_batch_data(self, data_list):
+ return TestSchema()
+
+ def build_index(self):
+ pass
+
+ def search(self, query, top_k=3):
+ return []
+
+ def dump_index(self, folder_path):
+ pass
+
+ def load_index(self, folder_path):
+ pass
+
+ mock_llm.invoke.return_value = TestSchema()
+ ka = TestAutoType(
+ data_schema=TestSchema,
+ llm_client=mock_llm,
+ embedder=mock_embedder,
+ chunk_size=2048,
+ )
+ ka.feed_text("Test input text")
+ finally:
+ logger.removeHandler(handler)
+
+ log_text = "\n".join(handler.messages)
+ assert "stage=feed_text_start" in log_text
+ assert "stage=extract_start" in log_text
+ assert "stage=extract_complete" in log_text
+ assert "stage=data_merged" in log_text
+
+
+class TestGraphExtractionLogging:
+ """Test that AutoGraph extraction emits debug logs."""
+
+ def test_merge_batch_emits_debug_logs(self):
+ """merge_batch_data should emit debug logs about merge stats."""
+ handler = LogCapture()
+ handler.setLevel(logging.DEBUG)
+ formatter = logging.Formatter("%(message)s")
+ handler.setFormatter(formatter)
+
+ logger = logging.getLogger("hyperextract.types.graph")
+ logger.addHandler(handler)
+ logger.setLevel(logging.DEBUG)
+
+ try:
+ mock_llm, mock_embedder = _make_mock_llm_and_embedder()
+
+ ag = AutoGraph(
+ node_schema=SimpleNode,
+ edge_schema=SimpleEdge,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.source}-{x.relation}-{x.target}",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=mock_llm,
+ embedder=mock_embedder,
+ extraction_mode="one_stage",
+ chunk_size=2048,
+ )
+
+ graph1 = ag.graph_schema(
+ nodes=[SimpleNode(name="A", description="Node A")],
+ edges=[SimpleEdge(source="A", target="B", relation="relates")],
+ )
+ graph2 = ag.graph_schema(
+ nodes=[SimpleNode(name="B", description="Node B")],
+ edges=[],
+ )
+
+ ag.merge_batch_data([graph1, graph2])
+ finally:
+ logger.removeHandler(handler)
+
+ log_text = "\n".join(handler.messages)
+ assert "stage=merge_batch_start" in log_text
+ assert "stage=merge_batch_raw" in log_text
+ assert "stage=merge_batch_complete" in log_text