Root Cause Analysis (RCA)¶

The dackar.RCA subsystem implements an AI-enhanced Root Cause Analysis workflow. Starting from unstructured event narratives, maintenance records and a domain knowledge graph, it extracts causal statements, retrieves supporting evidence, ranks candidate root causes with a rule-based causality engine, and synthesizes a validated, schema-conformant RCA artifact.

Note

A complete, auto-generated API reference for every dackar.RCA module is produced by autoapi (see the API Reference section of the sidebar). This page is a narrative overview; the full, code-grounded architecture — the exact stage order, the collaborator protocols and their implementations, the artifact/schema model and the configuration knobs — is maintained in src/dackar/RCA/ARCHITECTURE.md.

Architecture overview¶

A run is driven end to end by one object, RCAReasoningOrchestrator (orchestrators/rca_reasoning_orchestrator.py), which calls a set of injected collaborators in a fixed order and validates/persists each artifact as it goes. The main packages under src/dackar/RCA:

Package	Responsibility
`orchestrators`	The reasoning orchestrator that drives the end-to-end run, the rule-based causality engines, and the knowledge-graph context builder (`kg_context_builder.py`).
`schemas`	The Draft-7 JSON schemas, one per artifact type.
`validation`	Schema and cross-artifact semantic validation of every artifact.
`synthesis`	Synthesize the final RCA card (LLM-backed, with a deterministic fallback).
`signal_evidence` / `storage`	Signal-evidence construction and the (Chroma-backed) evidence store.
`ner` / `doc_extraction` / `doc_parsers`	Entity and causal-condition extraction, and document parsing. Causal extraction lives in `ner/causal_condition_adapter.py`; the top-level `dackar.causal` package provides the spaCy causal components.
`pm_compliance`	Preventive-maintenance compliance artifact (feeds Stage D governance).
`cmms_integration`, `cap_integration`, `cross_pattern`, `log_pattern_recognition`, `equipment_similarity`, `adapters`	Optional, pluggable integration modules. Each is gated on an injected adapter and degrades gracefully (its stage is skipped) when absent.
`viz`	A standalone Streamlit viewer (`viz/app.py`) that loads and displays artifact JSON produced by a run. It is not a Python package and does not call the orchestrator.

Note

There is no kg package and no causal package under src/dackar/RCA. KG-context building is in orchestrators and causal extraction is in ner plus the top-level dackar.causal package.

Reasoning orchestrator¶

orchestrators/rca_reasoning_orchestrator.py runs the pipeline in a fixed sequence through RCAReasoningOrchestrator.run():

Run context — validate inputs, build input guards, establish the run.
KG context — build (or reuse) the event-neighborhood knowledge-graph context, with optional live-CMMS augmentation.
Signal evidence then TSKR temporal patterns — build the signal-evidence view and score temporal patterns.
Causality candidates — the rule-based engine generates and ranks candidate causes over a 12-category (A–L) metamodel, then re-scores them against the retrieved evidence.
Evidence bundle — retrieve supporting/refuting evidence and apply supersession.
Optional stages — auto re-entry, Ishikawa evaluation, barrier analysis, similar-event / cross-pattern linkage, and epistemics digests.
Synthesis — produce the rca_card, then output validation.
Archive and manifest — archive to Chroma (optional) and finalize the run manifest.

The code labels progress two ways that are easy to confuse: a lettered stage_health map (stage_b_kg_context … stage_g_structuring) and a numbered analyst-checkpoint list (0 … 6). See ARCHITECTURE.md §3 for the exact order, methods and line anchors.

Fixture-only runs (no live Neo4j, Chroma or LLM required) are supported through the shared helpers used by the test suite, which makes the pipeline reproducible for regression testing.

Testing¶

The RCA test suites live under the repository-level tests directory:

tests/RCA/unit_tests/ — unit and component tests.
tests/RCA/scenario/ — show-and-tell scenarios, fixtures and shared helpers (run_helpers) used to drive fixture-only end-to-end runs.

Run them from the repository root (pytest.ini sets pythonpath = src):

python -m pytest tests/RCA/unit_tests -m "not slow" -q

Design documentation¶

The canonical, code-grounded architecture is src/dackar/RCA/ARCHITECTURE.md.

The dated working notes that accompanied the implementation — architecture assessments, causal-soundness reviews and the PM-compliance write-up — are kept alongside the code under src/dackar/RCA/devNotes (organized by date). They are a historical record and are not maintained in lockstep with the code; where they disagree with ARCHITECTURE.md or the source, the code wins.