Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: 更新搜索接口,支持分别指定节点和边的返回数量;添加多个示例查询
yifanfeng97181590364858
diff --git a/examples/auto_graph_demo.py b/examples/auto_graph_demo.pyindex 46918a8..419691c 100644--- a/examples/auto_graph_demo.py+++ b/examples/auto_graph_demo.py@@ -349,7 +349,7 @@ def run_demo():print(f"\n❓ Query: {q1}")try:# 默认同时搜索节点和边,返回 Tuple[nodes, edges]- nodes, edges = graph.search(q1, top_k=3)+ nodes, edges = graph.search(q1, top_k_nodes=3, top_k_edges=3)interactions = edgesif interactions:for i in interactions:@@ -363,7 +363,7 @@ def run_demo():q2 = "谁是治疗职业的?"print(f"\n❓ Query: {q2}")try:- nodes, edges = graph.search(q2, top_k=3)+ nodes, edges = graph.search(q2, top_k_nodes=3, top_k_edges=3)healers = nodesif healers:for h in healers:@@ -377,7 +377,7 @@ def run_demo():q3 = "谁和谁发生了冲突?"print(f"\n❓ Query: {q3}")try:- nodes, edges = graph.search(q3, top_k=3)+ nodes, edges = graph.search(q3, top_k_nodes=3, top_k_edges=3)conflicts = edgesif conflicts:for c in conflicts:@@ -391,7 +391,7 @@ def run_demo():q4 = "谁是主坦克?"print(f"\n❓ Query: {q4}")try:- nodes, edges = graph.search(q4, top_k=3)+ nodes, edges = graph.search(q4, top_k_nodes=3, top_k_edges=3)tanks = nodesif tanks:for t in tanks:diff --git a/examples/auto_spatial_graph_demo.py b/examples/auto_spatial_graph_demo.pyindex e2e3014..6f7d957 100644--- a/examples/auto_spatial_graph_demo.py+++ b/examples/auto_spatial_graph_demo.py@@ -247,7 +247,7 @@ def run_demo():q1 = "空间站里有哪些怪物或威胁?它们在哪?"print(f"\n❓ Search Query: {q1}")try:- nodes, edges = graph.search(q1, top_k=5)+ nodes, edges = graph.search(q1, top_k_nodes=5, top_k_edges=5)if nodes:print(f" 📍 相关实体:")for n in nodes:@@ -265,7 +265,7 @@ def run_demo():q2 = "黑匣子在哪里找到的?"print(f"\n❓ Search Query: {q2}")try:- nodes, edges = graph.search(q2, top_k=3)+ nodes, edges = graph.search(q2, top_k_nodes=3, top_k_edges=3)if nodes:print(f" 📍 相关实体:")for n in nodes:@@ -283,7 +283,7 @@ def run_demo():q3 = "动力反应堆舱(底层)里有什么东西?"print(f"\n❓ Search Query: {q3}")try:- nodes, edges = graph.search(q3, top_k=5)+ nodes, edges = graph.search(q3, top_k_nodes=5, top_k_edges=5)if nodes:print(f" 📍 相关实体:")for n in nodes:@@ -301,7 +301,7 @@ def run_demo():q4 = "权限卡在哪里?"print(f"\n❓ Search Query: {q4}")try:- nodes, edges = graph.search(q4, top_k=3)+ nodes, edges = graph.search(q4, top_k_nodes=3, top_k_edges=3)if nodes:print(f" 📍 相关实体:")for n in nodes:diff --git a/examples/auto_temporal_graph_demo.py b/examples/auto_temporal_graph_demo.pyindex e48512d..5d56917 100644--- a/examples/auto_temporal_graph_demo.py+++ b/examples/auto_temporal_graph_demo.py@@ -219,7 +219,7 @@ def run_demo():q1 = "Elias做了什么?"print(f"\n❓ Query: {q1}")try:- nodes, edges = graph.search(q1, top_k=5)+ nodes, edges = graph.search(q1, top_k_nodes=5, top_k_edges=5)if edges:for e in edges:print(f" ⚡ {e}")@@ -232,7 +232,7 @@ def run_demo():q2 = "发生在地铁站的事件有哪些?"print(f"\n❓ Query: {q2}")try:- nodes, edges = graph.search(q2, top_k=5)+ nodes, edges = graph.search(q2, top_k_nodes=5, top_k_edges=5)if edges:for e in edges:print(f" 📍 {e}")@@ -245,7 +245,7 @@ def run_demo():q3 = "Viktor和Elias之间的冲突"print(f"\n❓ Query: {q3}")try:- nodes, edges = graph.search(q3, top_k=5)+ nodes, edges = graph.search(q3, top_k_nodes=5, top_k_edges=5)if edges:for e in edges:print(f" 🔥 {e}")@@ -258,7 +258,7 @@ def run_demo():q4 = "下午的行动"print(f"\n❓ Query: {q4}")try:- nodes, edges = graph.search(q4, top_k=5)+ nodes, edges = graph.search(q4, top_k_nodes=5, top_k_edges=5)if edges:for e in edges:print(f" ⏰ {e}")@@ -271,7 +271,7 @@ def run_demo():q5 = "CIA和KGB分别做了什么?"print(f"\n❓ Query: {q5}")try:- nodes, edges = graph.search(q5, top_k=5)+ nodes, edges = graph.search(q5, top_k_nodes=5, top_k_edges=5)if nodes:print(f" 🏢 相关实体:")for n in nodes:diff --git a/examples/hyper_rag_demo.py b/examples/hyper_rag_demo.pyindex 3d53a4a..3ac1ea6 100644--- a/examples/hyper_rag_demo.py+++ b/examples/hyper_rag_demo.py@@ -236,9 +236,10 @@ if __name__ == "__main__":print("Engaging in multi-turn dialogue based on extracted knowledge...\n")chat_queries = [- "What are the main themes in this text?",- "How are different topics interconnected?",- "What insights can you draw from the relationships in this graph?"+ "虚空水晶现在在哪里?",+ "黑蛇和议员Valerius有什么阴谋?",+ "谁参与了泰坦空间站的秘密会议?",+ "Leona目前的状况如何?",]for q in chat_queries:diff --git a/hyperextract/graphs/base.py b/hyperextract/graphs/base.pyindex 77ff6ff..2af3720 100644--- a/hyperextract/graphs/base.py+++ b/hyperextract/graphs/base.py@@ -661,55 +661,47 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[NodeSchema, EdgeSchema]], Generic[Ndef search(self,query: str,- top_k: int = 3,- search_nodes: bool = True,- search_edges: bool = True,- ) -> List[NodeSchema] | List[EdgeSchema] | Tuple[List[NodeSchema], List[EdgeSchema]]:+ top_k_nodes: int = 3,+ top_k_edges: int = 3,+ ) -> Tuple[List[NodeSchema], List[EdgeSchema]]:"""Unified graph search interface.- 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 only, returns a flat list.+ Retrieves nodes and edges semantically related to the query.+ Always returns a tuple of (nodes, edges). If a count is 0, the corresponding list will be empty.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: True).+ top_k_nodes: Number of node results to return (default: 3). Set to 0 to disable node search.+ top_k_edges: Number of edge results to return (default: 3). Set to 0 to disable edge search.Returns:- - Tuple[List[NodeSchema], List[EdgeSchema]] if both search_nodes and search_edges are True (default).- - List[NodeSchema] if only search_nodes is True.- - List[EdgeSchema] if only search_edges is True.+ Tuple[List[NodeSchema], List[EdgeSchema]]: A tuple containing:+ - List of matching nodes (empty if top_k_nodes <= 0)+ - List of matching edges (empty if top_k_edges <= 0)Raises:- ValueError: If neither search_nodes nor search_edges is True.+ ValueError: If both top_k_nodes and top_k_edges are <= 0.+ ValueError: If search is requested (top_k > 0) but the corresponding index is not built."""- if not search_nodes and not search_edges:+ if top_k_nodes <= 0 and top_k_edges <= 0:raise ValueError(- "At least one of search_nodes or search_edges must be True."+ "At least one of top_k_nodes or top_k_edges must be positive.")- if search_nodes and search_edges:- if not self._node_memory.has_index():- raise ValueError("Node index not built. Call build_index() first.")- if not self._edge_memory.has_index():- raise ValueError("Edge index not built. Call build_index() first.")- nodes = self.search_nodes(query, top_k)- edges = self.search_edges(query, top_k)- return (nodes, edges)+ nodes: List[NodeSchema] = []+ edges: List[EdgeSchema] = []- if search_nodes:+ if top_k_nodes > 0:if not self._node_memory.has_index():raise ValueError("Node index not built. Call build_index() first.")- nodes = self.search_nodes(query, top_k)- return nodes+ nodes = self.search_nodes(query, top_k=top_k_nodes)- if search_edges:+ if top_k_edges > 0:if not self._edge_memory.has_index():raise ValueError("Edge index not built. Call build_index() first.")- edges = self.search_edges(query, top_k)- return edges+ edges = self.search_edges(query, top_k=top_k_edges)++ return nodes, edgesdef search_nodes(self, query: str, top_k: int = 3) -> List[NodeSchema]:"""Semantic search for nodes/entities only.diff --git a/hyperextract/hypergraphs/base.py b/hyperextract/hypergraphs/base.pyindex 6ef7892..67bde4c 100644--- a/hyperextract/hypergraphs/base.py+++ b/hyperextract/hypergraphs/base.py@@ -598,53 +598,47 @@ class AutoHypergraph(def search(self,query: str,- top_k: int = 3,- search_nodes: bool = True,- search_edges: bool = True,- ) -> List[Node] | List[Edge] | Tuple[List[Node], List[Edge]]:+ top_k_nodes: int = 3,+ top_k_edges: int = 3,+ ) -> 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.+ Retrieves nodes and hyperedges semantically related to the query.+ Always returns a tuple of (nodes, edges). If a count is 0, the corresponding list will be empty.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 hyperedges (default: True).+ top_k_nodes: Number of node results to return (default: 3). Set to 0 to disable node search.+ top_k_edges: Number of hyperedge results to return (default: 3). Set to 0 to disable hyperedge search.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]]: A tuple containing:+ - List of matching nodes (empty if top_k_nodes <= 0)+ - List of matching hyperedges (empty if top_k_edges <= 0)Raises:- ValueError: If neither search_nodes nor search_edges is True.+ ValueError: If both top_k_nodes and top_k_edges are <= 0.+ ValueError: If search is requested (top_k > 0) but the corresponding index is not built."""- if not search_nodes and not search_edges:+ if top_k_nodes <= 0 and top_k_edges <= 0:raise ValueError(- "At least one of search_nodes or search_edges must be True."+ "At least one of top_k_nodes or top_k_edges must be positive.")- if search_nodes and search_edges:- if not self._node_memory.has_index():- raise ValueError("Node index not built. Call build_index() first.")- if not self._edge_memory.has_index():- raise ValueError("Edge index not built. Call build_index() first.")- nodes = self.search_nodes(query, top_k)- edges = self.search_edges(query, top_k)- return (nodes, edges)+ nodes: List[Node] = []+ edges: List[Edge] = []- if search_nodes:+ if top_k_nodes > 0:if not self._node_memory.has_index():raise ValueError("Node index not built. Call build_index() first.")- return self.search_nodes(query, top_k)+ nodes = self.search_nodes(query, top_k=top_k_nodes)- if search_edges:+ if top_k_edges > 0:if not self._edge_memory.has_index():raise ValueError("Edge index not built. Call build_index() first.")- return self.search_edges(query, top_k)+ edges = self.search_edges(query, top_k=top_k_edges)++ return nodes, edgesdef search_nodes(self, query: str, top_k: int = 3) -> List[Node]:"""Semantic search for nodes/entities only."""diff --git a/hyperextract/hypergraphs/hyper_rag.py b/hyperextract/hypergraphs/hyper_rag.pyindex 06d7524..88f8143 100644--- a/hyperextract/hypergraphs/hyper_rag.py+++ b/hyperextract/hypergraphs/hyper_rag.py@@ -6,9 +6,12 @@ Extracts and manages multi-entity relationships with support for n-ary hyperedgefrom typing import Listfrom pydantic import BaseModel, Fieldfrom hyperextract.hypergraphs.base import AutoHypergraph-from langchain_core.language_models import BaseChatModel+from langchain_core.messages import AIMessagefrom langchain_core.embeddings import Embeddings+from langchain_core.language_models import BaseChatModel+from langchain_core.prompts.chat import ChatPromptTemplatefrom ontomem.merger import CustomRuleMerger+from ..utils.logging import logger# ============================================================================# Node Schema@@ -51,18 +54,34 @@ class EdgeSchema(BaseModel):)+# ============================================================================+# Query Analysis Schema+# ============================================================================+++class QueryKeywords(BaseModel):+ """Extracted keywords for multi-granular hypergraph retrieval."""++ high_level_keywords: List[str] = Field(+ description="Overarching concepts, themes, or abstract topics (e.g., 'International trade', 'Deforestation')."+ )+ low_level_keywords: List[str] = Field(+ description="Specific entities, concrete details, or tangible objects (e.g., 'Tariffs', 'Rainforest')."+ )++# ============================================================================# Extraction Prompts# ============================================================================-HYPER_RAG_NODE_EXTRACTION_PROMPT = """+Hyper_RAG_NODE_EXTRACTION_PROMPT = """-Goal-Identify relevant entities from the text.Entities will serve as participants in complex events later.\n\n### Source Text:"""-HYPER_RAG_EDGE_EXTRACTION_PROMPT = """+Hyper_RAG_EDGE_EXTRACTION_PROMPT = """-Goal-You are an expert hypergraph knowledge extraction assistant.Extract "Hyperedges" that represent relationships, events, or thematic groupings involving MULTIPLE entities (2 or more) simultaneously.@@ -79,11 +98,45 @@ It treats all involved entities as **participants** in a shared context"""+Hyper_RAG_KEYWORDS_EXTRACTION_PROMPT = """---Role---+You are a helpful assistant tasked with identifying both high-level and low-level keywords in the user's query.++---Goal---+Given the query, extract both high-level and low-level keywords.+- High-level keywords focus on overarching concepts, themes, or abstract topics.+- Low-level keywords focus on specific entities, concrete details, or tangible objects.++---Instructions---+- Output as a structured response with two lists.+- High-level keywords capture broader themes and relationships.+- Low-level keywords capture specific entities and concrete terms.++---Examples---++Example 1:+Query: "How does international trade influence global economic stability?"+High-Level: ["International trade", "Global economic stability", "Economic impact"]+Low-Level: ["Trade agreements", "Tariffs", "Currency exchange", "Imports", "Exports"]++Example 2:+Query: "What are the environmental consequences of deforestation on biodiversity?"+High-Level: ["Environmental consequences", "Deforestation", "Biodiversity loss"]+Low-Level: ["Species extinction", "Habitat destruction", "Carbon emissions", "Rainforest", "Ecosystem"]++Example 3:+Query: "What is the role of education in reducing poverty?"+High-Level: ["Education", "Poverty reduction", "Socioeconomic development"]+Low-Level: ["School access", "Literacy rates", "Job training", "Income inequality"]++---Real Data---+Query: {query}+"""+# ============================================================================# Merge Templates for LLM.CUSTOM_RULE Strategy# ============================================================================-NODE_MERGE_RULE = """You are an intelligent data merging assistant.+Hyper_RAG_NODE_MERGE_RULE = """You are an intelligent data merging assistant.You will receive a list of objects representing the same Entity.Your task is to merge them into a SINGLE object exactly matching the schema.@@ -93,7 +146,7 @@ Merge strategy:2. **description**: Synthesize a single, comprehensive description containing all unique details from the input descriptions. Write it in the third person. Resolve any contradictions coherently."""-EDGE_MERGE_RULE = """You are an intelligent data merging assistant.+Hyper_RAG_EDGE_MERGE_RULE = """You are an intelligent data merging assistant.You will receive a list of objects representing the same Hyperedge (Relationship/Event).Your task is to merge them into a SINGLE object exactly matching the schema.@@ -159,7 +212,7 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):key_extractor=node_key_fn,llm_client=llm_client,item_schema=NodeSchema,- rule=NODE_MERGE_RULE,+ rule=Hyper_RAG_NODE_MERGE_RULE,)# Edge merger: merges relationship descriptions using EDGE_MERGE_RULE@@ -167,7 +220,7 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):key_extractor=edge_key_fn,llm_client=llm_client,item_schema=EdgeSchema,- rule=EDGE_MERGE_RULE,+ rule=Hyper_RAG_EDGE_MERGE_RULE,)# 4. Call parent class initialization@@ -182,8 +235,8 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):# Enforce two-stage extraction (nodes first, then edges)extraction_mode="two_stage",# Inject customized prompts for extraction- prompt_for_node_extraction=HYPER_RAG_NODE_EXTRACTION_PROMPT,- prompt_for_edge_extraction=HYPER_RAG_EDGE_EXTRACTION_PROMPT,+ prompt_for_node_extraction=Hyper_RAG_NODE_EXTRACTION_PROMPT,+ prompt_for_edge_extraction=Hyper_RAG_EDGE_EXTRACTION_PROMPT,# Pass custom merger instancesnode_strategy_or_merger=node_merger,edge_strategy_or_merger=edge_merger,@@ -196,3 +249,133 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):max_workers=max_workers,verbose=verbose,)++ def chat(+ self,+ query: str,+ top_k_nodes: int = 3,+ top_k_edges: int = 3,+ ) -> AIMessage:+ """Performs a chat-like interaction using hypergraph knowledge.++ Implements the 'Hyper-RAG' dual-level retrieval strategy:+ 1. Analyzes the query to extract 'Low-Level' keywords (specific entities/details) and 'High-Level' keywords (overarching themes).+ 2. Retrieves Nodes using Low-Level keywords (finding specific entities).+ 3. Retrieves Hyperedges using High-Level keywords (finding broader relationships and themes).+ 4. Synthesizes an answer based on the combined multi-granular context.++ Args:+ query: User query string.+ top_k_nodes: Number of relevant nodes to retrieve (default: 3). Set to 0 to disable node context.+ top_k_edges: Number of relevant hyperedges to retrieve (default: 3). Set to 0 to disable edge context.++ Returns:+ An AIMessage object containing the LLM-generated response.+ Access the text content via response.content.++ Example:+ >>> # Dual-level retrieval: specific entities + broader themes+ >>> response = hg.chat("How does education reduce poverty?", top_k_nodes=5, top_k_edges=3)+ >>> print(response.content)+ """+ # Step 1: Validation+ if top_k_nodes <= 0 and top_k_edges <= 0:+ raise ValueError(+ "At least one of top_k_nodes or top_k_edges must be positive."+ )++ # Step 2: Extract Keywords (Dual-Level Strategy)+ keyword_prompt = ChatPromptTemplate.from_template(+ Hyper_RAG_KEYWORDS_EXTRACTION_PROMPT+ )+ keyword_chain = keyword_prompt | self.llm_client.with_structured_output(+ QueryKeywords+ )++ # Containers for keywords+ low_level_targets = []+ high_level_targets = []+ extraction_success = False++ try:+ keywords_result: QueryKeywords = keyword_chain.invoke({"query": query})+ if keywords_result.low_level_keywords:+ low_level_targets = keywords_result.low_level_keywords+ if keywords_result.high_level_keywords:+ high_level_targets = keywords_result.high_level_keywords++ extraction_success = True++ if self.verbose:+ logger.info(+ f"Query Analysis:\n"+ f" - Low-Level Targets: {low_level_targets}\n"+ f" - High-Level Targets: {high_level_targets}"+ )++ except Exception as e:+ if self.verbose:+ logger.warning(+ f"Keyword extraction failed ({e}), falling back to raw query."+ )++ context_parts = []++ # Step 3: Retrieve and format nodes context (Using Low-Level Keywords)+ if top_k_nodes > 0:+ found_nodes = []+ if extraction_success and low_level_targets:+ # Search for EACH keyword independently+ for kw in low_level_targets:+ # Append ALL results directly (no deduplication)+ found_nodes.extend(self.search_nodes(kw, top_k=top_k_nodes))+ else:+ # Fallback: search with original query+ found_nodes = self.search_nodes(query, top_k=top_k_nodes)++ if found_nodes:+ context_parts.append("=== Relevant Nodes (Entity Level) ===")+ for node in found_nodes:+ assert isinstance(node, BaseModel), (+ "Node must be a Pydantic BaseModel"+ )+ context_parts.append(node.model_dump_json(indent=2))++ # Step 4: Retrieve and format edges context (Using High-Level Keywords)+ if top_k_edges > 0:+ found_edges = []+ if extraction_success and high_level_targets:+ # Search for EACH keyword independently+ for kw in high_level_targets:+ # Append ALL results directly (no deduplication)+ found_edges.extend(self.search_edges(kw, top_k=top_k_edges))+ else:+ # Fallback: search with original query+ found_edges = self.search_edges(query, top_k=top_k_edges)++ if found_edges:+ context_parts.append("=== Relevant Hyperedges (Thematic Level) ===")+ for edge in found_edges:+ assert isinstance(edge, BaseModel), (+ "Edge must be a Pydantic BaseModel"+ )+ context_parts.append(edge.model_dump_json(indent=2))++ # Step 5: 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 6: Invoke LLM with structured context+ qa_prompt = ChatPromptTemplate.from_template(+ "Based on the following Hypergraph Knowledge, answer the user's question.\n"+ "The context includes both specific entities (Nodes) found via low-level keywords \n"+ "and broader relationships/themes (Hyperedges) found via high-level keywords.\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})diff --git a/hyperextract/templates/__init__.py b/hyperextract/templates/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/hyperextract/templates/graphs/__init__.py b/hyperextract/templates/graphs/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/hyperextract/templates/hypergraph/__init__.py b/hyperextract/templates/hypergraph/__init__.pynew file mode 100644index 0000000..e69de29