hyper-kg 0.1.0

A typed knowledge-graph interface for reified-infon (hyperedge) facts: ingest, store, retrieve over a pluggable data layer. Embedded SQLite default; bring-your-own backend via one protocol.

hyper-kg

A small, typed knowledge-graph interface for reified-infon facts — ingest a pile of infons, store them as a property graph, and retrieve with typed primitives. Dependency-free core (stdlib SQLite), with a bring-your-own data layer via one protocol.

An infon is a reified hyperedge: a fact promoted to a first-class, addressable node binding typed role-participants (subject, object, …), carrying polarity, an evidence-mass triple, and provenance — so other facts can point at it.

from hyper_kg import KG

kg = KG.open("sqlite:///world.db")            # or "sqlite://:memory:", or a custom scheme

# write a pile of infons (the {subject,predicate,object,polarity,mass,...} dict shape)
kg.write_infons("doc1", pile)                 # dedup → fan out → one transaction → idempotent

# typed retrieval
kg.find(predicate="supplies", polarity="affirmed")
kg.neighbors("Samsung SDI", hops=2)

# optional: extract straight from text (needs `pip install hyper-kg[extract]`)
kg.ingest("Samsung SDI supplies cells to BMW.", doc_id="doc2")

What it does

• write_infons(doc_id, pile) — each infon fans out into an :Infon node + canonical :Entity nodes + HAS_INFON/S_OF/O_OF edges, batched in one transaction. Idempotent by content-hash id (re-ingest is a no-op). Deduped by (subject, predicate, object, polarity).
• Typed retrieval — find(...) (indexed by subject/predicate/object/polarity), neighbors(node, hops=...) (graph walk), get_infon(id), anchors().
• Bring your own backend — implement the KGStore protocol and register it:

  KG.register_backend("mydb", MyStoreClass)
  kg = KG.open("mydb://...")
  

Design

• Entities arrive canonical. Subject/object are expected to be already-normalized canonical ids (e.g. resolved at extraction time), so there is no entity-resolution pass — the graph stays connected by construction. Un-anchored novel entities can be flagged provisional.
• Generic property graph. nodes(id, labels, props_json + virtual indexed columns) and edges(src, dst, type, props_json) — no per-fact schema migration.
• Typed ops, not query strings. The interface is a small typed method API every backend implements natively, so SQL and custom backends are first-class. A graph-native backend may expose an optional query escape hatch.

License

Apache-2.0.