src.dackar.RCA.ner.spacy_annotator

spacy_annotator.py ────────────────────────────────────────────────────────────────────────────── Thin wrapper that runs the six plant-specific spaCy pipeline components (Temporal, TemporalRelation, TemporalAttribute, Location, Conjecture, Unit) on arbitrary text and returns a structured SpacyAnnotationResult.

Used in two tiers of the RCA workflow:

Tier 1 (indexing) — called from ner_adapter to enrich NERSeed Tier 2 (scoring) — injected into ChromaEvidenceRetriever to annotate

each retrieved snippet inside _assess_hit_against_candidate

Attributes

_TO_HOURS
_DURATION_RE

Classes

SpacyAnnotationResult	Structured output from SpacyAnnotator.annotate().
SpacyAnnotator	One-time-initialised wrapper for the six plant-specific spaCy components.

Functions

_parse_lag_hours(texts)	Return the first parseable duration in hours from a list of temporal ref texts.
build_spacy_annotator([nlp_model])	Factory function — initialise a SpacyAnnotator and return it.

Module Contents

src.dackar.RCA.ner.spacy_annotator._TO_HOURS: Dict[str, float]

src.dackar.RCA.ner.spacy_annotator._DURATION_RE

src.dackar.RCA.ner.spacy_annotator._parse_lag_hours(texts)

Return the first parseable duration in hours from a list of temporal ref texts.

Returns None if no duration pattern is found.

Parameters:

texts (List[str])

Return type:

Optional[float]

class src.dackar.RCA.ner.spacy_annotator.SpacyAnnotationResult

Structured output from SpacyAnnotator.annotate().

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

{value, unit, entity_type, text}.

Type:

Physical measurements

temporal_refs: List[str] = []

‘March 14 2025’, ‘48 hours’.

Type:

Absolute dates and durations

temporal_relations: List[Dict[str, str]] = []

{text, sub_label} where sub_label is one of temporal_relation_order | temporal_relation_reverse_order | temporal_relation_concurrency.

Type:

Ordering words

temporal_qualifiers: List[str] = []

‘approximately’, ‘roughly’.

Type:

Fuzzy temporal qualifiers

locations: List[Dict[str, str]] = []

{text, sub_label} where sub_label is one of location_proximity | location_up | location_down.

Type:

Spatial terms

conjectures: List[str] = []

‘possibly’, ‘likely’, ‘suspected’.

Type:

Epistemic hedge markers

lag_hours: float | None = None

First parseable duration from temporal_refs, converted to hours.

lag_is_approximate: bool = False

True when temporal_qualifiers are present alongside a lag_hours value.

conjecture_fraction()

Ratio of conjecture markers to total semantic signals.

Used as a hedge-density proxy: high values indicate the source text is speculative rather than confirmatory.

Return type:

float

dominant_temporal_relation()

Most common temporal ordering label mapped to the schema enum.

Returns ‘precedes’, ‘follows’, ‘simultaneous’, or None.

Return type:

Optional[str]

class src.dackar.RCA.ner.spacy_annotator.SpacyAnnotator(nlp_model='en_core_web_sm')

One-time-initialised wrapper for the six plant-specific spaCy components.

Instantiate once per process (model load + pipe setup are expensive) and share the same instance across Tier 1 (ner_adapter) and Tier 2 (evidence_retriever).

Parameters:

nlp_model (str) – spaCy model name. Must include an NER component so that TemporalEntity’s Matcher patterns that rely on ENT_TYPE DATE/TIME fire correctly. Defaults to ‘en_core_web_sm’.

_UNIT_LABEL = 'unit'

_TEMPORAL_LABEL = 'Temporal'

_TEMPORAL_RELATION_LABELS

_TEMPORAL_ATTRIBUTE_LABEL = 'temporal_attribute'

_LOCATION_LABELS

_CONJECTURE_LABEL = 'conjecture'

nlp

annotate(text)

Run all six components on text and return a structured result.

Parameters:

text (str) – Arbitrary chunk or snippet text.

Returns:

SpacyAnnotationResult with all signal buckets populated.

Return type:

SpacyAnnotationResult

src.dackar.RCA.ner.spacy_annotator.build_spacy_annotator(nlp_model='en_core_web_sm')

Factory function — initialise a SpacyAnnotator and return it.

Centralises model selection so callers don’t need to import SpacyAnnotator directly.

Parameters:

nlp_model (str) – spaCy model name (default: ‘en_core_web_sm’).

Returns:

Configured and ready SpacyAnnotator instance.

Return type:

SpacyAnnotator