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: 添加 AutoSpatialGraph 类及示例,支持空间感知知识图谱提取

yifanfeng979501ba710219
diff --git a/examples/auto_spatial_graph_demo.py b/examples/auto_spatial_graph_demo.py
new file mode 100644
index 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__.py
index b6d608f..677dc82 100644
--- a/hyperextract/graphs/__init__.py
+++ b/hyperextract/graphs/__init__.py
@@ -4,6 +4,7 @@ from .itext2kg import iText2KG
from .itext2kg_star import iText2KG_Star
from .atom import Atom
from .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.py
index 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,
+ )