Hypabase

🚀 Hypabase

Hypabase是一个Python超图库，支持数据来源追溯和SQLite持久化存储，能有效处理复杂的多节点关系，并对数据来源进行追踪和管理。

🚀 快速开始

以下是一个简单的示例，展示了如何使用Hypabase创建超图、添加边、查询边和查找路径：

from hypabase import Hypabase

hb = Hypabase("my.db")

# One edge connecting five entities
hb.edge(
    ["dr_smith", "patient_123", "aspirin", "headache", "mercy_hospital"],
    type="treatment",
    source="clinical_records",
    confidence=0.95,
)

# Query edges involving a node
hb.edges(containing=["patient_123"])

# Find paths between entities
hb.paths("dr_smith", "mercy_hospital")

📦 安装指南

使用以下命令安装Hypabase：

uv add hypabase

✨ 主要特性

• 超边：一条边可以在单一关系中连接2个或更多节点。
• 来源追溯：每条边都携带 source（数据来源）和 confidence（置信度）信息。
• SQLite持久化：数据会自动持久化到本地文件。
• O(1) 顶点集查找：可以通过精确的节点集查找边。
• 命名空间隔离：使用 .database("name") 可以在单个文件中创建作用域视图。
• 来源追溯查询：可以通过 source 和 min_confidence 过滤查询，并使用 sources() 汇总所有数据来源。
• 内存MCP服务器：提供7种工具，用于AI代理的持久化内存管理（记住、召回、遗忘、合并、连接、谁知道什么、解决矛盾）。
• 命令行界面（CLI）：支持 hypabase init、hypabase node、hypabase edge、hypabase query 等命令。

💻 使用示例

基础用法

from hypabase import Hypabase

hb = Hypabase("my.db")

# One edge connecting five entities
hb.edge(
    ["dr_smith", "patient_123", "aspirin", "headache", "mercy_hospital"],
    type="treatment",
    source="clinical_records",
    confidence=0.95,
)

# Query edges involving a node
hb.edges(containing=["patient_123"])

# Find paths between entities
hb.paths("dr_smith", "mercy_hospital")

来源追溯用法

# 每条边携带 source 和 confidence
hb.edge(
    ["patient_123", "aspirin", "ibuprofen"],
    type="drug_interaction",
    source="clinical_decision_support_v3",
    confidence=0.92,
)

# 通过上下文管理器批量设置来源追溯信息
with hb.context(source="schema_analysis", confidence=0.9):
    hb.edge(["a", "b"], type="fk")
    hb.edge(["b", "c"], type="fk")

# 根据来源追溯信息查询
hb.edges(source="clinical_decision_support_v3")
hb.edges(min_confidence=0.9)

# 查看所有数据来源的概述
hb.sources()

命名空间隔离用法

# 将数据隔离到单个文件的不同命名空间中
hb = Hypabase("knowledge.db")

drugs = hb.database("drugs")
sessions = hb.database("sessions")

drugs.node("aspirin", type="drug")
sessions.node("s1", type="session")

drugs.nodes()     # -> [aspirin]
sessions.nodes()  # -> [s1]

MCP服务器用法

uv add hypabase
hypabase-memory

CLI用法

uv add hypabase
hypabase init
hypabase node dr_smith --type doctor
hypabase edge dr_smith patient_123 aspirin --type treatment --source clinical_records
hypabase query --containing dr_smith
hypabase stats

📚 详细文档

超图是一种图结构，其中的一条边（称为超边）可以同时连接任意数量的节点，而普通图中的边只能连接两个节点。例如，在医疗事件“史密斯医生在 Mercy 医院为 123 号患者开了阿司匹林治疗头痛”中，使用传统图需要将其拆分为多个二元边，而超图可以用一条边直接连接所有五个实体。

为什么需要来源追溯？

当关系来自不同的数据源（如手动输入、大语言模型提取、传感器数据、临床记录等）时，需要知道每个关系的来源以及对其的信任程度。Hypabase 通过在每条边上设置 source（标识来源的字符串）和 confidence（0 到 1 之间的浮点数）两个字段来跟踪这些信息。可以根据这些字段过滤查询，并使用 hb.sources() 汇总图中所有的数据源。

超图的应用场景

• 知识图谱：无需分解即可表示复杂的现实世界关系。
• 智能体记忆：为 AI 智能体提供结构化、可查询的跨会话持久内存。
• 生物医学数据：药物相互作用、临床事件、分子通路等。
• RAG 管道：存储提取的关系以用于检索增强生成。
• 供应链、协作网络以及任何涉及两个以上事物的关系场景。

超图的概念源于人工智能研究，如 OpenCog 的 AtomSpace 使用类似超图的结构为通用人工智能表示知识。近期的研究将超图应用于检索和推理：

• HyperGraphRAG — 跨医学、农业、计算机科学和法律领域的 n 元知识检索。
• Cog - RAG — 具有主题级和实体级召回的双超图检索。
• Hypergraph Memory for Multi - step RAG — 用于长上下文关系建模的基于超图的内存。

更多详细文档请访问 docs.hypabase.app。

📄 许可证

本项目采用 Apache 2.0 许可证。