mixle.substrate.kg_rag module

KG-RAG – typed retrieval over a knowledge graph, with an entity-linking leaf (D3).

Text retrieval finds passages; a knowledge graph answers with facts. link_entities() is the entity-linking leaf: it maps a question’s tokens onto the KG’s entity inventory (longest-name-first, so “new york city” links before “york”). retrieve_triples() returns the facts about the linked entities – filtered through an Ontology when one is given, so a schema-violating triple in an unvalidated store is never served as evidence. kg_action() packages that as a reasoner Action, so investigate() / the Reasoner can buy typed evidence: the fragment for (ada, lives_in, paris) reads ada lives_in paris, citable and checkable against the graph rather than parsed back out of prose.

link_entities(question, entities)[source]

The entity-linking leaf: which KG entities does the question mention?

Matches each entity’s normalized name as a token subsequence of the question, longest name first so multi-word entities win over their substrings. Returns the linked entities in match order.

Parameters:

  • question (str)

  • entities (Any)

Return type:

list[str]

retrieve_triples(triples, question, *, ontology=None, types=None, k=8)[source]

Typed KG retrieval: link the question’s entities, return the (schema-valid) facts about them.

Returns {entities, facts, rejected} – facts are the triples touching a linked entity (head or tail), at most k; when an ontology (+ entity types) is supplied, schema-violating triples are excluded and reported under rejected with named reasons, so an unvalidated store cannot inject a type-invalid fact as evidence.

k must be an exact, non-negative int (MXR-080-0253, see _require_count()) – a negative k used to fall through to ordinary Python slicing (hits[:-1] silently drops just the last hit) instead of being rejected. triples is materialized once, validated, into an immutable structure before any lookup runs (MXR-080-0253, see _materialize_triples()) – safe no matter how many times triples is a one-shot iterable and no matter how many times this function is called with it.

Parameters:
Return type:

dict[str, Any]

kg_action(triples, *, ontology=None, types=None, name='kg', cost=1.0, description='', k=8)[source]

A reasoner RETRIEVE action over a knowledge graph (typed facts, not passages).

Contributes one fragment per fact (head relation tail); nothing links -> no evidence, so the reasoner falls through honestly instead of forcing a match. Relevance comes from the action’s description plus the KG’s own entity inventory (queries naming a known entity score).

triples is materialized exactly once, here, into an immutable, arity-validated structure (MXR-080-0253, see _materialize_triples()) – both the inventory built below and every later _run call read from that same materialized data, so a one-shot triples generator can no longer be exhausted by the inventory pass and come up empty when the action actually runs. k shares retrieve_triples()’s exact-non-negative-integer contract, checked up front so a bad k fails at construction rather than silently inside a fired action.

Parameters:
Return type:

Any