src.dackar.RCA.doc_extraction.adapter

Attributes

logger
_GROUP_MECHANISM
_GROUP_OUTCOME
_GROUP_COMPONENT
_ENTITY_LINK_JACCARD_THRESHOLD
EXTRACTABLE_DOC_TYPES
_CAUSAL_KEYWORD_PATTERNS

Classes

DocExtractionAdapter

Wraps HybridNERPipeline + causal_condition_adapter to produce DocExtractionRecords.

Functions

_make_ner_cs_factory(mechanism_spans, outcome_spans, ...)	Build a causal_sentence_factory that injects NER entities as SSC patterns.
_best_entity_text(spans)	Return the text of the highest-scoring span, or None if list is empty.
_best_overlapping_entity(target_text, spans[, nlp])	Return the text of the best-matching span for target_text.
_text_overlaps_any(target_text, spans)	Return True if target_text overlaps (substring) with any span in the list.
_has_gazetteer_source(spans[, min_score])	Return True if any span has a gazetteer source with score >= min_score.
_assign_confidence(extractor_used, stmt_confidence, ...)	Assign confidence level per §3.4 of the design plan.

Module Contents

src.dackar.RCA.doc_extraction.adapter.logger

src.dackar.RCA.doc_extraction.adapter._GROUP_MECHANISM = 'G4_MECHANISM_PROCESS'

src.dackar.RCA.doc_extraction.adapter._GROUP_OUTCOME = 'G5_FAILURE_OUTCOME'

src.dackar.RCA.doc_extraction.adapter._GROUP_COMPONENT = 'G1_PHYSICAL_COMPONENT'

src.dackar.RCA.doc_extraction.adapter._ENTITY_LINK_JACCARD_THRESHOLD = 0.4

src.dackar.RCA.doc_extraction.adapter.EXTRACTABLE_DOC_TYPES

class src.dackar.RCA.doc_extraction.adapter.DocExtractionAdapter(ner_pipeline, nlp=None, llm_cfg=None, extraction_version='ner-v1.0_gaz-v1_llm-none', _causal_extractor=None)

Wraps HybridNERPipeline + causal_condition_adapter to produce DocExtractionRecords.

Produces one record per identified causal chain in the document. A document with no extractable causal language produces one null record (confidence=low, needs_human_review=True).

fm_id_candidate is always None at extraction time; resolved via batch KG lookup at RCA run time (see DocExtractionStore.resolve_fm_candidates).

Parameters:

• ner_pipeline (Any)

• nlp (Any)

• llm_cfg (Optional[Dict[str, Any]])

• extraction_version (str)

• _causal_extractor (Optional[Any])

_ner

_nlp = None

_llm_cfg = None

extraction_version = 'ner-v1.0_gaz-v1_llm-none'

__causal_extractor = None

_get_causal_extractor()

Return type:

Any

extract(doc_id, text, doc_type, section_role='body')

Extract all causal chains from a single document text.

Parameters:

• doc_id (str) – Source document identifier (e.g. “CR-2026-00123”).

• text (str) – Full document text (single chunk; multi-chunk handling is a future extension).

• doc_type (str) – Must be one of EXTRACTABLE_DOC_TYPES.

• section_role (str) – Hint for condition-state extraction (“body”, “as_found”, “as_left”, etc.).

Returns:

List of DocExtractionRecord, one per causal chain. Never empty — a document with no causal language returns a single null record.

Raises:

ValueError – if doc_type is not in EXTRACTABLE_DOC_TYPES.

Return type:

List[src.dackar.RCA.doc_extraction.schema.DocExtractionRecord]

_null_record(doc_id, as_found, as_left, proc_score)

Parameters:

• doc_id (str)

• as_found (Optional[str])

• as_left (Optional[str])

• proc_score (float)

Return type:

src.dackar.RCA.doc_extraction.schema.DocExtractionRecord

src.dackar.RCA.doc_extraction.adapter._CAUSAL_KEYWORD_PATTERNS: List[Dict[str, Any]]

src.dackar.RCA.doc_extraction.adapter._make_ner_cs_factory(mechanism_spans, outcome_spans, component_spans)

Build a causal_sentence_factory that injects NER entities as SSC patterns.

CausalSentence requires two types of EntityRuler patterns to fire:

1. SSC entity patterns — G4 mechanism, G5 outcome, G1 component spans from NER

2. Causal keyword patterns — lemma-based verb patterns for sentence selection

Without both, _matchedSents is empty and the extractor silently falls back to dep_fallback on every document. This factory bridges the NER pipeline output into the CausalSentence input contract.

Reproducibility note: the factory closes over this document’s ssc_patterns, and each per-document CausalSentence(nlp) construction calls resetPipeline (CausalBase.__init__), which removes the entity_ruler pipe from the shared nlp before addEntityPattern rebuilds it. The ruler is therefore reset and repopulated with only the current document’s SSC + causal-keyword patterns on every call — patterns do NOT accumulate across documents, so extraction is order-independent. (The 26 keyword patterns are re-added per document as a consequence of that reset; the cost is negligible relative to NER/parse.)

Returns None when no entity spans are available (CausalSentence would return empty anyway; dep_fallback remains the active extractor).

Parameters:

• mechanism_spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

• outcome_spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

• component_spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

Return type:

Optional[Any]

src.dackar.RCA.doc_extraction.adapter._best_entity_text(spans)

Return the text of the highest-scoring span, or None if list is empty.

Parameters:

spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

Return type:

Optional[str]

src.dackar.RCA.doc_extraction.adapter._best_overlapping_entity(target_text, spans, nlp=None)

Return the text of the best-matching span for target_text.

Priority chain (stops at first hit):

1. Exact substring match — O(n), no dependencies

2. Token-set Jaccard ≥ _ENTITY_LINK_JACCARD_THRESHOLD

3. Lemma match via spaCy: lemmatize both sides, re-apply (1) then (2) Only attempted when nlp is provided.

Parameters:

• target_text (Optional[str])

• spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

• nlp (Optional[Any])

Return type:

Optional[str]

src.dackar.RCA.doc_extraction.adapter._text_overlaps_any(target_text, spans)

Return True if target_text overlaps (substring) with any span in the list.

Parameters:

• target_text (Optional[str])

• spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

Return type:

bool

src.dackar.RCA.doc_extraction.adapter._has_gazetteer_source(spans, min_score=0.85)

Return True if any span has a gazetteer source with score >= min_score.

Parameters:

• spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

• min_score (float)

Return type:

bool

src.dackar.RCA.doc_extraction.adapter._assign_confidence(extractor_used, stmt_confidence, has_mechanism, mechanism_spans, outcome_spans, stmt_source='')

Assign confidence level per §3.4 of the design plan.

Rules (in priority order):

LOW — LLM fallback used LOW — no G4 mechanism entity found (cause is symptom-only or null) MEDIUM — dep_fallback source with mechanism present (Improvement E)

dep_fallback spans have lower linguistic quality than CausalSentence; they are never promoted to HIGH regardless of gazetteer hits.

HIGH — CausalSentence + gazetteer hit (score ≥ 0.85) + stmt_confidence ≥ 0.60 MEDIUM — CausalSentence or CausalSimple with mechanism present, no strong gazetteer hit LOW — fallback

Parameters:

• stmt_source (str) – per-statement source field (e.g. "dep_fallback", "CausalSentence"). When provided, takes precedence over extractor_used for the dep_fallback rule so that dep-tree statements embedded inside a CausalSentence result dict are not incorrectly promoted to MEDIUM/HIGH via the CausalSentence path (Improvement E).

• extractor_used (str)

• stmt_confidence (float)

• has_mechanism (bool)

• mechanism_spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

• outcome_spans (List[dackar.RCA.ner.hybrid_ner.models.ResolvedSpan])

Return type:

src.dackar.RCA.doc_extraction.schema.ConfidenceLevel