Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: 更新图形和超图索引及搜索功能,默认同时索引和搜索节点与边,新增聊天交互功能
yifanfeng9764f3f001848b
diff --git a/examples/auto_graph_demo.py b/examples/auto_graph_demo.pyindex 7e72fcb..4f5f46c 100644--- a/examples/auto_graph_demo.py+++ b/examples/auto_graph_demo.py@@ -341,13 +341,16 @@ def run_demo():print("🔍 游戏管理员(GM)调查查询模块")print("=" * 60)- graph.build_index(index_nodes=True, index_edges=True) # 建立索引+ # 建立索引(默认同时索引节点和边,无需指定参数)+ graph.build_index()# 场景1: 找谁拿了装备?q1 = "谁拿走了传说武器?"print(f"\n❓ Query: {q1}")try:- interactions = graph.search_edges(q1, top_k=3)+ # 默认同时搜索节点和边,返回 Tuple[nodes, edges]+ nodes, edges = graph.search(q1, top_k=3)+ interactions = edgesif interactions:for i in interactions:print(f" 🚨 {i}")@@ -360,7 +363,8 @@ def run_demo():q2 = "谁是治疗职业的?"print(f"\n❓ Query: {q2}")try:- healers = graph.search_nodes(q2, top_k=3)+ nodes, edges = graph.search(q2, top_k=3)+ healers = nodesif healers:for h in healers:print(f" 🚑 {h}")@@ -373,7 +377,8 @@ def run_demo():q3 = "谁和谁发生了冲突?"print(f"\n❓ Query: {q3}")try:- conflicts = graph.search_edges(q3, top_k=3)+ nodes, edges = graph.search(q3, top_k=3)+ conflicts = edgesif conflicts:for c in conflicts:print(f" 🔥 {c}")@@ -386,7 +391,8 @@ def run_demo():q4 = "谁是主坦克?"print(f"\n❓ Query: {q4}")try:- tanks = graph.search_nodes(q4, top_k=3)+ nodes, edges = graph.search(q4, top_k=3)+ tanks = nodesif tanks:for t in tanks:print(f" 🛡️ {t}")diff --git a/hyperextract/core/base.py b/hyperextract/core/base.pyindex c2e469f..b24e421 100644--- a/hyperextract/core/base.py+++ b/hyperextract/core/base.py@@ -366,42 +366,32 @@ class BaseAutoType(ABC, Generic[T]):def chat(self, query: str, top_k: int = 3) -> AIMessage:"""Performs a chat-like interaction with the knowledge base.- This method retrieves relevant knowledge items based on the query and generates- a response by feeding them as context to the LLM.-- Workflow:- 1. Search for top_k relevant items using semantic similarity- 2. Format the retrieved items as context- 3. Prompt the LLM with a QA template combining query + context- 4. Return the generated response as AIMessage+ This generic method retrieves relevant items and generates a response.+ Subclasses with complex data structures (like graphs) should override this+ to provide better context formatting.Args:query: User query string.- top_k: Number of relevant items to retrieve for context (default: 3).+ top_k: Number of relevant items to retrieve (default: 3).Returns:An AIMessage object containing the LLM-generated response.- Access the text content via response.content.-- Example:- >>> response = kb.chat("What is X?", top_k=5)- >>> print(response.content) # Print the generated answer"""# Step 1: Retrieve relevant items from knowledge base- related_items = self.search(query, top_k)+ search_results = self.search(query, top_k)# Step 2: Format context from retrieved items- if not related_items:+ formatted_context = []++ if not search_results:context = "No relevant information found in the knowledge base."else:- # Convert each item to a readable format (handles various data types)- formatted_items = []- for item in related_items:- if isinstance(item, BaseModel):- formatted_items.append(item.model_dump_json(indent=2))- else:- formatted_items.append(str(item))- context = "\n---\n".join(formatted_items)+ for item in search_results:+ assert isinstance(item, BaseModel), (+ "Search results must be Pydantic models for formatting."+ )+ formatted_context.append(item.model_dump_json(indent=2))+ context = "\n---\n".join(formatted_context)# Step 3: Create QA prompt template and invoke LLMqa_prompt = ChatPromptTemplate.from_template(@@ -418,7 +408,6 @@ class BaseAutoType(ABC, Generic[T]):# Step 4: Return the AIMessage responsereturn response-# ==================== Serialization: Orchestrator ====================def dump(self, folder_path: str | Path) -> None:diff --git a/hyperextract/graphs/base.py b/hyperextract/graphs/base.pyindex 3e92cae..8606c08 100644--- a/hyperextract/graphs/base.py+++ b/hyperextract/graphs/base.py@@ -16,6 +16,7 @@ from typing import ()from pathlib import Pathfrom pydantic import BaseModel, Field, create_model+from langchain_core.messages import AIMessagefrom langchain_core.embeddings import Embeddingsfrom langchain_core.language_models.chat_models import BaseChatModelfrom langchain_core.prompts import ChatPromptTemplate@@ -627,14 +628,16 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):merged_edges = self.edge_merger.merge(all_edges) if all_edges else []return self.graph_schema(nodes=merged_nodes, edges=merged_edges)- # ==================== Indexing & Search ====================+ # ==================== Indexing & Search & Chat ====================- def build_index(self, index_nodes: bool = True, index_edges: bool = False):+ def build_index(self, index_nodes: bool = True, index_edges: bool = True):"""Build vector index for graph search.+ By default, builds indices for both nodes and edges to support comprehensive search.+Args:index_nodes: Whether to index nodes (default: True).- index_edges: Whether to index edges (default: False).+ index_edges: Whether to index edges (default: True)."""if index_nodes:self.build_node_index()@@ -657,24 +660,24 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):query: str,top_k: int = 3,search_nodes: bool = True,- search_edges: bool = False,+ search_edges: bool = True,) -> List[Node] | List[Edge] | Tuple[List[Node], List[Edge]]:"""Unified graph search interface.- Supports searching nodes only, edges only, or both simultaneously.+ By default, searches both nodes and edges simultaneously to provide comprehensive results.When searching both, returns a tuple of (nodes_results, edges_results).- When searching one type, returns a flat list.+ When searching one type only, returns a flat list.Args:query: Search query string.top_k: Number of results to return per type (default: 3).search_nodes: Whether to search nodes (default: True).- search_edges: Whether to search edges (default: False).+ search_edges: Whether to search edges (default: True).Returns:+ - Tuple[List[Node], List[Edge]] if both search_nodes and search_edges are True (default).- List[Node] if only search_nodes is True.- List[Edge] if only search_edges is True.- - Tuple[List[Node], List[Edge]] if both search_nodes and search_edges are True.Raises:ValueError: If neither search_nodes nor search_edges is True.@@ -729,6 +732,79 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):"""return self._edge_memory.search(query=query, top_k=top_k)+ def chat(+ self,+ query: str,+ top_k: int = 3,+ chat_with_nodes: bool = True,+ chat_with_edges: bool = True,+ ) -> AIMessage:+ """Performs a chat-like interaction using graph knowledge.++ Retrieves relevant nodes and/or edges independently based on the query and flags,+ formats them into a structured context with clear headers, and generates an answer.++ Args:+ query: User query string.+ top_k: Number of relevant items to retrieve per type (default: 3).+ chat_with_nodes: Whether to include relevant entities in context (default: True).+ chat_with_edges: Whether to include relevant edges in context (default: True).++ Returns:+ An AIMessage object containing the LLM-generated response.+ Access the text content via response.content.++ Example:+ >>> response = kb.chat("What is X?", top_k=5)+ >>> print(response.content) # Print the generated answer+ """+ # Step 1: Validation+ if not chat_with_nodes and not chat_with_edges:+ raise ValueError(+ "At least one of chat_with_nodes or chat_with_edges must be True."+ )++ context_parts = []++ # Step 2: Retrieve and format nodes context+ if chat_with_nodes:+ nodes = self.search_nodes(query, top_k)+ if nodes:+ context_parts.append("=== Relevant Nodes ===")+ for node in nodes:+ assert isinstance(node, BaseModel), (+ "Node must be a Pydantic BaseModel"+ )+ context_parts.append(node.model_dump_json(indent=2))++ # Step 3: Retrieve and format edges context+ if chat_with_edges:+ edges = self.search_edges(query, top_k)+ if edges:+ context_parts.append("=== Relevant Edges ===")+ for edge in edges:+ assert isinstance(edge, BaseModel), (+ "Edge must be a Pydantic BaseModel"+ )+ context_parts.append(edge.model_dump_json(indent=2))++ # Step 4: Combine context or use fallback+ if not context_parts:+ context = "No relevant information found in the knowledge base."+ else:+ context = "\n\n".join(context_parts)++ # Step 5: Invoke LLM with structured context+ qa_prompt = ChatPromptTemplate.from_template(+ "Based on the following Graph Knowledge, answer the user's question.\n\n"+ "{context}\n\n"+ "Question: {question}\n\n"+ "Answer:"+ )++ qa_chain = qa_prompt | self.llm_client+ return qa_chain.invoke({"context": context, "question": query})+# ==================== Serialization ====================def dump_index(self, folder_path: str | Path) -> None:diff --git a/hyperextract/hypergraphs/base.py b/hyperextract/hypergraphs/base.pyindex 6857b88..3f713b2 100644--- a/hyperextract/hypergraphs/base.py+++ b/hyperextract/hypergraphs/base.py@@ -18,6 +18,7 @@ from typing import (from pathlib import Pathfrom pydantic import BaseModel, Field, create_modelfrom langchain_core.embeddings import Embeddings+from langchain_core.messages import AIMessagefrom langchain_core.language_models.chat_models import BaseChatModelfrom langchain_core.prompts import ChatPromptTemplatefrom ontomem import OMem@@ -569,12 +570,14 @@ class AutoHypergraph(# ==================== Indexing & Search ====================- def build_index(self, index_nodes: bool = True, index_edges: bool = False):+ def build_index(self, index_nodes: bool = True, index_edges: bool = True):"""Build vector index for hypergraph search.+ By default, builds indices for both nodes and hyperedges to support comprehensive search.+Args:index_nodes: Whether to index nodes (default: True).- index_edges: Whether to index hyperedges (default: False).+ index_edges: Whether to index hyperedges (default: True)."""if index_nodes:self.build_node_index()@@ -597,20 +600,27 @@ class AutoHypergraph(query: str,top_k: int = 3,search_nodes: bool = True,- search_edges: bool = False,+ search_edges: bool = True,) -> List[Node] | List[Edge] | Tuple[List[Node], List[Edge]]:"""Unified hypergraph search interface.+ By default, searches both nodes and hyperedges simultaneously to provide comprehensive results.+ When searching both, returns a tuple of (nodes_results, edges_results).+ When searching one type only, returns a flat list.+Args:query: Search query string.- top_k: Number of results to return per type.- search_nodes: Whether to search nodes.- search_edges: Whether to search hyperedges.+ top_k: Number of results to return per type (default: 3).+ search_nodes: Whether to search nodes (default: True).+ search_edges: Whether to search hyperedges (default: True).Returns:+ - Tuple[List[Node], List[Edge]] if both search_nodes and search_edges are True (default).- List[Node] if only search_nodes is True.- List[Edge] if only search_edges is True.- - Tuple[List[Node], List[Edge]] if both are True.++ Raises:+ ValueError: If neither search_nodes nor search_edges is True."""if not search_nodes and not search_edges:raise ValueError(@@ -644,6 +654,79 @@ class AutoHypergraph("""Semantic search for hyperedges/relationships only."""return self._edge_memory.search(query=query, top_k=top_k)+ def chat(+ self,+ query: str,+ top_k: int = 3,+ chat_with_nodes: bool = True,+ chat_with_edges: bool = True,+ ) -> AIMessage:+ """Performs a chat-like interaction using hypergraph knowledge.++ Retrieves relevant nodes and/or hyperedges independently based on the query and flags,+ formats them into a structured context with clear headers, and generates an answer.++ Args:+ query: User query string.+ top_k: Number of relevant items to retrieve per type (default: 3).+ chat_with_nodes: Whether to include relevant entities in context (default: True).+ chat_with_edges: Whether to include relevant hyperedges in context (default: True).++ Returns:+ An AIMessage object containing the LLM-generated response.+ Access the text content via response.content.++ Example:+ >>> response = hg.chat("What participates in X?", top_k=5)+ >>> print(response.content) # Print the generated answer+ """+ # Step 1: Validation+ if not chat_with_nodes and not chat_with_edges:+ raise ValueError(+ "At least one of chat_with_nodes or chat_with_edges must be True."+ )++ context_parts = []++ # Step 2: Retrieve and format nodes context+ if chat_with_nodes:+ nodes = self.search_nodes(query, top_k)+ if nodes:+ context_parts.append("=== Relevant Nodes ===")+ for node in nodes:+ assert isinstance(node, BaseModel), (+ "Node must be a Pydantic BaseModel"+ )+ context_parts.append(node.model_dump_json(indent=2))++ # Step 3: Retrieve and format edges context+ if chat_with_edges:+ edges = self.search_edges(query, top_k)+ if edges:+ context_parts.append("=== Relevant Edges ===")+ for edge in edges:+ assert isinstance(edge, BaseModel), (+ "Edge must be a Pydantic BaseModel"+ )+ context_parts.append(edge.model_dump_json(indent=2))++ # Step 4: Combine context or use fallback+ if not context_parts:+ context = "No relevant information found in the knowledge base."+ else:+ context = "\n\n".join(context_parts)++ # Step 5: Invoke LLM with structured context+ qa_prompt = ChatPromptTemplate.from_template(+ "Based on the following Hypergraph Knowledge answer the user's question.\n\n"+ "{context}\n\n"+ "Question: {question}\n\n"+ "Answer:"+ )++ qa_chain = qa_prompt | self.llm_client+ return qa_chain.invoke({"context": context, "question": query})+# ==================== Serialization ====================def dump_index(self, folder_path: str | Path) -> None: