src.dackar.RCA.ner.entity_normalizer

entity_normalizer.py — two-phase entity normalization against a KG subgraph.

Phase 1 (token overlap): fast Jaccard-based matching against failure mode names. Phase 2 (LLM shortlist): fires only when Phase 1 confidence is below llm_threshold and an LLM config is supplied; asks the model to pick from the top-3 Phase 1 candidates.

Typical usage

normalizer = EntityNormalizer(failure_modes=kg_context[“failure_modes”], llm_cfg=llm_cfg) results = normalizer.normalize_batch(mechanisms + outcomes, entity_type=”mechanism”)

Attributes

logger

Classes

NormResult	Result of normalizing a single surface form.
EntityNormalizer	Normalize surface-form entity strings to canonical KG failure-mode IDs.

Functions

tokenize(text)	Lowercase word tokens from a string.
_jaccard(a, b)
_call_llm_json(prompt, llm_cfg)	POST to an OpenAI-compatible chat endpoint, return parsed JSON or None.

Module Contents

src.dackar.RCA.ner.entity_normalizer.logger

class src.dackar.RCA.ner.entity_normalizer.NormResult

Result of normalizing a single surface form.

surface_form: str

canonical_id: str

canonical_label: str

component_id: str

confidence: float

method: str

src.dackar.RCA.ner.entity_normalizer.tokenize(text)

Lowercase word tokens from a string.

Parameters:

text (str)

Return type:

set

src.dackar.RCA.ner.entity_normalizer._jaccard(a, b)

Parameters:

• a (set)

• b (set)

Return type:

float

class src.dackar.RCA.ner.entity_normalizer.EntityNormalizer(failure_modes, llm_cfg=None, token_overlap_threshold=0.6, llm_threshold=0.3, top_k_shortlist=3)

Normalize surface-form entity strings to canonical KG failure-mode IDs.

Parameters:

• failure_modes (List[Dict[str, Any]]) – List of dicts with at least {fm_id, name}. Optional component_id.

• llm_cfg (Optional[Dict[str, Any]]) – Dict passed to _call_llm_json (same shape as in causal_condition_adapter). Set to None or omit to disable Phase 2.

• token_overlap_threshold (float) – Minimum Jaccard score to accept a Phase 1 match without consulting the LLM.

• llm_threshold (float) – Minimum Jaccard score for Phase 1 result to be forwarded to the LLM shortlist. Candidates below this score are not worth sending (too noisy).

• top_k_shortlist (int) – Number of Phase 1 candidates to include in the LLM prompt.

llm_cfg = None

token_overlap_threshold = 0.6

llm_threshold = 0.3

top_k_shortlist = 3

_index: List[Dict[str, Any]] = []

normalize(surface_form, entity_type='')

Normalize a single surface form.

Returns a NormResult with method=”none” and empty IDs when the index is empty or no candidate clears the minimum threshold.

Parameters:

• surface_form (str)

• entity_type (str)

Return type:

NormResult

normalize_batch(surface_forms, entity_type='')

Parameters:

• surface_forms (Sequence[str])

• entity_type (str)

Return type:

List[NormResult]

_top_k_by_token_overlap(surface_form)

Parameters:

surface_form (str)

Return type:

List[Tuple[float, Dict[str, Any]]]

_llm_pick(surface_form, entity_type, shortlist)

Parameters:

• surface_form (str)

• entity_type (str)

• shortlist (List[Tuple[float, Dict[str, Any]]])

Return type:

Optional[NormResult]

src.dackar.RCA.ner.entity_normalizer._call_llm_json(prompt, llm_cfg)

POST to an OpenAI-compatible chat endpoint, return parsed JSON or None.

Parameters:

• prompt (str)

• llm_cfg (Dict[str, Any])

Return type:

Optional[Dict[str, Any]]