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: Add AutoSpatioTemporalGraph for enhanced spatio-temporal entity extraction

yifanfeng97723082f5294e
diff --git a/examples/auto_spatial_graph_demo.py b/examples/auto_spatial_graph_demo.py
index 6f7d957..cfa3650 100644
--- a/examples/auto_spatial_graph_demo.py
+++ b/examples/auto_spatial_graph_demo.py
@@ -39,30 +39,27 @@ class DeepSeaEntity(BaseModel):
description="实体类型:'船员', '怪物', '关键设备', '房间/区域', '物品'",
default="未知",
)
- location: Optional[str] = Field(
- description="【关键字段】实体所处的具体位置。必须将相对位置解析为绝对位置。",
- default=None,
- )
status: str = Field(
description="当前状态(例如:已死亡、损坏、锁定、活跃)", default="正常"
)
description: str = Field(description="实体的详细描述")
def __repr__(self):
- loc_display = self.location if self.location else "位置未知"
- return f"📍 [{loc_display}] {self.name} ({self.status})"
+ return f"🕵️ {self.name} ({self.status}) [{self.category}]"
class InteractionEdge(BaseModel):
- """实体间的互动关系"""
+ """实体间的互动关系 (包含空间信息)"""
source: str = Field(description="发起者")
target: str = Field(description="对象")
- relation: str = Field(description="关系或动作(例如:'位于...内部','攻击','修复')")
+ relation: str = Field(description="关系或动作(例如:'攻击','修复','操作','持有/携带')")
+ location: Optional[str] = Field(description="互动发生的具体位置", default=None)
details: str = Field(description="互动的详细描述")
def __repr__(self):
- return f"{self.source} --[{self.relation}]--> {self.target}"
+ loc_str = f" @ {self.location}" if self.location else ""
+ return f"⚡ {self.source} --[{self.relation}]--> {self.target}{loc_str}"
# ==================== 2. 深海探险日志文本 ====================
@@ -155,38 +152,32 @@ def run_demo():
# 创建 AutoSpatialGraph
print("📊 构建 AutoSpatialGraph 实例...\n")
- # 关键:使用 location_in_node_extractor 解析位置属性
graph = AutoSpatialGraph[DeepSeaEntity, InteractionEdge](
node_schema=DeepSeaEntity,
edge_schema=InteractionEdge,
- # Split extractors: base name and location separately
node_key_extractor=lambda x: x.name,
- location_in_node_extractor=lambda x: x.location,
+ # 基础边 Key
edge_key_extractor=lambda x: f"{x.source}|{x.relation}|{x.target}",
+ # 空间提取器移至边上
+ location_in_edge_extractor=lambda x: x.location or "",
nodes_in_edge_extractor=lambda x: (x.source, x.target),
llm_client=llm,
embedder=embedder,
- observation_location="Atlas深海科研站", # 设定总的地理围栏
+ observation_location="Atlas深海科研站",
extraction_mode="two_stage",
node_strategy_or_merger=MergeStrategy.LLM.BALANCED,
edge_strategy_or_merger=MergeStrategy.LLM.BALANCED,
prompt_for_node_extraction=(
- "提取深海空间站中的所有实体。\n"
- "关键空间规则:\n"
- "1. **位置注入**:仔细分析文本中的相对位置描述。例如,如果主角在'中央枢纽',那么'头顶上方'应被解析为'上层甲板'。\n"
- "2. **属性化**:不要提取'上层'、'左边'、'地下'作为节点。将它们解析为实体具体的 location 属性。\n"
- "3. **3D结构**:注意区分甲板层级(上层甲板、主层、底层/动力舱)。\n"
- "4. **实体类型**:如果是尸体,状态标为'死亡'但仍需提取为实体(携带关键物品)。\n"
+ "提取深海空间站中的所有关键实体(船员、设备、怪物等)。\n"
+ "注意:不要在节点中提取位置信息,位置将作为关系属性提取。"
),
prompt_for_edge_extraction=(
- "提取实体之间所有有意义的互动与关联关系。由于位置已作为实体属性记录,**请勿提取简单的'位于...内部'关系**。\n\n"
- "重点提取以下类型的关系:\n"
- "1. **动作与交互**:例如 '攻击'、'修复'、'操作'、'持有/携带'、'观察到'。\n"
- "2. **物理连接与阻挡**:例如 '连接着'(线缆)、'阻挡了'(门/障碍物)、'覆盖'。\n"
- "3. **控制与功能**:例如 '门禁卡->开启->门'、'阀门->控制->管道'。\n"
- "4. **因果与逻辑**:例如 '爆炸->导致->泄露'、'日志->提及->怪物'、'任务->目标是->设备'。\n"
+ "提取实体之间的互动关系,并精确捕获它们发生的地理位置。\n"
+ "特别是:\n"
+ "- 解析相对位置(如'这里'解析为 observation_location)\n"
+ "- 注意 3D 空间层级(上层甲板、中央枢纽、反应堆舱)"
),
- verbose=True, # 开启日志以便观察提取过程
+ verbose=True,
chunk_size=2048,
)
@@ -203,35 +194,24 @@ def run_demo():
print("\n" + "=" * 70)
print(f"✅ 空间结构分析完成!")
- print("=" * 70)
+ print("=" * 80)
print(f" 提取的实体: {len(graph.nodes)} 个")
print(f" 记录的互动关系: {len(graph.edges)} 个")
print("\n" + "-" * 70)
- print("📍 空间站实体分布 (Nodes - 按位置分组)")
+ print("🕵️ 空间站实体清单 (Nodes)")
print("-" * 70)
-
- # 按位置简单的分组打印
- nodes_by_location = {}
- for node in graph.nodes:
- # 简单处理一下位置字符串,取前几个字作为粗略分组
- loc_key = node.location or "位置未知"
- if loc_key not in nodes_by_location:
- nodes_by_location[loc_key] = []
- nodes_by_location[loc_key].append(node)
-
- for loc, entities in sorted(nodes_by_location.items()):
- print(f"\n🏢 区域: {loc}")
- for entity in entities:
- print(f" - {entity.name} [{entity.category}]: {entity.status}")
+ for i, node in enumerate(graph.nodes, 1):
+ print(f" {i}. {node}")
print("\n" + "-" * 70)
- print("🔗 关键互动关系 (Edges)")
+ print("📍 空间互动时间表 (Edges - 按位置排序)")
print("-" * 70)
- for i, edge in enumerate(graph.edges[:15]): # 只打印前15个
- print(f" {i+1}. {edge}")
- if len(graph.edges) > 15:
- print(f" ... (还有 {len(graph.edges) - 15} 条关系)")
+
+ # 按位置排序打印关系
+ sorted_edges = sorted(graph.edges, key=lambda x: x.location or "ZZZ")
+ for i, edge in enumerate(sorted_edges, 1):
+ print(f" {i}. {edge}")
# ==================== 5. 空间情报检索 (Search 阶段) ====================
diff --git a/examples/auto_spatio_temporal_graph_demo.py b/examples/auto_spatio_temporal_graph_demo.py
new file mode 100644
index 0000000..e9c83c3
--- /dev/null
+++ b/examples/auto_spatio_temporal_graph_demo.py
@@ -0,0 +1,183 @@
+"""
+AutoSpatioTemporalGraph Demo: 谍战惊悚 - 柏林的48小时 (时空增强版) 🕵️‍♀️🏙️
+
+场景背景:
+在冷战时期的东柏林,特工 Elias 的行动不仅在时间线上推进,其地理位置的变化也至关重要。
+本 Demo 演示如何同时提取和处理:
+1. 时间信息 (Timestamp)
+2. 空间信息 (Location/Coordinates)
+3. 时空上下文注入 (Observation Time & Location)
+
+核心特性:
+- 分离的时间/空间提取器 (Time & Location Extractors)
+- 自动融合的时空唯一键 (Composite Spatio-Temporal Key)
+- 相对时空消歧 (Relative Spatio-Temporal Resolution)
+"""
+
+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 AutoSpatioTemporalGraph
+from ontomem import MergeStrategy
+
+import dotenv
+
+dotenv.load_dotenv()
+
+# ==================== 1. 定义时空感知知识结构 (Schema) ====================
+
+class SpyEntity(BaseModel):
+ """谍战实体节点"""
+ name: str = Field(description="实体名称")
+ category: str = Field(description="实体类型:'特工', '地点', '组织', '物品'", default="未知")
+ description: str = Field(description="实体的详细描述", default="")
+
+ def __repr__(self):
+ return f"🕵️ [{self.category}] {self.name}"
+
+class SpatioTemporalAction(BaseModel):
+ """时空感知的行动边"""
+ source: str = Field(description="行动发起者")
+ target: str = Field(description="行动对象")
+ action: str = Field(description="具体行动")
+ time: Optional[str] = Field(description="发生的具体时间 (YYYY-MM-DD HH:MM)", default=None)
+ location: Optional[str] = Field(description="发生的具体地点", default=None)
+ details: str = Field(description="行动细节描述", default="")
+
+ def __repr__(self):
+ ctx = []
+ if self.time: ctx.append(f"⏰ {self.time}")
+ if self.location: ctx.append(f"📍 {self.location}")
+ ctx_str = f" [{' '.join(ctx)}]" if ctx else ""
+ return f"⚡ {self.source} --[{self.action}]--> {self.target}{ctx_str}"
+
+# ==================== 2. 叙述文本 (包含丰富的时空信息) ====================
+
+ST_NARRATIVE = """
+【任务简报:代号"碎冰"】
+【当前基准:2024-03-15,柏林勃兰登堡门】
+
+08:30,Elias 抵达了勃兰登堡门。他在广场西侧的长椅上坐下,距离标志性建筑仅50米。他正在等待接头指令。
+五分钟后(08:35),Sarah 骑车从他身边经过,故意丢下一份夹着代码的《柏林日报》。
+
+09:00,Elias 穿过街道,进入了位于 Friedrichstraße 车站附近的一个隐藏安全屋。他在地下室的一层准备了电子干扰器。
+与此同时(09:00),主要目标 Viktor 出现在亚历山大广场(Alexanderplatz)。他在电视塔底层的咖啡馆购买了一杯拿铁,并与一名身份不明的男子交谈了五分钟。
+
+09:15,Viktor 离开了亚历山大广场,乘出租车前往查理检查站(Checkpoint Charlie)。他的公文包里显然装着危险品。
+
+09:45,冲突在 Friedrichstraße 车站的地下维修通道正式爆发。Elias 追上了 Bond(Viktor 的副手)。在一阵密集的交火后,Elias 成功击落了 Bond 手中的无线起爆器。
+起爆器掉落在 3 号站台生锈的导轨上,距离带电轨道仅几厘米。
+
+10:10,Viktor 出现在查理检查站附近的马路旁,他正准备与那里的地下组织会合。Sarah 的监视小组记录下了他与另一名接头人交换了一个蓝色的U盘。
+
+10:30,真炸弹的最终位置被确认为威廉皇帝纪念教堂(Kaiser Wilhelm Memorial Church)。
+Elias 在 10:28 冲上了教堂钟楼的最顶层平台,冒着巨大的生命危险剪断了那根决定生死的红线。
+
+11:00,警方封锁了教堂周围的所有街道。Elias 悄无声息地从后门撤离,回到了勃兰登堡门附近的接头点。
+"""
+
+# ==================== 3. 运行提取 ====================
+
+def run_demo():
+ print("=" * 80)
+ print("🕵️ AutoSpatioTemporalGraph 演示:冷战柏林行动")
+ print("=" * 80)
+
+ llm = ChatOpenAI(model="gpt-4o", temperature=0)
+ embedder = OpenAIEmbeddings()
+
+ # 创建 AutoSpatioTemporalGraph 实例
+ graph = AutoSpatioTemporalGraph[SpyEntity, SpatioTemporalAction](
+ node_schema=SpyEntity,
+ edge_schema=SpatioTemporalAction,
+ node_key_extractor=lambda x: x.name,
+ # 基础边 Key: (谁, 做了什么, 对谁)
+ edge_key_extractor=lambda x: f"{x.source}|{x.action}|{x.target}",
+ # 分离提取:时间
+ time_in_edge_extractor=lambda x: x.time or "",
+ # 分离提取:空间
+ location_in_edge_extractor=lambda x: x.location or "",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=llm,
+ embedder=embedder,
+ # 时空上下文注入
+ observation_time="2024-03-15",
+ observation_location="Brandenburg Gate, Berlin",
+ # 提示词微调
+ prompt_for_edge_extraction=(
+ "精确捕获行动发生的时间和地点。\n"
+ "特别是:\n"
+ "- 如果提到'这里',指 Brandenburg Gate\n"
+ "- 提取具体的车站名、建筑物名或房间号"
+ ),
+ verbose=True
+ )
+
+ print("\n⚙️ 执行时空感知提取流程...")
+ graph.feed_text(ST_NARRATIVE)
+
+ # ==================== 4. 结果展示 ====================
+
+ print("\n" + "=" * 80)
+ print(f"📊 提取结果统计:{len(graph.nodes)} 节点, {len(graph.edges)} 边")
+ print("=" * 80)
+
+ print("\n📍 关键时空事件表 (Edges):")
+ # 按时间排序展示
+ sorted_edges = sorted(graph.edges, key=lambda x: (x.time or "9999", x.location or ""))
+ for i, edge in enumerate(sorted_edges, 1):
+ print(f"{i}. {edge}")
+
+ # ==================== 5. 增强检索测试 ====================
+ print("\n" + "=" * 80)
+ print("🔍 多维时空检索测试")
+ print("=" * 80)
+ graph.build_index()
+
+ print("\n📍 检索场景 1: 地点相关检索")
+ q1 = "在亚历山大广场(Alexanderplatz)发生了什么?"
+ _, edges1 = graph.search(q1, top_k_edges=3)
+ for e in edges1: print(f" ✅ {e}")
+
+ print("\n💼 检索场景 2: 关键物品流转")
+ q2 = "Viktor 的公文包和蓝色 U 盘在哪里出现的?"
+ _, edges2 = graph.search(q2, top_k_edges=3)
+ for e in edges2: print(f" ✅ {e}")
+
+ print("\n⏰ 检索场景 3: 时间同步检索")
+ q3 = "早上 09:00 这一刻,Elias 和 Viktor 分别在内存中留下了什么记录?"
+ _, edges3 = graph.search(q3, top_k_edges=5)
+ for e in edges3: print(f" ✅ {e}")
+
+ # ==================== 6. 交互式分析 (Chat) ====================
+ print("\n" + "=" * 80)
+ print("💬 时空感知交互式情报分析 (Chat)")
+ print("=" * 80)
+
+ chat_queries = [
+ "请按时间顺序列出 Elias 在这次行动中的所有地理位置变化轨迹。",
+ "描述 Viktor 在亚历山大广场和查理检查站的具体活动细节及其时间点。",
+ "对比分析 Elias 和 Viktor 在 09:00 时的动作,他们是否在同一地点?"
+ ]
+
+ for cq in chat_queries:
+ print(f"\n👤 [高级分析师]: {cq}")
+ response = graph.chat(cq)
+ print(f"🤖 [情报分析系统]:\n{response.content}")
+
+ # ==================== 7. 保存图谱 ====================
+ print("\n" + "=" * 80)
+ save_path = project_root / "temp" / "auto_spatio_temporal_demo"
+ graph.dump(save_path)
+ print(f"💾 完整时空知识图谱已持久化至: {save_path}")
+
+if __name__ == "__main__":
+ run_demo()
diff --git a/hyperextract/graphs/__init__.py b/hyperextract/graphs/__init__.py
index 677dc82..9ea5cdc 100644
--- a/hyperextract/graphs/__init__.py
+++ b/hyperextract/graphs/__init__.py
@@ -5,6 +5,7 @@ from .itext2kg_star import iText2KG_Star
from .atom import Atom
from .temporal_graph import AutoTemporalGraph
from .spatial_graph import AutoSpatialGraph
+from .spatio_temporal_graph import AutoSpatioTemporalGraph
__all__ = [
@@ -15,4 +16,5 @@ __all__ = [
"Atom",
"AutoTemporalGraph",
"AutoSpatialGraph",
+ "AutoSpatioTemporalGraph",
]
diff --git a/hyperextract/graphs/spatial_graph.py b/hyperextract/graphs/spatial_graph.py
index 90ac52f..bc774d6 100644
--- a/hyperextract/graphs/spatial_graph.py
+++ b/hyperextract/graphs/spatial_graph.py
@@ -22,66 +22,64 @@ from hyperextract.utils.logging import logger
# Node Extraction Prompts
DEFAULT_SPATIAL_NODE_ROLE_PREFIX = """
-You are a professional spatial entity extraction specialist.
-Your task is to extract all important entities (Nodes) from the text, resolving their location attributes accurately.
+You are a professional entity extraction specialist.
+Your task is to extract all important entities (Nodes) from the text.
"""
DEFAULT_SPATIAL_NODE_RULES_SUFFIX = """
# Core Principles
1. **Comprehensiveness**: Extract persons, organizations, facilities, events, and objects.
-2. **Location as Attribute**: Extract location/coordinates as fields of the entity, NOT as separate nodes.
-3. **Exclude Pure Spatial Markers**: **NEVER** extract abstract directions, coordinates, or pointers (e.g., "here", "nearby", "left side", "34.05N") as independent entity nodes!
- Spatial context is an attribute of the entity itself.
-
-# Spatial Resolution Rules
-Current Observation Location/Reference: {observation_location}
-
-1. **Relative Location Resolution**: You MUST resolve relative location expressions based on the Observation Location.
- - "here" / "local" / "this place" -> {observation_location}
- - "nearby" / "adjacent" -> In the vicinity of {observation_location}
- - "north of here" / "south of this place" -> Resolve direction relative to {observation_location}
-
-2. **Explicit Locations**: Keep explicit addresses or coordinates consistent with the source text.
-
-3. **Missing Location**: If no location information is applicable for an entity, leave location fields empty. DO NOT hallucinate locations.
+2. **Accuracy**: Keep entity names consistent with the source text.
+3. **Exclude Spatial Markers**: **NEVER** extract locations or directions (e.g., "Room 101", "North") as entity nodes!
+ Spatial context belongs to the relationships between entities.
### Source Text:
"""
# Edge Extraction Prompts
DEFAULT_SPATIAL_EDGE_ROLE_PREFIX = """
-You are an expert knowledge extraction specialist.
-Extract meaningful relationships (edges) between the provided entities.
+You are an expert spatial knowledge extraction specialist.
+Extract meaningful relationships (edges) between the provided entities, specifically capturing WHERE they occur.
"""
DEFAULT_SPATIAL_EDGE_RULES_SUFFIX = """
+### Spatial Extraction Rules
+Current Observation Location: {observation_location}
+
+1. **Relative Location Resolution**: You MUST resolve relative location expressions based on the Observation Location.
+ - "here", "local", "this place" -> {observation_location}
+ - "nearby", "adjacent" -> In the vicinity of {observation_location}
+ - "north of here" -> North of {observation_location}
+
+2. **Explicit Locations**: Keep explicit addresses or room names consistent with the source text.
+
+3. **Missing Location**: If no location information is present, leave location fields empty. DO NOT hallucinate.
+
### General Constraints
1. ONLY extract edges connecting entities from the known entity list provided below.
- - Do NOT abbreviate or modify the entity identifiers.
2. DO NOT create edges involving entities that are not listed.
-3. Keep the graph structure clean and focused on valid relationships.
+3. Use the defined schema fields for location as specified in the output format.
"""
# One-Stage Graph Extraction Prompts
DEFAULT_SPATIAL_GRAPH_ROLE_PREFIX = """
You are a professional spatial knowledge graph extraction specialist.
-Your task is to extract spatial entities (Nodes) and their relationships (Edges) from the text.
+Your task is to extract entities (Nodes) and spatial relationships (Edges) from the text.
"""
DEFAULT_SPATIAL_GRAPH_RULES_SUFFIX = """
# Core Principles for Nodes
1. Extract persons, organizations, facilities, and objects.
-2. **NEVER** extract pure spatial markers (coordinates, "here", directions) as independent nodes. Location is an attribute.
-3. Resolve relative locations ("here", "local") based on the Observation Location below.
+2. **NEVER** extract locations as independent nodes. Location is an attribute of the relationship.
# Core Principles for Edges
-1. Extract explicit relationships between the extracted entities.
-2. Ensure edge consistency: only link entities that you have extracted.
-
-# Spatial Reference
Current Observation Location: {observation_location}
+1. **Relative Location Resolution**: Resolve relative location expressions based on {observation_location}.
+2. **Explicit Locations**: Keep explicit locations exactly as written.
+3. **Missing Space**: Leave location fields empty if not present.
+
### Source Text:
"""
@@ -90,42 +88,37 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
"""
Generic Spatial Graph Extractor (AutoSpatialGraph).
- A flexible implementation supporting user-defined Node schemas with spatial awareness:
- - **Location Injection**: Observation Location is injected to resolve relative spatial references (e.g., "local", "nearby").
- - **Spatial Attribute Focus**: Prompts enforce treating location as a Node attribute rather than a separate Node.
- - **Spatial Identity**: Nodes are uniquely identified by BOTH Name and Location. The same entity at different locations
- is treated as spatially distinct (e.g., "Dr. Chen @ Airlock" vs "Dr. Chen @ MedBay" are different node identities).
+ A flexible implementation supporting user-defined Node and Edge schemas with spatial awareness:
- **Schema Agnosticism**: Support any user-defined Node and Edge Pydantic models.
+ - **Location-Aware Deduplication**: Spatial information is integrated into edge deduplication.
+ - **Dynamic Localization**: Observation Location is injected during extraction for relative resolution.
+
+ Key Design:
+ - Decoupled Extractors: `location_in_edge_extractor` is a separate function.
+ - Spatial Identity: Edges are uniquely identified by (source, relation, target) + location.
Example:
>>> from pydantic import BaseModel, Field
- >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
>>>
- >>> class SpatialEntity(BaseModel):
+ >>> class MyEntity(BaseModel):
... name: str
- ... entity_type: str
- ... location: str | None = None
...
- >>> class Relation(BaseModel):
- ... source: str
- ... target: str
- ... relation_type: str
+ >>> class MySpatialEdge(BaseModel):
+ ... src: str
+ ... dst: str
+ ... relation: str
+ ... place: Optional[str] = None
>>>
- >>> llm = ChatOpenAI(model="gpt-4o-mini")
- >>> embedder = OpenAIEmbeddings()
- >>>
- >>> graph = AutoSpatialGraph(
- ... node_schema=SpatialEntity,
- ... edge_schema=Relation,
- ... # Split identity extraction: base name and location
+ >>> kg = AutoSpatialGraph(
+ ... node_schema=MyEntity,
+ ... edge_schema=MySpatialEdge,
... node_key_extractor=lambda x: x.name,
- ... location_in_node_extractor=lambda x: x.location,
- ... edge_key_extractor=lambda x: f"{x.source}-{x.relation_type}-{x.target}",
- ... nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ ... edge_key_extractor=lambda x: f"{x.src}|{x.relation}|{x.dst}",
+ ... location_in_edge_extractor=lambda x: x.place or "",
+ ... nodes_in_edge_extractor=lambda x: (x.src, x.dst),
... llm_client=llm,
... embedder=embedder,
- ... observation_location="New York City, NY",
- ... extraction_mode="two_stage"
+ ... observation_location="Main Hall"
... )
"""
@@ -134,8 +127,8 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
node_schema: Type[NodeSchema],
edge_schema: Type[EdgeSchema],
node_key_extractor: Callable[[NodeSchema], str],
- location_in_node_extractor: Callable[[NodeSchema], str],
edge_key_extractor: Callable[[EdgeSchema], str],
+ location_in_edge_extractor: Callable[[EdgeSchema], str],
nodes_in_edge_extractor: Callable[[EdgeSchema], Tuple[str, str]],
llm_client: BaseChatModel,
embedder: Embeddings,
@@ -158,124 +151,34 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
"""
Initialize AutoSpatialGraph.
- **Required Arguments:**
-
Args:
- node_schema: User-defined Node Pydantic model class. Defines the structure of
- extracted entities. Should include fields for entity attributes and optional
- location information (e.g., name, type, location, coordinates).
- Example: class Entity(BaseModel): name: str; location: str | None = None
-
- edge_schema: User-defined Edge Pydantic model class. Defines the structure of
- relationships between nodes. Must include fields to specify source and
- target nodes.
- Example: class Relation(BaseModel): source: str; target: str; relation_type: str
-
- node_key_extractor: Callable function to extract the BASE unique identifier from a node,
- excluding location (e.g., just the name logic).
- Example: lambda x: x.name
-
- location_in_node_extractor: Callable function to extract the location string from a node.
- Example: lambda x: x.location
-
- edge_key_extractor: Callable function to extract a unique key/identifier from each edge.
- Used for edge deduplication and matching.
- Example: lambda x: f"{x.source}-{x.relation_type}-{x.target}"
-
- nodes_in_edge_extractor: Function to extract (source_key, target_key) node keys from an edge for validation.
-
- llm_client: LangChain BaseChatModel instance (e.g., ChatOpenAI, ChatAnthropic).
- Responsible for extracting nodes and edges from text via LLM calls.
-
- embedder: LangChain Embeddings instance (e.g., OpenAIEmbeddings, HuggingFaceEmbeddings).
- Used for semantic similarity matching and vector indexing of nodes and edges.
-
- **Optional Keyword Arguments:**
-
- Args:
- observation_location: A string describing the reference location for relative spatial
- resolution (e.g., "New York City, NY", "Building A, Room 101",
- "37.7749,-122.4194"). Used by the LLM to resolve expressions like
- "here", "nearby", "local" to actual locations.
- Default: "Unknown Location"
-
- extraction_mode: Extraction strategy - either "one_stage" or "two_stage".
- - "one_stage": Extracts nodes and edges simultaneously (faster, less precise).
- - "two_stage": Extracts nodes first, then edges with node context (more accurate).
- Default: "two_stage"
-
- node_strategy_or_merger: Merge strategy for deduplicating nodes (when multiple chunks
- have duplicate nodes). Can be a MergeStrategy enum value
- (e.g., MergeStrategy.LLM.BALANCED, MergeStrategy.SIMPLE) or a
- custom BaseMerger instance.
- Default: MergeStrategy.LLM.BALANCED
-
- edge_strategy_or_merger: Merge strategy for deduplicating edges. Similar to
- node_strategy_or_merger.
- Default: MergeStrategy.LLM.BALANCED
-
- prompt_for_node_extraction: Additional user-specific prompt/context to append to the
- node extraction system prompt. This allows customization of
- node extraction behavior without replacing the full prompt.
- Example: "Focus on extracting only companies and their headquarters."
- Default: ""
-
- prompt_for_edge_extraction: Additional user-specific prompt/context to append to the
- edge extraction system prompt.
- Default: ""
-
- prompt: Additional user-specific prompt/context to append to the one-stage graph extraction
- system prompt. Only used when extraction_mode="one_stage".
- Default: ""
-
- chunk_size: Maximum character length of each text chunk for batch processing. Larger texts
- are split into chunks for parallel extraction.
- Default: 2048
-
- chunk_overlap: Number of overlapping characters between consecutive chunks to preserve
- context at chunk boundaries.
- Default: 256
-
- max_workers: Maximum number of parallel LLM calls during batch extraction. Higher values
- improve speed but increase API usage and cost.
- Default: 10
-
- verbose: Whether to print verbose logging messages during extraction, merging, and indexing.
- Default: False
-
- node_fields_for_index: List of node field names to include in the vector index. If None,
- all fields are indexed. Useful for focusing semantic search on
- specific attributes (e.g., ["name", "location"]).
- Default: None
-
- edge_fields_for_index: List of edge field names to include in the vector index. If None,
- all fields are indexed.
- Default: None
-
- **kwargs: Additional keyword arguments passed to ontomem.merger.create_merger() when
- node_strategy_or_merger or edge_strategy_or_merger are MergeStrategy enums.
- Ignored if they are BaseMerger instances.
+ node_schema: User-defined Node Pydantic model.
+ edge_schema: User-defined Edge Pydantic model with location fields.
+ node_key_extractor: Function to extract unique key from node.
+ edge_key_extractor: Function to extract the base unique identifier for an edge.
+ location_in_edge_extractor: Function to extract the spatial component from an edge.
+ nodes_in_edge_extractor: Function to extract (source_key, target_key) from edge.
+ ... (other args same as AutoGraph)
"""
# Set observation location
self.observation_location = observation_location or "Unknown Location"
self._constructor_kwargs = kwargs
- # Store split extractors
- self.raw_node_key_extractor = node_key_extractor
- self.location_in_node_extractor = location_in_node_extractor
+ # Store extractors
+ self.raw_edge_key_extractor = edge_key_extractor
+ self.location_in_edge_extractor = location_in_edge_extractor
- # Create combined extractor for unique identification in memory
- # CRITICAL FOR SPATIAL: Format becomes "Name @ Location" (or just Name if no location)
- def spatial_node_key_extractor(node: NodeSchema) -> str:
- raw_key = node_key_extractor(node)
- loc = location_in_node_extractor(node)
- return f"{raw_key} @ {loc}" if loc else raw_key
+ # Create composite extractor for unique identification in memory
+ def spatial_edge_key_extractor(edge: EdgeSchema) -> str:
+ raw_key = self.raw_edge_key_extractor(edge)
+ loc_val = self.location_in_edge_extractor(edge)
+ return f"{raw_key} at {loc_val}" if loc_val else raw_key
# -----------------------------------------------------------
# Construct Prompts
# -----------------------------------------------------------
- # 1. Node Extraction Prompt (Spatial logic lives here)
+ # 1. Node Extraction Prompt
full_node_prompt = DEFAULT_SPATIAL_NODE_ROLE_PREFIX
if prompt_for_node_extraction:
full_node_prompt += (
@@ -301,8 +204,8 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
super().__init__(
node_schema=node_schema,
edge_schema=edge_schema,
- node_key_extractor=spatial_node_key_extractor,
- edge_key_extractor=edge_key_extractor,
+ node_key_extractor=node_key_extractor,
+ edge_key_extractor=spatial_edge_key_extractor,
nodes_in_edge_extractor=nodes_in_edge_extractor,
llm_client=llm_client,
embedder=embedder,
@@ -320,82 +223,33 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
edge_fields_for_index=edge_fields_for_index,
**kwargs,
)
- self._node_memory.create_lookup("id", node_key_extractor)
# ==============================================================================
# Override Extraction Methods to Dynamically Inject Observation Location
# ==============================================================================
- def _extract_nodes_batch(
- self, chunks: List[str]
- ) -> List[NodeListSchema[NodeSchema]]:
- """
- Override: Inject observation_location into NODE extraction (Two-Stage).
-
- Unlike TemporalGraph (which injects into Edges), SpatialGraph injects into Nodes
- because location is an attribute of the Node. The observation_location placeholder
- in the prompt is replaced with the actual location value.
-
- Args:
- chunks: List of text chunks to extract nodes from.
-
- Returns:
- List of NodeListSchema containing extracted nodes from each chunk.
- """
- # The prompt string (self.node_prompt) contains {observation_location} placeholder
- prompt_template = ChatPromptTemplate.from_template(
- f"{self.node_prompt}{{chunk_text}}"
- )
- llm_chain = prompt_template | self.llm_client.with_structured_output(
- self.node_list_schema
- )
-
- inputs = [
- {
- "chunk_text": chunk,
- "observation_location": self.observation_location,
- }
- for chunk in chunks
- ]
- return llm_chain.batch(inputs, config={"max_concurrency": self.max_workers})
-
def _extract_edges_batch(
self, chunks: List[str], node_lists: List[NodeListSchema[NodeSchema]]
) -> List[EdgeListSchema[EdgeSchema]]:
"""
- Batch extract edges using corresponding node lists as context.
-
- Override: Use raw_node_key_extractor (base name only) instead of the combined
- spatial_node_key_extractor (name @ location).
-
- **CRITICAL**: This method uses raw_node_key_extractor (base name only) instead of the
- combined spatial_node_key_extractor (name @ location). This is intentional to provide
- clean entity references during edge extraction. The LLM will extract edges with source/target
- referring to these base names, which will be matched against the combined keys later.
-
- Args:
- chunks: List of text chunks.
- node_lists: List of NodeListSchema objects (one per chunk).
-
- Returns:
- List of EdgeListSchema objects with extracted edges.
+ Override: Inject observation_location into edge extraction during two-stage extraction.
"""
inputs = []
for chunk, node_list in zip(chunks, node_lists):
nodes = node_list.items if node_list else []
- if not nodes:
- node_context = "No specific entities identified in this chunk."
- else:
- # CRITICAL: Use raw_node_key_extractor (base keys without location) for entity references.
- # This prevents location suffixes from cluttering the prompt and allows the LLM to focus on relationships.
- # The edge extraction will reference these clean names, not the full "Name @ Location" identifiers.
- node_keys = [self.raw_node_key_extractor(n) for n in nodes]
- node_context = "Known entities: " + ", ".join(node_keys)
+ node_context = "Known entities: " + ", ".join([self.node_key_extractor(n) for n in nodes]) if nodes else "No specific entities identified."
- inputs.append({"chunk_text": chunk, "node_context": node_context})
+ inputs.append({
+ "chunk_text": chunk,
+ "node_context": node_context,
+ "observation_location": self.observation_location,
+ })
+ # Ensure observation_location is explicitly in the prompt if not already part of self.edge_prompt
+ prompt_with_location = f"Current location context: {{observation_location}}\n\n{self.edge_prompt}"
+
prompt_template = ChatPromptTemplate.from_template(
- f"{self.edge_prompt}{{node_context}}\n\n### Source Text:\n{{chunk_text}}"
+ f"{prompt_with_location}{{node_context}}\n\n### Source Text:\n{{chunk_text}}"
)
llm_chain = prompt_template | self.llm_client.with_structured_output(
self.edge_list_schema
@@ -406,17 +260,9 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
def _extract_data_by_one_stage(self, text: str) -> Any:
"""
Override: Inject observation_location into one-stage extraction.
-
- For single-stage extraction, processes entire text (or chunks if too long)
- and injects observation_location into the prompt template.
-
- Args:
- text: Full text to extract from.
-
- Returns:
- AutoGraphSchema containing extracted nodes and edges.
"""
- template_str = f"{self.prompt}{{chunk_text}}"
+ prompt_with_location = f"Current location context: {{observation_location}}\n\n{self.prompt}"
+ template_str = f"{prompt_with_location}{{chunk_text}}"
prompt_template = ChatPromptTemplate.from_template(template_str)
llm_chain = prompt_template | self.llm_client.with_structured_output(
self.graph_schema
@@ -441,80 +287,16 @@ class AutoSpatialGraph(AutoGraph[NodeSchema, EdgeSchema]):
return self.merge_batch_data(graph_list)
- def _prune_dangling_edges(
- self, graph: AutoGraphSchema[NodeSchema, EdgeSchema]
- ) -> AutoGraphSchema[NodeSchema, EdgeSchema]:
- """Override: Prune edges connecting to non-existent nodes using RAW keys.
-
- **Reason for Override**:
- In AutoSpatialGraph, the primary node storage uses a combined key ("Name @ Location")
- to distinguish spatially distinct entities. However, edges are extracted using
- only the raw entity name (to avoid location confusion in relationships).
-
- Therefore, standard validation would fail because "Name" != "Name @ Location".
- We must validate edge endpoints against the 'raw name' using the auxiliary lookup
- index created in __init__ (self._node_memory.create_lookup("id", node_key_extractor)).
-
- Args:
- graph: Raw graph containing nodes and edges from the current extraction batch.
-
- Returns:
- Graph with only valid edges where both source and target exist in the node set
- (verified via raw name lookup).
- """
- valid_nodes = graph.nodes
- valid_node_keys = {self.raw_node_key_extractor(n) for n in valid_nodes}
-
- refined_edges = []
- dropped_count = 0
-
- for edge in graph.edges:
- src_key, dst_key = self.nodes_in_edge_extractor(edge)
-
- # Check if endpoints exist in CURRENT batch OR in global memory using the ID lookup.
- # The lookup checks against the 'id' (raw name) extractor defined in __init__,
- # NOT the combined "Name @ Location" key used in the primary node storage.
- src_exists = (
- src_key in valid_node_keys
- or self._node_memory.get_by_lookup("id", src_key) != []
- )
- dst_exists = (
- dst_key in valid_node_keys
- or self._node_memory.get_by_lookup("id", dst_key) != []
- )
-
- if src_exists and dst_exists:
- refined_edges.append(edge)
- else:
- dropped_count += 1
- logger.debug(
- f"Pruning dangling edge: {src_key} -> {dst_key} "
- f"(src_exists={src_exists}, dst_exists={dst_exists})"
- )
-
- if dropped_count > 0:
- logger.info(
- f"Pruned {dropped_count} dangling edges to ensure graph consistency."
- )
-
- return self.graph_schema(nodes=valid_nodes, edges=refined_edges)
-
def _create_empty_instance(self) -> "AutoSpatialGraph[NodeSchema, EdgeSchema]":
"""
Override: Recreate instance with spatial attributes preserved.
-
- Used during serialization/deserialization to ensure all spatial configuration
- is maintained when creating a fresh instance.
-
- Returns:
- New AutoSpatialGraph instance with identical configuration.
"""
return self.__class__(
node_schema=self.node_schema,
edge_schema=self.edge_schema,
- node_key_extractor=self.raw_node_key_extractor,
- location_in_node_extractor=self.location_in_node_extractor,
- edge_key_extractor=self.edge_key_extractor,
+ node_key_extractor=self.node_key_extractor,
+ edge_key_extractor=self.raw_edge_key_extractor,
+ location_in_edge_extractor=self.location_in_edge_extractor,
nodes_in_edge_extractor=self.nodes_in_edge_extractor,
llm_client=self.llm_client,
embedder=self.embedder,
diff --git a/hyperextract/graphs/spatio_temporal_graph.py b/hyperextract/graphs/spatio_temporal_graph.py
new file mode 100644
index 0000000..c591f1b
--- /dev/null
+++ b/hyperextract/graphs/spatio_temporal_graph.py
@@ -0,0 +1,350 @@
+"""Generic temporal graph implementation supporting custom schemas with time-aware deduplication."""
+
+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
+from langchain_core.embeddings import Embeddings
+from ontomem.merger import MergeStrategy, BaseMerger
+
+from hyperextract.graphs.base import (
+ AutoGraph,
+ NodeSchema,
+ EdgeSchema,
+ NodeListSchema,
+ EdgeListSchema,
+)
+
+# ==============================================================================
+# Prompt Definition - Split for "Sandwich" Injection (Role -> User -> Rules)
+# ==============================================================================
+
+# Node Extraction Prompts
+DEFAULT_SPATIO_TEMPORAL_NODE_ROLE_PREFIX = """
+You are a professional entity extraction specialist.
+Your task is to extract all important entities (Nodes) from the text.
+"""
+
+DEFAULT_SPATIO_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.
+3. **Exclude Time Expressions**: **NEVER** extract dates, years, or time periods (e.g., "2023", "last year", "today") as entity nodes!
+ Time is an attribute of relationships, not a node.
+4. **Exclude Pure Numbers**: Do not extract standalone amounts or numeric values as independent nodes.
+
+### Source Text:
+"""
+
+# Edge Extraction Prompts
+DEFAULT_SPATIO_TEMPORAL_EDGE_ROLE_PREFIX = """
+You are an expert spatio-temporal knowledge extraction specialist.
+Extract meaningful relationships (edges) between the provided entities, specifically capturing WHEN and WHERE they occur.
+"""
+
+DEFAULT_SPATIO_TEMPORAL_EDGE_RULES_SUFFIX = """
+### Spatio-Temporal Extraction Rules
+Current Observation Date: {observation_time}
+Current Observation Location: {observation_location}
+
+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)
+
+2. **Relative Location Resolution**: You MUST resolve relative location expressions based on the Observation Location.
+ - "here", "local", "this city" -> {observation_location}
+ - "nearby" -> Near {observation_location}
+
+3. **Explicit Context**:
+ - Keep explicit dates (e.g., "2023", "2024-01-01") exactly as written.
+ - Keep explicit locations (e.g., "New York", "Room 101") specifically associated with the relationship.
+
+4. **Missing Information**: If no time or location information is present, leave those fields empty. DO NOT hallucinate.
+
+### 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 and space as specified in the output format.
+
+"""
+
+# One-Stage Graph Extraction Prompts
+DEFAULT_SPATIO_TEMPORAL_GRAPH_ROLE_PREFIX = """
+You are a professional spatio-temporal knowledge graph extraction specialist.
+Your task is to extract entities (Nodes) and spatio-temporal relationships (Edges) from the text.
+"""
+
+DEFAULT_SPATIO_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 and Space are attributes of relationships.
+3. Keep entity names consistent with the source text.
+
+# Core Principles for Edges
+Current Observation Date: {observation_time}
+Current Observation Location: {observation_location}
+
+1. **Relative Time Resolution**: Resolve relative time expressions based on {observation_time}.
+2. **Relative Location Resolution**: Resolve relative location expressions based on {observation_location}.
+3. **Explicit Context**: Keep explicit dates and locations as provided in the text.
+4. **Missing Information**: Leave time/location fields empty if not present.
+
+### Source Text:
+"""
+
+
+class AutoSpatioTemporalGraph(AutoGraph[NodeSchema, EdgeSchema]):
+ """
+ Generic Spatio-Temporal Graph Extractor (AutoSpatioTemporalGraph).
+
+ A flexible implementation supporting user-defined Node and Edge schemas with spatio-temporal awareness:
+ - **Schema Agnosticism**: Support any user-defined Node and Edge Pydantic models.
+ - **Spatio-Temporal-Aware Deduplication**: Time and Space info are integrated into edge deduplication.
+ - **Dynamic Context Injection**: Observation Date and Location are injected during extraction.
+
+ Key Design:
+ - Decoupled Extractors: `time_in_edge_extractor` and `location_in_edge_extractor` are separate.
+ - Composite Key: Automatically fuses base key, time, and location for unique identification.
+
+ Example:
+ >>> from pydantic import BaseModel, Field
+ >>>
+ >>> class MyEntity(BaseModel):
+ ... name: str
+ >>>
+ >>> class MySTEdge(BaseModel):
+ ... src: str
+ ... dst: str
+ ... relation: str
+ ... time: Optional[str] = None
+ ... place: Optional[str] = None
+ >>>
+ >>> kg = AutoSpatioTemporalGraph(
+ ... node_schema=MyEntity,
+ ... edge_schema=MySTEdge,
+ ... node_key_extractor=lambda x: x.name,
+ ... edge_key_extractor=lambda x: f"{x.src}|{x.relation}|{x.dst}",
+ ... time_in_edge_extractor=lambda x: x.time or "",
+ ... location_in_edge_extractor=lambda x: x.place or "",
+ ... nodes_in_edge_extractor=lambda x: (x.src, x.dst),
+ ... llm_client=llm,
+ ... embedder=embedder,
+ ... observation_time="2024-01-15",
+ ... observation_location="Beijing"
+ ... )
+ """
+
+ def __init__(
+ self,
+ node_schema: Type[NodeSchema],
+ edge_schema: Type[EdgeSchema],
+ node_key_extractor: Callable[[NodeSchema], str],
+ edge_key_extractor: Callable[[EdgeSchema], str],
+ time_in_edge_extractor: Callable[[EdgeSchema], str],
+ location_in_edge_extractor: Callable[[EdgeSchema], str],
+ nodes_in_edge_extractor: Callable[[EdgeSchema], Tuple[str, str]],
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ observation_time: str | None = None,
+ observation_location: 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,
+ ):
+ """
+ Initialize AutoSpatioTemporalGraph.
+
+ Args:
+ node_schema: User-defined Node Pydantic model.
+ edge_schema: User-defined Edge Pydantic model with time/space fields.
+ node_key_extractor: Function to extract unique key from node.
+ edge_key_extractor: Function to extract the base unique identifier for an edge.
+ time_in_edge_extractor: Function to extract the time component.
+ location_in_edge_extractor: Function to extract the spatial component.
+ 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_time: Date context for relative time resolution (default: today in YYYY-MM-DD format).
+ extraction_mode: "one_stage" or "two_stage" (default: "two_stage").
+ 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 contexts
+ self.observation_time = observation_time or datetime.now().strftime("%Y-%m-%d")
+ self.observation_location = observation_location or "Unknown"
+
+ # Store extractors
+ self.raw_edge_key_extractor = edge_key_extractor
+ self.time_in_edge_extractor = time_in_edge_extractor
+ self.location_in_edge_extractor = location_in_edge_extractor
+ self._constructor_kwargs = kwargs
+
+ # Create composite extractor for unique identification in memory
+ def composite_spatio_temporal_key_extractor(edge: EdgeSchema) -> str:
+ raw_key = self.raw_edge_key_extractor(edge)
+ time_val = self.time_in_edge_extractor(edge)
+ loc_val = self.location_in_edge_extractor(edge)
+
+ final_key = raw_key
+ if time_val:
+ final_key += f" @ {time_val}"
+ if loc_val:
+ final_key += f" at {loc_val}"
+ return final_key
+
+ # Construct Prompts
+ full_node_prompt = DEFAULT_SPATIO_TEMPORAL_NODE_ROLE_PREFIX
+ if prompt_for_node_extraction:
+ full_node_prompt += f"\n### Context:\n{prompt_for_node_extraction}\n"
+ full_node_prompt += DEFAULT_SPATIO_TEMPORAL_NODE_RULES_SUFFIX
+
+ full_edge_prompt = DEFAULT_SPATIO_TEMPORAL_EDGE_ROLE_PREFIX
+ if prompt_for_edge_extraction:
+ full_edge_prompt += f"\n### Context:\n{prompt_for_edge_extraction}\n"
+ full_edge_prompt += DEFAULT_SPATIO_TEMPORAL_EDGE_RULES_SUFFIX
+
+ full_graph_prompt = DEFAULT_SPATIO_TEMPORAL_GRAPH_ROLE_PREFIX
+ if prompt:
+ full_graph_prompt += f"\n### Context:\n{prompt}\n"
+ full_graph_prompt += DEFAULT_SPATIO_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=composite_spatio_temporal_key_extractor,
+ nodes_in_edge_extractor=nodes_in_edge_extractor,
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode=extraction_mode,
+ 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,
+ )
+
+ # ==============================================================================
+ # Override Extraction Methods to Dynamically Inject Context
+ # ==============================================================================
+
+ def _extract_edges_batch(
+ self, chunks: List[str], node_lists: List[NodeListSchema[NodeSchema]]
+ ) -> List[EdgeListSchema[EdgeSchema]]:
+ """Inject observation_time and observation_location into edge extraction."""
+ inputs = []
+ for chunk, node_list in zip(chunks, node_lists):
+ nodes = node_list.items if node_list else []
+ node_context = (
+ "Known entities: "
+ + ", ".join([self.node_key_extractor(n) for n in nodes])
+ if nodes
+ else "No specific entities identified."
+ )
+
+ inputs.append(
+ {
+ "chunk_text": chunk,
+ "node_context": node_context,
+ "observation_time": self.observation_time,
+ "observation_location": self.observation_location,
+ }
+ )
+
+ prompt_template = ChatPromptTemplate.from_template(
+ 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
+ )
+ return llm_chain.batch(inputs, config={"max_concurrency": self.max_workers})
+
+ def _extract_data_by_one_stage(self, text: str) -> Any:
+ """Inject observation_time and observation_location into one-stage extraction."""
+ 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
+ )
+
+ if len(text) <= self.chunk_size:
+ inp = {
+ "chunk_text": text,
+ "observation_time": self.observation_time,
+ "observation_location": self.observation_location,
+ }
+ graph = llm_chain.invoke(inp)
+ graph_list = [graph]
+ else:
+ chunks = self.text_splitter.split_text(text)
+ inputs = [
+ {
+ "chunk_text": chunk,
+ "observation_time": self.observation_time,
+ "observation_location": self.observation_location,
+ }
+ for chunk in chunks
+ ]
+ graph_list = llm_chain.batch(
+ inputs, config={"max_concurrency": self.max_workers}
+ )
+
+ return self.merge_batch_data(graph_list)
+
+ def _create_empty_instance(
+ self,
+ ) -> "AutoSpatioTemporalGraph[NodeSchema, EdgeSchema]":
+ """Recreate instance with all spatio-temporal attributes."""
+ 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,
+ time_in_edge_extractor=self.time_in_edge_extractor,
+ location_in_edge_extractor=self.location_in_edge_extractor,
+ nodes_in_edge_extractor=self.nodes_in_edge_extractor,
+ llm_client=self.llm_client,
+ embedder=self.embedder,
+ observation_time=self.observation_time,
+ observation_location=self.observation_location,
+ extraction_mode=self.extraction_mode,
+ node_strategy_or_merger=self.node_merger,
+ edge_strategy_or_merger=self.edge_merger,
+ 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,
+ )