Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

Enhance AutoGraph and related classes with improved chunk size and overlap settings; introduce AutoTemporalGraph demo for time-aware entity extraction and analysis.

yifanfeng975d2c680e09d8
diff --git a/examples/atom_demo.py b/examples/atom_demo.py
index 32d0819..0a9cfcb 100644
--- a/examples/atom_demo.py
+++ b/examples/atom_demo.py
@@ -294,6 +294,29 @@ def main():
except Exception as e:
print(f"⚠ 警告: 无法保存结果: {str(e)}")
+ # ============================================================================
+ # 智能对话 (Chat)
+ # ============================================================================
+ print("\n" + "=" * 80)
+ print("💬 知识图谱智能问答")
+ print("=" * 80)
+ print("基于提取的知识进行深度对话...\n")
+
+ chat_questions = [
+ "Apple 公司的发展历史中,有哪些关键的人物和事件?",
+ "iPhone 对 Apple 公司和整个科技行业产生了什么影响?",
+ "从时间线看,Apple 的创新节奏是如何变化的?"
+ ]
+
+ kg.build_index()
+ for q in chat_questions:
+ print(f"❓ 提问: {q}")
+ try:
+ response = kg.chat(q, top_k=5)
+ print(f"💡 回答: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ 对话异常: {e}\n")
+
print("\n" + "=" * 80)
print("✨ Atom 演示完成!")
print("=" * 80)
@@ -302,6 +325,7 @@ def main():
print(" ✓ 时序追踪:产品发布日期、人物任职期间")
print(" ✓ 证据追踪:每条关系都关联到源事实")
print(" ✓ 语义去重:自动合并同义实体")
+ print(" ✓ 智能对话:基于知识图谱的 RAG 问答")
if __name__ == "__main__":
diff --git a/examples/auto_graph_demo.py b/examples/auto_graph_demo.py
index 4f5f46c..0c752f8 100644
--- a/examples/auto_graph_demo.py
+++ b/examples/auto_graph_demo.py
@@ -401,7 +401,28 @@ def run_demo():
except Exception as e:
print(f" (搜索出错: {e})")
- # ==================== 6. 保存知识图谱 ====================
+ # ==================== 6. 交互式对话 (Chat RAG) ====================
+
+ print("\n" + "=" * 60)
+ print("💬 进入交互式对话模式")
+ print("=" * 60)
+ print("🤖 正在基于提取的知识图谱回答复杂问题...\n")
+
+ chat_queries = [
+ "请总结这个公会冲突的核心原因。",
+ "暗影刺客和小甜甜的行为对团队造成了什么影响?",
+ "从这个事件中,我们学到了什么关于公会管理的经验?"
+ ]
+
+ for q in chat_queries:
+ print(f"👤 提问: {q}")
+ try:
+ response = graph.chat(q, top_k=5)
+ print(f"🤖 回答: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ 对话异常: {e}\n")
+
+ # ==================== 7. 保存知识图谱 ====================
print("\n" + "=" * 60)
print("💾 保存知识图谱到本地...")
diff --git a/examples/auto_hypergraph_demo.py b/examples/auto_hypergraph_demo.py
index 84b4f66..b0146d2 100644
--- a/examples/auto_hypergraph_demo.py
+++ b/examples/auto_hypergraph_demo.py
@@ -347,6 +347,26 @@ def main():
except Exception as e:
print(f"\n ⚠️ 保存失败: {e}")
+ # ==================== 第六部分:智能对话 ====================
+ print("\n" + "=" * 70)
+ print("💬 超图智能问答")
+ print("=" * 70)
+ print("基于提取的超边关系进行多角度分析...\n")
+
+ hypergraph_questions = [
+ "这个研究小组的主要合作特点是什么?",
+ "团队成员之间的互动模式如何?",
+ "从超图结构看,谁是这个社区的关键人物?"
+ ]
+
+ for q in hypergraph_questions:
+ print(f"🔍 分析师: {q}")
+ try:
+ result = hypergraph.chat(q, top_k=5)
+ print(f"📊 深层分析: {result.content}\n")
+ except Exception as e:
+ print(f"⚠️ 分析异常: {e}\n")
+
print("\n" + "=" * 70)
print("✅ 分析完成!")
print("=" * 70)
diff --git a/examples/auto_list_demo.py b/examples/auto_list_demo.py
index 744be29..b8f74e1 100644
--- a/examples/auto_list_demo.py
+++ b/examples/auto_list_demo.py
@@ -206,6 +206,25 @@ def main():
a_loaded_event_list.clear()
print(f" 清空后: {len(a_loaded_event_list)} 个事件")
+ # 14. 智能对话 (Chat)
+ print("\n" + "=" * 80)
+ print("💬 智能对话功能")
+ print("=" * 80)
+ print("正在基于提取的事件列表进行智能问答...\n")
+
+ chat_questions = [
+ "这些新闻中,哪些事件对科技行业的影响最大?",
+ "请总结一下2024年科技领域的主要趋势。"
+ ]
+
+ for q in chat_questions:
+ print(f"❓ 问题: {q}")
+ try:
+ resp = a_event_list.chat(q, top_k=5)
+ print(f"✨ 回答: {resp.content}\n")
+ except Exception as e:
+ print(f"⚠️ 对话出错: {e}\n")
+
print("\n" + "=" * 80)
print("示例运行完成!")
print("=" * 80)
diff --git a/examples/auto_model_demo.py b/examples/auto_model_demo.py
index 0a47a7c..9cd4ece 100644
--- a/examples/auto_model_demo.py
+++ b/examples/auto_model_demo.py
@@ -233,6 +233,26 @@ def main():
print(" 加载成功!")
print(f" 标题: {a_loaded_document_model.data.title}")
+ # 11. 智能对话 (Chat)
+ print("\n" + "=" * 80)
+ print("💬 文档智能咨询")
+ print("=" * 80)
+ print("基于提取的文档结构进行智能对话...\n")
+
+ doc_questions = [
+ "这篇文档的核心观点是什么?",
+ "文档中提到的主要技术有哪些?"
+ ]
+
+ a_document_model.build_index()
+ for q in doc_questions:
+ print(f"❓ 读者: {q}")
+ try:
+ resp = a_document_model.chat(q, top_k=3)
+ print(f"📖 AI助手: {resp.content}\n")
+ except Exception as e:
+ print(f"⚠️ 回答失败: {e}\n")
+
print("\n" + "=" * 80)
print("示例运行完成!")
print("=" * 80)
diff --git a/examples/auto_set_demo.py b/examples/auto_set_demo.py
index b227563..881307c 100644
--- a/examples/auto_set_demo.py
+++ b/examples/auto_set_demo.py
@@ -257,6 +257,27 @@ def main():
print(" √ 智能合并多个来源的冲突信息")
print(" √ 支持所有怪物的语义搜索")
print(" √ 持久化存储和加载")
+
+ # 交互式对话 (Chat)
+ print("\n" + "=" * 80)
+ print("💬 冒险者智能咨询系统")
+ print("=" * 80)
+ print("根据怪物图鉴回答冒险者的提问...\n")
+
+ adventurer_questions = [
+ "我想去地下矿井冒险,应该带什么装备来对付那里的怪物?",
+ "哪些怪物掉落最值钱的宝物?",
+ "请给我推荐一个适合新手的狩猎对象。"
+ ]
+
+ for q in adventurer_questions:
+ print(f"⚔️ 冒险者: {q}")
+ try:
+ answer = monster_codex.chat(q, top_k=5)
+ print(f"🧙 NPC商人: {answer.content}\n")
+ except Exception as e:
+ print(f"⚠️ 无法回答: {e}\n")
+
print("=" * 80)
diff --git a/examples/auto_temporal_graph_demo.py b/examples/auto_temporal_graph_demo.py
new file mode 100644
index 0000000..2cfaaa0
--- /dev/null
+++ b/examples/auto_temporal_graph_demo.py
@@ -0,0 +1,329 @@
+"""
+AutoTemporalGraph Demo: 谍战惊悚 - 柏林的48小时 🕵️‍♀️💣
+
+场景背景:
+在冷战时期的东柏林,一名CIA特工Elias必须在48小时内阻止恐怖分子的炸弹计划。
+时间信息隐含在叙述中,通过人物对话、观察和行动序列自然出现。
+
+难点:
+1. 时间隐藏在对话中:"看了一眼手表"、"两分钟后"等自然表述
+2. 并发事件:同一时间多个地点的不同行动
+3. 时间精度:需要提取到分钟级别(HH:MM)
+4. 实体合并:同一个人的不同代称需要被识别和合并
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+# 添加项目根目录到路径
+project_root = Path(__file__).resolve().parent.parent
+sys.path.append(str(project_root))
+
+from pydantic import BaseModel, Field
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+
+from hyperextract.graphs import AutoTemporalGraph
+from ontomem import MergeStrategy
+
+import dotenv
+
+dotenv.load_dotenv()
+
+# ==================== 1. 定义时间感知知识结构 (Schema) ====================
+
+
+class SpyEntity(BaseModel):
+ """谍战实体节点(特工、地点、组织等)"""
+
+ name: str = Field(description="实体名称,例如特工ID、地点名、组织名")
+ category: str = Field(
+ description="实体类型:'特工', '地点', '组织', '物品', '事件'", default="未知"
+ )
+ description: str = Field(
+ description="实体的详细描述或身份背景", default=""
+ )
+
+ def __repr__(self):
+ return f"🕵️ [{self.category}] {self.name} - {self.description}"
+
+
+class TemporalAction(BaseModel):
+ """时间感知的行动边"""
+
+ source: str = Field(description="行动发起者")
+ target: str = Field(description="行动对象(可以是人、地点或物品)")
+ action: str = Field(description="具体行动内容")
+ timestamp: Optional[str] = Field(
+ description="行动发生的具体时间点(YYYY-MM-DD HH:MM 格式,精确到分钟)", default=None
+ )
+ description: str = Field(
+ description="行动的详细描述、上下文或发生地点", default=""
+ )
+
+ def __repr__(self):
+ time_str = f" @ {self.timestamp}" if self.timestamp else ""
+ desc_str = f" ({self.description})" if self.description else ""
+ return f"⚡ {self.source} --[{self.action}]--> {self.target}{time_str}{desc_str}"
+
+
+# ==================== 2. 谍战叙述文本 ====================
+
+SPY_THRILLER_NARRATIVE = """
+【CIA 绝密档案:代号"日蚀"行动日志】
+【日期:2024-03-15】
+【地点:柏林】
+【特工:Elias】
+
+08:30,柏林的晨雾还未散去。特工 Elias 穿着一身灰色风衣,在勃兰登堡门附近的 Tiergarten 公园长椅上坐下。他在喂鸽子,看似悠闲,实则警惕地观察四周。
+
+五分钟后(08:35),联络员 Sarah 骑着自行车经过,故意丢下了一份报纸。夹在报纸里的是一张加密纸条:"Viktor 在东区活动。第一枚炸弹已部署在 Friedrichstraße 车站。"
+
+Elias 迅速离开。09:00,他在安全屋换装完毕,携带了干扰器和开锁工具。
+
+09:15,Elias 抵达 Friedrichstraße 车站。车站人流如织。他在月台的自动售票机旁,发现了 Viktor 的助手 Bond。Bond 手提一个沉重的黑色公文包,神色慌张,正在频繁看表。
+
+此时(09:15),在城市的另一端,废弃工厂的地下室里,Viktor 正在通过无线电向所有战斗小组下达指令:"不用等了,现在就启动倒计时。"
+
+09:42,Bond 走向了车站深处的地下维修通道入口。Elias 悄无声息地跟了进去。通道里光线昏暗,只有滴水的声音。
+
+突然,Bond 猛地转身,手里多了一把消音手枪。两人展开了近身搏斗。09:44,Bond 试图按下公文包上的红色按钮。
+
+09:45,随着一声沉闷的枪响,Elias 击中了 Bond 的手腕,起爆器滑落到铁轨旁。此时公文包上的红色 LED 灯亮起,显示倒计时剩余时间:15分钟。
+
+Elias 开始拆弹。这其实是一个复杂的诱饵装置。他在切断第一根红线时,发现电路逻辑不对。现在是 09:50。
+
+"真的炸弹在哪里?" Elias 踩住 Bond 的伤口逼问。
+Bond 疼得满头大汗,狞笑道:"你来不及了。真家伙在威廉皇帝纪念教堂。定时 10:30 引爆,那里现在全是游客。"
+
+10:05,Elias 冲出车站,抢了一辆停在路边的杜卡迪摩托车。他在早高峰的车流中狂飙,连闯三个红灯。
+与此同时(10:05),Sarah 收到了 Elias 的警报,带领 CIA 战术小队开始疏散教堂外围的人群。
+
+10:15,Elias 冲进教堂。他在螺旋楼梯上被两名雇佣兵拦截。经过一番激烈的枪战,他解决了守卫,冲上钟楼顶部。
+
+10:20,他在钟楼顶层发现了 Viktor。Viktor 手里抓着扩音器,似乎正准备发表某种宣言。看到 Elias,Viktor 拔出了匕首。
+
+10:25,Elias 与 Viktor 在狭窄的钟楼平台展开肉搏。Viktor 试图将不知情的游客作为人质,Elias 抓住破绽,一记重拳将 Viktor 击倒,随后将其拷在栏杆上。
+
+10:26,Elias 找到了藏在大钟底座下的生化炸弹。显示屏跳动着:00:03:59。
+这不是普通的定时炸弹,还有倾斜传感器。
+
+10:28,Elias 满头大汗。他通过耳机连接了 Sarah 传来的蓝图指示。"剪蓝线,还是黄线?"
+"等等!" Sarah 在耳机里喊道,"图纸有更新,是红蓝相间的那根地线!"
+Elias 深吸一口气,剪断了那根不起眼的细线。
+
+计时器定格在 00:01:30。危机解除。
+
+11:00,警方封锁线建立。Viktor 和 Bond 被押上囚车。Elias 在混乱的人群中压低帽檐,转身走进了一条小巷,消失在柏林的喧嚣中。
+"""
+
+# ==================== 3. 运行提取 ====================
+
+
+def run_demo():
+ print("=" * 70)
+ print("🕵️ 柏林谍战行动 - 时间线分析模块启动")
+ print("=" * 70)
+
+ # 初始化 LLM
+ print("\n🔧 初始化 LLM 和嵌入模型...")
+ llm = ChatOpenAI(model="gpt-4o", temperature=0)
+ embedder = OpenAIEmbeddings()
+
+ # 创建 AutoTemporalGraph
+ print("📊 构建 AutoTemporalGraph 实例...\n")
+ graph = AutoTemporalGraph[SpyEntity, TemporalAction](
+ node_schema=SpyEntity,
+ edge_schema=TemporalAction,
+ # 1. 实体ID提取规则
+ node_key_extractor=lambda x: x.name,
+ # 2. 时间感知的行动唯一性规则(包含时间维度)
+ temporal_edge_key_extractor=lambda x: f"{x.source}|{x.action}|{x.target}|{x.timestamp or ''}",
+ # 3. 行动双方映射规则
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=llm,
+ embedder=embedder,
+ # 观察时间:故事背景
+ observation_time="2024-03-15",
+ # 两阶段提取
+ extraction_mode="two_stage",
+ # 智能合并:能识别"Elias" = "特工" 等
+ node_strategy_or_merger=MergeStrategy.LLM.BALANCED,
+ edge_strategy_or_merger=MergeStrategy.LLM.BALANCED,
+ # 针对谍战的特化提示词
+ prompt_for_node_extraction=(
+ "提取文本中的所有关键实体作为节点。包括:特工/人物、地点、组织、物品、事件。\n"
+ "关键要求:\n"
+ "1. 提取所有人名(Elias、Viktor、Bond、Katya、Sarah等)及其别称或代称\n"
+ "2. 提取所有地点(柏林、Black Swan酒吧、Charlottenburg Palace等)\n"
+ "3. 提取组织(CIA、KGB等)和物品(炸弹、枪、起爆器等)\n"
+ "4. 将代称和别名标准化为主要名称"
+ ),
+ prompt_for_edge_extraction=(
+ "提取人物之间和与物品/地点之间的**时间感知的行动**。\n"
+ "关键要求:\n"
+ "1. 时间信息可能隐含在叙述中,如'看了一眼手表——秒针刚好划过十二点。现在是 18:42'\n"
+ "2. 相对时间表达如'两分钟后'、'十分钟过去了'需要根据前文推算具体时间\n"
+ "3. 并发事件('与此同时')需提取相同的时间戳\n"
+ "4. 提取精确到分钟级别(HH:MM格式),日期使用 YYYY-MM-DD\n"
+ "5. 在 description 字段中记录行动发生的地点或其他上下文信息\n"
+ "6. 如果时间不明确,填写空值而不是猜测"
+ ),
+ verbose=True,
+ chunk_size=2048,
+ )
+
+ print(f"\n📖 正在加载谍战行动日志...")
+ print("=" * 70)
+ print(SPY_THRILLER_NARRATIVE[:300] + "...")
+ print("=" * 70)
+
+ # 执行提取
+ print("\n⚙️ 执行两阶段时间感知提取...\n")
+ graph.feed_text(SPY_THRILLER_NARRATIVE)
+
+ # ==================== 4. 时间线分析 ====================
+
+ print("\n" + "=" * 70)
+ print(f"✅ 时间线分析完成!")
+ print("=" * 70)
+ print(f" 提取的实体: {len(graph.nodes)} 个")
+ print(f" 记录的行动事件: {len(graph.edges)} 个")
+
+ print("\n" + "-" * 70)
+ print("🕵️ 实体信息 (Nodes)")
+ print("-" * 70)
+ for i, entity in enumerate(graph.nodes, 1):
+ print(f"{i}. {entity}")
+
+ print("\n" + "-" * 70)
+ print("⚡ 时间感知行动时间表 (Edges)")
+ print("-" * 70)
+
+ # 排序有时间的边
+ all_sorted_edges = sorted(graph.edges, key=lambda x: x.timestamp or "9999-12-31")
+ for i, action in enumerate(all_sorted_edges, 1):
+ print(f"{i}. {action}")
+
+ # ==================== 5. 情报检索系统 ====================
+
+ print("\n" + "=" * 70)
+ print("🔍 CIA 情报检索系统")
+ print("=" * 70)
+
+ # 建立索引
+ graph.build_index()
+
+ # 检索场景1: 找关键人物
+ q1 = "Elias做了什么?"
+ print(f"\n❓ Query: {q1}")
+ try:
+ nodes, edges = graph.search(q1, top_k=5)
+ if edges:
+ for e in edges:
+ print(f" ⚡ {e}")
+ else:
+ print(" (无相关记录)")
+ except Exception as e:
+ print(f" (检索出错: {e})")
+
+ # 检索场景2: 找地点
+ q2 = "发生在地铁站的事件有哪些?"
+ print(f"\n❓ Query: {q2}")
+ try:
+ nodes, edges = graph.search(q2, top_k=5)
+ if edges:
+ for e in edges:
+ print(f" 📍 {e}")
+ else:
+ print(" (无相关记录)")
+ except Exception as e:
+ print(f" (检索出错: {e})")
+
+ # 检索场景3: 找对抗
+ q3 = "Viktor和Elias之间的冲突"
+ print(f"\n❓ Query: {q3}")
+ try:
+ nodes, edges = graph.search(q3, top_k=5)
+ if edges:
+ for e in edges:
+ print(f" 🔥 {e}")
+ else:
+ print(" (无相关记录)")
+ except Exception as e:
+ print(f" (检索出错: {e})")
+
+ # 检索场景4: 找时间关键点
+ q4 = "下午的行动"
+ print(f"\n❓ Query: {q4}")
+ try:
+ nodes, edges = graph.search(q4, top_k=5)
+ if edges:
+ for e in edges:
+ print(f" ⏰ {e}")
+ else:
+ print(" (无相关记录)")
+ except Exception as e:
+ print(f" (检索出错: {e})")
+
+ # 检索场景5: 找组织
+ q5 = "CIA和KGB分别做了什么?"
+ print(f"\n❓ Query: {q5}")
+ try:
+ nodes, edges = graph.search(q5, top_k=5)
+ if nodes:
+ print(f" 🏢 相关实体:")
+ for n in nodes:
+ print(f" - {n}")
+ if edges:
+ print(f" 📋 相关行动:")
+ for e in edges:
+ print(f" - {e}")
+ if not nodes and not edges:
+ print(" (无相关记录)")
+ except Exception as e:
+ print(f" (检索出错: {e})")
+
+ # ==================== 6. 交互式情报问答 (Chat) ====================
+
+ print("\n" + "=" * 70)
+ print("💬 正在切换至:CIA 交互式情报分析终端")
+ print("=" * 70)
+ print("系统提示: 您现在可以直接用自然语言询问关于行动的细节、动机或因果关系。\n")
+
+ chat_queries = [
+ "Viktor的炸弹袭击计划最终是如何失败的?请按时间顺序列出导致他失败的关键转折点。",
+ "Elias在整个行动中使用了哪些交通工具?请结合时间点说明。",
+ "这次行动中,哪些人物的决策改变了事件的进程?"
+ ]
+
+ for q in chat_queries:
+ print(f"👤 [高级分析师]: {q}")
+ print("🤖 [系统核心]: 正在检索关联情报节点并生成分析报告...")
+
+ try:
+ # 使用 chat 接口进行 RAG 问答
+ response = graph.chat(q, top_k=5)
+ print(f"📄 [情报简报]:\n{response.content}\n")
+ except Exception as e:
+ print(f"⚠️ 系统响应异常: {e}\n")
+
+ # ==================== 7. 保存知识图谱 ====================
+
+ print("\n" + "=" * 70)
+ print("💾 保存时间感知知识图谱到本地...")
+ print("=" * 70)
+ save_path = project_root / "temp" / "auto_temporal_graph_demo"
+ try:
+ graph.dump(save_path)
+ print(f"✅ 图谱已保存到: {save_path}")
+ except Exception as e:
+ print(f"⚠️ 保存失败: {e}")
+
+ print("\n" + "=" * 70)
+ print("✅ 演示完成!时间线已成功提取并分析。")
+ print("=" * 70)
+
+
+if __name__ == "__main__":
+ run_demo()
diff --git a/examples/hyper_rag_demo.py b/examples/hyper_rag_demo.py
index 2d0c8d8..1acdda6 100644
--- a/examples/hyper_rag_demo.py
+++ b/examples/hyper_rag_demo.py
@@ -227,6 +227,28 @@ if __name__ == "__main__":
except Exception as e:
print(f" Search error: {str(e)}")
+ # ============================================================================
+ # Chat with HyperRAG
+ # ============================================================================
+ print("\n" + "=" * 80)
+ print("💬 Interactive Chat with HyperRAG")
+ print("=" * 80)
+ 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?"
+ ]
+
+ for q in chat_queries:
+ print(f"❓ User: {q}")
+ try:
+ response = rag.chat(q, top_k=5)
+ print(f"🤖 HyperRAG: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ Chat error: {e}\n")
+
# ============================================================================
# Save Results
# ============================================================================
diff --git a/examples/itext2kg_demo.py b/examples/itext2kg_demo.py
index 6f9ce42..d5cb68c 100644
--- a/examples/itext2kg_demo.py
+++ b/examples/itext2kg_demo.py
@@ -279,7 +279,28 @@ def main():
# 保存结果
# ============================================================================
print("\n" + "=" * 70)
- print("💾 保存结果...")
+ print("� 智能对话功能")
+ print("=" * 70)
+ print("基于提取的知识图谱进行智能问答...\n")
+
+ chat_queries = [
+ "这个公会冲突的主要原因是什么?",
+ "哪些人物在这个事件中扮演了关键角色?",
+ "如果你是公会管理者,你会如何处理这个局面?"
+ ]
+
+ kg.build_index()
+ for q in chat_queries:
+ print(f"❓ 问题: {q}")
+ try:
+ response = kg.chat(q, top_k=5)
+ print(f"💡 分析: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ 对话异常: {e}\n")
+
+ # ============================================================================
+ print("\n" + "=" * 70)
+ print("�💾 保存结果...")
print("=" * 70)
try:
diff --git a/examples/itext2kg_star_demo.py b/examples/itext2kg_star_demo.py
index 4edb2a2..6168c99 100644
--- a/examples/itext2kg_star_demo.py
+++ b/examples/itext2kg_star_demo.py
@@ -274,6 +274,27 @@ def main():
print(" ✓ 每条边都自动添加了观测日期(提取时间)")
print(" ✓ 图谱结构得到了优化和规范化")
+ # 6. 智能对话 (Chat)
+ print("\n" + "=" * 70)
+ print("💬 主题感知的知识问答")
+ print("=" * 70)
+ print("基于提取的主题知识图谱进行深度分析...\n")
+
+ topic_questions = [
+ "根据提取的知识,这篇文本的主要话题是什么?",
+ "文中提到的关键实体之间有什么联系?",
+ "从时间和主题的角度,你能总结一下这篇文本的核心内容吗?"
+ ]
+
+ kg.build_index()
+ for q in topic_questions:
+ print(f"🤔 提问: {q}")
+ try:
+ response = kg.chat(q, top_k=5)
+ print(f"📚 回答: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ 对话异常: {e}\n")
+
# 保存
try:
output_dir = "temp/itext2kg_star_demo"
diff --git a/examples/kg_gen_demo.py b/examples/kg_gen_demo.py
index f993c63..376c5f0 100644
--- a/examples/kg_gen_demo.py
+++ b/examples/kg_gen_demo.py
@@ -338,6 +338,29 @@ def main():
for entity, count in entity_degree.most_common(5):
print(f" • {entity}: 参与 {count} 个关系")
+ # ============================================================================
+ # Chat with Knowledge Graph
+ # ============================================================================
+ print("\n" + "=" * 70)
+ print("💬 Knowledge Graph Intelligence")
+ print("=" * 70)
+ print("Interactive dialogue based on extracted relationships...\n")
+
+ kg_questions = [
+ "What are the main conflicts mentioned in this text?",
+ "Which characters played the most important roles in the guild drama?",
+ "What lessons can be learned from this event?"
+ ]
+
+ kg.build_index()
+ for q in kg_questions:
+ print(f"❓ Question: {q}")
+ try:
+ response = kg.chat(q, top_k=5)
+ print(f"🤖 Answer: {response.content}\n")
+ except Exception as e:
+ print(f"⚠️ Chat error: {e}\n")
+
# ============================================================================
# Save Results
# ============================================================================
diff --git a/hyperextract/core/base.py b/hyperextract/core/base.py
index b24e421..bd218b9 100644
--- a/hyperextract/core/base.py
+++ b/hyperextract/core/base.py
@@ -42,8 +42,8 @@ class BaseAutoType(ABC, Generic[T]):
embedder: Embeddings,
*,
prompt: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
):
diff --git a/hyperextract/core/list.py b/hyperextract/core/list.py
index efda648..3f78abe 100644
--- a/hyperextract/core/list.py
+++ b/hyperextract/core/list.py
@@ -59,8 +59,8 @@ class AutoList(BaseAutoType[AutoListSchema[Item]], Generic[Item]):
embedder: Embeddings,
*,
prompt: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
fields_for_index: List[str] | None = None,
@@ -81,6 +81,7 @@ class AutoList(BaseAutoType[AutoListSchema[Item]], Generic[Item]):
"""
self.item_schema = item_schema
self.fields_for_index = fields_for_index
+ self._constructor_kwargs = kwargs
container_name = f"{item_schema.__name__}List"
self.item_list_schema = create_model(
@@ -143,6 +144,7 @@ class AutoList(BaseAutoType[AutoListSchema[Item]], Generic[Item]):
max_workers=self.max_workers,
verbose=self.verbose,
fields_for_index=self.fields_for_index,
+ **self._constructor_kwargs, # Propagate additional arguments
)
@property
diff --git a/hyperextract/core/model.py b/hyperextract/core/model.py
index a3a3061..ffe03ee 100644
--- a/hyperextract/core/model.py
+++ b/hyperextract/core/model.py
@@ -40,8 +40,8 @@ class AutoModel(BaseAutoType[T]):
*,
strategy_or_merger: MergeStrategy | BaseMerger = MergeStrategy.LLM.BALANCED,
prompt: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
**kwargs,
@@ -64,6 +64,7 @@ class AutoModel(BaseAutoType[T]):
"""
# Store strategy before calling super().__init__
self._strategy_or_merger = strategy_or_merger
+ self._constructor_kwargs = kwargs
super().__init__(
data_schema,
@@ -111,6 +112,7 @@ class AutoModel(BaseAutoType[T]):
chunk_overlap=self.chunk_overlap,
max_workers=self.max_workers,
verbose=self.verbose,
+ **self._constructor_kwargs, # Propagate additional arguments
)
def _default_prompt(self) -> str:
diff --git a/hyperextract/core/set.py b/hyperextract/core/set.py
index 5deaa42..4e0dd58 100644
--- a/hyperextract/core/set.py
+++ b/hyperextract/core/set.py
@@ -92,8 +92,8 @@ class AutoSet(BaseAutoType[AutoSetSchema[Item]], Generic[Item]):
*,
strategy_or_merger: MergeStrategy | BaseMerger = MergeStrategy.LLM.BALANCED,
prompt: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
fields_for_index: List[str] | None = None,
@@ -125,6 +125,7 @@ class AutoSet(BaseAutoType[AutoSetSchema[Item]], Generic[Item]):
# Store item_schema and index config
self.item_schema = item_schema
self.fields_for_index = fields_for_index
+ self._constructor_kwargs = kwargs
# Create AutoSetSchema container dynamically (similar to AutoList's AutoListSchema)
container_name = f"{item_schema.__name__}Set"
@@ -203,6 +204,7 @@ class AutoSet(BaseAutoType[AutoSetSchema[Item]], Generic[Item]):
max_workers=self.max_workers,
verbose=self.verbose,
fields_for_index=self.fields_for_index, # Persist index field configuration
+ **self._constructor_kwargs, # Propagate additional arguments
)
def _default_prompt(self) -> str:
diff --git a/hyperextract/graphs/__init__.py b/hyperextract/graphs/__init__.py
index bf69b20..b6d608f 100644
--- a/hyperextract/graphs/__init__.py
+++ b/hyperextract/graphs/__init__.py
@@ -3,6 +3,14 @@ from .kg_gen import KG_Gen
from .itext2kg import iText2KG
from .itext2kg_star import iText2KG_Star
from .atom import Atom
+from .temporal_graph import AutoTemporalGraph
-__all__ = ["AutoGraph", "KG_Gen", "iText2KG", "iText2KG_Star", "Atom"]
+__all__ = [
+ "AutoGraph",
+ "KG_Gen",
+ "iText2KG",
+ "iText2KG_Star",
+ "Atom",
+ "AutoTemporalGraph",
+]
diff --git a/hyperextract/graphs/atom.py b/hyperextract/graphs/atom.py
index b806b9b..de6c590 100644
--- a/hyperextract/graphs/atom.py
+++ b/hyperextract/graphs/atom.py
@@ -84,15 +84,15 @@ class EdgeSchema(BaseModel):
default_factory=list,
description=(
"A time or interval indicating when this relationship begins or is active. "
- "Resolve relative temporal expressions based on the observation_date:\n"
- " - 'today' → exact observation_date\n"
- " - 'yesterday' → observation_date minus 1 day\n"
- " - 'this week' → Monday of observation_date's week\n"
- " - 'last week' → Monday of the week before observation_date\n"
- " - 'this month' → first day of observation_date's month\n"
- " - 'last month' → first day of the month before observation_date\n"
- " - 'this year' → January 1st of observation_date's year\n"
- " - 'last year' → January 1st of the year before observation_date\n"
+ "Resolve relative temporal expressions based on the observation_time:\n"
+ " - 'today' → exact observation_time\n"
+ " - 'yesterday' → observation_time minus 1 day\n"
+ " - 'this week' → Monday of observation_time's week\n"
+ " - 'last week' → Monday of the week before observation_time\n"
+ " - 'this month' → first day of observation_time's month\n"
+ " - 'last month' → first day of the month before observation_time\n"
+ " - 'this year' → January 1st of observation_time's year\n"
+ " - 'last year' → January 1st of the year before observation_time\n"
"Keep explicit dates as-is (e.g., '18-06-2024'). "
"For example, if 'Yassir became CEO from 2023', then t_start=['01-01-2023']. "
"This can be a single year, a date, or a resolved relative reference. "
@@ -103,10 +103,10 @@ class EdgeSchema(BaseModel):
default_factory=list,
description=(
"A time or interval indicating when this relationship ceases to hold. "
- "Resolve relative temporal expressions based on the observation_date using the same rules as t_start:\n"
- " - 'today' → exact observation_date\n"
- " - 'yesterday' → observation_date minus 1 day\n"
- " - 'this week' → Monday of observation_date's week\n"
+ "Resolve relative temporal expressions based on the observation_time using the same rules as t_start:\n"
+ " - 'today' → exact observation_time\n"
+ " - 'yesterday' → observation_time minus 1 day\n"
+ " - 'this week' → Monday of observation_time's week\n"
" - etc. (same resolution rules as t_start)\n"
"Keep explicit dates as-is. "
"For example, if 'Yassir left his position in 2025', then t_end=['01-01-2025']. "
@@ -138,12 +138,12 @@ class EdgeSchema(BaseModel):
Atom_FACTOID_EXTRACTION_PROMPT = """
-Observation Date: {observation_date}
+Observation Date: {observation_time}
You are an expert factoid extraction engine. Your primary function is to read a news paragraph and its associated observation date, and then decompose the text into a comprehensive list of atomic, self-contained, and temporally-grounded facts.
## Task
-Given an input paragraph and an `observation_date`, generate a list of all distinct factoids present in the text.
+Given an input paragraph and an `observation_time`, generate a list of all distinct factoids present in the text.
## Guidelines for Generating Temporal Factoids
@@ -158,17 +158,17 @@ Given an input paragraph and an `observation_date`, generate a list of all disti
- Include any necessary modifiers so that each factoid is understandable in isolation
### 3. Temporal Context
-- Convert ALL time references to absolute dates/times using the observation_date
+- Convert ALL time references to absolute dates/times using the observation_time
#### Conversion Rules:
-- "today" → exact observation_date
-- "yesterday" → observation_date minus 1 day
-- "this week" → Monday of observation_date's week
-- "last week" → Monday of the week before observation_date
-- "this month" → first day of observation_date's month
-- "last month" → first day of the month before observation_date
-- "this year" → January 1st of observation_date's year
-- "last year" → January 1st of the year before observation_date
+- "today" → exact observation_time
+- "yesterday" → observation_time minus 1 day
+- "this week" → Monday of observation_time's week
+- "last week" → Monday of the week before observation_time
+- "this month" → first day of observation_time's month
+- "last month" → first day of the month before observation_time
+- "this year" → January 1st of observation_time's year
+- "last year" → January 1st of the year before observation_time
- Keep explicit dates as-is (e.g., "June 18, 2024")
#### Additional Temporal Guidelines:
@@ -198,7 +198,7 @@ Given an input paragraph and an `observation_date`, generate a list of all disti
"""
Atom_EDGE_EXTRACTION_PROMPT = """
-Observation Date: {observation_date}
+Observation Date: {observation_time}
You are a precise knowledge extraction engine designed to distill unstructured text into a structured Knowledge Graph.
Your goal is to extract all meaningful relationships (edges) between entities, while rigorously capturing their temporal bounds and grounding evidence.
@@ -222,8 +222,8 @@ Extract a list of relationships where each relationship consists of:
#### 2. Temporal Extraction (Critical)
- **Format**: All dates must be in `YYYY-MM-DD` or `YYYY` format.
- **Lists**: `t_start` and `t_end` must always be lists of strings. If no date is found, use an empty list `[]`.
-- **Relative Time Resolution**: Calculate absolute dates based on the **Observation Date** ({observation_date}).
- - "last year" -> {observation_date} year - 1 (Jan 1st)
+- **Relative Time Resolution**: Calculate absolute dates based on the **Observation Date** ({observation_time}).
+ - "last year" -> {observation_time} year - 1 (Jan 1st)
- "a few months ago" -> Estimate conservatively based on context.
- "currently" -> implies the relationship is active (no `t_end`).
- **End Actions**: If the text says someone "left" or "stopped", capture this in `t_end` while keeping the relation positive (e.g., Relation: "works_at", t_end: ["2023-01-01"]).
@@ -318,9 +318,9 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
self,
llm_client: BaseChatModel,
embedder: Embeddings,
- observation_date: str | None = None,
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ observation_time: str | None = None,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
facts_per_chunk: int = 10,
max_workers: int = 10,
verbose: bool = False,
@@ -330,7 +330,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
Args:
llm_client: Language model for extraction
embedder: Embedding model for vector indexing
- observation_date: Date when the extraction was performed, like '1997-10-10' or '1997-10-10 23:59:59'.
+ observation_time: Date when the extraction was performed, like '1997-10-10' or '1997-10-10 23:59:59'.
If None, uses current date and time.
chunk_size: Characters per chunk
chunk_overlap: Overlapping characters between chunks
@@ -340,7 +340,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
"""
self.facts_per_chunk = facts_per_chunk
- self.observation_date = observation_date
+ self.observation_time = observation_time
# 1. Define Key Extractors (critical for deduplication)
# Node deduplication: exact match by name
@@ -407,7 +407,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
Returns:
Extracted and validated graph.
"""
- obs_date_str = self.observation_date or datetime.now().strftime("%Y-%m-%d")
+ obs_date_str = self.observation_time or datetime.now().strftime("%Y-%m-%d")
# ==================== Step 1: Extract Atomic Facts ====================
logger.info("🔍 [Phase 1] Extracting Atomic Facts...")
@@ -420,7 +420,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
# 2. Define Fact Extraction Chain
fact_prompt_template = ChatPromptTemplate.from_template(
- f"{Atom_FACTOID_EXTRACTION_PROMPT}\n\nObservation Date: {{observation_date}}\n\n### Source Text:\n{{chunk_text}}"
+ f"{Atom_FACTOID_EXTRACTION_PROMPT}\n\nObservation Date: {{observation_time}}\n\n### Source Text:\n{{chunk_text}}"
)
fact_chain = fact_prompt_template | self.llm_client.with_structured_output(
AtomicFactSchema
@@ -428,7 +428,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
# 3. Batch Extract Facts
fact_inputs = [
- {"chunk_text": chunk, "observation_date": obs_date_str}
+ {"chunk_text": chunk, "observation_time": obs_date_str}
for chunk in raw_chunks
]
chunk_fact_lists: List[AtomicFactSchema] = fact_chain.batch(
@@ -491,7 +491,7 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
# 6. Batch Extract Edges directly from Fact Chunks
# Format the edge prompt with observation date
- edge_prompt_with_date = self.edge_prompt.format(observation_date=obs_date_str)
+ edge_prompt_with_date = self.edge_prompt.format(observation_time=obs_date_str)
edge_prompt_template = ChatPromptTemplate.from_template(
f"{edge_prompt_with_date}\n\n### Source Text:\n{{chunk_text}}"
)
diff --git a/hyperextract/graphs/base.py b/hyperextract/graphs/base.py
index 7c174fd..77ff6ff 100644
--- a/hyperextract/graphs/base.py
+++ b/hyperextract/graphs/base.py
@@ -154,8 +154,8 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[NodeSchema, EdgeSchema]], Generic[N
prompt: str = "",
prompt_for_node_extraction: str = "",
prompt_for_edge_extraction: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
node_fields_for_index: List[str] | None = None,
@@ -200,6 +200,8 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[NodeSchema, EdgeSchema]], Generic[N
self.extraction_mode = extraction_mode
self.node_fields_for_index = node_fields_for_index
self.edge_fields_for_index = edge_fields_for_index
+ # Persist kwargs for reconstruction
+ self._constructor_kwargs = kwargs
# Initialize prompts (use custom if provided, otherwise use defaults)
self.node_prompt = prompt_for_node_extraction or DEFAULT_NODE_PROMPT
@@ -316,8 +318,9 @@ class AutoGraph(BaseAutoType[AutoGraphSchema[NodeSchema, EdgeSchema]], Generic[N
chunk_overlap=self.chunk_overlap,
max_workers=self.max_workers,
verbose=self.verbose,
- node_fields_for_index=self.node_fields_for_index, # Persist node index field configuration
- edge_fields_for_index=self.edge_fields_for_index, # Persist edge index field configuration
+ node_fields_for_index=self.node_fields_for_index,
+ edge_fields_for_index=self.edge_fields_for_index,
+ **self._constructor_kwargs, # Propagate additional arguments
)
@property
diff --git a/hyperextract/graphs/itext2kg.py b/hyperextract/graphs/itext2kg.py
index 1c92bbd..1e908d6 100644
--- a/hyperextract/graphs/itext2kg.py
+++ b/hyperextract/graphs/itext2kg.py
@@ -119,8 +119,8 @@ class iText2KG(AutoGraph[NodeSchema, EdgeSchema]):
self,
llm_client: BaseChatModel,
embedder: Embeddings,
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
):
diff --git a/hyperextract/graphs/itext2kg_star.py b/hyperextract/graphs/itext2kg_star.py
index 4b75914..b8d2d77 100644
--- a/hyperextract/graphs/itext2kg_star.py
+++ b/hyperextract/graphs/itext2kg_star.py
@@ -134,8 +134,8 @@ class iText2KG_Star(AutoGraph[NodeSchema, EdgeSchema]):
llm_client: BaseChatModel,
embedder: Embeddings,
observation_date: str | None = None,
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
):
diff --git a/hyperextract/graphs/kg_gen.py b/hyperextract/graphs/kg_gen.py
index b2a775e..cb12716 100644
--- a/hyperextract/graphs/kg_gen.py
+++ b/hyperextract/graphs/kg_gen.py
@@ -103,8 +103,8 @@ class KG_Gen(AutoGraph[NodeSchema, EdgeSchema]):
self,
llm_client: BaseChatModel,
embedder: Embeddings,
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
):
diff --git a/hyperextract/graphs/temporal_graph.py b/hyperextract/graphs/temporal_graph.py
index eb126be..135baf3 100644
--- a/hyperextract/graphs/temporal_graph.py
+++ b/hyperextract/graphs/temporal_graph.py
@@ -1,6 +1,6 @@
"""Generic temporal graph implementation supporting custom schemas with time-aware deduplication."""
-from typing import Type, Callable, Tuple, Any, List, Optional
+from typing import Type, Callable, Tuple, Any, List
from datetime import datetime
from langchain_core.language_models import BaseChatModel
from langchain_core.prompts import ChatPromptTemplate
@@ -10,13 +10,16 @@ from ontomem.merger import MergeStrategy, BaseMerger
from .base import AutoGraph, NodeSchema, EdgeSchema, NodeListSchema, EdgeListSchema
# ==============================================================================
-# Prompt Definition
+# Prompt Definition - Split for "Sandwich" Injection (Role -> User -> Rules)
# ==============================================================================
-GENERIC_TEMPORAL_NODE_PROMPT = """
+# Node Extraction Prompts
+DEFAULT_TEMPORAL_NODE_ROLE_PREFIX = """
You are a professional entity extraction specialist.
Your task is to extract all important entities (Nodes) from the text.
+"""
+DEFAULT_TEMPORAL_NODE_RULES_SUFFIX = """
# Core Principles
1. **Comprehensiveness**: Extract persons, organizations, locations, events, concepts, and other noun-based entities.
2. **Accuracy**: Keep entity names consistent with the source text.
@@ -27,20 +30,22 @@ Your task is to extract all important entities (Nodes) from the text.
### Source Text:
"""
-# Note: This prompt contains {observation_date} placeholder for dynamic injection during extraction
-GENERIC_TEMPORAL_EDGE_PROMPT = """
+# Edge Extraction Prompts
+DEFAULT_TEMPORAL_EDGE_ROLE_PREFIX = """
You are an expert temporal knowledge extraction specialist.
-Extract meaningful relationships (edges) between the provided entities, paying STRICT attention to temporal correctness.
+Extract meaningful relationships (edges) between the provided entities.
+"""
+DEFAULT_TEMPORAL_EDGE_RULES_SUFFIX = """
### Temporal Extraction Rules
-Current Observation Date: {observation_date}
+Current Observation Date: {observation_time}
1. **Relative Time Resolution**: You MUST resolve relative time expressions based on the Observation Date.
- - "last year" -> Calculate the year before {observation_date}
- - "yesterday" -> Calculate the date before {observation_date}
+ - "last year" -> Calculate the year before {observation_time}
+ - "yesterday" -> Calculate the date before {observation_time}
- "currently" -> The relationship is active (implies no end date)
- - "this month" -> First day of the month in {observation_date}
- - "last month" -> First day of the month before {observation_date}
+ - "this month" -> First day of the month in {observation_time}
+ - "last month" -> First day of the month before {observation_time}
2. **Explicit Dates**: Keep explicit dates (e.g., "2023", "2024-01-01") exactly as written.
@@ -49,8 +54,37 @@ Current Observation Date: {observation_date}
### General Constraints
1. ONLY extract edges connecting entities from the known entity list provided below.
2. DO NOT create edges involving entities that are not listed.
-3. Use the defined schema fields for time (e.g., t_start, t_end, timestamp) as specified in your output format.
+3. Use the defined schema fields for time as specified in the output format.
+
+"""
+
+# One-Stage Graph Extraction Prompts
+DEFAULT_TEMPORAL_GRAPH_ROLE_PREFIX = """
+You are a professional temporal knowledge graph extraction specialist.
+Your task is to extract entities (Nodes) and temporal relationships (Edges) from the text.
+"""
+
+DEFAULT_TEMPORAL_GRAPH_RULES_SUFFIX = """
+# Core Principles for Nodes
+1. Extract persons, organizations, locations, events, concepts, and other noun-based entities.
+2. **NEVER** extract dates/times as independent nodes. Time is an attribute of relationships, not a node.
+3. Keep entity names consistent with the source text.
+
+# Core Principles for Edges
+Current Observation Date: {observation_time}
+
+1. **Relative Time Resolution**: You MUST resolve relative time expressions based on the Observation Date.
+ - "last year" -> Calculate the year before {observation_time}
+ - "yesterday" -> Calculate the date before {observation_time}
+ - "currently" -> The relationship is active (implies no end date)
+ - "this month" -> First day of the month in {observation_time}
+ - "last month" -> First day of the month before {observation_time}
+
+2. **Explicit Dates**: Keep explicit dates (e.g., "2023", "2024-01-01") exactly as written.
+
+3. **Missing Time**: If no time information is present, leave time fields empty. DO NOT hallucinate dates.
+### Source Text:
"""
@@ -58,40 +92,39 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
"""
Generic Temporal Graph Extractor (AutoTemporalGraph).
- A flexible implementation supporting user-defined Node and Edge schemas with:
+ A flexible implementation supporting user-defined Node and Edge schemas with temporal awareness:
- **Schema Agnosticism**: Support any user-defined Node and Edge Pydantic models.
- **Temporal-Aware Deduplication**: Time information is integrated into edge deduplication logic.
- **Dynamic Time Injection**: Observation Date is injected during extraction for relative time resolution.
Key Design:
- - `edge_timestamp_extractor`: Function to extract time info from edges (e.g., lambda x: x.year).
+ - `temporal_edge_key_extractor`: A unified function to extract the unique key for an edge,
+ including temporal components (e.g., lambda x: f"{x.src}|{x.relation}|{x.dst}|{x.year}").
This ensures (A, rel, B) @ 2020 and (A, rel, B) @ 2021 are treated as different edges.
- - Wrapper around `edge_key_extractor`: Combines base relation key with timestamp key.
- - Dynamic Prompt Injection: Observation Date is injected into edge extraction prompts at runtime.
+ - Unified Prompt Management: Temporal system prompts are prepended to any user-provided prompts.
Example:
>>> from pydantic import BaseModel, Field
- >>>
+ >>>
>>> class MyEntity(BaseModel):
... name: str
... category: str = "Unknown"
- >>>
+ >>>
>>> class MyTemporalEdge(BaseModel):
... src: str
... dst: str
... relation: str
... year: Optional[str] = None
- >>>
+ >>>
>>> kg = AutoTemporalGraph(
... node_schema=MyEntity,
... edge_schema=MyTemporalEdge,
... node_key_extractor=lambda x: x.name,
- ... edge_key_extractor=lambda x: f"{x.src}|{x.relation}|{x.dst}",
- ... edge_timestamp_extractor=lambda x: x.year or "",
+ ... temporal_edge_key_extractor=lambda x: f"{x.src}|{x.relation}|{x.dst}|{x.year or ''}",
... nodes_in_edge_extractor=lambda x: (x.src, x.dst),
... llm_client=llm,
... embedder=embedder,
- ... observation_date="2024-01-15"
+ ... observation_time="2024-01-15"
... )
"""
@@ -100,13 +133,23 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
node_schema: Type[NodeSchema],
edge_schema: Type[EdgeSchema],
node_key_extractor: Callable[[NodeSchema], str],
- edge_key_extractor: Callable[[EdgeSchema], str],
- edge_timestamp_extractor: Callable[[EdgeSchema], str],
+ temporal_edge_key_extractor: Callable[[EdgeSchema], str],
nodes_in_edge_extractor: Callable[[EdgeSchema], Tuple[str, str]],
llm_client: BaseChatModel,
embedder: Embeddings,
- observation_date: str | None = None,
+ observation_time: str | None = None,
extraction_mode: str = "two_stage",
+ node_strategy_or_merger: "MergeStrategy | BaseMerger" = MergeStrategy.LLM.BALANCED,
+ edge_strategy_or_merger: "MergeStrategy | BaseMerger" = MergeStrategy.LLM.BALANCED,
+ prompt_for_node_extraction: str = "",
+ prompt_for_edge_extraction: str = "",
+ prompt: str = "",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ node_fields_for_index: List[str] | None = None,
+ edge_fields_for_index: List[str] | None = None,
**kwargs: Any,
):
"""
@@ -116,61 +159,78 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
node_schema: User-defined Node Pydantic model.
edge_schema: User-defined Edge Pydantic model with time fields.
node_key_extractor: Function to extract unique key from node (e.g., lambda x: x.name).
- edge_key_extractor: Function to extract base relationship key (e.g., lambda x: f"{x.src}|{x.relation}|{x.dst}").
- edge_timestamp_extractor: Function to extract time fingerprint from edge (e.g., lambda x: x.year).
- This is critical for differentiating edges at different times.
+ temporal_edge_key_extractor: Function to extract unique edge key including temporal info
+ (e.g., lambda x: f"{x.src}|{x.relation}|{x.dst}|{x.year}").
+ This ensures (A, rel, B) @ 2020 and (A, rel, B) @ 2021 are treated as different edges.
nodes_in_edge_extractor: Function to extract (source_key, target_key) from edge.
llm_client: LangChain BaseChatModel for extraction.
embedder: LangChain Embeddings for semantic operations.
- observation_date: Date context for relative time resolution (default: today in YYYY-MM-DD format).
+ observation_time: Date context for relative time resolution (default: today in YYYY-MM-DD format).
extraction_mode: "one_stage" or "two_stage" (default: "two_stage").
- **kwargs: Additional arguments passed to parent AutoGraph (e.g., prompt_for_node_extraction,
- node_strategy_or_merger, edge_strategy_or_merger, etc.).
+ node_strategy_or_merger: Merge strategy for duplicate nodes (default: LLM.BALANCED).
+ edge_strategy_or_merger: Merge strategy for duplicate edges (default: LLM.BALANCED).
+ prompt_for_node_extraction: Additional user prompt to append to node extraction system prompt.
+ prompt_for_edge_extraction: Additional user prompt to append to edge extraction system prompt.
+ prompt: Additional user prompt to append to one-stage graph extraction system prompt.
+ chunk_size: Size of text chunks for processing (default: 2048).
+ chunk_overlap: Overlap between text chunks (default: 256).
+ max_workers: Maximum number of concurrent LLM calls (default: 10).
+ verbose: Whether to print verbose output (default: False).
+ node_fields_for_index: List of node fields to include in vector index (optional).
+ edge_fields_for_index: List of edge fields to include in vector index (optional).
+ **kwargs: Additional arguments passed to create_merger() when strategy_or_merger is
+ a MergeStrategy enum. Ignored if strategy_or_merger is a BaseMerger instance.
"""
# Set observation date (default: today)
- self.observation_date = observation_date or datetime.now().strftime("%Y-%m-%d")
-
- # Store raw extractors for instance recreation (_create_empty_instance)
- self.raw_timestamp_extractor = edge_timestamp_extractor
- self.raw_edge_key_extractor = edge_key_extractor
+ self.observation_time = observation_time or datetime.now().strftime("%Y-%m-%d")
- # -----------------------------------------------------------
- # Core Logic 1: Decorate Edge Key Extractor
- # -----------------------------------------------------------
- # Combine "base relation fingerprint" (e.g., A|rel|B) with "time fingerprint" (e.g., 2023)
- # This ensures OMem treats (A, rel, B) @ t1 and (A, rel, B) @ t2 as different records
- def temporal_edge_key_wrapper(edge: EdgeSchema) -> str:
- base_key = edge_key_extractor(edge)
- time_key = edge_timestamp_extractor(edge)
- # Only append timestamp if valid time info exists
- if time_key:
- return f"{base_key}|{time_key}"
- return base_key
+ # Store for instance recreation
+ self.temporal_edge_key_extractor = temporal_edge_key_extractor
+ self._constructor_kwargs = kwargs
# -----------------------------------------------------------
- # Core Logic 2: Prepare Edge Extraction Prompt
+ # Construct Prompts: Role -> User Context -> System Rules
+ # ("Sandwich" structure for optimal LLM instruction sequencing)
# -----------------------------------------------------------
- # Extract user-provided edge prompt or use default
- edge_prompt = kwargs.pop("prompt_for_edge_extraction", GENERIC_TEMPORAL_EDGE_PROMPT)
- # Store the template (with {observation_date} placeholder) for later injection
- self.temporal_edge_prompt_template = edge_prompt
-
+ # 1. Node Extraction Prompt
+ full_node_prompt = DEFAULT_TEMPORAL_NODE_ROLE_PREFIX
+ if prompt_for_node_extraction:
+ full_node_prompt += f"\n### Context & Instructions:\n{prompt_for_node_extraction}\n"
+ full_node_prompt += DEFAULT_TEMPORAL_NODE_RULES_SUFFIX
+
+ # 2. Edge Extraction Prompt
+ full_edge_prompt = DEFAULT_TEMPORAL_EDGE_ROLE_PREFIX
+ if prompt_for_edge_extraction:
+ full_edge_prompt += f"\n### Context & Instructions:\n{prompt_for_edge_extraction}\n"
+ full_edge_prompt += DEFAULT_TEMPORAL_EDGE_RULES_SUFFIX
+
+ # 3. One-Stage Graph Extraction Prompt
+ full_graph_prompt = DEFAULT_TEMPORAL_GRAPH_ROLE_PREFIX
+ if prompt:
+ full_graph_prompt += f"\n### Context & Instructions:\n{prompt}\n"
+ full_graph_prompt += DEFAULT_TEMPORAL_GRAPH_RULES_SUFFIX
# Initialize parent AutoGraph
super().__init__(
node_schema=node_schema,
edge_schema=edge_schema,
node_key_extractor=node_key_extractor,
- edge_key_extractor=temporal_edge_key_wrapper, # Inject wrapped extractor
+ edge_key_extractor=temporal_edge_key_extractor,
nodes_in_edge_extractor=nodes_in_edge_extractor,
llm_client=llm_client,
embedder=embedder,
extraction_mode=extraction_mode,
- prompt_for_edge_extraction=edge_prompt, # Pass template with placeholder
- # Use default node prompt if not provided
- prompt_for_node_extraction=kwargs.pop(
- "prompt_for_node_extraction", GENERIC_TEMPORAL_NODE_PROMPT
- ),
+ node_strategy_or_merger=node_strategy_or_merger,
+ edge_strategy_or_merger=edge_strategy_or_merger,
+ prompt_for_node_extraction=full_node_prompt,
+ prompt_for_edge_extraction=full_edge_prompt,
+ prompt=full_graph_prompt,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ node_fields_for_index=node_fields_for_index,
+ edge_fields_for_index=edge_fields_for_index,
**kwargs,
)
@@ -182,17 +242,7 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
self, chunks: List[str], node_lists: List[NodeListSchema[NodeSchema]]
) -> List[EdgeListSchema[EdgeSchema]]:
"""
- Override: Inject observation_date into edge extraction chain during two-stage extraction.
-
- This method is called during the second stage (edge extraction from nodes + text).
- It dynamically injects the observation_date into the LLM chain inputs.
-
- Args:
- chunks: List of text chunks.
- node_lists: List of extracted node schemas for each chunk.
-
- Returns:
- List of extracted edge schemas.
+ Override: Inject observation_time into edge extraction during two-stage extraction.
"""
inputs = []
for chunk, node_list in zip(chunks, node_lists):
@@ -203,19 +253,16 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
node_keys = [self.node_key_extractor(n) for n in nodes]
node_context = "Known entities: " + ", ".join(node_keys)
- # Build input dictionary with dynamic observation_date injection
inputs.append(
{
"chunk_text": chunk,
"node_context": node_context,
- "observation_date": self.observation_date, # <--- DYNAMIC INJECTION
+ "observation_time": self.observation_time,
}
)
- # Create prompt template with placeholder for observation_date
- # The self.temporal_edge_prompt_template contains {observation_date} which will be filled
prompt_template = ChatPromptTemplate.from_template(
- f"{self.temporal_edge_prompt_template}{{node_context}}\n\n### Source Text:\n{{chunk_text}}"
+ f"{self.edge_prompt}{{node_context}}\n\n### Source Text:\n{{chunk_text}}"
)
llm_chain = prompt_template | self.llm_client.with_structured_output(
self.edge_list_schema
@@ -225,36 +272,24 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
def _extract_data_by_one_stage(self, text: str) -> Any:
"""
- Override: Inject observation_date into one-stage extraction if the prompt contains the placeholder.
-
- Args:
- text: Input text to extract.
-
- Returns:
- Extracted graph.
+ Override: Inject observation_time into one-stage extraction.
"""
- # Check if prompt template contains observation_date placeholder
- needs_date = "{observation_date}" in self.prompt
-
template_str = f"{self.prompt}{{chunk_text}}"
prompt_template = ChatPromptTemplate.from_template(template_str)
llm_chain = prompt_template | self.llm_client.with_structured_output(
self.graph_schema
)
- # Prepare base input
- base_input = {}
- if needs_date:
- base_input["observation_date"] = self.observation_date
-
- # Process text (chunked if necessary)
if len(text) <= self.chunk_size:
- inp = {"chunk_text": text, **base_input}
+ inp = {"chunk_text": text, "observation_time": self.observation_time}
graph = llm_chain.invoke(inp)
graph_list = [graph]
else:
chunks = self.text_splitter.split_text(text)
- inputs = [{"chunk_text": chunk, **base_input} for chunk in chunks]
+ inputs = [
+ {"chunk_text": chunk, "observation_time": self.observation_time}
+ for chunk in chunks
+ ]
graph_list = llm_chain.batch(
inputs, config={"max_concurrency": self.max_workers}
)
@@ -264,29 +299,24 @@ class AutoTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
def _create_empty_instance(self) -> "AutoTemporalGraph[NodeSchema, EdgeSchema]":
"""
Override: Recreate instance with all temporal-specific attributes.
-
- This is called by the parent class to create new instances during certain operations.
- We need to preserve raw extractors and temporal 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.raw_edge_key_extractor, # Pass original (unwrapped)
- edge_timestamp_extractor=self.raw_timestamp_extractor, # Pass original
+ temporal_edge_key_extractor=self.temporal_edge_key_extractor,
nodes_in_edge_extractor=self.nodes_in_edge_extractor,
llm_client=self.llm_client,
embedder=self.embedder,
- observation_date=self.observation_date,
+ observation_time=self.observation_time,
extraction_mode=self.extraction_mode,
node_strategy_or_merger=self.node_merger,
edge_strategy_or_merger=self.edge_merger,
- prompt_for_node_extraction=self.node_prompt,
- prompt_for_edge_extraction=self.temporal_edge_prompt_template,
chunk_size=self.chunk_size,
chunk_overlap=self.chunk_overlap,
max_workers=self.max_workers,
verbose=self.verbose,
node_fields_for_index=self.node_fields_for_index,
edge_fields_for_index=self.edge_fields_for_index,
+ **self._constructor_kwargs, # Propagate additional arguments
)
diff --git a/hyperextract/hypergraphs/base.py b/hyperextract/hypergraphs/base.py
index 1a90ef5..6ef7892 100644
--- a/hyperextract/hypergraphs/base.py
+++ b/hyperextract/hypergraphs/base.py
@@ -150,8 +150,8 @@ class AutoHypergraph(
prompt: str = "",
prompt_for_node_extraction: str = "",
prompt_for_edge_extraction: str = "",
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = False,
node_fields_for_index: List[str] | None = None,
diff --git a/hyperextract/hypergraphs/hyper_rag.py b/hyperextract/hypergraphs/hyper_rag.py
index 86e71bc..06d7524 100644
--- a/hyperextract/hypergraphs/hyper_rag.py
+++ b/hyperextract/hypergraphs/hyper_rag.py
@@ -127,8 +127,8 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):
self,
llm_client: BaseChatModel,
embedder: Embeddings,
- chunk_size: int = 2000,
- chunk_overlap: int = 200,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
max_workers: int = 10,
verbose: bool = True,
):