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.pyindex 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():# 创建 AutoSpatialGraphprint("📊 构建 AutoSpatialGraph 实例...\n")- # 关键:使用 location_in_node_extractor 解析位置属性graph = AutoSpatialGraph[DeepSeaEntity, InteractionEdge](node_schema=DeepSeaEntity,edge_schema=InteractionEdge,- # Split extractors: base name and location separatelynode_key_extractor=lambda x: x.name,- location_in_node_extractor=lambda x: x.location,+ # 基础边 Keyedge_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.pynew file mode 100644index 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__.pyindex 677dc82..9ea5cdc 100644--- a/hyperextract/graphs/__init__.py+++ b/hyperextract/graphs/__init__.py@@ -5,6 +5,7 @@ from .itext2kg_star import iText2KG_Starfrom .atom import Atomfrom .temporal_graph import AutoTemporalGraphfrom .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.pyindex 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 PromptsDEFAULT_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 Principles1. **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 PromptsDEFAULT_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 Constraints1. 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 PromptsDEFAULT_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 Nodes1. 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 ReferenceCurrent 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 locationself.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 Promptfull_node_prompt = DEFAULT_SPATIAL_NODE_ROLE_PREFIXif 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.pynew file mode 100644index 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,+ )