Metadata-Version: 2.4
Name: hyper-kg
Version: 0.1.0
Summary: 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.
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/hyper-kg/
Keywords: knowledge-graph,infon,hypergraph,information-extraction,sqlite,property-graph
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: extract
Requires-Dist: hyper-gliner>=0.1.1; extra == "extract"

# 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.

```python
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:
  ```python
  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.
