ExposoGraph.grounding

Grounding and graph-preparation helpers used to reconcile free-text or seeded content with canonical reference entities.

Grounding helpers for reconciling nodes and graphs to canonical references.

This module adds a lightweight normalization layer on top of the existing knowledge-graph schema. It does not rewrite node IDs; instead it annotates nodes and edges with canonical metadata so later merge/validation stages can decide whether to keep, normalize, or reject exploratory content.

class ExposoGraph.grounding.GroundingMatch(canonical_id, canonical_label, canonical_namespace, match_status, extra_fields=<factory>)[source]

Canonical match metadata for a grounded term.

Parameters:
canonical_id: str
canonical_label: str
canonical_namespace: str
match_status: MatchStatus
extra_fields: Mapping[str, str | int | float | None]
ExposoGraph.grounding.normalize_grounding_key(value)[source]

Normalize a label or identifier for fuzzy exact-match grounding.

Parameters:

value (str)

Return type:

str

ExposoGraph.grounding.build_graph_grounding_index(graph, *, namespace)[source]

Build a normalized lookup index from a reference KnowledgeGraph.

Parameters:
Return type:

dict[str, GroundingMatch]

ExposoGraph.grounding.build_iarc_grounding_index(classifier=None)[source]

Build a normalized lookup index from the bundled IARC classifier data.

Parameters:

classifier (IARCClassifier | None)

Return type:

dict[str, GroundingMatch]

ExposoGraph.grounding.build_default_grounding_index(*, reference_graphs=None, classifier=None)[source]

Build the default grounding index from reference panels plus IARC.

Parameters:
Return type:

dict[str, GroundingMatch]

ExposoGraph.grounding.ground_node(node, *, grounding_index=None, reference_graphs=None, classifier=None)[source]

Return a grounded copy of node using built-in or supplied references.

Parameters:
Return type:

Node

ExposoGraph.grounding.ground_knowledge_graph(graph, *, grounding_index=None, reference_graphs=None, classifier=None)[source]

Ground all nodes in graph and derive edge grounding status.

Parameters:
Return type:

KnowledgeGraph

ExposoGraph.grounding.prepare_knowledge_graph(graph, *, mode=GraphMode.EXPLORATORY, grounding_index=None, reference_graphs=None, classifier=None)[source]

Ground graph and optionally filter it for strict-mode workflows.

Parameters:
Return type:

tuple[KnowledgeGraph, list[str]]