src.dackar.RCA.orchestrators.rca_reasoning_orchestrator

Attributes

LOGGER

JsonDict

_SCORING_FIELDS_PROTECTED

Classes

KGContextBuilder

Collaborator that builds the knowledge-graph context for an event.

TSKRTemporalScorer

Collaborator that scores TSKR temporal chain-position patterns.

CausalityEngine

Collaborator that generates and refines causal candidate hypotheses.

EvidenceRetriever

Collaborator that retrieves documentary evidence for candidates.

RCASynthesizer

Collaborator that synthesizes the final validated RCA card.

IshikawaEvaluator

Collaborator that builds the Ishikawa (fishbone) contributing-factor matrix.

SchemaValidator

Backward-compatible validator protocol.

ArtifactStore

Collaborator that persists run artifacts and returns their storage keys.

OrchestratorConfig

Tunable configuration for RCAReasoningOrchestrator.

RCAReasoningOrchestrator

Deterministic RCA pipeline coordinating the reasoning collaborators.

Functions

utcnow_iso()

parse_dt(value)

_serialize_signal_episode(ep)

Convert a HistoricalSignalEpisode to a JSON-serializable dict.

_summarize_signal_episodes(historical_signal_episodes)

Build the run_manifest artifacts summary for historical_signal_episodes.

_summarize_cross_pattern_evidence(cross_pattern_evidence)

Build the run_manifest artifacts summary for cross_pattern_evidence.

_build_epistemics_manifest_summary(...)

Delegate to build_epistemics_manifest_summary() in doc_extraction/epistemics.py.

_assert_cross_pattern_non_intrusion(...)

Runtime guard: verify cross_pattern_evidence does not contain protected scoring fields.

_collect_keys(obj, out, depth, max_depth)

Recursively collect dict keys up to max_depth.

build_dev_orchestrator(output_dir, client[, database, ...])

Build a fully wired RCAReasoningOrchestrator for local development.

Module Contents

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.LOGGER[source]
src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.JsonDict[source]
src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.utcnow_iso()[source]
Return type:

str

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.parse_dt(value)[source]
Parameters:

value (Optional[str])

Return type:

Optional[datetime.datetime]

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.KGContextBuilder[source]

Bases: Protocol

Collaborator that builds the knowledge-graph context for an event.

build(event, telemetry_summary, operational_context, pm_compliance, run_context, focus_component_ids=None)[source]

Build the KG neighbourhood for an event.

Parameters:

  • event (JsonDict) – Target abnormal event (must carry event_id or id).

  • telemetry_summary (JsonDict) – Telemetry anomaly summary for the event window.

  • operational_context (Optional[JsonDict]) – Optional operating-state and PM-compliance inputs, or None.

  • pm_compliance (Optional[JsonDict]) – Optional operating-state and PM-compliance inputs, or None.

  • run_context (JsonDict) – Orchestrator run context (run_id and related identifiers).

  • focus_component_ids (Optional[List[str]]) – When provided, narrows the neighbourhood to these components; auto re-entry uses it to refocus a second pass.

Returns:

KG neighbourhood (components, failure modes, barriers) conforming to schemas/kg_context.json.

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.TSKRTemporalScorer[source]

Bases: Protocol

Collaborator that scores TSKR temporal chain-position patterns.

score(event, telemetry_summary, kg_context, operational_context, run_context, signal_evidence=None)[source]

Score temporal patterns for the event’s candidate failure modes.

Parameters:

  • event (JsonDict) – Target abnormal event.

  • telemetry_summary (JsonDict) – Telemetry anomaly summary for the event window.

  • kg_context (JsonDict) – KG neighbourhood from KGContextBuilder.build().

  • operational_context (Optional[JsonDict]) – Optional operating-state input, or None.

  • run_context (JsonDict) – Orchestrator run context.

  • signal_evidence (Optional[JsonDict]) – Optional signal-episode evidence, or None when unavailable.

Returns:

TSKR patterns conforming to schemas/tskr_patterns.json.

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.CausalityEngine[source]

Bases: Protocol

Collaborator that generates and refines causal candidate hypotheses.

generate(event, telemetry_summary, kg_context, tskr_patterns, operational_context, pm_compliance, run_context)[source]

Generate ranked causal candidate hypotheses for the event.

Parameters:

  • event (JsonDict) – Target abnormal event.

  • telemetry_summary (JsonDict) – Telemetry anomaly summary for the event window.

  • kg_context (JsonDict) – KG neighbourhood from KGContextBuilder.build().

  • tskr_patterns (Optional[JsonDict]) – TSKR chain-position patterns, or None when unavailable.

  • operational_context (Optional[JsonDict]) – Optional supporting artifacts, or None.

  • pm_compliance (Optional[JsonDict]) – Optional supporting artifacts, or None.

  • run_context (JsonDict) – Orchestrator run context.

Returns:

Candidate hypotheses conforming to schemas/causality_candidates.json.

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.EvidenceRetriever[source]

Bases: Protocol

Collaborator that retrieves documentary evidence for candidates.

retrieve(event, kg_context, causality_candidates, operational_context, run_context)[source]

Retrieve an evidence bundle supporting the candidate hypotheses.

Parameters:

  • event (JsonDict) – Target abnormal event.

  • kg_context (JsonDict) – KG neighbourhood from KGContextBuilder.build().

  • causality_candidates (JsonDict) – Candidate hypotheses to gather evidence for.

  • operational_context (Optional[JsonDict]) – Optional operating-state input, or None.

  • run_context (JsonDict) – Orchestrator run context.

Returns:

Evidence bundle conforming to schemas/evidence_bundle.json (its results list holds normalized, candidate-linked hits).

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.RCASynthesizer[source]

Bases: Protocol

Collaborator that synthesizes the final validated RCA card.

synthesize(event, telemetry_summary, kg_context, tskr_patterns, causality_candidates, evidence_bundle, operational_context, pm_compliance, ishikawa_matrix, run_context)[source]

Synthesize a validated RCA card from the reasoning artifacts.

Parameters:

  • event (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • telemetry_summary (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • kg_context (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • tskr_patterns (Optional[JsonDict]) – TSKR chain-position patterns, or None.

  • causality_candidates (JsonDict) – Ranked candidate hypotheses and their retrieved evidence.

  • evidence_bundle (JsonDict) – Ranked candidate hypotheses and their retrieved evidence.

  • operational_context (Optional[JsonDict]) – Optional supporting artifacts folded into the card when present.

  • pm_compliance (Optional[JsonDict]) – Optional supporting artifacts folded into the card when present.

  • ishikawa_matrix (Optional[JsonDict]) – Optional supporting artifacts folded into the card when present.

  • run_context (JsonDict) – Orchestrator run context.

Returns:

An RCA card conforming to schemas/rca_card.json.

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.IshikawaEvaluator[source]

Bases: Protocol

Collaborator that builds the Ishikawa (fishbone) contributing-factor matrix.

evaluate(event, telemetry_summary, kg_context, tskr_patterns, causality_candidates, evidence_bundle, operational_context, pm_compliance, run_context)[source]

Build the Ishikawa contributing-factor matrix for the event.

Parameters:

  • event (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • telemetry_summary (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • kg_context (JsonDict) – Target event, its telemetry summary, and the KG neighbourhood.

  • tskr_patterns (Optional[JsonDict]) – TSKR chain-position patterns, or None.

  • causality_candidates (JsonDict) – Ranked candidate hypotheses and their retrieved evidence.

  • evidence_bundle (JsonDict) – Ranked candidate hypotheses and their retrieved evidence.

  • operational_context (Optional[JsonDict]) – Optional supporting artifacts, or None.

  • pm_compliance (Optional[JsonDict]) – Optional supporting artifacts, or None.

  • run_context (JsonDict) – Orchestrator run context.

Returns:

An Ishikawa matrix conforming to schemas/ishikawa_matrix.json.

Return type:

JsonDict

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.SchemaValidator[source]

Bases: Protocol

Backward-compatible validator protocol.

Supported validator styles:
  1. legacy:

    validate(artifact_name, payload) -> None

  2. richer per-artifact:

    validate_artifact(artifact_name, payload) -> ValidationReport|dict|None

  3. richer bundle:

    validate_run_bundle(event=…, telemetry_summary=…, …) -> ValidationReport|dict|None

validate(artifact_name, payload)[source]

Legacy style: validate payload for artifact_name, raising on failure.

Parameters:

  • artifact_name (str)

  • payload (JsonDict)

Return type:

None

validate_artifact(artifact_name, payload)[source]

Richer per-artifact style: return a validation report (or None) without raising.

Parameters:

  • artifact_name (str)

  • payload (JsonDict)

Return type:

Any

validate_run_bundle(**kwargs)[source]

Richer bundle style: cross-validate a whole run’s artifacts passed as keywords.

Parameters:

kwargs (Any)

Return type:

Any

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.ArtifactStore[source]

Bases: Protocol

Collaborator that persists run artifacts and returns their storage keys.

save(run_id, artifact_name, payload)[source]

Persist a single artifact payload under run_id and return its storage key.

Parameters:

  • run_id (str)

  • artifact_name (str)

  • payload (JsonDict)

Return type:

str

save_list(run_id, artifact_name, payload)[source]

Persist a list-valued artifact payload under run_id and return its storage key.

Parameters:

  • run_id (str)

  • artifact_name (str)

  • payload (List[JsonDict])

Return type:

str

class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.OrchestratorConfig[source]

Tunable configuration for RCAReasoningOrchestrator.

enable_ishikawa[source]

When True, build the optional Ishikawa matrix (requires an ishikawa_evaluator).

persist_intermediate_artifacts[source]

When True, persist per-stage artifacts (not just the final card).

stop_on_validation_error[source]

When True (the default), a required-artifact validation failure — and a genuine failure in an optional stage such as supersession or epistemics — raises; when False, optional-stage failures are recorded in the run’s optional_artifact_failures and logged instead of raising.

run_label[source]

Optional human-readable label stamped into run context.

top_k_candidates, top_k_evidence

Caps on candidates carried forward and evidence snippets retrieved.

enable_semantic_recurrence, semantic_similarity_threshold, near_match_window, fm_id_resolution_threshold, top_k_semantic

Semantic document-recurrence parameters (§4.5).

enable_signal_episode_search, signal_episode_staleness_window_days

Signal-episode retrieval parameters (Step 2d, Phase 1).

enable_cross_pattern_linkage[source]

When True, link candidates to historical signal episodes (Phase 2).

epistemics_policy_version[source]

Policy version forwarded to the Phase C supersession pass, or None.

fast_transient_event_types[source]

Event types that use a fast-transient Allen epsilon (Issue 5).

category_l_score_floor[source]

Organizational (Category L) minimum score floor (Issue 11).

tier_confidence_multipliers[source]

Per-tier (plant/fleet/industry) confidence multipliers (Issue 12).

extra[source]

Free-form overrides (e.g. enable_auto_reentry, auto_reentry_max_attempts) consulted by optional stages.

enable_ishikawa: bool = False[source]
persist_intermediate_artifacts: bool = True[source]
stop_on_validation_error: bool = True[source]
run_label: str | None = None[source]
top_k_candidates: int = 5[source]
top_k_evidence: int = 10[source]
enable_semantic_recurrence: bool = False[source]
semantic_similarity_threshold: float = 0.75[source]
near_match_window: float = 0.1[source]
fm_id_resolution_threshold: float = 0.88[source]
top_k_semantic: int = 5[source]
signal_episode_staleness_window_days: int = 30[source]
enable_cross_pattern_linkage: bool = False[source]
epistemics_policy_version: str | None = None[source]
fast_transient_event_types: Set[str][source]
category_l_score_floor: float = 0.2[source]
tier_confidence_multipliers: Dict[str, float][source]
extra: JsonDict[source]
class src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.RCAReasoningOrchestrator[source]

Deterministic RCA pipeline coordinating the reasoning collaborators.

Wires the injected collaborators (KG context, TSKR scoring, causality, evidence retrieval, synthesis, and the optional Ishikawa evaluator) into a single run() that produces a validated RCA card and its supporting artifacts. Collaborators are supplied as Protocol-typed dependencies so the orchestrator stays agnostic to their concrete implementations; see build_dev_orchestrator() for a ready-to-use development wiring.

validator, artifact_store, kg_context_builder, causality_engine, evidence_retriever, rca_synthesizer

Required collaborators (see the corresponding Protocols).

tskr_temporal_scorer, ishikawa_evaluator

Optional collaborators; when None their stages are skipped.

cap_adapter, cap_config, workflow_dispatch_adapter, cmms_adapter, cmms_context_builder_config, similar_event_adapter, doc_extraction_store, pattern_searcher, cross_pattern_linker, epistemics_classifier

Optional integration adapters enabling downstream/side features.

config[source]

OrchestratorConfig controlling stage toggles and thresholds.

validator: SchemaValidator[source]
artifact_store: ArtifactStore[source]
kg_context_builder: KGContextBuilder[source]
tskr_temporal_scorer: TSKRTemporalScorer | None[source]
causality_engine: CausalityEngine[source]
evidence_retriever: EvidenceRetriever[source]
rca_synthesizer: RCASynthesizer[source]
ishikawa_evaluator: IshikawaEvaluator | None = None[source]
cap_adapter: Any | None = None[source]
cap_config: Any | None = None[source]
workflow_dispatch_adapter: Any | None = None[source]
cmms_adapter: Any | None = None[source]
cmms_context_builder_config: Any | None = None[source]
similar_event_adapter: Any | None = None[source]
doc_extraction_store: Any | None = None[source]
pattern_searcher: Any | None = None[source]
cross_pattern_linker: Any | None = None[source]
epistemics_classifier: Any | None = None[source]
config: OrchestratorConfig[source]
set_similar_event_adapter(adapter)[source]

Inject a SimilarEventAdapter for fleet/industry OE queries.

Parameters:

adapter (Any)

Return type:

None

set_doc_extraction_store(store)[source]

Inject a DocExtractionStore for semantic recurrence queries.

Parameters:

store (Any)

Return type:

None

set_pattern_searcher(searcher)[source]

Inject a PatternSearcher for Step 2d signal episode retrieval.

Parameters:

searcher (Any)

Return type:

None

set_cross_pattern_linker(linker)[source]

Inject a CrossPatternLinker for Phase 2 cross-pattern linkage.

Parameters:

linker (Any)

Return type:

None

set_epistemics_classifier(classifier)[source]

Inject an EpistemicClassifier for Phase A epistemic annotation.

Parameters:

classifier (Any)

Return type:

None

_attach_epistemics_digests(causality_candidates, evidence_bundle, optional_artifact_failures)[source]

Phase D — Build per-candidate EpistemicsDigests and attach in-place.

Runs post-refine_with_evidence() so that observationally_ungrounded (set by Phase C) is already present on each candidate.

A missing epistemics_digest module is treated as an optional capability (debug-logged, skipped). A genuine failure while building the digests re-raises under stop_on_validation_error; otherwise it is recorded in optional_artifact_failures and logged rather than silently swallowed.

Parameters:
Return type:

None

_apply_supersession(evidence_bundle, optional_artifact_failures)[source]

Apply Phase C supersession pass to an evidence bundle (ADR-1, 2026-04-30).

Lazy-imports resolve_supersession so the orchestrator does not hard-depend on the supersession module when Phase C is not active.

A missing supersession module is treated as an optional capability (debug-logged, bundle returned unmodified). A genuine failure during the pass re-raises under stop_on_validation_error; otherwise it is recorded in optional_artifact_failures and logged, and the unmodified bundle is returned rather than swallowing the error silently.

Parameters:
Return type:

JsonDict

run(event, telemetry_summary, operational_context=None, pm_compliance=None, kg_context=None, signal_evidence=None, tskr_patterns=None, causality_candidates=None, evidence_bundle=None, soe_log=None, alarm_log=None, protection_logic_context=None, configuration_change_records=None, environmental_monitoring=None, vendor_supply_chain_records=None, training_records=None, initial_scope_management=None)[source]

Run the full RCA reasoning pipeline for a single event.

Executes the ordered stages — KG context, TSKR temporal scoring, causality generation, evidence retrieval, Phase C supersession, evidence refinement, optional auto re-entry, Phase D epistemics digests, optional Ishikawa evaluation, and synthesis — persisting each artifact and validating it against its schema along the way. Pre-computed artifacts may be supplied to skip the corresponding stage.

Parameters:

  • event (JsonDict) – Target abnormal event. Must carry event_id (or id).

  • telemetry_summary (JsonDict) – Telemetry anomaly summary for the event window.

  • operational_context (Optional[JsonDict]) – Optional operating-state and PM-compliance inputs, or None.

  • pm_compliance (Optional[JsonDict]) – Optional operating-state and PM-compliance inputs, or None.

  • kg_context (Optional[JsonDict]) – Optional pre-computed stage outputs; when provided, the matching stage reuses them instead of recomputing.

  • signal_evidence (Optional[JsonDict]) – Optional pre-computed stage outputs; when provided, the matching stage reuses them instead of recomputing.

  • tskr_patterns (Optional[JsonDict]) – Optional pre-computed stage outputs; when provided, the matching stage reuses them instead of recomputing.

  • causality_candidates (Optional[JsonDict]) – Optional pre-computed stage outputs; when provided, the matching stage reuses them instead of recomputing.

  • evidence_bundle (Optional[JsonDict]) – Optional pre-computed stage outputs; when provided, the matching stage reuses them instead of recomputing.

  • soe_log (Optional[JsonDict]) – Optional sequence-of-events and alarm logs feeding TSKR scoring (including the auto re-entry rebuild).

  • alarm_log (Optional[JsonDict]) – Optional sequence-of-events and alarm logs feeding TSKR scoring (including the auto re-entry rebuild).

  • protection_logic_context (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

  • configuration_change_records (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

  • environmental_monitoring (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

  • vendor_supply_chain_records (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

  • training_records (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

  • initial_scope_management (Optional[JsonDict]) – Optional supplementary evidence artifacts folded in when present.

Returns:

The run bundle: the validated RCA card plus references to every persisted artifact and the run manifest.

Return type:

JsonDict

Raises:

Exception – Under config.stop_on_validation_error (the default), a required-artifact validation failure or a genuine failure in an optional stage (supersession/epistemics) propagates; otherwise optional-stage failures are recorded in optional_artifact_failures.

_build_tskr_patterns(*, event, telemetry_summary, kg_context, operational_context, run_context, signal_evidence=None, alarm_log=None, soe_log=None, pm_compliance=None)[source]
Parameters:
Return type:

JsonDict

_apply_tskr_runtime_overrides()[source]
Return type:

None

_tskr_runtime_snapshot()[source]
Return type:

JsonDict

_build_semantic_recurrence_provenance(tskr_patterns)[source]

Summarise semantic recurrence usage across all TSKR patterns for run_manifest provenance.

Parameters:

tskr_patterns (Optional[JsonDict])

Return type:

JsonDict

_build_signal_evidence(*, run_id, event, telemetry_summary, kg_context)[source]
Parameters:
Return type:

JsonDict

_build_pm_compliance_if_needed(*, event, operational_context, kg_context)[source]
Parameters:
Return type:

Tuple[Optional[JsonDict], JsonDict]

static _extract_pm_export_rows(operational_context)[source]
Parameters:

operational_context (Optional[JsonDict])

Return type:

List[JsonDict]

_resolve_signal_evidence_historian_policy()[source]
Return type:

Dict[str, Any]

static _evaluate_input_guard_policy(*, input_guards, strict_enabled, blocking_flags=None, hard_stop_on_any_flag=False)[source]
Parameters:

  • input_guards (Optional[JsonDict])

  • strict_enabled (bool)

  • blocking_flags (Optional[List[str]])

  • hard_stop_on_any_flag (bool)

Return type:

JsonDict

_enforce_input_guard_policy(*, run_id, run_context, input_guards)[source]
Parameters:
Return type:

None

_should_hard_abort_for_kg_governance(kg_governance)[source]
Parameters:

kg_governance (Optional[JsonDict])

Return type:

bool

_enforce_kg_governance_policy(*, run_id, kg_governance)[source]
Parameters:
Return type:

None

_stage_i_archive_chroma(*, run_id, run_context)[source]
Parameters:
Return type:

JsonDict

_should_hard_abort_for_chroma_archive(chroma_archive)[source]
Parameters:

chroma_archive (Optional[JsonDict])

Return type:

bool

_run_auto_reentry_if_needed(*, run_id, event, telemetry_summary, operational_context, pm_compliance, run_context, kg_context, signal_evidence, tskr_patterns, causality_candidates_pre_refine, causality_candidates, evidence_bundle, protection_logic_context=None, alarm_log=None, soe_log=None, optional_artifact_failures=None)[source]
Parameters:
Return type:

JsonDict

static _cmms_record_to_past_event(*, record, record_type, asset_id)[source]
Parameters:

  • record (JsonDict)

  • record_type (str)

  • asset_id (Optional[str])

Return type:

Optional[JsonDict]

static _classify_past_event_source(event_id)[source]
Parameters:

event_id (Optional[str])

Return type:

str

static _source_doc_id_from_event_id(event_id)[source]

Derive source document ID from a CMMS-injected past event’s event_id.

CMMS past events use format "CMMS::CR::<doc_id>" or "CMMS::WO::<doc_id>". Returns None for KG-native events that have no corresponding extraction record.

Parameters:

event_id (str)

Return type:

Optional[str]

_build_doc_id_semantic_scores(*, kg_context, causality_candidates, query_top_n)[source]

Query DocExtractionStore for top FM candidates; return doc_id → max_similarity map.

Returns None when semantic recurrence is disabled or store is absent. When returned as a dict (possibly empty), _query_plant_past_events switches to renormalized weights and adds the semantic dimension to plant-tier scoring.

Parameters:

  • kg_context (Optional[JsonDict])

  • causality_candidates (Optional[JsonDict])

  • query_top_n (int)

Return type:

Optional[Dict[str, float]]

_enrich_past_events_temporal_metadata(*, kg_context, event)[source]
Post-processing pass over kg_context.past_events (WS1–WS3 for Step 2b):

  1. Tag each event with in_precursor_window (bool) and window_tier (str).

  2. Build per_component_past_events index: {component_id: [event_id, …]}.

  3. Build temporal_search_summary in seed_context.

Parameters:
Return type:

JsonDict

_augment_kg_context_with_cmms_past_events(*, kg_context, cmms_context, event)[source]
Parameters:
Return type:

JsonDict

static _augment_kg_context_with_cmms_documents(*, kg_context, cmms_context)[source]

Route Path-A CMMS records into retrieval scope via kg_context.documents.

Parameters:
Return type:

JsonDict

static _build_canonical_event_graph(*, current_event_id, asset_id, past_events)[source]
Parameters:

  • current_event_id (Optional[str])

  • asset_id (Optional[str])

  • past_events (List[JsonDict])

Return type:

JsonDict

static _build_historical_support_channels(*, past_events, injected_event_ids=None)[source]
Parameters:

  • past_events (List[JsonDict])

  • injected_event_ids (Optional[Set[Optional[str]]])

Return type:

JsonDict

_stage_a_build_run_context(run_id, event, telemetry_summary, operational_context, pm_compliance, input_validation=None, input_guards=None, cmms_context=None, soe_log=None, alarm_log=None, protection_logic_context=None, configuration_change_records=None)[source]
Parameters:
Return type:

JsonDict

static _build_initial_scope_revision_record(*, event, operational_context, pm_compliance=None, cmms_context=None, soe_log=None, alarm_log=None, protection_logic_context=None, configuration_change_records=None, started_at)[source]
Parameters:
Return type:

JsonDict

apply_scope_revision(*, run_id, run_context, revision_input, persist=True)[source]

Apply a scope revision decision to run_context.scope_management.

Accepted revisions become the active scope; deferred/rejected revisions are logged for audit and keep the current active scope version.

Parameters:
Return type:

JsonDict

resolve_expansion_suggestion(*, run_id, run_context, signal_id, decision, rationale=None, persist=True)[source]

Mark a scope-expansion suggestion and, if accepted, update the scope.

This is the canonical bridge between the expansion-suggestion write path (_detect_scope_expansion_signals → expansion_suggestions[]) and the scope-revision lifecycle (apply_scope_revision).

Parameters:

  • signal_id (str) – The signal_id of the suggestion to resolve.

  • decision (str) – One of "accepted", "deferred", or "rejected".

  • rationale (Optional[str]) – Free-text analyst note stored alongside the decision.

  • run_context. (Returns the updated)

  • run_id (str)

  • run_context (JsonDict)

  • persist (bool)

Raises:

ValueError – When signal_id does not match any existing suggestion.

Return type:

JsonDict

static _apply_rank_inversion_attention_flag(rca_card, pre_refine, post_refine)[source]

SE review §3.1 short-term: surface pre- vs post-evidence leader change.

Parameters:
Return type:

None

_summarize_primary_candidate_posture(rca_card, causality_candidates)[source]
Parameters:
Return type:

JsonDict

_validate_and_persist(run_id, artifact_name, payload, *, optional=False, optional_failures=None)[source]

Validate and persist a pipeline artifact.

If optional is True, a validation failure is logged as a warning and appended to optional_failures (if provided) rather than aborting the run. Required artifacts (optional=False) still raise on failure.

Parameters:

  • run_id (str)

  • artifact_name (str)

  • payload (JsonDict)

  • optional (bool)

  • optional_failures (Optional[List[JsonDict]])

Return type:

None

static _rank_candidates_by_composite(cands)[source]
Parameters:

cands (List[JsonDict])

Return type:

Dict[str, int]

_build_scoring_evolution(pre_refine, post_refine)[source]

Compact v1→v2 summary for run_manifest when pre-refine snapshot exists.

Parameters:
Return type:

Optional[List[JsonDict]]

static _build_scope_revision_summary(run_context)[source]
Parameters:

run_context (JsonDict)

Return type:

JsonDict

_stage_g_finalize_manifest(run_context, kg_context, tskr_patterns, causality_candidates, causality_candidates_pre_refine, evidence_bundle, ishikawa_matrix, cmms_context, rca_card, input_validation, output_validation, optional_artifact_failures=None, kg_governance=None, barrier_analysis=None, reentry_execution=None, reentry_hook=None, chroma_archive=None, signal_evidence=None, telemetry_summary=None, soe_log=None, alarm_log=None, protection_logic_context=None, configuration_change_records=None, environmental_monitoring=None, vendor_supply_chain_records=None, training_records=None, event=None, pre_computed_allen_map=None, pre_computed_similar_event_list=None, historical_signal_episodes=None, cross_pattern_evidence=None)[source]
Parameters:
Return type:

JsonDict

static _compute_pipeline_health(*, output_validation, causality_candidates, evidence_bundle, optional_artifact_failures, kg_governance=None, stage_health=None, chroma_archive=None)[source]
Parameters:
Return type:

JsonDict

static _compute_stage_health(*, kg_context, tskr_patterns, causality_candidates, evidence_bundle, ishikawa_matrix, optional_artifact_failures, chroma_archive=None)[source]
Parameters:
Return type:

JsonDict

static _annotate_candidates_with_oe_evidence(*, causality_candidates, similar_event_list)[source]

Inject matched similar events into each candidate’s oe_reinstatement_evidence.

Mutates candidates in-place. Matches on component_id OR failure_mode_id overlap. Only events with confidence_weight ≥ 0.30 are cited.

Parameters:
Return type:

None

static _query_plant_past_events(*, event, kg_context, causality_candidates, top_n=5, doc_id_semantic_scores=None)[source]

Score kg_context.past_events against current event dimensions.

Returns top-N plant-tier SimilarEvent records sorted by confidence_weight descending.

When doc_id_semantic_scores is provided (not None), a semantic similarity dimension is added at weight 0.10 and the other five dimensions are renormalized (× 0.90) so the total remains 1.0. Only CMMS-sourced past events (event_id starting with CMMS::CR:: or CMMS::WO::) carry a source_doc_id that can be looked up in the semantic store; KG-native events receive semantic score 0.0.

Parameters:

  • event (JsonDict)

  • kg_context (Optional[JsonDict])

  • causality_candidates (Optional[JsonDict])

  • top_n (int)

  • doc_id_semantic_scores (Optional[Dict[str, float]])

Return type:

List[JsonDict]

_build_similar_event_list(*, event, kg_context, causality_candidates)[source]

Build the Step 2d similar_event_list artifact.

Plant tier always runs (in-memory, zero latency). Fleet and industry tiers run when self.similar_event_adapter is set.

Parameters:
Return type:

JsonDict

static _build_signal_lessons_learned(*, tskr_patterns, alarm_log=None, soe_log=None, run_context=None, history_score_threshold=0.2)[source]

Build the Step-3.5 signal_lessons_learned artifact from tskr_patterns.

Separates patterns into: - matched_patterns: historical support exists (recurrence_count > 0 OR

history_score >= threshold). Causal/resolution text attached when available from the pattern’s recurrence profile.

  • novel_patterns: novel_pattern == True (no history, no match).

Returns a dict conforming to signal_lessons_learned.json schema.

Parameters:
Return type:

JsonDict

_build_historical_signal_episodes(*, event, telemetry_summary, alarm_log, soe_log)[source]

Build the historical_signal_episodes artifact via PatternSearcher.

Constructs a query IncidentFingerprint from the current event’s alarm, SOE, and anomaly data, then runs PatternSearcher.search() against the pre-built episode index.

Returns a JSON-serializable artifact dict, or None on unrecoverable failure.

Parameters:
Return type:

Optional[JsonDict]

_build_cross_pattern_evidence(*, historical_signal_episodes, causality_candidates, event, kg_context=None)[source]

Build cross_pattern_evidence artifact via CrossPatternLinker.

Converts historical_signal_episodes[“episodes”] dicts back to HistoricalSignalEpisode objects, queries DocExtractionStore for doc extractions, then calls CrossPatternLinker.run().

Returns a JSON-serializable dict or None on unrecoverable failure.

Parameters:
Return type:

Optional[JsonDict]

static _semantic_match_to_historical_doc(sm)[source]

Convert a SemanticMatch to a HistoricalDocExtraction.

SemanticMatch (as currently defined in doc_extraction/store.py) has:

record_id, doc_id, chain_index, identified_effect, assessed_cause, inferred_fm_label, fm_id_candidate, confidence (ConfidenceLevel), cause_is_symptom, similarity_score, fm_resolution_status, doc_type, finding_status, authority_level, epistemic_class, classification_resolution_level, degraded_classification

Fields not present on SemanticMatch are defaulted safely.

Parameters:

sm (Any)

Return type:

Any

static _apply_cross_pattern_attention_flags(rca_card, cross_pattern_evidence, causality_candidates)[source]

Add analyst attention flags derived from cross-pattern evidence (Phase 2).

Parameters:
Return type:

None

static _build_rca_card_cross_pattern_summary(cross_pattern_evidence)[source]

Build rca_card[‘cross_pattern_summary’] block (Phase 3).

Contains narrative text (§4.7 wording), linkage_outcome_distribution, and a per-candidate summary. Never contains or modifies scoring fields.

Parameters:

cross_pattern_evidence (Optional[JsonDict])

Return type:

JsonDict

static _build_allen_relation_map(*, event, telemetry_summary=None, alarm_log=None, soe_log=None, epsilon_hours=0.5, max_soe_nodes=200)[source]

Build a Step-2c Allen-relation map for anomalies, alarm entries, and SOE records.

Returns None when the event interval cannot be determined.

Parameters:

  • event (Optional[JsonDict])

  • telemetry_summary (Optional[JsonDict])

  • alarm_log (Optional[JsonDict])

  • soe_log (Optional[JsonDict])

  • epsilon_hours (float)

  • max_soe_nodes (int)

Return type:

Optional[JsonDict]

static _detect_scope_expansion_signals(*, run_context, allen_relation_map=None, signal_evidence=None, tskr_patterns=None)[source]

Scan pipeline outputs and emit scope-expansion suggestion signals.

Each signal identifies a component or pattern that is either (a) causally implicated but outside the current scope boundary, or (b) flagged as a novel pattern with no historical precedent.

Returns a (possibly empty) list of signal dicts ready to be merged into run_context.scope_management.expansion_suggestions.

Parameters:
Return type:

List[JsonDict]

static _inject_scope_expansion_signals(run_context, signals)[source]

Merge new scope-expansion signals into run_context.scope_management.

Existing signals with the same signal_id are NOT overwritten (idempotent — supports re-runs). Returns the mutated run_context (in-place update on the same dict).

Parameters:
Return type:

JsonDict

static _resolve_approved_scope_boundary(run_context)[source]

Return the approved component-ID boundary from the latest accepted scope revision, or None when the pipeline is in discovery mode.

Returns None when: - active_scope_version == 0 (initial run, no analyst decisions yet). - The latest accepted revision has an empty component_ids list.

The returned frozenset is lower-cased and stripped so it can be compared directly against candidate["component_id"].strip().lower().

Parameters:

run_context (JsonDict)

Return type:

Optional[FrozenSet[str]]

static _apply_scope_boundary_filter(candidates, approved_boundary, scope_version)[source]

Move out-of-scope candidates to candidates['ruled_out'].

Candidates whose component_id is NOT in approved_boundary are soft-filtered: they are appended to ruled_out[] with reason_code = "scope_filtered" and removed from candidates[].

Candidates that carry no component_id are left untouched — we never silently discard candidates for which the boundary check is ambiguous.

Mutates candidates in-place and returns it.

Parameters:

  • candidates (JsonDict)

  • approved_boundary (FrozenSet[str])

  • scope_version (int)

Return type:

JsonDict

static _build_data_coverage_summary(*, kg_context, tskr_patterns, evidence_bundle, causality_candidates, run_context=None, telemetry_summary=None, soe_log=None, alarm_log=None, protection_logic_context=None, configuration_change_records=None, environmental_monitoring=None, vendor_supply_chain_records=None, training_records=None)[source]
Parameters:
Return type:

JsonDict

static _compute_ap913_completeness(*, rca_card, causality_candidates, cmms_context)[source]
Parameters:
Return type:

JsonDict

_compute_review_hooks(rca_card, output_validation, pipeline_health=None, coverage_summary=None, reentry_hook=None, stage_health=None, event_severity=None, scope_expansion_summary=None)[source]
Parameters:
Return type:

JsonDict

_evaluate_stage_policy_hooks(*, stage_health)[source]
Parameters:

stage_health (Optional[JsonDict])

Return type:

JsonDict

static _barrier_summary_for_card(barrier_analysis)[source]
Parameters:

barrier_analysis (JsonDict)

Return type:

JsonDict

_compute_barrier_analysis(*, event, kg_context, causality_candidates, evidence_bundle, ishikawa_matrix)[source]
Parameters:
Return type:

JsonDict

_compute_reentry_hook(*, causality_candidates_pre_refine, causality_candidates, kg_context)[source]
Parameters:
Return type:

JsonDict

_compute_kg_governance(*, event, kg_context)[source]
Parameters:
Return type:

JsonDict

static _extract_snapshot_modified_timestamp(version)[source]
Parameters:

version (Optional[str])

Return type:

Optional[datetime.datetime]

static _apply_kg_governance_attention_flags(rca_card, kg_governance)[source]
Parameters:
Return type:

None

static _apply_recurrence_match_quality_attention_flags(rca_card, tskr_patterns)[source]
Parameters:
Return type:

None

static _apply_near_match_pattern_attention_flags(rca_card, tskr_patterns)[source]

Add attention flag when any pattern is a near-match but not a full semantic match (§4.3).

Parameters:
Return type:

None

static _apply_signal_episode_index_attention_flags(rca_card, historical_signal_episodes)[source]

Add attention flags when the signal episode index is missing or stale (§4.11).

Parameters:
Return type:

None

static _apply_fm_resolution_ambiguity_flags(rca_card, tskr_patterns)[source]

Add attention flag when any TSKR pattern has fm_resolution_ambiguous = True (§4.10).

Parameters:
Return type:

None

static _apply_accelerating_recurrence_attention_flags(rca_card, tskr_patterns)[source]

Add attention flag when any TSKR pattern shows an accelerating recurrence trend.

Parameters:
Return type:

None

static _apply_ishikawa_skip_attention_flag(rca_card, ishikawa_matrix)[source]
Parameters:
Return type:

None

static _apply_signal_evidence_attention_flags(rca_card, signal_evidence)[source]
Parameters:
Return type:

None

static _apply_out_of_boundary_attention_flags(rca_card, kg_context)[source]
Parameters:
Return type:

None

static _apply_metamodel_coverage_attention_flags(rca_card, causality_candidates)[source]
Parameters:
Return type:

None

static _apply_residual_anomaly_gaps(rca_card, allen_relation_map, causality_candidates)[source]

Issue 2 (residual variant) — Tag Allen map nodes as ‘explained’ or ‘residual’.

After the primary hypothesis is selected, each causal-candidate Allen node is classified relative to that hypothesis: - ‘explained’: node’s component_id matches the primary candidate’s component_id. - ‘residual’: node is a causal candidate but on a different component — it may

indicate a co-existing cause, an upstream trigger, or a scope gap.

Residual nodes are written to rca_card[‘unresolved_gaps’] so the analyst has a structured list of unexplained causal signals to investigate.

Nodes with relation ‘follows’ (temporal contradiction) are excluded — they are already handled by the contradiction gate and are not causal residuals.

Parameters:
Return type:

None

static _apply_fast_transient_attention_flags(rca_card, event, allen_relation_map, fast_transient_event_types)[source]

Issue 5 — Flag when Allen epsilon (0.5 h) is larger than the causal sequence duration.

Fires when event_type is a known fast-transient type AND the Allen map contains at least one causal node, meaning temporal interval assignments were computed for signals whose actual ordering may resolve within seconds rather than the 30-minute epsilon window.

Parameters:
Return type:

None

static _apply_pm_corrective_actions(rca_card, pm_compliance)[source]

Architecture §4 — inject deterministic pm_corrective recommended actions.

When the pm_compliance artifact carries scope gaps for the primary hypothesis failure mode and KG PM↔FM linkage is available, a pm_corrective action is appended to rca_card.recommended_actions for each affected component.

Priority rule (architecture §3.6): - maintenance_induced_risk == "high" → priority: "high" (unconditional) - otherwise → priority: "medium"

Guards: - No pm_compliance or no components → no-op. - fmea_pm_linkage_available must be True; without KG linkage the scope

gaps are not reliable enough to generate a structured corrective action.

  • Existing pm_corrective actions for a component are not duplicated.

Parameters:
Return type:

None

static _apply_category_l_floor_attention_flags(rca_card, causality_candidates, cmms_context, category_l_score_floor)[source]

Issue 11 — Flag when no Category L (systemic/organizational) candidate clears the floor.

Fires when: (a) no L-category candidate has composite_score >= category_l_score_floor, AND (b) the event has any recurrence signal (open CRs or unresolved prior events). The flag forces the analyst to actively document why organizational root cause does not apply, rather than letting it silently score low.

Parameters:

  • rca_card (JsonDict)

  • causality_candidates (Optional[JsonDict])

  • cmms_context (Optional[JsonDict])

  • category_l_score_floor (float)

Return type:

None

_build_workflow_dispatch(*, run_context, rca_card, review_hooks)[source]
Parameters:
Return type:

JsonDict

_execute_workflow_dispatch_transport(payload)[source]
Parameters:

payload (JsonDict)

Return type:

JsonDict

_summarize_primary_evidence(rca_card, evidence_bundle)[source]
Parameters:
Return type:

JsonDict

static _build_analyst_checkpoints(*, rca_card, stage_health=None)[source]
Parameters:
Return type:

List[JsonDict]

static _build_replayability_signature(*, causality_candidates, stage_health, decision_posture, uncertainty_summary, review_hooks)[source]
Parameters:
Return type:

JsonDict

static _build_decision_trail(*, causality_candidates, rca_card)[source]
Parameters:
Return type:

List[JsonDict]

_validate_artifact(run_id, artifact_name, payload)[source]

Validate a single artifact while supporting both legacy and richer validators.

Parameters:

  • run_id (str)

  • artifact_name (str)

  • payload (JsonDict)

Return type:

Optional[JsonDict]

_validate_bundle(run_id, stage, *, event=None, telemetry_summary=None, kg_context=None, signal_evidence=None, tskr_patterns=None, causality_candidates=None, evidence_bundle=None, ishikawa_matrix=None, barrier_analysis=None, rca_card=None, operational_context=None, pm_compliance=None, cmms_context=None)[source]

Cross-artifact validation for an RCA run stage.

Parameters:
Return type:

Optional[JsonDict]

_normalize_validation_report(report, fallback_artifact)[source]
Parameters:

  • report (Any)

  • fallback_artifact (str)

Return type:

JsonDict

_raise_if_invalid(report, message)[source]
Parameters:
Return type:

None

apply_override(run_id, rca_card, override_input)[source]

Apply an analyst override to a completed RCA card.

Validates the override, mutates the card to reflect the analyst decision, persists the structured override record, and returns both artifacts.

Parameters:

  • run_id (str) – The RCA run_id that produced rca_card.

  • rca_card (JsonDict) – The RCA card artifact to be overridden.

  • override_input (JsonDict) –

    Dict conforming to the override input schema. At minimum:

    {
    "override_type": "accept",
    "rationale": "...",
    "writeback_decision": "accept",
}

Returns:

(modified_rca_card, override_record)

Return type:

tuple[JsonDict, JsonDict]

Raises:

ValueError – If the override_input fails validation.

export_cap(run_id, rca_card, kg_context, override_record)[source]

Serialize an accepted rca_card into a CAPExportPackage and submit it via the configured CAPAdapter.

Parameters:

  • run_id (str) – RCA run identifier.

  • rca_card (JsonDict) – Analyst-accepted RCA card (writeback_recommendation must be "ready_if_accepted").

  • kg_context (JsonDict) – KG context artifact from the same run (used for FLOC resolution).

  • override_record (JsonDict) – The AnalystOverride record returned by apply_override(); must carry writeback_decision == "accept" and seeds the stable export_id.

Returns:

package — the CAPExportPackage dict. receipt — CAPSubmissionReceipt from the adapter.

Return type:

(package, receipt)

Raises:

  • ValueError – If the override record is not an accepted writeback, or the card has not been approved (wrong writeback_recommendation).

  • RuntimeError – If no CAPAdapter is configured.

build_cmms_context(run_id, event, kg_context)[source]

Fetch live CMMS context (CRs and WOs) for the event and persist the artifact. Also injects narrative text into the evidence store for semantic retrieval in Stage 6.

Called automatically by run() when cmms_adapter is set. Can also be called standalone for incremental/staged pipelines.

Parameters:

  • run_id (str) – RCA run identifier.

  • event (JsonDict) – Raw event dict (provides event_time and asset_id).

  • kg_context (JsonDict) – KG context artifact from Stage 5A (provides last PM date and sister component IDs).

Returns:

cmms_context artifact, or None if no adapter is configured.

Return type:

dict or None

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._serialize_signal_episode(ep)[source]

Convert a HistoricalSignalEpisode to a JSON-serializable dict.

Parameters:

ep (Any)

Return type:

JsonDict

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._summarize_signal_episodes(historical_signal_episodes)[source]

Build the run_manifest artifacts summary for historical_signal_episodes.

Parameters:

historical_signal_episodes (Optional[JsonDict])

Return type:

JsonDict

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._summarize_cross_pattern_evidence(cross_pattern_evidence)[source]

Build the run_manifest artifacts summary for cross_pattern_evidence.

Delegates to build_manifest_cross_pattern_summary() for full detail including precedence_level_distribution, temporal_link_skipped_count, and per-candidate summaries (§4.9).

Parameters:

cross_pattern_evidence (Optional[JsonDict])

Return type:

JsonDict

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._SCORING_FIELDS_PROTECTED: frozenset[source]
src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._build_epistemics_manifest_summary(cross_pattern_evidence, policy_version)[source]

Delegate to build_epistemics_manifest_summary() in doc_extraction/epistemics.py.

Parameters:

  • cross_pattern_evidence (Optional[JsonDict])

  • policy_version (Optional[str])

Return type:

JsonDict

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._assert_cross_pattern_non_intrusion(cross_pattern_evidence, causality_candidates)[source]

Runtime guard: verify cross_pattern_evidence does not contain protected scoring fields.

Logs a warning if any scoring field is detected inside cross_pattern_evidence. Does not raise — cross-pattern failures must never abort the pipeline.

Parameters:

  • cross_pattern_evidence (Optional[JsonDict])

  • causality_candidates (Optional[JsonDict])

Return type:

None

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator._collect_keys(obj, out, depth, max_depth)[source]

Recursively collect dict keys up to max_depth.

Parameters:

  • obj (Any)

  • out (set)

  • depth (int)

  • max_depth (int)

Return type:

None

src.dackar.RCA.orchestrators.rca_reasoning_orchestrator.build_dev_orchestrator(output_dir, client, database=None, evidence_store=None, llm_client=None, schema_dir=None, validator_mode='compat', stop_on_validation_error=True, causality_engine_version='v32', cap_adapter=None, cap_config=None, cmms_adapter=None, cmms_context_builder_config=None)[source]

Build a fully wired RCAReasoningOrchestrator for local development.

Constructs concrete collaborators (KG context builder over client, TSKR scorer, the selected causality engine, a Chroma-backed evidence retriever, the rule-validated synthesizer, and the heuristic Ishikawa evaluator) around a dev-local OrchestratorConfig with Ishikawa and auto re-entry enabled.

Parameters:

  • output_dir (str | pathlib.Path) – Directory the FileArtifactStore writes run artifacts to.

  • client (dackar.knowledge_graph.py2neo.Py2Neo) – Neo4j/Py2Neo client backing the KG context builder.

  • database (Optional[str]) – Optional Neo4j database name, or None for the default.

  • evidence_store – Pre-built evidence store; when None a Chroma-backed store is used.

  • llm_client – LLM client for synthesis; when None a deterministic fallback is used.

  • schema_dir (str | pathlib.Path | None) – Directory of JSON schemas for the validator, or None for the default.

  • validator_mode (str) – Validator style key stored in config.extra (default "compat").

  • stop_on_validation_error (bool) – Passed through to OrchestratorConfig.stop_on_validation_error.

  • causality_engine_version (str) – Which causality engine to wire (default "v32").

  • cap_adapter – Optional CAP / CMMS integration adapters and their configs.

  • cap_config – Optional CAP / CMMS integration adapters and their configs.

  • cmms_adapter – Optional CAP / CMMS integration adapters and their configs.

  • cmms_context_builder_config – Optional CAP / CMMS integration adapters and their configs.

Returns:

A ready-to-run orchestrator instance.

Return type:

RCAReasoningOrchestrator