src.dackar.RCA.doc_extraction.schema

Classes

ConfidenceLevel	str(object='') -> str
EventTimeConfidence	Confidence level for the event_time_start / event_time_end fields on a DocExtractionRecord.
FMResolutionStatus	Resolution status of fm_id_candidate after batch KG embedding lookup.
EpistemicClass	Four-way epistemic classification for data elements (§2 of epistemics_notes_4.md).
ClassificationResolutionLevel	Which level of the priority chain resolved the epistemic classification (§3.3).
FindingStatus	Semantic status of a document's finding — primary input to the classifier (Level 1).
AuthorityLevel	Epistemic authority of a document — secondary input to the classifier (Level 2).
DocExtractionRecord	One extraction record per identified causal chain within a source document.

Module Contents

class src.dackar.RCA.doc_extraction.schema.ConfidenceLevel

Bases: str, enum.Enum

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

HIGH = 'high'

MEDIUM = 'medium'

LOW = 'low'

class src.dackar.RCA.doc_extraction.schema.EventTimeConfidence

Bases: str, enum.Enum

Confidence level for the event_time_start / event_time_end fields on a DocExtractionRecord.

Used by the cross-pattern linkage layer (§4.1) to decide whether temporal matching can be attempted. “absent” causes temporal_link_skipped = True.

EXPLICIT = 'explicit'

INFERRED = 'inferred'

ABSENT = 'absent'

class src.dackar.RCA.doc_extraction.schema.FMResolutionStatus

Bases: str, enum.Enum

Resolution status of fm_id_candidate after batch KG embedding lookup.

Thresholds (cosine similarity vs. KG FM embeddings):

>= 0.88 → AUTO_RESOLVED (eligible for recurrence counting) [0.80, 0.88) → AMBIGUOUS (candidate stored; requires analyst promotion) < 0.80 → UNRESOLVED (fm_id_candidate remains None)

AUTO_RESOLVED = 'auto_resolved'

AMBIGUOUS = 'ambiguous'

UNRESOLVED = 'unresolved'

class src.dackar.RCA.doc_extraction.schema.EpistemicClass

Bases: str, enum.Enum

Four-way epistemic classification for data elements (§2 of epistemics_notes_4.md).

Answers: what relationship does this data element have to equipment performance?

AFFECTS_PERFORMANCE — things that act on the equipment; candidate causes

(WOs, config changes, PM compliance, operational context)

MONITORS_PERFORMANCE — things that observe the equipment’s state; evidence of

condition, not cause (CRs, telemetry, alarms, SOE)

ANALYZES_PAST_DEGRADATION — things whose primary purpose is causal interpretation

of a specific past event (ECAs, RCAs, OE/LER documents)

CHARACTERIZES_THE_SYSTEM — things that define the reference frame: KG, FMEA,

protection logic, SOPs

AFFECTS_PERFORMANCE = 'affects_performance'

MONITORS_PERFORMANCE = 'monitors_performance'

ANALYZES_PAST_DEGRADATION = 'analyzes_past_degradation'

CHARACTERIZES_THE_SYSTEM = 'characterizes_the_system'

class src.dackar.RCA.doc_extraction.schema.ClassificationResolutionLevel

Bases: str, enum.Enum

Which level of the priority chain resolved the epistemic classification (§3.3).

Priority order: FINDING_STATUS → AUTHORITY_LEVEL → DOC_TYPE → DEFAULT

FINDING_STATUS — resolved via semantic finding_status field; not degraded AUTHORITY_LEVEL — resolved via semantic authority_level field; not degraded DOC_TYPE — resolved via syntactic doc_type proxy; degraded_classification=True DEFAULT — no metadata available; degraded_classification=True

FINDING_STATUS = 'finding_status'

AUTHORITY_LEVEL = 'authority_level'

DOC_TYPE = 'doc_type'

DEFAULT = 'default'

class src.dackar.RCA.doc_extraction.schema.FindingStatus

Bases: str, enum.Enum

Semantic status of a document’s finding — primary input to the classifier (Level 1).

Populated at document ingestion when the source document carries a structured finding_status field (e.g., CR closure code, ECA conclusion type).

FORMAL_CONCLUSION — document is a finalized causal interpretation

→ routes to analyzes_past_degradation

PRELIMINARY_ASSESSMENT — document contains a preliminary cause observation

→ routes to monitors_performance (CR) or

analyzes_past_degradation (ECA/RCA) per doc_type

OBSERVATION_ONLY — document records a condition with no causal assessment

→ routes to monitors_performance

FORMAL_CONCLUSION = 'formal_conclusion'

PRELIMINARY_ASSESSMENT = 'preliminary_assessment'

OBSERVATION_ONLY = 'observation_only'

class src.dackar.RCA.doc_extraction.schema.AuthorityLevel

Bases: str, enum.Enum

Epistemic authority of a document — secondary input to the classifier (Level 2).

Populated at ingestion for OE/industry documents and formal plant documents. Captures the tier-distance discount described in §2.3 (plant 1.0 / fleet 0.80 / industry 0.60).

MANDATORY — plant-level formal conclusion; highest authority GUIDANCE — fleet or industry analogy; discounted authority INFORMATIONAL — background or preliminary; no causal authority

MANDATORY = 'mandatory'

GUIDANCE = 'guidance'

INFORMATIONAL = 'informational'

class src.dackar.RCA.doc_extraction.schema.DocExtractionRecord

One extraction record per identified causal chain within a source document.

A single CR/WO may produce multiple records (one per causal chain). Records with all semantic fields null are stored but flagged for human review. fm_id_candidate is null at ingestion time; resolved via batch KG lookup at RCA run time (§3.3 Step C). embedding_model_version is null until the record is embedded in Stage 2.

doc_id: str

chain_index: int

identified_effect: str | None

assessed_cause: str | None

inferred_fm_label: str | None

fm_id_candidate: str | None

fm_id_candidate_alt: str | None

confidence: ConfidenceLevel

cause_is_symptom: bool

as_found: str | None

as_left: str | None

procedural_deviation_score: float

extraction_version: str

embedding_model_version: str | None

needs_human_review: bool = False

ruled_out_mechanisms: List[str] = []

event_time_start: datetime.datetime | None = None

event_time_end: datetime.datetime | None = None

event_time_confidence: str | None = None

source_cr_id: str | None = None

source_wo_id: str | None = None

source_event_id: str | None = None

fm_resolution_status: str | None = None

fm_resolution_score: float | None = None

doc_type: str = ''

finding_status: str | None = None

authority_level: str | None = None

epistemic_class: str | None = None

classification_resolution_level: str | None = None

degraded_classification: bool = False

embed_text()

Concatenation of semantic fields used for embedding (null-safe).

Return type:

str

is_null_record()

Return True when no semantic content was extracted (all three core fields empty).

Null records are the sentinel produced for a document with no extractable causal language; they are stored and retrievable by metadata but never surface in similarity queries (their embed_text is a single space).

Return type:

bool

is_recurrence_eligible()

Return True when this record may contribute to recurrence counting.

Records with fm_resolution_status == “ambiguous” require analyst promotion before being eligible; all others (auto_resolved, unresolved, or not yet resolved) are treated as eligible by default.

Phase C will add an additional gate: records whose epistemic_class is not “analyzes_past_degradation” will be ineligible regardless of fm_resolution_status. That gate is intentionally off here to avoid a scoring change before calibration.

Return type:

bool

as_chroma_metadata()

Flat metadata dict for Chroma upsert (all values must be str/int/float/bool).

Return type:

dict