Granite Lifeline

Time	Coolant [°C]	RPM	Speed	MAP [kPa]	Fault Code
07:16:31.257	31	0	0	96.0	does not exist
07:49:20.958	91	1718	102	140.0	does not exist

Cooling System

HighRisk level

Failure Prediction This component has already reached the High-risk threshold based on the current pattern. Arrange a professional inspection soon.

This is a risk-pattern estimate, not a confirmed mechanical fault.

Risk Trend

08-0208-0308-0408-0508-07

Last updated: 2017-08-02 05:40

End-to-end integration · inputs, checks and failure paths

ORCHESTRATION · DASHBOARD controls the sequence and checks that each handoff is available. Each receiving layer then validates its own input contract before processing. The layers do not call one another directly.

DASHBOARD UPLOAD

1 raw CSV, or ≥5 dated CSVs
Original filenames retained

→

DATA INPUT GATE

Non-empty; valid KIT filename
11 required columns; minimum rows
History: each file valid, names unique, date ordered

PASS →FAIL →

DATA RUNS

Single file or one joint history run
Trip boundaries preserved

STOP

Specific upload error
No downstream run

DATA OUTPUT · ONE PAIR

production_features.csv · 46-column sample evidence
proxy_decisions.csv · 21-column rule decisions

→

MODEL INPUT GATE

Feature file exists; proxy file exists when reported
Feature schema, calibration and 1 Hz timing
Usable ≥700-row segment; proxy schema valid

PASS →FAIL →

MODEL RUNS

One isolated batch subprocess
Writes one model_output.json

STOP

Non-zero ERROR: or timeout
Dashboard shows failure

MODEL OUTPUT · ONE JSON

summary · highest primary-risk window
windows · every eligible window

→

REPORT INPUT GATE

Output file exists and parses as JSON
Select affected components
Pydantic checks fields, values and relationships

PASS →FAIL →

REPORT RUNS

One report per affected component
Each section validated before release

STOP

Invalid Model output
No report generation

REPORT OUTPUT · IN MEMORY

Model evidence retained
What was observed
Possible causes
Recommended actions
Component-keyed result + source label

→

DASHBOARD ACCEPTANCE GATE

At least one affected component
Detect all-empty Report fallback
Only accepted result updates session state

PASS →FAIL →

DISPLAY

Overview, detail and risk history
Key signals, report and export

STOP

Report unavailable card
Previous state not overwritten

IF ANY BOUNDARY CHECK FAILS · Processing stops before the next layer and the Dashboard shows that the upload could not be completed.

UPLOADOriginal KIT CSV file

DATAClean signals, features and rule evidence

MODELBatch anomaly and component risk JSON

REPORTValidated report for each affected component

DASHBOARDOverview, detail evidence and export

TEAMWORK EVIDENCE

Teamwork across four connected components

IBM supplied the project direction. The team converted it into Sprint work, reviewed code through GitHub and used regular records and updates to keep parallel development aligned.

IBM brief and MoSCoW priorities

MustAnalyse temperature, RPM and load data; train a model to predict component failure; use Granite to explain predictions.

ShouldVisualise failure risk over time.

CouldSimulate different driving conditions.

Won'tInclude real-time in-vehicle integration.

From the delivery plan to a completed Jira task

Project Gantt chart showing seven Sprints and five major Epics — PROJECT GANTT · SEVEN SPRINTS AND THE PLANNED DURATION OF EACH MAJOR EPIC

Jira task GL-129 with four completed subtasks — SPRINT 4 EVIDENCE · GL-129 CONNECTED THE FIRST THREE AVAILABLE MODEL OUTPUTS TO THE DASHBOARD; THE FINAL PIPELINE LATER SUPPORTED FIVE TYPES

How the work was organised

EPICA major functional area, such as System Integration & Pipeline.

→

USER STORY OR TASKA user-facing outcome or a defined piece of engineering work, such as GL-129.

→

SUBTASKA smaller action required to complete its parent. GL-129 contained GL-130 to GL-133.

SPRINTA two-week period containing selected Stories, Tasks and Subtasks. It is a timebox, not another level in the hierarchy.

Sprint meetings recorded plans, progress and improvements

Confluence folders containing Sprint planning, stand-up, progress update and viva dry-run records — CONFLUENCE RECORD INDEX · MEETING DOCUMENTS ORGANISED BY SPRINT

PLANNINGRecorded each group's intended work and the next action items.

STAND-UPRecorded completed work, current work and blockers for each member.

RETROSPECTIVERecorded what worked and what the team needed to change in the next Sprint.

S3 PLANNINGPlans, cross-layer interface work and action itemsOpen evidence

Sprint 3 planning record page 1 — PAGE 1 OF 1

S5.1 STAND-UPCompleted work, work in progress and blockers by team memberOpen evidence

Sprint 5 week 1 stand-up record page 1 — PAGE 1 OF 5

Sprint 5 week 1 stand-up record page 2 — PAGE 2 OF 5

Sprint 5 week 1 stand-up record page 3 — PAGE 3 OF 5

Sprint 5 week 1 stand-up record page 4 — PAGE 4 OF 5

Sprint 5 week 1 stand-up record page 5 — PAGE 5 OF 5

S3 RETROSPECTIVECommunication, documentation and interface improvementsOpen evidence

Sprint 3 retrospective record page 1 — PAGE 1 OF 1

Jira automation kept task and code-review status in step

Jira automation that creates a GitHub branch when a Task or Story moves to In Progress — PROJECT EVIDENCE · JIRA AUTOMATION FOR THE IN PROGRESS TRANSITION

IN PROGRESSCreate a named GitHub branch from develop.

IN REVIEWOpening a pull request updates the Jira work item.

DONEMerging the approved pull request completes the Jira workflow.

The automation made progress easier to follow. Acceptance criteria, review and tests still determined whether the work was complete.

The CI workflow checked each proposed code change

TRIGGERPush or pull requestdevelop or main

→

ENVIRONMENTUbuntu and Python 3.11Checkout code, restore the uv cache and install uv.lock.

→

STATIC CHECKSpy_compile then flake8Find syntax errors, style problems and common code issues.

→

BLOCKING TESTSpytest -m "not model_download"Run the core suite without external model downloads.

→

EXTERNAL TESTSpytest -m model_downloadCheck the real Hugging Face download path. Failure warns but does not block unrelated work.

WHY THE LAST STEP IS SEPARATENetwork availability and a cold model cache can fail independently of the repository code, so the workflow records this result without failing every pull request.

Regular updates made cross-layer progress visible

Discord Sprint 2 project and team update sent to IBM — PROJECT EVIDENCE · TEAM, CONTRACT AND CI UPDATE TO IBM, 22 JUNE 2026

SUPERVISORMeeting approximately once a week.

IBMProgress update approximately once per Sprint.

TEAMJira, Discord and meeting records used between scheduled meetings.

Shared interfaces allowed each group to develop against the same field definitions before the complete pipeline was connected.

01 · DATA LAYER

Raw recording → governed evidence

DATA LAYER TEAM

Upload intake and run isolation

Reject recordings that cannot satisfy the Data or Model contract before expensive processing begins, then preserve every accepted run as a traceable set of artefacts.

6 REJECT CODES

User-uploaded KIT CSVOriginal filename carries the recording date.

Pre-run intake checksFilename, readable CSV, required columns, ≥700 rows, ≥700 s duration; multi-file uploads also reject duplicate file names.

Isolated processingA temporary copy is processed; the original file is never touched; each run gets its own run ID.

Post-cleaning acceptanceLongest cleaned segment must reach ≥700 contiguous rows, or no_usable_segment is raised (run kept for inspection).

Intake rejection code	Triggered when
`bad_filename`	The recording date cannot be recovered from the file name.
`missing_columns`	The CSV does not carry the required KIT source columns.
`too_few_rows`	Fewer than 700 raw rows, or under 700 seconds of recording.
`unreadable_csv`	The file cannot be parsed as CSV at all.
`duplicate_upload_filenames`	A multi-file upload history repeats the same KIT file name.

These two “700”s are both intake-time, but they check different things: 700 raw rows is a cheap row-count screen, and 700 seconds checks real elapsed time separately, because KIT’s raw sampling rate is uneven (roughly 6–12 Hz), so rows do not equal seconds. A third “700” — ≥700 contiguous cleaned rows — is not an intake check at all: it can only be known after cleaning has produced segment_id, so it is judged after the pipeline runs (see the last flow step above), not before.

CODE PATHdata_layer/pipeline_data/upload_contract.py :: validate_upload_csv(), validate_usable_segment()data_layer/run_pipeline.py :: run_data_pipeline_for_upload(), run_data_pipeline_for_uploads()data_layer/pipeline_data/paths.py :: RunLayout117 selected Data contract tests passed in 9.46s

Continuity-aware cleaning

Turn irregular OBD-II recordings into 1 Hz evidence without inventing continuity across missing time, invalid samples or recording boundaries.

249,694 ROWS · 81→118

Raw source identityFilename date + in-file time; stable chronological file order.

UTC timelineLocalise in Europe/Berlin, sort timestamps and keep the last duplicate.

Hard-invalid maskingWhole-file pass: values outside physical bounds are set to missing, before any segment split.

Trip → segmentsA gap greater than 3 seconds on the masked timeline starts a new continuous segment.

Segment-safe 1 Hz gridResample each segment independently; fill only complete gaps of at most 2 seconds.

Rule	Threshold / behaviour
New segment	Raw timestamp gap >3 s starts a new `segment_id`.
Short-gap fill	Gaps of ≤2 s are filled on the 1 Hz grid; longer gaps are left missing, never bridged.
Hard-invalid values	Outside physical bounds → set to missing, but flagged (`had_hard_invalid_source`).
Suspicious values	Physically possible but unusual → kept as-is, flagged (`is_suspicious`); never silently rewritten.
Cross-field checks	Flags contradictions, e.g. RPM=0 with speed>0, MAF=0 with RPM>0, sub-zero coolant in warm ambient.

Identity	Breaks when	Granularity
`trip_id`	Never breaks within one source file.	Coarsest — file-level provenance.
`segment_id`	Raw timestamp gap >3 s — a genuine recording break.	Medium — “was recording paused or restarted”.
`continuity_block_id`	Not a D1 output — computed on demand by downstream feature-engineering (D3) and proxy (D4) scripts, each with its own required-valid-signal set. Breaks whenever any row in that set fails the quality-valid mask (missing / imputed / suspicious / hard-invalid) or the row/timestamp is not perfectly consecutive — on both sides, even with no time gap at all.	Finest, but caller-dependent — no single block count for the whole corpus.

Same segment ≠ same block: a segment only breaks on a genuine recording gap (>3 s). A single bad or flagged reading inside an otherwise continuous segment still splits the block on both sides of it — so a 700-row segment can still fail to contain any 700-row block. Rolling features and Model windows are gated on continuity_block_id, the strictest of the three identities.

249,694cleaned rows, full corpus

81 → 118trips → segments

>3s / ≤2sbreak / fill thresholds

12 / 12continuity tests passed

CODE PATHdata_layer/data_cleaning/src/cleaning_core.pydata_layer/pipeline_data/continuity.py :: build_quality_valid_mask(), build_continuity_blocks()data_layer/data_cleaning/src/cleaning_config.yaml (v3.0)

Hierarchical operating-condition stratification

Give every 1 Hz sample physically meaningful context, so normal warm-up, idle and high-load behaviour are not mistaken for faults—and real deviations are not hidden by global averages.

77.85% POST-WARMUP

Segment-bounded signalsSpeed smoothing, differencing and cumulative MAF reset at every segment.

Thermal stateengine_off / warmup / post_warmup / unknown.

Kinematic child stateidle / high_load / acceleration / deceleration / steady_driving.

Auditable contextCombined state + confidence + explicit missing-field flags.

Thermal state (parent)	Determined by
`engine_off`	RPM <50.
`warmup`	Engine on, post-warmup condition not yet met.
`post_warmup`	Engine on, coolant ≥75°C, plus hot-idle RPM <850, cumulative intake air ≥1,500 g, or IAT−ambient >8°C.
`unknown`	RPM missing; forward-filled from the prior state within the same segment.

Child state (kinematic)	Determined by
`idle`	Speed <1 km/h and \|acceleration\| <0.15 m/s².
`high_load`	Moving and VSP ≥20 kW/t or acceleration ≥1.2 m/s².
`acceleration`	Moving, acceleration ≥0.15 m/s², not already high load.
`deceleration`	Moving, acceleration ≤−0.15 m/s², not already high load or accelerating.
`steady_driving`	Moving, none of the above conditions met.

Context labels, not fault labels: thermal and child state only describe what the vehicle was doing, not whether anything was wrong. Precedence is Idle → High Load → Acceleration → Deceleration → Steady Driving, and fragments shorter than 3 s are cleaned up within their segment. post_warmup itself is inferred, not measured: the dataset has no catalyst-temperature channel, so coolant ≥75°C plus one corroborating signal (hot idle, cumulative intake air, or IAT−ambient heat soak) stands in for true catalyst warm-up.

77.85%post-warmup, 194,394 / 249,694 rows

35.39%steady driving, largest child state

99.99%high confidence, 249,669 rows

3 ssmoothing + fragment cleanup window

CODE PATH

data_layer/operating_condition_statistics/src/operating_condition_analysis.py :: add_operating_conditions(), build_counts(), build_rules()

Outputs: operating_condition_enriched.csv, operating_condition_counts_overall.csv, operating_condition_signal_summary.csv, operating_condition_rules.csv

docs/adr/102-operating-condition-stratification.md

Frozen feature contract and production assembly

Convert governed 1 Hz evidence into one deterministic, versioned Data–Model handoff whose fields, order, ownership and provenance cannot drift silently.

46 COLUMNS · FROZEN

00 · Contract gateValidate authoritative inputs, keys, quality tables and frozen manifest.

10 / 20 / 30 / 40Build atomic, engine-start, window and calibrated feature families separately.

41 · Strict assemblerOne-to-one joins on identical sample keys; no extra columns and no imputation.

Production handoff46 ordered columns plus an adjacent checksum-bearing stage manifest.

Layer	What it computes	Why kept separate
B1a · Atomic (8)	Per-row deterministic values: segment gap, engine state, thermal deltas, pedal/RPM slopes.	Cheapest tier — no calibration input, no cross-row window state.
B1b · Calibrated residuals (2)	Deviation from an offline physics baseline: speed-density MAF residual, pedal-mapping residual.	Depends on the frozen calibration registry — a separately audited failure surface.
B2 · Engine-start context (6)	Facts about the most recent engine start: episode ID, elapsed time, starting ECT/AAT/IAT.	Needs its own episode-boundary logic, distinct from per-row or windowed builders.
B3 · Window features (8)	60–180 s rolling aggregates: MAF integral, ECT rate, intake stability, rolling std-devs, MAP range.	Gated on continuity blocks — a window can never be built across an invalid or discontinuous stretch.

Handoff to Model: Script 41 assembles exactly 46 ordered columns — 4 sample keys + 16 context fields + 24 engineered features (8+2+6+8 above) + 2 provenance fields — checked against a frozen manifest (feature_schema.v1, v1.2.0). Unexpected columns are rejected, key order and dtypes are validated, and the assembler performs no imputation: missingness stays visible rather than being silently filled. A new feature requires an explicit contract/version change, so it can never appear silently in the production CSV.

CODE PATHdata_layer/contracts/feature_manifest.v1.json

data_layer/feature_engineering/src/00_input_contract_validator.py, 10_atomic_feature_builder.py, 20_engine_start_context_builder.py, 30_window_feature_builder.py, 40_calibrated_feature_builder.py, 41_production_feature_assembler.py

Outputs: features/41_production/production_features.csv, production_features_manifest.json

Executable proxy failure evidence

Screen physically plausible fault symptoms into a deliberately small set of runtime checks, preserving the difference between a verdict, supporting evidence, a pending precursor and a design that was never executable.

14 CHECKS / 5 FAMILIES

DTC candidate catalogueSAE J2012 codes collected before assuming any are executable.

Standards-side screeningFiltered on domain visibility, ownership, signal coverage, reconstructability and 1 Hz sampling observability.

Observability + baseline censusRequires an enable window plus stable baseline evidence for a margin/persistence rule.

19 Jul freeze · ADR 10314 executable sub-checks across 5 families frozen; everything else stays research-only.

Stage	What it does
50 · Rule state	Checks each sub-check's guards/thresholds against the frozen calibration baseline; produces per-row eligibility and raw rule evidence.
60 · Event evidence	Detects driver-demand pedal-step events, for the one sub-check (5-S1) that needs a transient trigger.
61 · Duration evidence	Builds bounded persistence episodes from Stage 50's rule state, for every sub-check whose verdict depends on a sustained condition.
70 · Decision	Reads only Stages 50/60/61 — never the raw feature table again. Assigns `decision_role` (verdict / pending_precursor / support / arbitration_evidence) and `result_state` (pass / triggered / not_evaluable / pending), attributes a candidate DTC and whether it is actually emitted, and records confidence, margin and calibration version. Writes `proxy_decisions.csv` — the artefact handed to the Model layer.

Role ≠ result ≠ DTC emission: a candidate DTC label only identifies the diagnostic family — only a permitted verdict row with dtc_emitted=true actually authorises a code, and support/arbitration rows always carry dtc_emitted=false. not_evaluable means a live check lacked a valid opportunity, not that a rejected design ran. These are controlled proxy-screening decisions, not confirmed real faults — ADR 201 keeps the Model layer from training on them as ground truth.

CODE PATH

data_layer/proxy_failure/src/50_rule_state_builder.py, 60_event_evidence_builder.py, 61_duration_evidence_builder.py, 70_proxy_decision_builder.py

proxy_failure_definition.md (authoritative) · proxy_support.md (research companion) · calibration_registry.v1.json (frozen baseline)

Outputs: proxy/70_decisions/proxy_decisions.csv, proxy_decision_manifest.jsondocs/adr/103-proxy-screening-and-theoretical-basis.md

Offline calibration and governed residual features

Keep the baseline reference fixed: user uploads may apply approved transformations, but can never redefine “normal” by fitting on the vehicle currently being diagnosed.

48/48 PASS · 66-TRIP COHORT

Approved baseline cohortOffline/admin evidence—not the current user upload.

90 · Reproduction auditRefit approved methods only to compare against frozen values.

Checksum-bound releaseRegistry + feature contract + evidence identities frozen together.

40 · Online applicationRead-only transforms produce two residual features; no fit path exists.

Invariant	What it guarantees
Offline-only fitting	Online scripts 00–70 forbid fitting, quantile search and threshold selection (`online_fit_paths_forbidden=true`; Script 40 exposes no `fit` function) — a slowly failing upload can never teach the system its own decline is "normal".
Frozen 66-trip reference cohort	Every proxy family (cooling, MAF, MAP, pedal, intake temperature) calibrates against the same fixed `cohort_trip_count: 66` cohort — no family cherry-picks its own subset.
SHA-256 checksum binding	Registry (`calibration_registry.v1.json`) and feature-manifest checksums are embedded and verified before online use; Script 40 fails closed on any drift.
Null on invalid input	Quality-invalid required inputs yield null residuals rather than a fabricated estimate.

What 48/48 PASS proves — and what it doesn't: the audit (recalibrate_20260723) proves the frozen release can be reproduced from its declared evidence within tolerance. It does not prove the calibration generalises to every make, engine or sensor package — broader external-vehicle validation remains future work.

CODE PATHdata_layer/calibration/calibration_registry.v1.json, calibration_registry.v1.manifest.jsondata_layer/feature_engineering/src/90_calibration_registry_builder.py :: run_calibration_audit()

data_layer/feature_engineering/src/40_calibrated_feature_builder.py :: _validate_release_bundle(), build_calibrated_features()

calibration_audit_manifest.json — 48 PASS / 0 FAIL

Graded synthetic fault-injection validation

Challenge every executable proxy end to end with paired, single-signal interventions—testing severity response, independent contexts and diagnostic semantics without claiming synthetic detection is field recall.

14 / 14 ACCEPTED

Eligible baseline windowOriginal state, quality, confidence and continuity guards already satisfied.

Target signal onlyMild, moderate and strong intervention; guard signals remain unchanged.

Recompute dependenciesAffected features rebuilt; frozen stages 50/60/61/70 rerun unchanged.

Paired adjudicationCompare baseline/injected result, DTC identity, role and emission semantics.

Design factor	Value / rule
Severities	3 ordered levels (mild / moderate / strong); detection rate must not decrease as severity rises.
Independent trips per severity	3, so one favourable trip can't be counted as independent evidence.
Scoped observations	14 cases × 3 severities × 3 trips = 126.
Unique injected runs	42 — one copied run hosts all 3 severity points for a case/trip.
Acceptance rule	Per case curve, not per observation: non-decreasing detection rate, ≥0.8 at strongest severity, and the equivalent baseline must not already be positive.

87/126 vs 14/14 is not a contradiction: 87 of the 126 individual observations hit their expected outcome — mild/boundary injections are intentionally allowed not to trigger (e.g. 0/3 → 2/3 → 3/3 across severities still counts as coherent). The registered unit of acceptance is the case curve, not the single observation: all 14 curves passed and every strongest-severity point reached 3/3. Validated: implementation reachability, monotonic severity response, repeatability. Not validated: real-world prevalence, physical causation or workshop diagnostic accuracy.

126scoped observations

42unique injected runs

14 / 14case curves accepted

148 testsfull Data-layer verification

CODE PATHdata_layer/fault_injection/configs/fault_injection_cases.v1.jsondata_layer/fault_injection/src/run_fault_injection.pyOutputs: fault_injection_summary_20260903T051231Z.csv/.jsontest_fault_injection_campaign.py

Two deliveries, one traceable Data handoff

Hand Model both sample-grain forecasting evidence and decision-grain proxy evidence from the same isolated run, while preserving their different meanings, consumers and claim boundaries.

2 DELIVERIES · SAME RUN

One RunLayoutCleaning through stage 70 shares run ID, paths and source identity.

Sample-grain delivery46-column production_features.csv for forecasting and context.

Decision-grain deliveryproxy_decisions.csv for governed verdict forwarding and evaluation.

Absolute handoff pathsSummary exposes both artefacts plus ordered stage manifests.

Boundary question	A · production_features.csv	B · proxy_decisions.csv
Upstream input	Stage 41 reads only the four feature-family tables (10/20/30/40), joined on identical sample keys.	Stage 70 reads only Stages 50/60/61's evidence outputs plus the frozen calibration registry — never the raw feature table again.
Format	CSV, sample grain — one row per 1 Hz sample, exact 46 ordered columns (`DataLayerOutput` contract).	CSV, decision grain — one row per sub-check × evaluation unit.
Required fields	Every column is a required key — nullable fields stay as required keys rather than being dropped.	`trip_id`, `segment_id` (nullable), evidence start/end timestamps, `decision_role`, `result_state`, `dtc_candidate_label`, `dtc_emitted`, margin, confidence, calibration version.
Can Data redefine field meaning here?	No — Stage 41 only joins already-computed fields verbatim, with strict type/order checks.	No — Stage 70 only routes existing evidence into a decision; it doesn't redefine what the evidence means.
Invalid / missing input	No imputation at the interface — missingness stays visible through explicit null semantics rather than being silently filled.	`not_evaluable` when a live check lacks a valid opportunity — never forced into `pass` or `triggered`.
What Model (next layer) receives	512-context / 96-forecast windows and residual scoring — measurement/features, not a diagnostic conclusion.	Governed verdict forwarding and evaluation/filtering — must not be merged column-by-column into the 46-column feature table (different cardinality).
Tests covering this boundary	Field contract: valid/optional/nullable fields, missing required field, wrong type.	Decision semantics: role/result/DTC attribution. Shared with A: both deliveries come from one run (default stops at 41, proxy stages opt-in, all stages share one run).

CODE PATHdata_layer/run_pipeline.py :: run_data_pipeline(), run_data_pipeline_for_upload()shared/interface_models.py :: DataLayerOutput

tests/test_interface.py, data_layer/tests/proxy_test/test_70_proxy_decisions.py, data_layer/tests/pipeline_data_test/test_public_pipeline_contract.py

docs/INTERFACE.md v1.3–v1.4

02 · MODEL LAYER

Forecast evidence → bounded risk

MODEL PIPELINE · VIVA BACKUP

Input checks and forecast windows

The model only forecasts when the input data is complete, valid and continuous.

46 COLUMNS · 512s INPUT · 96s FORECAST

512 secondsPast data from six signals at 1 Hz.

96 secondsForecast for the same six signals.

INPUT MUST PASS

Required fields must be present and numeric.
At least 700 continuous rows from one driving section.
Correct sampling rate, file format and calibration version.

INVALID DATA STOPS THE FORECAST

Impossible values are repaired when safe or rejected.
More than 5% invalid values stops the run.
Separate driving sections are never joined.

The forecast uses 608 rows: 512 for the past and 96 for the future. The 700-row requirement leaves room to find one complete window. After checks, 61 of 118 sections across 59 trips were usable.

CODE PATHmodel_layer/ttm-related/src/model/input_validation.pymodel_layer/ttm-related/src/model/kit_residual_detector.py::select_segment()model_layer/ttm-related/src/model/prepare_finetune_split.py

Forecasting normal behaviour without fault labels

TTM learns normal driving patterns without using fault labels.

NORMAL DATA · NO FAULT LABELS

1 · Read history512 seconds of six signals: RPM, speed, coolant, MAP, MAF and throttle.

2 · Scale signalsEach signal is placed on a comparable scale before forecasting.

3 · ForecastTTM predicts the next 96 seconds of all six signals.

4 · ComparePredictions return to real units and are compared with recorded values.

Approach	Training target	Decision
Fault classifier	Needs verified examples of each fault	Not used: the dataset has no confirmed fault labels.
TTM forecasting	Normal signal behaviour	Selected: no proxy type or DTC is used as a target.

WHY THIS AVOIDS CIRCULAR LABELS

Using the same proxy rules for training and testing would mean that the rules created both the training answers and the test answers.

ROLE OF PHYSICAL RULES

Rules are added after the forecast to help explain the result. They are not TTM training labels.

The selected TTM model uses 512 seconds of input and a 96-second forecast. Other window sizes would require new training, calibration and testing; this project did not compare them.

CODE PATHmodel_layer/ttm-related/src/model/kit_residual_detector.py::run_ttm_forecast()model_layer/ttm-related/src/model/finetune_ttm.pydocs/adr/201-residual-detection-over-classification.md

Risk scores and ranked results

We turn forecast errors into risk scores and rank the five supported fault types.

3 MODEL · 2 DATA

Fault type	Result comes from	Main evidence
Cooling degradation	Model Layer	Forecast error + temperature checks
Reduced airflow	Model Layer	Forecast error + airflow checks
Accelerator pedal	Model Layer	Forecast result + pedal agreement
IAT sensor fault	Data Layer	No response, stuck signal and cold start
MAP/load plausibility	Data Layer	MAP and MAF disagreement

Forecast errorAverage absolute difference across the 96-second forecast.

Normal rangeDivide by the signal's normal range so different units can be compared.

Physical checksCombine the forecast result with component-specific rules.

Risk scoreRank all five fault types on a 0–1 evidence scale.

RANKED OUTPUT

The highest score is the main candidate, not a diagnosis. The second candidate appears in secondary_risk.

Only the top two are shown; real multi-fault cases were not available.

SCORE ≠ PROBABILITY

A risk score of 0.8 means strong unusual modelled behaviour. It does not mean an 80% probability of mechanical failure.

CONFIDENCE

For Model results, confidence measures how stable the forecast errors are. It is not diagnostic probability.

Data results keep confidence values of 0.9, 0.6 or 0.35.

FORWARDED SCORE

Emitted DTC: 0.9 · triggered rule: 0.6 · supporting evidence: 0.5 · otherwise: 0.

Forwarding does not mean TTM detected them. The Model Layer checks and passes on the IAT and MAP/load results without running the Data Layer rules again. Related codes: cooling P0128/P0217; airflow P0101/P0102; pedal P2138; IAT P0111–P0113; MAP/load P0106.

CODE PATHmodel_layer/ttm-related/src/model/kit_residual_detector.py::calculate_residuals()model_layer/ttm-related/src/model/kit_residual_detector.py::calculate_ranked_risks()model_layer/ttm-related/src/model/proxy_decision_forwarding.pyshared/interface_models.py::ModelLayerOutput

Training and final model

We trained on normal driving data and selected one final model for evaluation and runtime use.

EPOCH 5 · SELECTED

Model setup	Observed result	Final use
Original pretrained TTM	Comparison starting point	Comparison only
Epoch-five fine-tuned TTM	5.23% lower forecast MAE on 250 validation windows	Selected for evaluation and runtime
Signal-mixing version	Overall MAE worsened from 54.9666 to 55.6532	Rejected

5training epochs

47training trips

250validation windows

+0.15%MAP MAE change

WHY NORMAL DATA ONLY?

The model must learn normal behaviour. Training on faults could teach it to predict the fault and make the forecast error smaller.

WHAT DID NOT IMPROVE?

MAP MAE changed from 21.63 to 21.66. Relationships with other signals may explain this, but the project did not prove the cause.

The result uses one data split, one random seed and no external benchmark. Both formal evaluation and the final pipeline load OFFICIAL_DETECTOR_MODEL_PATH.

CODE PATHmodel_layer/ttm-related/src/model/finetune_ttm.pymodel_layer/ttm-related/src/model/compare_finetune_residuals.pymodel_layer/ttm-related/outputs/finetune_residual_comparison_e5_lr5e-5.json

Testing and alarm threshold

We tested artificial faults, measured each fault type separately and set a threshold to limit false alarms.

154 INJECTIONS · 11 CONTROLS

154artificial-fault cases

11unchanged controls

11MAP checks

0.5214macro F1

Fault type	Measured result	What it tells us
Cooling	Recall 1.0000	Artificial cooling changes were caught consistently.
Accelerator pedal	Precision 1.0000 · recall 0.3247	Few false positives, but many injected cases were missed.
MAF / airflow	Precision 0.2000 · recall 0.0455	Only 2 of 44 artificial cases were detected correctly.

Clean dataStart with normal-driving sections that pass the input checks.

Add a faultApply one of 14 controlled fault settings.

Run detectorCompare the ranked result with the known artificial fault.

Check controlsMeasure alarms on unchanged data separately.

Threshold stage	Normal-data alarms	Decision
Before calibration	3 of 11	Too many false alarms
Selected threshold: 0.4129	1 of 11	Best macro F1 with false alarms ≤10%
High-risk threshold: 0.9	—	Unchanged

Overall macro F1 0.5214 shows that performance is uneven across fault types. A 5.23% lower forecast MAE means better normal forecasting, but it does not prove better fault detection. Eight of 11 sections helped choose the threshold and also appeared in the final results, so the evaluation is not fully independent.

CODE PATHmodel_layer/ttm-related/src/model/fault_injection.pymodel_layer/ttm-related/src/model/risk_threshold_calibration.pymodel_layer/ttm-related/src/model/run_synthetic_evaluation.pymodel_layer/ttm-related/outputs/synthetic_eval_metrics_e5_lr5e-5_calibrated.json

Risk trends across trips

We use risk scores from several trips to estimate when the score may reach 0.9. This is not a failure prediction.

≥5 TRIPS · HIGH = 0.9

1 · Collect tripsAt least five chronological trips are required.

2 · Average riskCalculate one average score per component and trip.

3 · Fit trendCheck whether the component risk is rising over time.

4 · Project 0.9Estimate trips to High and the chance of reaching it within ten trips.

6Seat Leon trips

22real Model windows

≈5trips to risk 0.9

75.02%chance within ten trips

75.02% MEANS

The estimated chance that this detector's risk score reaches 0.9 within ten trips.

75.02% DOES NOT MEAN

The probability that the vehicle or component will mechanically fail.

Fewer than five trips returns no estimate. A flat or falling trend does not produce a near-term trip estimate. No real failure occurred in this example.

CODE PATHmodel_layer/ttm-related/src/model/failure_estimation.py::estimate_from_history()model_layer/ttm-related/src/model/risk_history.pyreport_layer/evaluation/viva_real_case

Passing results between layers

A fixed interface passes Model results to Dashboard and stops when the files do not match.

INTERFACE v1.6 · STOPS ON ERROR

Data LayerSends cleaned features and rule decisions.

Model LayerChecks both files, forecasts and ranks every window.

DashboardReceives the highest-risk summary and all ranked windows.

Report LayerBuilds component histories from primary and secondary results.

Input state	Model response
Wrong columns, sampling rate or version	Stop and return one clear `ERROR:` message.
No continuous 700-row section	Stop without producing a risk result.
Valid input	Return the highest-risk summary and every analysed window.

ERROR CAUGHT

A historical °C/s versus °C/min mismatch changed values by 60 times.

OWNERSHIP CORRECTED

P0116 and P0128 were moved to the correct cooling owner.

217tests passed

18tests skipped

235tests collected

73/73core interface tests

Tests confirm that the code and interfaces work as designed. They do not prove that a mechanical diagnosis is correct.

CODE PATHdashboard/csv_pipeline.pymodel_layer/ttm-related/src/model/kit_residual_detector.pymodel_layer/ttm-related/src/model/validate_output.pyshared/interface_models.py

Limits and next steps

This is an offline research system, not a confirmed diagnostic tool for real vehicles.

OFFLINE RESEARCH SYSTEM

Evidence supports	Evidence does not support
Response to artificial faults	Accuracy on real breakdowns
Risk trends across recorded trips	Mechanical-failure probability or remaining useful life
Proxy-rule evidence	A confirmed diagnosis
Offline pipeline behaviour	Readiness for live vehicle deployment

1 · Real faultsTest another dataset with mechanically confirmed failures.

2 · Better airflowCompare measured MAF with an estimate from pressure and engine speed.

3 · More vehiclesRepeat testing across different vehicles and driving conditions.

4 · Deployment checksAdd live integration, monitoring, model records and safety review.

AVAILABLE EVIDENCE

Artificial-fault tests and normal-driving risk histories from one vehicle dataset.

MISSING EVIDENCE

None of the 81 normal-driving trips contains a confirmed fault, repair result or failure event.

Important: risk score, confidence and the chance of reaching risk 0.9 measure different things. None gives the probability that the vehicle will break.

CODE PATHmodel_layer/ttm-related/src/model/fault_injection.pymodel_layer/ttm-related/src/model/run_synthetic_evaluation.pymodel_layer/ttm-related/src/model/kit_residual_detector.pyreport_layer/evaluation/viva_real_case

03 · REPORT LAYER

Risk evidence → grounded explanation

REPORT LAYER TEAM

Validated input and deterministic context injection

Convert Model's machine-oriented object into a stable evidence brief that Granite can read—without asking the LLM to recalculate abnormality, reinterpret units or turn data-quality notes into mechanical causes.

ADR 301 · CONTEXT CONTRACT

Validate shapeAccept single ModelLayerOutput or validate the full batch envelope and select summary.

Format statusComponent, risk level, score and confidence become labelled human-readable sections.

Classify signalsValue vs reference range deterministically produces NORMAL / ABNORMAL.

Add bounded contextCorrelations, projection fields, Model notes, certainty guidance and RAG knowledge.

WHAT BUILD_CONTEXT() DOES

Converts 0–1 risk/confidence into percentages for natural owner-facing language.
Includes every key signal with value, unit and reference range; units are omitted cleanly when absent.
Pre-computes abnormality instead of letting Granite inconsistently compare numbers.
Maps code names such as coolant_temp and speed_density_maf_residual to readable labels.
Preserves normal signals because the contrast between normal and abnormal evidence matters in atypical/contradictory cases.

ADDITIONAL EVIDENCE CONTROLS

Known multi-signal patterns cover thermal stress, MAF/MAP, dual pedal channels, intake temperature and MAP/load plausibility.
Unknown multi-signal combinations are described as possible systemic patterns, not confirmed causes.
Model notes are explicitly labelled as data-quality, repaired-value or disabled-detection information—not mechanical causes.
Batch windows become displayable risk_history, while generation uses the validated worst-risk summary.
Confidence generates language-strength guidance: >0.8 stronger predictive, >0.5 moderate, otherwise cautious.

5-TYPE INPUTPydantic validated

DETERMINISTIC LABELSNORMAL / ABNORMAL

31 DISPLAY NAMESowner-readable signals

5 CORRELATION PATTERNSmulti-signal context

3 CERTAINTY BANDSconfidence-controlled language

Implementation evolution

GL-30 / ADR 301 · JUNStructured context injection established and documented why the LLM must not judge raw abnormality.

→

GL-135/136 · 4 JULConfidence-based certainty guidance and multi-signal correlation were added.

→

GL-178/182/187 · 11 JULNew Model estimate fields, Report output pass-through and Model notes were aligned across interfaces.

→

GL-206 + v1.5Readable signal-name coverage and current batch/history semantics removed stale prompt inputs.

Why not send raw Model JSON directly to Granite?

Raw field names reduce readability and may leak into owner-facing output.
The LLM could classify the same boundary value differently between runs.
Structured headings act as a lightweight attention schema for three different prompt tasks.
Explicit notes/projection sections preserve semantic boundaries that a flat JSON dump does not explain.
The trade-off is coupling: context-format changes require prompt and evaluation updates.

Failure projection wording boundary

The context passes Model's two estimate fields because they are part of the shared contract.
Model notes state that the probability concerns crossing the High-risk score threshold, not mechanical failure probability.
Prompts must preserve this limitation and must not turn a linear risk projection into remaining useful life.
If estimates are null, the projection section is omitted rather than filled with invented values.

Code and integration evidence

context_injection.py: build_context(), build_context_with_rag(), display names and correlation maps.
report_generator.py: _extract_summary_payload() and _extract_risk_history_payload().
shared/interface_models.py: the initial shared Pydantic contract and later cross-layer alignment.
GL-178, GL-182 and GL-187 record resolution of estimate/notes interface misalignment.

RAG knowledge architecture and retrieval evidence

Retrieve only the fault explanation and action tier relevant to the known anomaly and current risk, grounding Granite in source-backed domain knowledge without exposing it to unrelated or over-urgent instructions.

ADR 303 · META + SECTION

Grounded YAMLFive current anomaly families, causes and source-attributed actions.

Section indexingFour documents per type: description+causes, low, medium and high actions.

Exact metadata retrievalKnown anomaly type + section + current risk level.

Prompt groundingOnly relevant explanation and risk-appropriate actions reach Granite.

CURRENT COLLECTIONS

fault_knowledge: 5 types × 4 sections = 20 documents.
symptom_knowledge: 5 types × one merged document = 5 documents; retained for comparison.
The four production sections are exactly: description_causes, actions_low, actions_medium, actions_high.
Collections are deleted/rebuilt on indexing so changed source text cannot hide behind stable document IDs.
Startup validates all five interface anomaly names and exact expected document counts.

WHY SECTION-LEVEL MATTERS

Layer 1/2 need explanation and possible causes; Layer 3 needs actions.
More importantly, Layer 3 must receive only the action tier appropriate to Low, Medium or High risk.
A merged document contains all three tiers; a semantic match could expose “stop immediately” guidance to a Low-risk report.
Section metadata makes retrieval deterministic and reduces token/attention dilution.
Adding a type changes source/index content, not prompt templates or retrieval algorithm.

20 CURRENT DOCSfault_knowledge

5 MERGED DOCSsymptom_knowledge

4 SECTIONS / TYPErisk-scoped actions

100% META ACCURACYhistorical 7-type test

~180× FASTERmetadata vs semantic

Historical evolution and design decisions

ADR 303 · GL-111/112ChromaDB metadata retrieval was selected, with indexing/exact filters.

→

GL-114/135/136RAG entered context injection with certainty guidance and correlation evidence.

→

GL-156/166 · 7 JULA 2×2 metadata/semantic × section/document experiment tested the design.

→

INTERFACE v1.xSeven historical types became five; indexers now validate and rebuild 20/5-document current collections.

Exact historical 2×2 retrieval experiment

A Meta+28: 7/7 = 100%; mean 0.341 ms.
B Semantic+28: 4/7 = 57.14%; mean 61.011 ms.
C Meta+7: 7/7 = 100%; mean 0.309 ms.
D Semantic+7: 6/7 = 85.71%; mean 57.407 ms.
Metadata was approximately 178.8× faster under section chunking and 186.0× faster under document chunking.
The experiment used three timing trials per method and evaluation-authored symptom descriptions.

What semantic retrieval got wrong

electronic_throttle_tracking_fault failed semantic retrieval under both chunking strategies.
Its symptom language overlapped strongly with pedal, RPM, airflow and load concepts, so embedding similarity did not preserve the exact intended type.
Section-level semantic search also missed the historical IAT/heat-soak and MAF cases, giving only 4/7 accuracy.
The exact Model enum made semantic uncertainty unnecessary for this interface.

RAG, fine-tuning and lookup table

LLM fine-tuning: domain updates would require retraining and sources would be harder to inspect.
Hard-coded lookup output: deterministic, with limited flexibility for combining live evidence into owner-readable language.
RAG: keeps knowledge external, reviewable and updateable while Granite performs controlled language generation.
Metadata retrieval is lookup-like for selection; the retrieved content supplies richer evidence to the generator.

Knowledge and generation boundary

The collection uses declared automotive handbooks, workshop manuals and troubleshooting references.
Retrieval reduces unsupported generation risk, while generated claims still require validation.
The knowledge base contains vehicle-general guidance and project-classified urgency tiers.

Code and evaluation evidence

knowledge_indexer.py: create_documents_for_anomaly(), index_knowledge_base().
symptom_knowledge_indexer.py: merged-document comparison collection.
rag_retriever.py::retrieve_all() and context_injection.py::build_context_with_rag().
retrieval_comparison.md preserves the historical 7-type experiment; current code truth is five types and 20/5 documents.

Three-layer Granite prompt chain

Generate the owner-facing report in three dependent, narrowly scoped steps so observed evidence, possible explanation and recommended action remain distinguishable—and so only the action layer receives risk-specific maintenance guidance.

ADR 302 · GRANITE 4.1:8B

Layer 1 · What?Describe anomaly, signals, practical risk and available projection.

Layer 2 · Why?Use Layer 1 + fault knowledge to propose supported, explicitly uncertain causes.

Layer 3 · What next?Use both prior sections + governed action knowledge to return four role-based steps.

JSON fieldsOne exact key per call: description, cause, then action array.

EVIDENCE VISIBILITY BY LAYER

All three: deterministic context, certainty guidance and audience=non-technical vehicle owner.
Layer 1: receives Model evidence only and translates the observed pattern.
Layer 2: also receives Layer 1 and filtered cause knowledge.
Layer 3: receives both prior outputs plus governed action knowledge.
Input context remains authoritative when retrieved knowledge conflicts with live evidence.

OWNER-SAFETY RULES

Translate raw names and unexplained acronyms into plain language.
Preserve uncertainty around possible mechanical causes.
Use only supplied projection values and current risk.
Return four roles in order: Now, Service timing, Stop driving and seek help if, Tell the mechanic.
Technical checks are framed as requests for a qualified mechanic.

3 CALLSdescription → cause → action

1 JSON KEY / CALLparseable contract

4 ACTION ROLESfixed owner contract

0.80validator release threshold

1 CORRECTIONfailed section only

Why three focused calls?

Each call has one semantic responsibility and one JSON key.
Layer 2 builds on the written evidence; Layer 3 acts on the observation and cautious interpretation.
Each failed section can be corrected independently.
The trade-off is three local inference calls and accumulated latency.

Prompt evolution

The three-stage decomposition established separate evidence, cause and action responsibilities.
Positive and negative examples helped expose missing boundaries during development.
Example details sometimes reappeared in output, so production templates retain the lessons as explicit rules.
Action guidance was reorganised into owner and mechanic roles after controlled review.

Live validator scope

Each generated section is scored against layer-specific deterministic checks.
A score below 0.80 blocks release and creates exact correction instructions.
The failed section receives one targeted regeneration attempt.
A second failure returns an explicit error through the report fallback path.

Code evidence

prompts/layer1_description.txt, layer2_cause.txt, layer3_action.txt: current roles, tasks, constraints, edge cases and JSON contracts.
report_generator.py::_correct_and_validate_layer() connects validation and one targeted correction.
prompt_chain_validator.py::validate_layer1(), validate_layer2(), validate_layer3().
Prompt-refinement and final-ablation artefacts preserve the controlled inputs, outputs and review conclusions.

Production execution, retry and graceful fallback

Run the three dependent local-LLM calls defensively: accept parseable field-level JSON, retry transient or malformed responses, and preserve Model evidence in a schema-shaped fallback instead of crashing the Dashboard pipeline.

GL-241–246 · NEVER RAISES

Validate + retrieveAny invalid input or context/RAG failure enters the outer fallback boundary.

Call each layerOllama Granite 4.1:8B, non-streaming, 120-second request timeout.

Parse + retryDirect JSON first, then first “{” to last “}”; up to 3 attempts with 2-second gaps.

Assemble or preserveAll three fields succeed, otherwise return pass-through evidence with empty generated fields.

SUCCESS PATH

extract_json() first uses json.loads(response), then extracts an embedded outer object as a repair attempt.
Each layer is accepted only when parsing succeeds and its expected key exists.
The cleaned section passes its live layer-specific validator at ≥0.80.
Layer 2 starts after Layer 1; Layer 3 starts after both earlier sections pass.
Pass-through Model fields, request-local risk history and three generated fields are assembled.

FAILURE PATH

Request or JSON failure uses the request retry path.
A validator score below 0.80 triggers one targeted correction for that section.
A second validation failure returns an explicit error and enters the report fallback.
_build_empty_report() keeps Model scores, signals, estimates, notes and risk history.
The function logs the failure and does not raise to its caller.

3 ATTEMPTSper prompt layer

2 s BACKOFFbetween attempts

120 srequest timeout

MODEL DATA KEPTon fallback

0 GENERATED FIELDSon fallback

Why fallback is deliberately incomplete

Inventing generic advice after a generation failure would hide the fact that grounding or generation did not complete.
Preserving Model evidence allows Dashboard to show risk/signals while treating narrative fields as unavailable.
The trade-off is that an empty report can still look structurally plausible; downstream UI must visibly distinguish “generation unavailable” from “no anomaly.”
Current fallback uses safe defaults for absent pass-through keys, so strict downstream schema validation remains valuable.

Failure modes a viva question may target

Ollama offline: connection failures retry, then fallback.
Slow model: each request has a 120-second timeout; worst-case user latency can still be large across three layers.
Markdown around JSON: outer-brace extraction may recover it.
Valid JSON but wrong value type: expected key is accepted here; this reveals the need for final schema/semantic validation.
Layer 3 failure after Layers 1/2: current all-or-fallback policy discards both generated strings, preserving atomic report consistency.

Historical implementation evidence

SCENARIO SCRIPTSPrompt calls and parsing first existed as evaluation helpers.

→

GL-241/242The end-to-end production function connected validated Model input to RAG and three prompts.

→

GL-243/244Retry behaviour and empty-field fallback were formalised.

→

GL-245/246Pipeline code and mocked unit coverage made the failure paths repeatable without live Ollama.

Code evidence

report_generator.py::generate_report(): outer non-raising boundary and sequential layer loops.
extract_json(), call_ollama(), _build_empty_report().
tests/test_report_generator.py: success, timeout, malformed JSON, invalid input and pass-through preservation on success/fallback; 6 tests passed in 0.30 s with HTTP mocked rather than a live Ollama dependency.

Controlled RAG ablation and manual review

Hold the generation pipeline constant, vary only the knowledge supplied to the prompts, and inspect what retrieval changes across all five current anomaly types.

4 CONDITIONS · 5 TYPES · 20 REPORTS

Hold constantGranite 4.1 8B, temperature 0, model inputs, prompt rules and validator.

Vary knowledgeBaseline, Cause RAG, Full workshop RAG and Owner-safe RAG.

Cover scopeOne controlled fixture for each of the five implemented anomaly types.

Manual reviewCheck relevance, use, audience fit, action roles and contradictions.

FOUR CONTROLLED CONDITIONS

Baseline: Model context only.
Cause RAG: reviewed component descriptions and possible causes.
Full workshop RAG: cause knowledge plus workshop procedures.
Owner-safe RAG: owner observations and mechanic requests governed separately.
Granite 4.1 8B, temperature 0, fixtures, prompt rules and validator were held constant.

FINAL MANUAL-REVIEW FINDINGS

Cause RAG: relevant in 4/5 cases; one Cooling case was partially relevant.
Full workshop RAG: audience and action-role criteria passed in 1/5 cases.
Owner-safe RAG: audience and action-role criteria passed in 5/5 cases.
Release: all 20 reports completed, while two High-risk fixtures retained relationship-level contradictions.
These are structured review outcomes, not diagnostic-accuracy percentages.

4 CONDITIONSknowledge ablation

5 TYPEScurrent implemented scope

20 REPORTSheld generation settings

5/5 AUDIENCEOwner-safe RAG

5/5 ACTIONOwner-safe RAG

Why RAG scored lower in the typical case

The RAG report gave technically specific advice—thermostat operation around 82°C, radiator, coolant and fan checks—but omitted the evaluator's expected word “soon,” losing 0.30 Actionability.
It also exposed raw coolant_temp, losing 0.30 Readability.
The baseline used more generic but keyword-friendly urgency language, so scored 1.00.
GL-206 added SIGNAL_DISPLAY_NAMES so future context uses “coolant temperature” rather than raw schema names; prompt rules were also tightened.
The honest interpretation is: RAG added useful specificity but presentation quality still needed refinement.

What the evaluator actually checks—and misses

Factual Grounding detects whether any description number exists and matches a context number; it does not verify every numerical claim or unit.
Readability uses a finite blacklist and regex acronym heuristic; plain language outside the list is not semantically assessed.
Hedging performs substring matching, so “no confirmed fault yet” is incorrectly penalised because it contains confirmed.
Actionability recognises fixed urgency words; a detailed safe action can lose points merely because it omits “soon.”
Therefore 0.95 is an automated comparison supported by manual review—not proof of factual correctness or safety.

Contradictory evidence remains unresolved

The contradictory fixture combines Low risk/31% confidence with abnormal coolant temperature at 108°C.
RAG hedged successfully, but neither baseline nor RAG explicitly explained why the abnormal signal and Low classification disagree.
A useful next design would detect input contradictions deterministically and require the report to surface them before possible causes.
This limitation matters more than the perfect 1.00 heuristic score in that scenario.

Critical self-evaluation and future work

Only three authored scenarios were tested, all cooling degradation; no real owner language or full five-type report set was evaluated.
No automotive domain expert validated causal statements, urgency tiers or maintenance actions.
Replace substring rules with semantic entailment/similarity and explicit negation handling.
Add blinded human-in-the-loop review by vehicle owners and domain experts, inter-rater agreement, all anomaly types and real/mixed inputs.
Integrate quality/schema gates into production only after deciding whether low-quality output should retry, degrade or be blocked.

Code and evidence

report_quality_evaluator.py::evaluate_factual_grounding(), evaluate_readability(), evaluate_hedging_appropriateness(), evaluate_actionability(), evaluate_report().
rag_baseline_comparison_table.md: exact scenario and aggregate scores plus manual interpretation.
rag_evaluation_criteria.md: Huang/Qi/ADR 302 grounding and >0.7 quality threshold.
GL-119/120/121 and GL-123 preserve the evaluation design, execution artefacts and report-ready comparison.

ReportLayerOutput contract and Dashboard handoff

Package machine evidence and owner-facing language in one shared shape: Model facts pass through unchanged, batch-window risk becomes request-local chart history, and Granite adds exactly three narrative fields.

INTERFACE v1.5 · 3 FIELD GROUPS

Model pass-throughTimestamp, risk, component, confidence, signals, estimates and notes.

Report-maintainedOptional risk_history distilled from the current batch's windows.

Granite-generatedDescription string, possible-cause string and recommended-action list.

Dashboard consumptionSummary cards, evidence, narrative, actions and optional trend visualisation.

SUCCESS OBJECT

Pass-through: timestamp, risk_score, risk_level, component, prediction_confidence, key_signals, two nullable estimate fields and notes.
Maintained: risk_history: [{timestamp, risk_score}] | null.
Generated: anomaly_description: string, possible_cause: string, recommended_action: string[].
The report does not recompute Model scores, ranges or projection values.
Shared ReportLayerOutput constrains component enum and 0–1 score/probability ranges.

FALLBACK OBJECT

Uses the same keys so Dashboard integration does not branch on an entirely different payload type.
Model evidence and available request history are retained.
Description and cause become empty strings; actions become an empty list.
No explicit report_generation_success flag exists; Dashboard must infer unavailable narrative from empty fields.
The generator returns a compatible dictionary but does not itself instantiate ReportLayerOutput; strict final validation is a documented hardening opportunity.

9 PASS-THROUGHModel-owned fields

1 MAINTAINEDrisk_history

3 GENERATEDtext · text · list

BATCH → TRENDrequest-local only

SAME SHAPEsuccess / fallback

How batch history becomes a Dashboard trend

A batch envelope is validated, while its summary supplies the report's single-window facts.
_extract_risk_history_payload() scans windows and keeps entries containing both timestamp and risk score.
The Report layer does not persist this list across Dashboard sessions; it describes only the current request/batch.
Model component projections use separate in-request histories assembled from primary and secondary_risk appearances.
The append-only, deduplicated primary-risk file remains a distinct audit and single-window estimation path.

Interface leadership embodied in the output

The initial shared Pydantic model replaced an ambiguous single explanation_text with three report fields and structured key signals.
Sprint 3 alignment added/propagated estimated_cycles_to_failure, estimated_failure_probability and notes through Report and Dashboard-facing contracts.
GL-178, GL-182 and GL-187 resolved mismatches between shared models, context/generator code and interface documentation.
GL-405/INTERFACE v1.5 aligns the current five-type enum, batch envelope and projection semantics.

What Dashboard may safely say

Risk score is Model anomaly evidence; prediction confidence is attribution confidence; failure probability is a projected threshold-crossing probability. They are not interchangeable percentages.
Generated possible causes remain hypotheses, even at High risk.
Empty narrative means generation unavailable, not “the vehicle is healthy.”
Any displayed cycle estimate must retain Model notes explaining why it is a trend projection rather than physical remaining useful life.

Code and contract evidence

shared/interface_models.py::ReportLayerOutput and RiskHistoryEntry.
report_generator.py::_extract_risk_history_payload(), _build_empty_report(), generate_report().
docs/INTERFACE.md §3.1–3.3 and v1.5 change history.
tests/test_report_generator.py verifies pass-through preservation on both success and fallback.
The wider current Report/interface group passed 78 tests in 0.95 s; this proves contract behaviour, not LLM narrative quality, which remains covered by the separate three-scenario and five-type review artefacts.

03 · REPORT LAYER

Evidence behind the final report pipeline

FINAL DESIGN · VIVA BACKUP

Granite model selection

Four locally runnable Granite models were compared on the same Cooling case and the same three-call sequence.

HISTORICAL SELECTION TEST

Criterion	Weight	3.3 2B	3.3 8B	4.1 3B	4.1 8B
Plain language	30%	3	4	4	5
Grounding	25%	4	4	4	5
Valid JSON	20%	2	5	5	5
Action quality	15%	3	3	4	5
Uncertainty	10%	4	4	4	4
Weighted total	100%	3.15	4.05	4.15	4.85 · selected

Evidence boundary: this single controlled case supported the project choice; it is not a general ranking of Granite models.

Automotive knowledge storage design

The storage method had to keep reviewed knowledge inspectable and select only the part required by the current report section.

20 REVIEWED RECORDS

Option	Observed trade-off	Decision
Full knowledge in every prompt	Unrelated material and unnecessary prompt length	Not used
Semantic vector retrieval	Useful when the category is unknown; ranking varied across records	Compared
Metadata-filtered ChromaDB	Exact filtering from the anomaly key already supplied by the Model Layer	Selected

5supported anomaly types

1cause record per type

3risk-specific action records

20records rebuilt from YAML

Storage evidence

report_layer/rag/grounded_knowledge.yaml is the reviewed source.
report_layer/rag/knowledge_indexer.py rebuilds the collection and checks all five anomaly types.

How knowledge is indexed and retrieved

knowledge_indexer.py prepares the reviewed YAML for retrieval; rag_retriever.py selects the two records required for the current report.

BUILD TIME → RUNTIME

OVERALL KNOWLEDGE PATH

grounded_knowledge.yamlReviewed source

knowledge_indexer.pyBuild records

ChromaDB collectionStore 20 records

rag_retriever.pySelect for prompts

KNOWLEDGE_INDEXER.PY · BUILD TIME

Load YAMLproxy_failures

ValidateFive required types

Cause recordDescription + causes

Action recordsLow · Medium · High

Upsert4 records × 5 types

VerifyCount = 20

RAG_RETRIEVER.PY · RUNTIME

Open collectionOtherwise fallback

Find causesType + section

Find actionsType + section + risk

Return bothTo context construction

Metadata and semantic retrieval comparison

RAG is the overall method. This experiment compared two ways of choosing which reviewed record enters a prompt.

HISTORICAL · 7 TYPES

Retrieval method	Correct record	Average time
Metadata + section	7/7	≈0.34 ms
Semantic + section	4/7	≈61.0 ms
Metadata + whole document	7/7	≈0.31 ms
Semantic + whole document	6/7	≈57.4 ms

METADATA FILTERING · EXACT LABELS

Use fields already supplied by the Model Layer to select one matching record.

collection.get(where={"$and": [
  {"anomaly_type": {"$eq": anomaly_type}},
  {"section": {"$eq": "actions"}},
  {"risk_level": {"$eq": risk_level}}
]})

SEMANTIC RETRIEVAL · MEANING SIMILARITY

Embed a symptom description and rank records by similarity, even when their wording differs.

collection.query(
  query_texts=[symptom_description],
  n_results=1
)

Scope: this design experiment used seven categories available at that stage. Production now supports five anomaly types.

Model evidence received

One Medium-risk Cooling case is used through the next three cards to show what the Report Layer receives and what it may explain.

STRUCTURED INPUT

CURRENT RESULT

cooling_degradation
Risk score: 0.5021 · Medium
Prediction confidence: 0.842

SUPPORTING SIGNALS

Coolant: 85°C · reference 90–95°C
Rise rate: 5.0486°C/min · reference 0–2
Both values remain Model Layer evidence.

TRIP ESTIMATE

estimated_cycles_to_failure = 5
Projected trips until the risk trend reaches the High threshold.

TEN-TRIP PROBABILITY

estimated_failure_probability = 0.7502
Chance of crossing High within the fixed next ten trips.

These projections describe the Model risk threshold. They are not a probability or countdown of confirmed mechanical failure.

What the Model input contract checks

ModelLayerOutput(**summary) triggers these Pydantic rules before retrieval or any Granite call begins.

SHARED/INTERFACE_MODELS.PY

report_layer/pipeline/report_generator.py: validated = ModelLayerOutput(**summary_payload) → only the validated object is passed to build_context_with_rag(validated).

1 · REQUIRED FIELDS + ALLOWED VALUES

AnomalyType = Literal[
  "cooling_degradation",
  "air_intake_maf_anomaly",
  "accelerator_pedal_sensor",
  "intake_air_temperature_sensor_fault",
  "map_load_signal_plausibility_fault"
]
RiskLevel = Literal["Low", "Medium", "High"]

class ComponentRiskOutput(BaseModel):
  timestamp: str
  anomaly_type: AnomalyType
  risk_score: float
  component: AnomalyType
  prediction_confidence: float
  key_signals: List[KeySignal]
  estimated_cycles_to_failure: Optional[int] = Field(...)
  estimated_failure_probability: Optional[float] = Field(...)

2 · FIELD VALIDATORS

@field_validator(
  "risk_score",
  "prediction_confidence"
)
def _score_in_unit_range(value):
  if not 0 <= value <= 1:
    raise ValueError(...)

@field_validator(
  "estimated_failure_probability"
)
def _failure_probability_in_unit_range(value):
  if value is not None and not 0 <= value <= 1:
    raise ValueError(...)

@field_validator("reference_range")
def _reference_range_has_two_values(value):
  if len(value) != 2:
    raise ValueError(...)

3 · RELATIONSHIP VALIDATORS

@model_validator(mode="after")
def _component_mirrors_anomaly_type(self):
  if self.component != self.anomaly_type:
    raise ValueError(...)

@model_validator(mode="after")
def _secondary_risk_is_distinct_and_ranked(self):
  secondary = self.secondary_risk
  if secondary is None:
    return self
  if secondary.anomaly_type == self.anomaly_type:
    raise ValueError(...)
  if secondary.risk_score > self.risk_score:
    raise ValueError(...)

Boundary: schema validation catches malformed or internally invalid input. It cannot prove that a structurally valid anomaly classification is correct for the real vehicle.

Prompt context construction

Technical fields are converted into a short evidence summary while their values and meanings remain unchanged.

PREPARED EVIDENCE

Readable namescoolant_temp → coolant temperature.

Reference check85°C is below the supplied 90–95°C range.

RelationshipLow temperature + rapid warming activates the defined thermal pattern.

Meaning retainedRisk, confidence and projections remain separate values.

“Coolant temperature is below its reference range, while its rate of increase is above the expected range.”

# Abridged from build_context_with_rag()
context = build_context(ttm_output)
risk = ttm_output.risk_level.lower()

rag_knowledge = retrieve_all(
    anomaly_type=ttm_output.anomaly_type,
    risk_level=risk,
)

# R7 applies the signal-relevance gate here.
return {
    "context": context,
    "fault_knowledge": fault_knowledge,
    "actions_knowledge": actions_knowledge,
}

contextCurrent Model evidence prepared for owner-facing language.

fault_knowledgeReviewed possible-cause record matched to the anomaly type.

actions_knowledgeReviewed guidance matched to the anomaly type and risk level.

What a defined relationship means

The relationship is activated only when the required signals are available.
It describes a combination chosen in the implementation; Granite does not discover a new statistical correlation.
report_layer/pipeline/context_injection.py prepares the context.

Knowledge admitted to this Cooling case

Retrieval finds category-matched material; an additional check decides whether its explanation fits the direction of the current signals.

CASE-LEVEL ADMISSION

RETRIEVED POSSIBILITIES

Coolant circulation
Thermostat operation
Cooling fan operation
Coolant level or quality
Radiator airflow or restriction

CURRENT EVIDENCE

Temperature is below its reference range.
Temperature is rising faster than expected.
Pure overheating wording does not fit this observation.
Cautious circulation, sensor or fan checks may still be presented as possibilities.

Current limit: Cooling has this signal-direction check. The other four production categories currently use exact metadata filtering only.

Three production Calls

Each Call has a separate question, evidence allowance and output contract.

SEQUENTIAL GENERATION

CALL 1 · WHAT HAPPENED?Evidence

Prepared Model fields only.

Example

“Coolant temperature is low while warming faster than expected.”

CALL 2 · WHY MIGHT IT MATTER?Evidence

Accepted Call 1 + admitted cause knowledge.

Example

“This pattern may relate to sensing or coolant circulation.”

CALL 3 · WHAT SHOULD I DO?Evidence

Risk state + role-separated action knowledge.

Example

“Arrange an inspection and report the two readings to the mechanic.”

Call	Fixed boundary	Output
1	No diagnosis or retrieved cause	Observed pattern
2	Possible causes remain conditional	Explanation
3	Technical procedures assigned to mechanic	Now · timing · stop conditions · mechanic information

Example-value leakage

A specific number in an early few-shot example appeared in a new report even though it was absent from that report’s Model input.

OBSERVED FAILURE → REGRESSION CASE

CURRENT COOLING INPUT

Failure-threshold probability: 1.0
Estimated trips: 4
No value of 0.31% was supplied.

EARLY EXAMPLE

An unrelated accelerator-pedal example contained the illustrative value 0.31%.

“The model projects a very low probability (0.31%) of crossing the High-risk threshold…”

Remove concrete examplesProduction prompts no longer receive reusable fictional values.

Write direct rulesEvery reported value must occur in the current Model context.

Keep the failureThe leaked-value case becomes a regression input.

VerifyThe corrected run uses 100% and four trips from the real input.

R10

Three Calls through sequential gates

Each accepted section becomes part of the next prompt. A failed section is corrected before generation continues.

GENERATE → VALIDATE → CONTINUE

CALL 1

Observation

Model evidence and prepared context.

Clean → validate → one correction if required

CALL 2

Possible causes

Model evidence + accepted Call 1 + cause knowledge.

Clean → validate → one correction if required

CALL 3

Recommended actions

Model evidence + accepted Calls 1–2 + action knowledge.

Clean → validate → one correction if required

DEPENDENCY

Call 2 receives the accepted observation. Call 3 receives both accepted earlier sections. Each Call also keeps access to the relevant Model evidence.

RELEASE PATH

After Call 3 passes, the complete cleaned chain is checked once more. Release follows only when all three sections score at least 0.80; otherwise the report uses the fallback path.

R11

How the Validator checks one section

The same validation framework selects rules for the section, scores the result and returns exact warnings for one correction attempt.

SECTION-SPECIFIC RULES · ≥0.80

Generated JSON

Owner-facing cleanup

Select section rules

Score + warnings

Accept or correct once

RULE SEVERITY

−0.10−0.20−0.40

Start at 1.00 · release at 0.80 or above

Threshold check: The 0.80 threshold was checked against ten generated reports covering the five supported anomaly types.

ONE FRAMEWORK · DIFFERENT CHECKS

ObservationEvidence meaning · unsupported values · fault certainty

Possible causesHedging · repetition · signal direction

ActionsFour roles · urgency · owner safety

SharedHigh-risk projection consistency · release threshold

FAILED SECTION

“coolant_temp is high and the cooling fan has failed.”

Warnings identify the raw field, unsupported direction and confirmed-fault wording.

TARGETED CORRECTION

The correction prompt receives the original task, rejected JSON and exact warnings. Only this section is regenerated and checked again.

R12

Two failure paths

The pipeline treats a failed model request differently from a readable JSON response that breaks a report rule.

RETRY · CORRECT · FALLBACK

TECHNICAL FAILURE

Request error
Timeout
Malformed JSON
Response: retry the call, up to three attempts.

CONTENT FAILURE

JSON parses successfully
Section scores below 0.80
Response: one targeted correction, then check again.

Second content failureStop further generation.

Fallback objectKeep the same interface shape.

Preserve evidenceRisk values and signals remain available.

Leave text emptyDashboard shows report generation unavailable.

R13

Four knowledge conditions

The final evaluation changed only the knowledge supplied to Granite while keeping the model, prompts, temperature, inputs and Validator fixed.

4 × 5 = 20 REPORTS

Condition	Knowledge supplied	Purpose
No retrieved knowledge	Model context only	Generation baseline
Cause knowledge	Reviewed descriptions and possible causes	Test explanation grounding
Cause + raw workshop actions	Cause records and unseparated procedures	Expose audience/action-role problems
Cause + role-separated actions	Owner observations, timing and stop conditions separated from mechanic procedures	Final design

OWNER GUIDANCE

What to observe now, when to arrange service, and which visible warning signs require urgent help.

MECHANIC INFORMATION

Scan-tool checks, wiring inspection, calibration and replacement decisions are presented as requests for a qualified mechanic.

R14

Automated checks and manual review

The same 20 reports produced machine-checkable results and separate human judgements about meaning and audience.

FINAL V5 EVIDENCE

01 · AUTOMATED EXECUTION AND RULE AUDIT

Condition	Released	Valid structure	No unsupported numbers	No unsafe owner procedure detected	Fallback
Controlled baseline	5/5	5/5	5/5	5/5	0/5
Cause RAG	5/5	5/5	5/5	5/5	0/5
Cause + raw actions	5/5	5/5	5/5	5/5	0/5
Cause + role-separated actions	5/5	5/5	5/5	5/5	0/5

02 · STRUCTURED MANUAL REVIEW

Condition	Input faithfulness	Retrieval relevance	Knowledge use	Audience	Action safety	Uncertainty
Controlled baseline	5 pass	N/A	N/A	5 pass	5 pass	5 pass
Cause RAG	5 pass	4 pass · 1 partial	1 pass · 4 partial	3 pass · 2 partial	5 pass	5 pass
Cause + raw actions	5 pass	4 pass · 1 partial	1 pass · 4 partial	3 pass · 2 partial	5 pass	5 pass
Cause + role-separated actions	5 pass	4 pass · 1 partial	1 pass · 4 partial	3 pass · 2 partial	5 pass	5 pass

Where did manual review record partial?	Reason
Retrieval relevance · IAT	The record matched the intake-temperature category, but all displayed temperatures were within range. The current evidence could not show whether a circuit issue or a connector issue better matched this case.
Knowledge use · MAF, pedal, IAT and MAP	Retrieved knowledge added several plausible causes, but the current signals did not contain enough evidence to choose which cause best matched the case. Cooling was the only full pass.
Audience · MAF and IAT	The reports respected the evidence and action boundaries, but their cause explanations remained longer and more technical than ideal for a non-specialist reader.

SUPPORTED

20/20 reports generated and released
Input meaning and uncertainty preserved
Owner–mechanic action boundary maintained
RAG usually retrieved the correct category

LIMITATION

RAG-only measures cannot prove improvement over baseline
Only five unlabelled cases per condition
No verified fault or technician judgement
Signals could not select among several possible causes

NEXT EVALUATION

Use technician-verified faults and repair outcomes
Include more vehicles and operating conditions
Check signal direction before admitting knowledge
Compare both conditions on specificity, clarity and decision usefulness

Meaning of partial: the report was released, but manual review found a material limitation in that dimension. These results assess report behaviour and rule compliance; technician-verified faults are still required to assess mechanical accuracy.

04 · DASHBOARD

Evidence behind the owner-facing Dashboard

13 TOPICS · VIVA BACKUP

User journey and data sources

Start with an explicit choice: analyse uploaded OBD-II data or explore a labelled demonstration.

UPLOAD · DEMO · SOURCE

PrepareStart the local dependencies and Streamlit Dashboard.

ChooseUpload raw CSV trips or select Explore with demo data.

AnalyseValidate, then run Data → Model → Report.

ExploreReview affected components, signals and owner guidance.

Source	Meaning
uploaded / uploaded_history	Results from a live single-upload or joint-history request.
real	Real-source output identified by the loader.
mock	Demonstration values; not evidence of a live run.
missing	No available component data.

The per-component _data_source map carries provenance. Demo/missing warnings prevent silent substitution; accepted uploads override static data within the active session.

Implementation and evidence

dashboard/data_store.py: session result → cached static data → emergency fallback; static path can be set through DASHBOARD_TEST_DATA.
dashboard/data_loader.py: source map and real/mock loading. GL-85 → GL-129/131 → GL-132/133 established source-aware integration.

Local deployment and usability

Live analysis relies on local Model dependencies and Ollama; installation remains a barrier for non-technical owners.

LOCAL LIVE ANALYSIS

CURRENT SETUP

Python, the Model environment, Ollama and Granite must be available. The hosted demonstration uses static results.

NEXT STEP

Package the application or provide a hosted inference service so owners can upload data without terminal setup.

Decision	Reason / trade-off
Model batch subprocess	Uses the published CLI and isolates pinned Torch/Transformers dependencies; adds process startup and serialization overhead.
Interpreter selection	MODEL_LAYER_PYTHON → dedicated Model virtual environment → current Python.
Local artefacts	Temporary raw/Model files are cleaned up; Data artefacts persist by run. Retention and privacy handling require further work.

Implementation and evidence

README.md and dashboard/README.md: live setup and hosted-demo scope.
dashboard/csv_pipeline.py::_run_model_layer(): fixed Model working directory and 120-second subprocess timeout.

Multiple files as driving history

Accepted trips are ordered chronologically and processed together while retaining individual trip boundaries.

AT LEAST 5 TRIPS

OrderSort uploaded trips by filename date.

PreserveKeep original filenames and trip boundaries.

CombineData produces joint features and optional proxy decisions.

Analyse onceModel evaluates the combined artefact; Report generates component results.

The history route requires at least five chronological trips. Its uploaded_history label distinguishes the result. This request history is not a persistent cross-session vehicle record.

Implementation and evidence

dashboard/csv_pipeline.py::run_uploaded_csv_history_batch() and _run_data_layer_history().
The joint route calls Model once on combined production features and forwards optional proxy decisions; GL-398/399 closed the earlier proxy handoff gap.

Upload validation

Reject unusable files before expensive processing and show the owner a readable reason.

SCHEMA · TIME · LENGTH

Check	Behaviour
Readable, non-empty CSV	Reject absent bytes, empty data and parsing failures.
11 required raw columns	Validate time, temperature, pressure, RPM, speed, airflow, throttle and pedal fields; accept the known °C/Â°C header variant.
At least 700 rows per admission check	Protect the temporal input requirement; 700 rows is about 11.7 minutes at 1 Hz. UI guidance asks for roughly 15 minutes.
Original KIT filename	Preserve the recording-date identity instead of renaming to a generic temporary file.
Continuity and usable segments	The Data Layer can still reject a file that passes the initial column/row checks.

A failed required check rejects the analysis and leaves the previous accepted result intact. Passing the admission checks does not guarantee a usable Model window.

Implementation and evidence

dashboard/csv_validator.py, dashboard/pages/overview.py and dashboard/csv_pipeline.py.
GL-256–258: upload UI, schema/row validation and readable failure cards. Model context/future requirements are 512 + 96 points, with additional segment constraints.

Dashboard responsibilities

Dashboard coordinates the layers and presents their evidence; it does not make a new vehicle prediction.

CONTRACT → DISPLAY

Owner	Responsibility
Model	Risk score, supplied risk level, attribution confidence, key signals, window history and optional projections.
Report	Preserve structured evidence and add anomaly description, possible cause and recommended action.
Dashboard	Validate/adapt payloads, select and sort components, draw rings/charts, compare signal ranges and format exports.

BOUNDARY ADAPTER

Accept single outputs or batch envelopes; normalise legacy coolant_slope to ect_rate_180s, remove retired coolant_stability and canonicalise component aliases.

PORTABLE OUTPUT

PDF offers Summary, Failure Prediction, Risk Trend, Key Signals and Diagnostic Report. CSV offers feature, value, unit, range and status; multiple components can be packaged as ZIP files.

The ring uses the 0–1 score; the High/Medium label comes from the payload. Export reformats existing results and never reruns the diagnosis.

Implementation and evidence

dashboard/data_loader.py: extraction, normalisation and Pydantic validation.
dashboard/export_helper.py: missing-value formatting, safe filenames, PDF/CSV and ZIP packaging.

Risk metrics and interpretation

Different indicators answer different questions; none is a validated probability of mechanical breakdown.

RISK ≠ CONFIRMED FAILURE

Indicator	Meaning
Risk score	Model internal anomaly indicator on a 0–1 scale.
Risk level	Model-supplied Low, Medium or High category.
Prediction confidence	Support for the component attribution; not breakdown probability.
Risk Trend	Internal risk scores across recorded analysis windows in the request.
Estimated cycles to failure	Projection of trips until the score crosses the High-risk threshold; not physical remaining useful life.
Estimated failure probability	Projected chance of crossing that threshold within the prediction horizon; not calibrated mechanical-failure probability.

Keep Model notes and unavailable states visible. Explain these as risk-pattern estimates and possible causes; recommend professional inspection without claiming a confirmed fault. Projection headline wording remains an area for alignment.

Implementation and evidence

shared/interface_models.py, docs/INTERFACE.md, dashboard/pages/detail.py.
Model backup explains threshold-crossing semantics and the lack of technician-confirmed failure labels.

Component selection and no-risk state

The Overview prioritises supported components that may need attention.

MEDIUM / HIGH

FilterCreate cards for Medium and High results.

PrioritiseHigh first, then descending risk score.

Open detailStore the selected component and show supporting evidence.

No affected resultShow the no-supported-risk state instead of misleading cards.

Five canonical types are supported. The current viva example shows Cooling System as High and Air Intake System as Medium. No supported risk found is limited to the analysed data and implemented detectors.

Implementation and evidence

dashboard/data_store.py::get_overview_components(), dashboard/pages/overview.py and dashboard/anomaly_display.py.
Aliases are canonicalised and duplicate components suppressed.

Normal and abnormal signals

Compare each available reading with its supplied reference range and preserve the evidence next to the status.

VALUE VS RANGE

Input / result	Interpretation
Reading + reference range	Values outside the range are Abnormal; values within it are Normal.
Coolant example	84.0°C and rise rate 5.5069°C/min are shown as abnormal in the viva payload.
Supporting normal readings	Vehicle speed 70.0 km/h and manifold pressure 132.0 kPa remain normal.
Owner-readable labels	Show signal name, value, unit and range; glossary tooltips explain technical terms.

A signal status is a comparison with the supplied range, not an independent confirmed fault. Normal signals remain useful context alongside abnormal readings.

Implementation and evidence

dashboard/pages/detail.py::_render_signals(), dashboard/glossary.py and dashboard/export_helper.py.

Missing data display

Unavailable evidence remains unavailable instead of becoming an invented measurement or estimate.

MISSING ≠ ZERO

Missing item	Display behaviour
Trend	Show an empty/unavailable state when usable history is insufficient.
Key signals	Show no available signals rather than fabricated readings.
Projection fields	Retain null/unavailable values; do not invent percentages or cycles.
Component source	Keep the missing/demo provenance visible.
Export values	Normalise missing values explicitly in the portable report.

Missing evidence differs from generation failure. An empty generated explanation requires the failure check described in D10.

Implementation and evidence

dashboard/pages/detail.py, dashboard/data_store.py and dashboard/export_helper.py.
Historical edge fixtures cover empty, missing, single-component, no-signal and no-trend states.

D10

Processing failures and empty reports

A failed generation must not be presented as evidence that the vehicle is healthy.

FAILURE → RECOVERY

Failure	Response
Model unavailable / non-zero exit	Show a readable Model error; extract the documented ERROR message when available.
Model timeout / invalid output	Handle the 120-second timeout, missing JSON or invalid JSON as pipeline failure.
Returned components all have empty descriptions	Treat the returned components as generation failure even when their shape is valid.
Recovery	Clear loading state in finally; only accepted results update the Dashboard session.

Current check applies only when components exist and every description is empty. No affected components follows the no-supported-risk path (D7). One non-empty description can allow a partial multi-component report through; explicit generation status and per-component validation would be stronger.

Implementation and evidence

dashboard/pages/overview.py::_handle_uploaded_csv_submit(); GL-261 and commit bc50667 document silent-fallback detection.
Report catches normal generation failures internally, so an outer timeout exception alone cannot detect them. Progress percentages are stage milestones, not measured completion estimates.

D11

Explanation grounding and errors

Granite translates structured evidence and reviewed knowledge into owner-facing language, but grounding does not guarantee correctness.

EVIDENCE + REVIEWED KNOWLEDGE

Model evidenceRisk, signals, context and projection notes.

Retrieved knowledgeReviewed category-specific causes and risk-specific actions.

Constrained generationSeparate what, why and action; apply report validation.

Dashboard evidenceKeep original signals visible beside generated possibilities.

WHAT GROUNDING ADDS

Relevant knowledge and structured facts constrain the explanation. Owner observations are separated from mechanic procedures.

WHAT REMAINS UNCERTAIN

A plausible cause is still a hypothesis. Report checks address specified errors, but cannot prove every explanation matches a real mechanical condition.

See Report backup for the final Validator, correction/fallback route and manual-review results. Dashboard presentation cannot independently establish diagnostic accuracy.

Implementation and evidence

report_layer/report_generator.py and the reviewed RAG knowledge; Report backup cards R3–R11.

D12

Testing evidence and limitations

Contract tests, controlled substitutes and saved live runs answer different validation questions.

WORKFLOW ≠ ACCURACY

Evidence	What it establishes
Validation and UI tests	Upload gates, source labels, sorting, missing states, loading recovery, risk display, glossary and report rendering.
Controlled pipeline tests	Data/Model handoff, proxy forwarding, timeouts and output contracts without expensive live calls.
Export tests	Deterministic PDF/CSV transformation, packaging and formatting.
Saved real-case run	The available vehicle data can exercise the integration route; it does not establish accuracy on confirmed breakdowns.
Historical Dashboard run	171 passed, 1 skipped on 2 Aug 2026; a historical snapshot, not a fresh test result.

The largest evidence gap is confirmed mechanical failures across vehicles. Also needed: wider live five-type coverage, accessibility evaluation, latency improvements and per-component failure handling.

Implementation and evidence

dashboard/tests/ and report_layer/evaluation/viva_real_case/.
Earlier focused runs recorded 40 loader/integration tests, 19 upload tests and 62 display/UI tests; their scopes overlap and should not be added together.

D13

User feedback and interface changes

Make risk easier to interpret without suggesting that a clearer interface makes the prediction more accurate.

RISK TREND · OWNER LANGUAGE

Interpretation problem	Interface response
Percentage-led visuals can look like breakdown probability	Emphasise Low, Medium and High risk levels while retaining the internal score for visual scale.
Risk Score Trend sounds like a probability forecast	Use Risk Trend and explain that the chart represents an internal risk pattern.
Technical evidence is difficult to read	Use owner-facing component names, glossary help and what / why / action sections.

User feedback supports presentation changes. It does not validate mechanical predictions; use the saved user-testing evidence when discussing participant findings.

Implementation and evidence

report_layer/evaluation/user_testing_ab/, dashboard/pages/detail.py and dashboard/glossary.py.
GL-41/42/44 introduced details, trends and signal evidence; GL-85/96 aligned Report data and confidence; later viva refinement changed risk wording.

What happens when the Check Engine light comes on?

Fleet operators use vehicle data to plan maintenance earlier.

We begin with data.

How Do You Define Failure Without Verified Fault Labels?

Raw OBD-II readings are now clean, contextualised, and linked to fault evidence.

How can we detect change without fault examples?

Learns from verified examples

Contains no verified fault outcomes

Tiny Time Mixers

Convert each gap to the same 0-1 scale

Retain change over time

1. Does it identify a known change?

2. Does extra training improve the forecast?

We can now see what changed, how strong the evidence is, and which system ranks highest.

How can we turn technical evidence into clear, reliable guidance for vehicle owners?

Selective RAG

What happened?

What might it mean?

What should I do next?

Role

Task

Evidence

Boundaries

Fixed output

Automated technical checks

Manual report review

The evidence is now a clear action plan.

From local setup to owner action.

Four steps to reproduce the local pipeline.

Each step has a matching command group.

From OBD-II data to guidance an owner can act on.

What have we demonstrated—and what remains unproven?

How do we move from one vehicle dataset to broader use?

End-to-end integration · inputs, checks and failure paths

IBM brief and MoSCoW priorities

From the delivery plan to a completed Jira task

How the work was organised

Sprint meetings recorded plans, progress and improvements

Jira automation kept task and code-review status in step

The CI workflow checked each proposed code change

Regular updates made cross-layer progress visible

Upload intake and run isolation

Continuity-aware cleaning

Hierarchical operating-condition stratification

Frozen feature contract and production assembly

Executable proxy failure evidence

Offline calibration and governed residual features

Graded synthetic fault-injection validation

Two deliveries, one traceable Data handoff

Input checks and forecast windows

Forecasting normal behaviour without fault labels

Risk scores and ranked results

Training and final model

Testing and alarm threshold

Risk trends across trips

Passing results between layers

Limits and next steps

Validated input and deterministic context injection

RAG knowledge architecture and retrieval evidence

Three-layer Granite prompt chain

Production execution, retry and graceful fallback

Controlled RAG ablation and manual review

ReportLayerOutput contract and Dashboard handoff

Granite model selection

Automotive knowledge storage design

How knowledge is indexed and retrieved

Metadata and semantic retrieval comparison

Model evidence received

What the Model input contract checks

Prompt context construction

Knowledge admitted to this Cooling case

Three production Calls

Example-value leakage

Three Calls through sequential gates

Observation

Possible causes

Recommended actions

How the Validator checks one section

Two failure paths