Core types for knowledge graphs.

This crate provides foundational types for working with knowledge graphs:

• [Triple] - A (subject, predicate, object) triple
• [Entity] - A node in the knowledge graph
• [Relation] - An edge type in the knowledge graph
• [KnowledgeGraph] - A homogeneous graph structure built from triples
• [HeteroGraph] - A heterogeneous graph with typed nodes and edges

Historical Context: From Databases to Graphs

Knowledge graphs became essential when search engines realized that "things, not strings" (Google, 2012) captures real-world semantics that keyword matching misses.

The Triple: Atomic Unit of Knowledge

All knowledge graph formalisms reduce to the triple:

(subject, predicate, object)
(Albert Einstein, born_in, Ulm)
(Ulm, located_in, Germany)

This simple structure enables:

• Inference: If A → B → C, deduce A → C
• Composition: Merge graphs by merging shared entities
• Embedding: Represent triples as vectors for ML

Beyond Triples: N-ary Relations and Hypergraphs

Triples are limited - they can only express binary relations. Real-world facts often involve more than two entities:

(Einstein, won, Nobel Prize, Physics, 1921)  -- 4 entities!
(Alice, purchased, Book, $20, Amazon, 2024-01-15)  -- 6 entities!

Three approaches handle this:

Reification (Workaround)

Convert n-ary facts to binary by introducing intermediate nodes:

Original: (Einstein, won, Nobel, Physics, 1921)
Reified:  (Award_1, recipient, Einstein)
          (Award_1, prize, Nobel)
          (Award_1, field, Physics)
          (Award_1, year, 1921)

Problem: Loses the atomic nature of the fact. Embedding models struggle because Award_1 is artificial - it has no semantic meaning.

Hyper-relational KGs (Wikidata Style)

Attach qualifiers to triples:

(Einstein, won, Nobel Prize)
  qualifiers: {field: Physics, year: 1921}

Implemented in [hyper::HyperTriple]. Embeddings: StarE, HINGE.

Knowledge Hypergraphs (Native N-ary)

Represent facts as hyperedges connecting multiple entities with roles:

HyperEdge {
  relation: "award_ceremony",
  bindings: {
    recipient: Einstein,
    prize: Nobel,
    field: Physics,
    year: 1921
  }
}

Implemented in [hyper::HyperEdge]. Embeddings: HSimplE, HypE, HyCubE.

Key insight: Position-aware or role-aware encoding is essential. The relation "recipient" carries different semantics than "year".

See [hyper] module for hypergraph types.

Homogeneous vs Heterogeneous Graphs

[HeteroGraph] supports typed nodes and edges, essential for:

• RGCN: Relation-specific weight matrices
• HGT: Heterogeneous graph transformers
• Link prediction: Typed edge prediction

Serialization Formats

Supports modern RDF 1.2 specifications (2024):

• N-Triples - Line-based, simple (fastest parsing)
• N-Quads - N-Triples with named graphs
• Turtle - Human-readable (best for debugging)
• JSON-LD - Linked data (web integration)

Algorithms

Centrality ([algo::centrality])

Other Algorithms

• [algo::random_walk] - Node2Vec style random walks (biased BFS/DFS)
• [algo::components] - Connected components (graph structure)
• [algo::sampling] - Neighbor sampling for mini-batch GNN training

When to Use Which Structure

Example

use lattix::{Triple, KnowledgeGraph};

let mut kg = KnowledgeGraph::new();

// Add triples
kg.add_triple(Triple::new("Apple", "founded_by", "Steve Jobs"));
kg.add_triple(Triple::new("Apple", "headquartered_in", "Cupertino"));
kg.add_triple(Triple::new("Steve Jobs", "born_in", "San Francisco"));

// Query
let apple_relations = kg.relations_from("Apple");
assert_eq!(apple_relations.len(), 2);