Hypabase

A Python hypergraph library with provenance and SQLite persistence.

A single edge connects 2+ nodes. Every edge tracks where it came from. Data persists to a local SQLite file automatically.

$ uv add hypabase

Documentation GitHub

Quick example

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")

Features

N-ary hyperedges

An edge connects 2+ nodes in a single relationship. No need to decompose complex events into pairs.

Provenance

Every edge carries source and confidence. Filter by origin and trust level.

SQLite persistence

Data persists to a local file automatically. WAL mode, foreign keys, zero configuration.

What is a hypergraph?

In a regular graph, an edge connects exactly two nodes. In a hypergraph, a single edge — called a hyperedge — can connect any number of nodes at once.

Consider a medical event: Dr. Smith prescribes aspirin to Patient 123 for a headache at Mercy Hospital. In a traditional graph, you'd split this into binary edges — doctor-patient, doctor-drug, patient-hospital — and the fact that they belong to one event becomes an inference, not a structure. A hypergraph stores this natively: one edge connecting all five entities.

This matters because real-world relationships often involve more than two things. A paper has multiple authors. A transaction involves a buyer, a seller, a product, and a payment method. Forcing these into pairs means the grouping becomes implicit.