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.pyindex 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.pyindex 1e1834c..84ae85b 100644--- a/hyperextract/types/base.py+++ b/hyperextract/types/base.py@@ -10,6 +10,10 @@ from langchain_core.prompts import ChatPromptTemplatefrom langchain_core.language_models.chat_models import BaseChatModelfrom 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_datadef 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+setself._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.pyindex 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 resultdef _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 chunksif 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 resultdef _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.pynew file mode 100644index 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