Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: 添加 AutoSpatialGraph 类及示例,支持空间感知知识图谱提取
yifanfeng979501ba710219
diff --git a/examples/auto_spatial_graph_demo.py b/examples/auto_spatial_graph_demo.pynew file mode 100644index 0000000..4865635--- /dev/null+++ b/examples/auto_spatial_graph_demo.py@@ -0,0 +1,357 @@+"""+AutoSpatialGraph Demo: 深海惊魂 - "阿特拉斯"号的幽灵 🌊👻++场景背景:+一名深海打捞专家进入失联的科研站"阿特拉斯"号。由于电力系统故障,导航地图失效。+主角必须通过观察周围环境、阅读墙壁标识和逻辑推理来确定自己在空间站的具体位置。++难点:+1. 3D 空间结构:不仅有东南西北,还有"上层甲板"、"下层动力舱"、"垂直维修井"。+2. 相对位置推理:"这里的阀门控制着楼下的..."、"头顶传来了..."。+3. 空间作为属性:位置不再是节点,而是实体(尸体、设备、怪物)的固有属性。+4. 观察点注入:所有相对描述("这里")必须解析为主角当前的观察点。+"""+import sys+import os+from pathlib import Path+from typing import Optional+from dotenv import load_dotenv++# 添加项目根目录到路径+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 AutoSpatialGraph+from ontomem import MergeStrategy++load_dotenv()++# ==================== 1. 定义空间感知知识结构 (Schema) ====================+++class DeepSeaEntity(BaseModel):+ """深海空间站实体节点"""++ name: str = Field(description="实体名称(人名、设备名、怪物代号、房间名)")+ category: str = Field(+ description="实体类型:'船员', '怪物', '关键设备', '房间/区域', '物品'",+ default="未知",+ )+ location: str = Field(+ description="【关键字段】实体所处的具体位置。必须将相对位置解析为绝对位置。",+ default="位置不明",+ )+ status: str = Field(+ description="当前状态(例如:已死亡、损坏、锁定、活跃)", default="正常"+ )++ def __repr__(self):+ return f"📍 [{self.location}] {self.name} ({self.status})"+++class InteractionEdge(BaseModel):+ """实体间的互动关系"""++ source: str = Field(description="发起者")+ target: str = Field(description="对象")+ relation: str = Field(description="关系或动作(例如:'位于...内部','攻击','修复')")+ details: str = Field(description="互动的详细描述", default="")++ def __repr__(self):+ return f"{self.source} --[{self.relation}]--> {self.target}"+++# ==================== 2. 深海探险日志文本 ====================++DEEP_SEA_LOG = """+【自动日志转录 - 救援队员编号:R-09】+【任务:阿特拉斯(Atlas)轨道工厂 - 重启冷却系统】+【当前环境:重力异常,高温警报】+【初始观察点:主气闸舱 (Airlock Alpha)】++08:00+气闸舱的警示灯在闪烁。我刚对接进入「主气闸舱」。这里的空气中弥漫着烧焦的臭氧味。+在我面前(气闸舱正中央)是两台处于休眠状态的安保机器人,型号分别是 "Sentinel-01" 和 "Loader-Bot Beta"。+Sentinel-01 的机械臂严重扭曲,似乎是被某种巨大的力量强行折断的,而 Loader-Bot Beta 的抓手里紧紧握着一张蓝色的 "工程维护卡"。++08:15+维护卡显示拥有「高能物理实验室-B区」的权限。+我看向气闸舱的左侧,那里的重型隔离门上喷着 "To Crew Quarters (船员休眠区)" 的字样,门禁面板显示"封锁中"。+右侧的舱门半开着,门楣上写着 "To Central Hub (中央枢纽)"。地上有一道明显的机油泄露痕迹,延伸进右侧的黑暗走廊中。++08:30+我穿过右侧舱门,进入了「中央枢纽」。这是一个巨大的圆形大厅,占据了空间站的主层。+这里的上方是网格状的金属地板。透过网格,我能看到头顶上方(上层甲板)悬挂着巨大的「备用冷却罐」。那个冷却罐表面覆盖着厚厚的冰霜,显然发生了泄露。+大厅的正中央是一座全息控制台,现在正不断弹出红色的错误代码。++08:45+顺着中央枢纽的地板格栅往下看,我能隐约看到下方的「动力反应堆舱」。那里闪烁着危险的橙色光芒。+突然,反应堆舱那个方向传来了一声金属爆裂的巨响。有什么设备炸了。+我想去找通往下层的梯子,但在枢纽的北侧墙壁上,我发现了一张破损的结构图。如果图纸没更新,那里正是「核心控制阀」所在的位置。++09:00+我决定先去寻找备用电源。根据记忆,就在这个大厅(中央枢纽)的东侧回廊尽头。+我走进东侧回廊。路过「维修车间」时,自动门突然卡住了。+通过门缝,我看到维修车间的一张工作台上,放着被称为 "Prototype-X" 的实验型外骨骼。它看起来像是被拆解了……外壳被暴力撕开。+最关键的是,在这台外骨骼的胸腔核心位置,插着一枚闪烁的「系统引导盘」。++09:10+我试图撬开门取出引导盘。+这时,工作台旁边的阴影里窜出了一只小型的 "Scavenger-Drone (清道夫无人机)"。它处于失控暴走状态。+它向我发射了激光切割束。我举起电磁脉冲盾,将它弹飞到旁边的工具柜上。这里的工具柜被撞得粉碎。++09:20+拿到系统引导盘后,我必须去恢复电力才能重启冷却。+回到中央枢纽,我找到了通往顶部的维修梯。我爬上了头顶的「上层甲板」。+这里的重力系统失效了,冷却液凝结成的冰晶在空中漂浮。+在上层甲板的最南端,就是「主控室」。透过破碎的观察窗,我看到里面的情况很糟。+站长AI终端 "Master Computer" 的屏幕完全碎裂。+终端机的数据接口上插着一根不明来源的数据线,一直连接到地板下的线路中。++09:30+我走进主控室。Master Computer 发出了断断续续的合成音,声音从四周的扬声器(位于主控室墙壁)里传出来:+"警告……核心温度临界……无法控制……"+我看了一眼备用屏幕。监控显示,刚才发出爆炸声的「核心控制阀」(位于我们正下方的底层/反应堆舱)已经被熔化的金属覆盖。+而那种高温熔融物,正通过通风管道,从底层慢慢向上层的各个房间蔓延。++09:45+我必须做出选择。是立刻撤离,还是尝试手动关闭反应堆?+无论如何,我现在的位置(主控室)温度正在急剧升高。通风管道里吹出了灼热的风。++09:50+我冲出主控室,回到上层甲板。这时我发现了一个关键信息——在备用冷却罐下方贴着一份维护日志:+"实验机体 Prototype-X 的核心电池极不稳定。原计划移送至 高能物理实验室-B区 进行拆解,暂存维修车间。"+这意味着,Prototype-X 原本是要送去「高能物理实验室-B区」的。而那间实验室的权限卡,正在主气闸舱里 Loader-Bot Beta 的手中。++10:00+我需要获取那张维护卡,但这意味着我要冒着高温熔穿地板的风险,返回主气闸舱。+在我犹豫的时候,我听到了休眠区的方向传来了结构断裂的声音。+通过内部通讯系统,我听到了一段自动广播:+"注意……高能物理实验室-B区……结构性……崩溃……电池组……连锁反应……"++10:15+我的决定已经定了。我必须到达「高能物理实验室-B区」切断电池组。+为了到达那里,我有两条路:+一是返回主气闸舱取维护卡(路径较远但温度较低)。+二是通过维修通道的紧急截断阀(位于底层的动力反应堆舱侧面)绕过门禁系统(不仅路远,而且是高温核心区,危险系数极大)。+"""++# ==================== 3. 运行提取 ====================+++def run_demo():+ print("=" * 70)+ print("🌊 深海惊魂 - 空间感知分析模块启动")+ print("=" * 70)++ # 初始化 LLM+ print("\n🔧 初始化 LLM 和嵌入模型...")+ llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)+ embedder = OpenAIEmbeddings()++ # 创建 AutoSpatialGraph+ print("📊 构建 AutoSpatialGraph 实例...\n")+ # 关键:spatial_node_key_extractor 组合 name 和 location+ # 这样即使同一对象出现在不同位置也会被视为不同节点+ graph = AutoSpatialGraph[DeepSeaEntity, InteractionEdge](+ node_schema=DeepSeaEntity,+ edge_schema=InteractionEdge,+ spatial_node_key_extractor=lambda x: f"{x.name}@{x.location}",+ edge_key_extractor=lambda x: f"{x.source}|{x.relation}|{x.target}",+ nodes_in_edge_extractor=lambda x: (x.source, x.target),+ llm_client=llm,+ embedder=embedder,+ 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"+ ),+ prompt_for_edge_extraction=(+ "提取实体之间的互动关系。\n"+ "1. 包含物理位置关系(如 '位于...内部')。\n"+ "2. 包含动作互动(如 '杀死了','连接着')。\n"+ "3. 如果实体A拿着实体B,建立 '持有' 关系。\n"+ ),+ verbose=True, # 开启日志以便观察提取过程+ chunk_size=3000, # 文本较短,一次性处理以保持上下文连贯性+ )++ print(f"\n📖 正在加载深海探险日志...")+ print("=" * 70)+ print(DEEP_SEA_LOG[:300] + "...")+ print("=" * 70)++ # 执行提取+ print("\n⚙️ 执行空间感知提取(解析相对方位词)...\n")+ graph.feed_text(DEEP_SEA_LOG)++ # ==================== 4. 空间分析结果 ====================++ print("\n" + "=" * 70)+ print(f"✅ 空间结构分析完成!")+ print("=" * 70)+ print(f" 提取的实体: {len(graph.nodes)} 个")+ print(f" 记录的互动关系: {len(graph.edges)} 个")++ print("\n" + "-" * 70)+ print("📍 空间站实体分布 (Nodes - 按位置分组)")+ print("-" * 70)++ # 按位置简单的分组打印+ nodes_by_location = {}+ for node in graph.nodes:+ # 简单处理一下位置字符串,取前几个字作为粗略分组+ loc_key = node.location if node.location else "未知区域"+ 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}")++ print("\n" + "-" * 70)+ 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} 条关系)")++ # ==================== 5. 空间情报检索 (Search 阶段) ====================++ print("\n" + "=" * 70)+ print("🔍 空间站导航系统 - 向量检索阶段")+ print("=" * 70)++ # 建立索引+ print("\n🏗️ 构建向量索引...")+ graph.build_index()++ # 场景1:找怪物+ q1 = "空间站里有哪些怪物或威胁?它们在哪?"+ print(f"\n❓ Search Query: {q1}")+ try:+ nodes, edges = graph.search(q1, top_k=5)+ if nodes:+ print(f" 📍 相关实体:")+ for n in nodes:+ print(f" - {n}")+ if edges:+ print(f" 🔗 相关关系:")+ for e in edges:+ print(f" - {e}")+ if not nodes and not edges:+ print(" (无相关记录)")+ except Exception as e:+ print(f" 检索失败: {e}")++ # 场景2:找关键物品+ q2 = "黑匣子在哪里找到的?"+ print(f"\n❓ Search Query: {q2}")+ try:+ nodes, edges = graph.search(q2, top_k=3)+ if nodes:+ print(f" 📍 相关实体:")+ for n in nodes:+ print(f" - {n}")+ if edges:+ print(f" 🔗 相关关系:")+ for e in edges:+ print(f" - {e}")+ if not nodes and not edges:+ print(" (无相关记录)")+ except Exception as e:+ print(f" 检索失败: {e}")++ # 场景3:3D 空间理解+ q3 = "动力反应堆舱(底层)里有什么东西?"+ print(f"\n❓ Search Query: {q3}")+ try:+ nodes, edges = graph.search(q3, top_k=5)+ if nodes:+ print(f" 📍 相关实体:")+ for n in nodes:+ print(f" - {n}")+ if edges:+ print(f" 🔗 相关关系:")+ for e in edges:+ print(f" - {e}")+ if not nodes and not edges:+ print(" (无相关记录)")+ except Exception as e:+ print(f" 检索失败: {e}")++ # 场景4:权限卡位置+ q4 = "权限卡在哪里?"+ print(f"\n❓ Search Query: {q4}")+ try:+ nodes, edges = graph.search(q4, top_k=3)+ if nodes:+ print(f" 📍 相关实体:")+ for n in nodes:+ print(f" - {n}")+ if edges:+ print(f" 🔗 相关关系:")+ for e in edges:+ print(f" - {e}")+ if not nodes and not edges:+ print(" (无相关记录)")+ except Exception as e:+ print(f" 检索失败: {e}")+++ # ==================== 6. 交互式情报问答 (Chat 阶段) ====================++ print("\n" + "=" * 70)+ print("💬 深海空间站 - 交互式情报分析终端")+ print("=" * 70)+ print("系统提示: 您现在可以直接用自然语言询问关于空间结构、实体关系和危险评估的复杂问题。\n")++ chat_queries = [+ "这个空间站里发生了什么悲剧?请根据现场的尸体、伤口和位置信息推断事件的发展顺序。",+ "Subject X 是如何逃出医务室的?它现在可能在空间站的哪些地方?",+ "潜水员如果要从医务室安全抵达生物实验室-B区,应该如何规划路线?需要注意哪些危险?",+ ]++ for i, q in enumerate(chat_queries, 1):+ print(f"👤 [深海调查官 {i}]: {q}")+ print("🤖 [AI 空间分析引擎]: 正在检索空间拓扑结构并生成情报分析报告...")++ try:+ # 使用 chat 接口进行 RAG 问答+ response = graph.chat(q)+ print(f"📄 [情报简报]:\n{response.content}\n")+ except Exception as e:+ print(f"⚠️ 系统响应异常: {e}\n")++ # ==================== 7. 保存 ====================++ print("\n" + "=" * 70)+ print("💾 保存空间知识图谱...")+ print("=" * 70)+ save_path = project_root / "temp" / "auto_spatial_graph_demo"+ try:+ graph.dump(str(save_path))+ print(f" 已保存至: {save_path}")+ except Exception as e:+ print(f" 保存失败: {e}")++ print("\n" + "=" * 70)+ print("✅ 演示完成!")+ print("=" * 70)+++if __name__ == "__main__":+ run_demo()diff --git a/hyperextract/graphs/__init__.py b/hyperextract/graphs/__init__.pyindex b6d608f..677dc82 100644--- a/hyperextract/graphs/__init__.py+++ b/hyperextract/graphs/__init__.py@@ -4,6 +4,7 @@ from .itext2kg import iText2KGfrom .itext2kg_star import iText2KG_Starfrom .atom import Atomfrom .temporal_graph import AutoTemporalGraph+from .spatial_graph import AutoSpatialGraph__all__ = [@@ -13,4 +14,5 @@ __all__ = ["iText2KG_Star","Atom","AutoTemporalGraph",+ "AutoSpatialGraph",]diff --git a/hyperextract/graphs/spatial_graph.py b/hyperextract/graphs/spatial_graph.pyindex e69de29..9ac14f7 100644--- a/hyperextract/graphs/spatial_graph.py+++ b/hyperextract/graphs/spatial_graph.py@@ -0,0 +1,412 @@+"""Generic spatial graph implementation supporting custom schemas with location-aware extraction."""++from typing import Type, Callable, Tuple, Any, List+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 .base import AutoGraph, NodeSchema, EdgeSchema, NodeListSchema++# ==============================================================================+# Prompt Definition - Spatial "Sandwich" Injection+# ==============================================================================++# 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.+"""++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.++### 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.+"""++DEFAULT_SPATIAL_EDGE_RULES_SUFFIX = """+### General Constraints+1. ONLY extract edges connecting entities from the known entity list provided below.+ - **CRITICAL**: The entity list identifies spatial entities by their Name AND Location (e.g., "Dr. Chen @ Airlock", "Dr. Chen @ Airlock").+ - You MUST use the exact entity identifier strings from the list for 'source' and 'target' fields.+ - 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.++"""++# 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.+"""++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.++# 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}++### Source Text:+"""+++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).+ - **Schema Agnosticism**: Support any user-defined Node and Edge Pydantic models.++ Example:+ >>> from pydantic import BaseModel, Field+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings+ >>>+ >>> class SpatialEntity(BaseModel):+ ... name: str+ ... entity_type: str+ ... location: str | None = None+ ...+ >>> class Relation(BaseModel):+ ... source: str+ ... target: str+ ... relation_type: str+ >>>+ >>> llm = ChatOpenAI(model="gpt-4")+ >>> embedder = OpenAIEmbeddings()+ >>>+ >>> graph = AutoSpatialGraph(+ ... node_schema=SpatialEntity,+ ... edge_schema=Relation,+ ... # CRITICAL: Combine Name + Location for unique spatial node identity+ ... spatial_node_key_extractor=lambda x: f"{x.name} @ {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),+ ... llm_client=llm,+ ... embedder=embedder,+ ... observation_location="New York City, NY",+ ... extraction_mode="two_stage"+ ... )+ """++ def __init__(+ self,+ node_schema: Type[NodeSchema],+ edge_schema: Type[EdgeSchema],+ spatial_node_key_extractor: Callable[[NodeSchema], str],+ edge_key_extractor: Callable[[EdgeSchema], str],+ nodes_in_edge_extractor: Callable[[EdgeSchema], Tuple[str, str]],+ llm_client: BaseChatModel,+ embedder: Embeddings,+ *,+ 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 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++ spatial_node_key_extractor: Callable function to extract a unique key/identifier from+ each node. Used for deduplication and matching nodes.++ **CRITICAL FOR SPATIAL GRAPHS**: Unlike general graphs, spatial nodes+ must be identified by BOTH their Name AND Location. This reflects the fact+ that the same entity (e.g., "Dr. Chen") at different locations ("Airlock" vs+ "MedBay") represents different spatial states or contexts. This ensures edges+ correctly reference spatially-contextualized entities.++ Example: lambda x: f"{x.name} ({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: Callable function to extract the (source_node_key, target_node_key)+ tuple from an edge. Used to validate edge connectivity and ensure+ edges only connect existing nodes.++ NOTE: The source and target values in your edge schema should already be+ in the format produced by spatial_node_key_extractor (e.g., "Dr. Chen (Airlock)"),+ NOT just the name. The LLM's edge extraction prompt will guide this.++ Example: lambda x: (x.source, x.target)++ 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.+ """+ # Set observation location+ self.observation_location = observation_location or "Unknown Location"+ self._constructor_kwargs = kwargs++ # -----------------------------------------------------------+ # Construct Prompts+ # -----------------------------------------------------------++ # 1. Node Extraction Prompt (Spatial logic lives here)+ full_node_prompt = DEFAULT_SPATIAL_NODE_ROLE_PREFIX+ if prompt_for_node_extraction:+ full_node_prompt += f"\n### Context & Instructions:\n{prompt_for_node_extraction}\n"+ full_node_prompt += DEFAULT_SPATIAL_NODE_RULES_SUFFIX++ # 2. Edge Extraction Prompt+ full_edge_prompt = DEFAULT_SPATIAL_EDGE_ROLE_PREFIX+ if prompt_for_edge_extraction:+ full_edge_prompt += f"\n### Context & Instructions:\n{prompt_for_edge_extraction}\n"+ full_edge_prompt += DEFAULT_SPATIAL_EDGE_RULES_SUFFIX++ # 3. One-Stage Graph Extraction Prompt+ full_graph_prompt = DEFAULT_SPATIAL_GRAPH_ROLE_PREFIX+ if prompt:+ full_graph_prompt += f"\n### Context & Instructions:\n{prompt}\n"+ full_graph_prompt += DEFAULT_SPATIAL_GRAPH_RULES_SUFFIX++ # Initialize parent AutoGraph+ super().__init__(+ node_schema=node_schema,+ edge_schema=edge_schema,+ node_key_extractor=spatial_node_key_extractor,+ edge_key_extractor=edge_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 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_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_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_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_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) -> "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,+ spatial_node_key_extractor=self.node_key_extractor,+ edge_key_extractor=self.edge_key_extractor,+ nodes_in_edge_extractor=self.nodes_in_edge_extractor,+ llm_client=self.llm_client,+ embedder=self.embedder,+ 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,+ )