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: Enhance AutoSet and AutoGraph functionality

yifanfeng975abe50540cbf
diff --git a/examples/auto_graph_game_demo.py b/examples/auto_graph_demo.py
similarity index 88%
rename from examples/auto_graph_game_demo.py
rename to examples/auto_graph_demo.py
index ff1cc4b..b2f1acf 100644
--- a/examples/auto_graph_game_demo.py
+++ b/examples/auto_graph_demo.py
@@ -21,7 +21,7 @@ sys.path.append(str(project_root))
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.graphs.base import AutoGraph
+from hyperextract.graphs import AutoGraph
from ontomem import MergeStrategy
import dotenv
@@ -29,24 +29,37 @@ import dotenv
dotenv.load_dotenv()
# ==================== 1. 定义游戏知识结构 (Schema) ====================
-class Player(BaseModel):
- """玩家/角色节点"""
- game_id: str = Field(description="游戏角色ID")
- role_class: str = Field(description="职业/职责,如:坦克(Tank)、治疗(Healer)、法师(DPS)", default="未知")
- guild: str = Field(description="所属公会", default="无公会")
+
+class GameEntity(BaseModel):
+ """游戏实体节点(包含玩家、BOSS、NPC、公会等)"""
+
+ name: str = Field(description="实体名称或ID,例如玩家ID、BOSS名、'星辰阁'")
+ category: str = Field(
+ description="实体类型,例如:'玩家', 'BOSS', '公会', '群体'", default="玩家"
+ )
+ info: str = Field(
+ description="职业、描述或状态,如'战神'、'最终BOSS'、'解散'", default="未知"
+ )
def __repr__(self):
- return f"🎮 ID:[{self.game_id}] 职业:<{self.role_class}> 公会:{self.guild}"
+ return f"🎮 [{self.category}] {self.name} <{self.info}>"
+
class GameInteraction(BaseModel):
"""游戏互动边"""
- source: str = Field(description="发起互动的玩家")
- target: str = Field(description="互动的对象(玩家或BOSS)")
- action_type: str = Field(description="互动类型:'治疗', '攻击', '抢装备', '辱骂', '踢出队伍', '拉入队伍'")
+
+ source: str = Field(description="发起互动的实体名称")
+ target: str = Field(description="互动的对象名称(可以是玩家、BOSS或公会)")
+ action_type: str = Field(
+ description="互动类型:'治疗', '攻击', '抢装备', '辱骂', '踢出队伍', '拉入队伍'"
+ )
details: str = Field(description="具体的互动描述或原因")
def __repr__(self):
- return f"⚡ {self.source} --[{self.action_type}]--> {self.target} ({self.details})"
+ return (
+ f"⚡ {self.source} --[{self.action_type}]--> {self.target} ({self.details})"
+ )
+
# ==================== 2. 模拟论坛爆料贴 (Data Source - 加长版) ====================
@@ -251,6 +264,7 @@ GAME_FORUM_POST = """
# ==================== 3. 运行提取 ====================
+
def run_demo():
print("=" * 60)
print("🕹️ 正在加载游戏日志分析模块...")
@@ -263,49 +277,43 @@ def run_demo():
# 创建 AutoGraph
print("📊 构建 AutoGraph 实例...\n")
- graph = AutoGraph[Player, GameInteraction](
- node_schema=Player,
+ graph = AutoGraph[GameEntity, GameInteraction](
+ node_schema=GameEntity,
edge_schema=GameInteraction,
-
# 1. ID 提取规则
- node_key_extractor=lambda x: x.game_id,
+ node_key_extractor=lambda x: x.name,
# 2. 互动唯一性规则
edge_key_extractor=lambda x: f"{x.source}_{x.action_type}_{x.target}",
# 3. 验证规则
nodes_in_edge_extractor=lambda x: (x.source, x.target),
-
llm_client=llm,
embedder=embedder,
-
# 两阶段提取,适合处理这种连贯的剧情
extraction_mode="two_stage",
-
# 智能合并:能识别 "主T" = "雷霆之怒" = "会长"
node_strategy_or_merger=MergeStrategy.LLM.BALANCED,
-
# 针对游戏的特化提示词
prompt_for_node_extraction=(
- "提取文本中的游戏玩家和BOSS。注意识别ID、职业(如坦克/治疗/DPS)和公会归属。"
- "将别名(如'会长'、'主T'、'奶妈')统一合并到其主要游戏ID上。"
- "提取玩家的真实身份(括号内的信息)。"
+ "提取文本中的所有游戏实体作为节点。关键:必须提取BOSS(如深渊魔龙)、公会(如星辰阁)以及关键玩家。"
+ "如果文中提到'全团'或'所有人',也将其作为一个群体实体提取。"
+ "注意识别ID和别名,将别名(如'团长')标准化为具体ID。"
),
prompt_for_edge_extraction=(
- "提取玩家之间和玩家与BOSS之间的互动行为。包括战斗行为(治疗/攻击/防守)、"
- "社交行为(辱骂/踢人/拉人)以及物品分配(抢装备/黑装备)。"
- "确保只记录文中明确发生的事件。重点关注有争议的互动。"
+ "提取实体之间的互动行为。"
+ "重要规则:互动中的 source 和 target 必须是你刚才提取过的实体名称。"
+ "例如,如果之前提取了节点'深渊魔龙',那么攻击BOSS的互动 target 必须填'深渊魔龙'。"
),
-
- show_progress=True
+ show_progress=True,
)
print(f"\n📖 正在阅读游戏论坛爆料帖...")
print("=" * 60)
print(GAME_FORUM_POST[:200] + "...")
print("=" * 60)
-
+
# 执行提取
print("\n⚙️ 执行两阶段提取...\n")
- graph.extract(GAME_FORUM_POST)
+ graph.feed_text(GAME_FORUM_POST)
# ==================== 4. 战报分析 ====================
@@ -326,15 +334,15 @@ def run_demo():
print("-" * 60)
for i, e in enumerate(graph.edges, 1):
print(f"{i}. {e}")
-
+
# ==================== 5. 语义搜索 (查内鬼) ====================
print("\n" + "=" * 60)
print("🔍 游戏管理员(GM)调查查询模块")
print("=" * 60)
-
- graph.build_index() # 建立索引
-
+
+ graph.build_index(index_nodes=True, index_edges=True) # 建立索引
+
# 场景1: 找谁拿了装备?
q1 = "谁拿走了传说武器?"
print(f"\n❓ Query: {q1}")
@@ -388,16 +396,17 @@ def run_demo():
print(f" (搜索出错: {e})")
# ==================== 6. 保存知识图谱 ====================
-
+
print("\n" + "=" * 60)
print("💾 保存知识图谱到本地...")
print("=" * 60)
- save_path = project_root / "temp" / "game_guild_graph"
+ save_path = project_root / "temp" / "auto_graph_demo"
try:
graph.dump(save_path)
print(f"✅ 图谱已保存到: {save_path}")
except Exception as e:
print(f"⚠️ 保存失败: {e}")
+
if __name__ == "__main__":
run_demo()
diff --git a/hyperextract/core/set.py b/hyperextract/core/set.py
index 4803cd9..3ac90f1 100644
--- a/hyperextract/core/set.py
+++ b/hyperextract/core/set.py
@@ -335,6 +335,8 @@ class AutoSet(BaseAutoType[AutoSetSchema[Item]], Generic[Item]):
if not self.items:
logger.warning("No items to search")
return []
+ if not self._data_memory.has_index():
+ raise ValueError("Index not built. Call build_index() first.")
return self._data_memory.search(query, top_k=top_k)
# ==================== Index Storage ====================
diff --git a/hyperextract/graphs/__init__.py b/hyperextract/graphs/__init__.py
index e69de29..42331f7 100644
--- a/hyperextract/graphs/__init__.py
+++ b/hyperextract/graphs/__init__.py
@@ -0,0 +1,4 @@
+from .base import AutoGraph
+
+
+__all__ = ["AutoGraph"]
diff --git a/hyperextract/graphs/base.py b/hyperextract/graphs/base.py
index 464c3b4..6f78934 100644
--- a/hyperextract/graphs/base.py
+++ b/hyperextract/graphs/base.py
@@ -114,7 +114,8 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
extraction_mode: str = "one_stage",
node_strategy_or_merger: MergeStrategy
| BaseMerger = MergeStrategy.LLM.BALANCED,
- edge_strategy_or_merger: MergeStrategy | BaseMerger = MergeStrategy.MERGE_FIELD,
+ edge_strategy_or_merger: MergeStrategy
+ | BaseMerger = MergeStrategy.LLM.BALANCED,
prompt: str = "",
prompt_for_node_extraction: str = "",
prompt_for_edge_extraction: str = "",
@@ -136,7 +137,7 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
embedder: Embedding model for vector indexing.
extraction_mode: "one_stage" (extract nodes+edges together) or "two_stage" (nodes first, then edges).
node_strategy_or_merger: Merge strategy for duplicate nodes (default: LLM.BALANCED).
- edge_strategy_or_merger: Merge strategy for duplicate edges (default: MERGE_FIELD).
+ edge_strategy_or_merger: Merge strategy for duplicate edges (default: LLM.BALANCED).
prompt: Custom extraction prompt for one-stage mode.
prompt_for_node_extraction: Custom extraction prompt for two-stage node extraction.
prompt_for_edge_extraction: Custom extraction prompt for two-stage edge extraction.
@@ -242,6 +243,34 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
"""Returns the default prompt for one-stage graph extraction."""
return self._default_graph_prompt
+ def _create_empty_instance(self) -> "AutoGraph[Node, Edge]":
+ """Creates a new empty AutoGraph instance with the same configuration as this one.
+
+ Overrides parent method to handle AutoGraph-specific parameters.
+
+ Returns:
+ A new empty AutoGraph instance with identical configuration.
+ """
+ return self.__class__(
+ node_schema=self.node_schema,
+ edge_schema=self.edge_schema,
+ node_key_extractor=self.node_key_extractor,
+ edge_key_extractor=self.edge_key_extractor,
+ nodes_in_edge_extractor=self.nodes_in_edge_extractor,
+ llm_client=self.llm_client,
+ embedder=self.embedder,
+ extraction_mode=self.extraction_mode,
+ node_strategy_or_merger=self.node_merger,
+ edge_strategy_or_merger=self.edge_merger,
+ prompt=self.prompt,
+ prompt_for_node_extraction=self.node_prompt,
+ prompt_for_edge_extraction=self.edge_prompt,
+ chunk_size=self.chunk_size,
+ chunk_overlap=self.chunk_overlap,
+ max_workers=self.max_workers,
+ show_progress=self.show_progress,
+ )
+
@property
def _default_graph_prompt(self) -> str:
"""Default prompt for one-stage graph extraction (nodes + edges together).
@@ -451,9 +480,10 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
chunk_edge_lists = self._extract_edges_batch(chunks, chunk_node_lists)
# 4. Construct Partial Graphs (Tuple format for merge optimization)
- partial_graphs = []
- for node_list, edge_list in zip(chunk_node_lists, chunk_edge_lists):
- partial_graphs.append((node_list.items, edge_list.items))
+ partial_graphs = (
+ [node_list.items for node_list in chunk_node_lists],
+ [edge_list.items for edge_list in chunk_edge_lists],
+ )
# 5. Global Merge (passes tuples to merge_batch_data)
return self.merge_batch_data(partial_graphs)
@@ -531,8 +561,8 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
src_key, dst_key = self.nodes_in_edge_extractor(edge)
# Check if both endpoints exist
- src_exists = src_key in valid_node_keys or src_key in self._node_memory
- dst_exists = dst_key in valid_node_keys or dst_key in self._node_memory
+ src_exists = src_key in valid_node_keys or src_key in self._node_memory.keys
+ dst_exists = dst_key in valid_node_keys or dst_key in self._node_memory.keys
if src_exists and dst_exists:
refined_edges.append(edge)
@@ -580,10 +610,10 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
"Invalid input format for batch merging"
)
nodes_lists, edges_lists = data_list_or_tuple[0], data_list_or_tuple[1]
- assert isinstance(nodes_lists[0], Node), (
+ assert self.node_schema.model_validate(nodes_lists[0][0]), (
"Invalid node list format for batch merging"
)
- assert isinstance(edges_lists[0], Edge), (
+ assert self.edge_schema.model_validate(edges_lists[0][0]), (
"Invalid edge list format for batch merging"
)
@@ -654,15 +684,25 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[Node, Edge]], Generic[Node, Edge]):
)
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)
if search_nodes:
- return self.search_nodes(query, top_k)
+ 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
if search_edges:
- return self.search_edges(query, top_k)
+ 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
def search_nodes(self, query: str, top_k: int = 3) -> List[Node]:
"""Semantic search for nodes/entities only.
diff --git a/pyproject.toml b/pyproject.toml
index 0d4ab1f..1663497 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,7 +27,7 @@ dependencies = [
"langchain-community>=0.4.1",
"langchain-openai>=1.1.7",
"loguru>=0.7.3",
- "ontomem>=0.1.8",
+ "ontomem>=0.1.9",
"numpy>=2.4.1",
"python-dotenv>=1.2.1",
]
diff --git a/uv.lock b/uv.lock
index d41a7ce..0a9efc2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -587,7 +587,7 @@ requires-dist = [
{ name = "langchain-openai", specifier = ">=1.1.7" },
{ name = "loguru", specifier = ">=0.7.3" },
{ name = "numpy", specifier = ">=2.4.1" },
- { name = "ontomem", specifier = ">=0.1.8" },
+ { name = "ontomem", specifier = ">=0.1.9" },
{ name = "python-dotenv", specifier = ">=1.2.1" },
]
@@ -1353,7 +1353,7 @@ wheels = [
[[package]]
name = "ontomem"
-version = "0.1.8"
+version = "0.1.9"
source = { registry = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/" }
dependencies = [
{ name = "faiss-cpu" },
@@ -1365,9 +1365,9 @@ dependencies = [
{ name = "pytest" },
{ name = "python-dotenv" },
]
-sdist = { url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/ef/56/f62f9cdcce9a9132f9bd0a56ba1684f78269926dcf1bcee19894e8c3d9be/ontomem-0.1.8.tar.gz", hash = "sha256:562885f7c10991604bbacbe957a77af824e73a1ed7ee610e06c48d52f0ce0d49", size = 2521167, upload-time = "2026-01-22T07:40:47.474Z" }
+sdist = { url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/5b/03/6545152c7b899104452d2d4f1aa083eb7bb9fc69cce8095bb0cc1fb18cf0/ontomem-0.1.9.tar.gz", hash = "sha256:426020f97521241b497b584d30a2aa8649690d91e821853bedd026461a198285", size = 2521743, upload-time = "2026-01-23T06:02:56.283Z" }
wheels = [
- { url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/cf/27/d2b1cabb64891a59de4917a903e3b02164de08b91853c1926c15e933e2ba/ontomem-0.1.8-py3-none-any.whl", hash = "sha256:71ae701d70870ec2dc4b52ed8dd77404f3df1f8ddab37ae3a53addcf55cf8d9a", size = 36913, upload-time = "2026-01-22T07:40:45.845Z" },
+ { url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/packages/24/f3/52adb021f4ee8c82bbee998b1451d7355a4aa5ed2e853bcf7953bcf00b49/ontomem-0.1.9-py3-none-any.whl", hash = "sha256:d5dbbda0c9336b104b9c6a84486926ff5a0c917efd1206ba8746befd7a9a143a", size = 36992, upload-time = "2026-01-23T06:02:54.321Z" },
]
[[package]]