.. _auto_find_root_cause:

*FIND ROOT CAUSE*
=================

Applies a KPI Library set against already-extracted Responses (from a simulation's stored responses, a Response Template applied to a simulation, or an inline dataset) and emits Diagnoses keyed to each KPI Target that matched a Response. Source-agnostic: the worker doesn't care whether responses came from a binout, a physical-test DAQ, a BMS scatter file, or upstream workflow output — extraction is upstream. Outputs the Diagnosis list, the Responses actually evaluated (for audit), and a model-level summary log.

When to use
-----------

Tagged: ``rca``, ``root_cause``, ``diagnoses``, ``kpi``, ``kpi_library``, ``responses``, ``template``, ``dataset``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Simulation
     - source_sim_id
     - remote_lookup
     - —
     - 
     - Source: simulation id. Alone: loads all stored responses on the sim. With template_id: filters to that template's response set on that sim.
   * - Response Template
     - template_id
     - remote_lookup
     - —
     - 
     - Optional. Used together with source_sim_id to filter the sim's responses to those produced by this Response Template.
   * - Inline responses (JSON)
     - dataset
     - text
     - —
     - 
     - Inline { "responses": [ { name, value, unit, type, channel_group?, meta? }, ... ] } payload. Used for workflow composition. Pick exactly one of source_sim_id or dataset.
   * - KPI Library set
     - kpis_id
     - remote_lookup
     - —
     - 
     - KPI Library set to evaluate. Pick from the existing platform library (Admin → KPI Library).
   * - Rule filter
     - rule_filter
     - text
     - —
     - 
     - Restrict evaluated targets by glob ('head_*') or domain ('domain=automotive'). Comma-separated filters AND-combine.
   * - Enable internal derivation
     - enable_internal
     - string
     - 1
     - 
     - When 1 (default), targets whose metric isn't found in dataset/template responses are computed internally from the sim's raw time-history via the operator packs.
   * - Internal operator packs
     - internal_packs
     - text
     - time_series,crash_structure
     - 
     - Comma-separated list of operator pack ids to enable for internal derivation. Available: time_series, crash_structure. (crash_occupant + bms ship in Phase D.3/D.4.)
   * - Channel map (JSON)
     - channel_map
     - text
     - —
     - 
     - Optional JSON object mapping canonical roles to per-sim entity ids, e.g. {"driver.head":"90001","front_rail":"5"}. Used when KPI targets reference roles instead of concrete entities. Auto-discovered if absent (planned).

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Diagnoses
     - diagnoses
     - dataset
     - { items: [{ id, rule_id, rule_label, severity ('info'/'warn'/'crit'), label, response_name, response_id, value, unit, threshold_op, threshold_value, breach, prescription, evidence }], severity_counts, hit_count }
   * - Responses
     - responses
     - dataset
     - { count, preview: first 5 responses evaluated }. Full set is in memory; surfaced for audit + downstream composition.
   * - Provenance
     - provenance
     - dataset
     - { kpi_set_id, kpi_set_name, kpi_set_regulator, kpi_set_revision, source_kind, source_ref, rule_filter, elapsed_ms, response_count, target_count, matched_count, unmatched_count }
   * - Summary log
     - summary_log
     - dataset
     - Model-level observations: severity counts, critical labels, unmatched targets, etc.

Disciplines
-----------

- cae.postprocessing.diagnosis
- cae.postprocessing.response
- engineering.crash.injury

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>find_root_cause</code>. Schema hash: <code>a1a309096022</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>