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 許可證。