Module kg_embedding 

Knowledge-graph embedding (TransE / DistMult / ComplEx / RotatE) — score a triple (head, relation, tail) for plausibility, and rank candidate entities for link prediction over the semantic graph.

Affordability gating (PROJECT RULE — the honest-scope test)

KG embedding has two halves with wildly different cost:

• Scoring / ranking (score, predict) — a few dot products per triple. Trivially cheap, always present, runs on any device. This is the path a user exercises: given an already-trained EmbeddingTable, score and rank.
• Training ([train]) — gradient descent over many epochs and negatives. This is the heavy, run-once pass: it is structured as an artifact producer that runs on capable hardware and is then distributed (the trained table), never on a user’s critical path. It is dispatch-ready (§13): the per-triple score/gradient batch is kernel-class DenseLinear, with the CPU reference here always present.

So nothing here forces a user into food-vs-compute: they consume a table; they do not have to train one.

Honesty

Every public entry fails closed (KgEmbeddingError) on a dimension/index mismatch rather than returning a fabricated score. A score is only ever produced from real embedding arithmetic.

Re-exports

pub use predict::hits_at_k;

pub use predict::mean_rank;

pub use predict::mean_reciprocal_rank;

pub use predict::rank_tail;

pub use predict::RankFilter;

pub use score::ScoreModel;

pub use train::train;

pub use train::TrainConfig;

Modules

predict

Link prediction: rank candidate entities for an incomplete triple, and the standard ranking metrics (mean rank, MRR, Hits@k). This is the cheap, always-on path — given a trained EmbeddingTable, answer “which tail best completes (h, r, ?)” by scoring candidates and ranking by plausibility.

score

Score functions and their analytic gradients for the four embedding families.

train

Embedding training — the heavy, run-once artifact producer (see the module docs on affordability gating). Stochastic gradient descent with negative sampling: a margin ranking loss for the translational models (TransE, RotatE) and a logistic loss for the bilinear models (DistMult, ComplEx).

Structs

EmbeddingTable

A trained (or freshly-initialised) embedding table: one vector per entity and one per relation. The storage length per entity/relation is fixed by the model and the rank k (see ScoreModel::dims).

Enums

KgEmbeddingError

Fail-closed errors for the embedding library.