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.pysimilarity index 88%rename from examples/auto_graph_game_demo.pyrename to examples/auto_graph_demo.pyindex 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, Fieldfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.graphs.base import AutoGraph+from hyperextract.graphs import AutoGraphfrom ontomem import MergeStrategyimport dotenv@@ -29,24 +29,37 @@ import dotenvdotenv.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():# 创建 AutoGraphprint("📊 构建 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.pyindex 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__.pyindex 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.pyindex 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,+ )+@propertydef _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.keysif 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 nodesif 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 edgesdef search_nodes(self, query: str, top_k: int = 3) -> List[Node]:"""Semantic search for nodes/entities only.diff --git a/pyproject.toml b/pyproject.tomlindex 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.lockindex 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]]