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: 更新图形和超图索引及搜索功能,默认同时索引和搜索节点与边,新增聊天交互功能

yifanfeng9764f3f001848b
diff --git a/examples/auto_graph_demo.py b/examples/auto_graph_demo.py
index 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 = edges
if 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 = nodes
if 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 = edges
if 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 = nodes
if tanks:
for t in tanks:
print(f" 🛡️ {t}")
diff --git a/hyperextract/core/base.py b/hyperextract/core/base.py
index 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 LLM
qa_prompt = ChatPromptTemplate.from_template(
@@ -418,7 +408,6 @@ class BaseAutoType(ABC, Generic[T]):
# Step 4: Return the AIMessage response
return response
-
# ==================== Serialization: Orchestrator ====================
def dump(self, folder_path: str | Path) -> None:
diff --git a/hyperextract/graphs/base.py b/hyperextract/graphs/base.py
index 3e92cae..8606c08 100644
--- a/hyperextract/graphs/base.py
+++ b/hyperextract/graphs/base.py
@@ -16,6 +16,7 @@ from typing import (
)
from pathlib import Path
from pydantic import BaseModel, Field, create_model
+from langchain_core.messages import AIMessage
from langchain_core.embeddings import Embeddings
from langchain_core.language_models.chat_models import BaseChatModel
from 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.py
index 6857b88..3f713b2 100644
--- a/hyperextract/hypergraphs/base.py
+++ b/hyperextract/hypergraphs/base.py
@@ -18,6 +18,7 @@ from typing import (
from pathlib import Path
from pydantic import BaseModel, Field, create_model
from langchain_core.embeddings import Embeddings
+from langchain_core.messages import AIMessage
from langchain_core.language_models.chat_models import BaseChatModel
from langchain_core.prompts import ChatPromptTemplate
from 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: