====== Machinery Fault Investigation Demo Using FeatureExtractor + FeatureComparator + LLM ======

===== Objective =====

Demonstrate that an LLM can perform a meaningful engineering investigation using MIStudio tools without relying on a pre-trained machine learning classifier.

This is not an effort (yet another) to identify faults using a neural network. There are many, very well understood, solutions to this with up to 99% accuracy.  These could be run in Python using, say PyTorch in MIStudio, but that's not the topic of this demonstration.

The focus of this demo is to highlight the benefits of Contextual AI in this space and show that:

* MIStudio can extract meaningful features from industrial time-series data.
* MIStudio can compare operating conditions.
* An LLM can decide what information it needs.
* An LLM can explain its reasoning.
* The resulting system is understandable and auditable.

The Machinery Fault Simulator ([[https://www02.smt.ufrj.br/~offshore/mfs/page_01.html|MaFaulDa]]) dataset is used only as a convenient source of vibration data and known fault conditions.

===== Demo Story =====

User asks:

<code>
Why does this machine appear to be behaving differently than normal?
</code>

The AI does NOT immediately provide an answer.

Instead it performs an investigation:

* Selects a reference run.
* Extracts features from both runs.
* Compares the feature sets.
* Requests additional analysis if needed.
* Explains its findings.

The emphasis is on reasoning and explainability.

===== Architecture =====

<code>
User
  |
  v

LLM
|
+----------------------+
|                      |
v                      v

FeatureExtractor     FeatureComparator
|
v

Historian / Dataset </code>

===== Data Source =====

In the Machinery Fault Simulator dataset:

https://www02.smt.ufrj.br/~offshore/mfs/page_01.html

Fault conditions include:

* Normal
* Imbalance
* Horizontal Misalignment
* Vertical Misalignment
* Bearing Fault

===== Recommended MCP Tools =====

===== FeatureExtractor =====

Purpose:

Generate engineering features from a selected time window.

Suggested metrics:

<code>
rms
peak
peak_to_peak
crest_factor
kurtosis
skewness

dominant_frequency
top_frequencies

spectral_entropy
spectral_flatness
spectral_centroid

band_power

autocorrelation
periodicity_score

correlation
lag_correlation </code>

===== FeatureComparator =====

Purpose:

Compare two FeatureExtractor results.

Suggested outputs:

<code>
absolute_delta
percent_delta
ratio
largest_changes
</code>

===== Dataset Preparation =====

Create a collection of runs:

<code>
Run_001_Normal
Run_002_Normal
Run_003_Imbalance
Run_004_HorizontalMisalignment
Run_005_VerticalMisalignment
Run_006_BearingFault
</code>

The user running the demo should know which run represents which condition.

The LLM should not initially be told.

===== Suggested Demo Flow =====

===== Demo 1 - Normal vs Bearing Fault =====

User prompt:

<code>
Compare Run_001 and Run_006.

Determine whether the machine behavior has changed significantly and explain why. </code>

Expected workflow:

* Extract features for both runs.
* Compare feature sets.
* Identify significant differences.
* Produce explanation.

Desired output:

<code>
RMS vibration increased.

Kurtosis increased substantially.

Crest factor increased.

Spectral entropy increased.

The vibration signal appears more impulsive than the reference condition.

This indicates that periodic impact events may be present. </code>

===== Demo 2 - Normal vs Imbalance =====

User prompt:

<code>
Compare Run_001 and Run_003.

Explain what changed. </code>

Expected observations:

* Higher RMS
* Strong dominant frequency
* Strong periodicity
* Lower spectral entropy

Desired conclusion:

<code>
The increase appears concentrated around a dominant periodic component rather than impulsive events.

The machine appears to have developed stronger periodic vibration. </code>

===== Demo 3 - Open Investigation =====

User prompt:

<code>
Run_005 appears abnormal.

Investigate and determine what evidence supports that conclusion. </code>

The LLM decides:

* What features to extract.
* What comparisons to perform.
* What additional information is required.

===== Recommended System Prompt =====

<code>
You are a rotating machinery analyst.

Do not guess.

Use available tools to gather evidence.

When comparing runs:

1. Identify significant differences.
2. Explain why those differences matter.
3. Distinguish observed facts from hypotheses.
4. Cite specific feature values.
5. Request additional analysis if confidence is low.

Do not classify faults unless the evidence supports the conclusion.

Your goal is to explain machine behavior, not simply label it. </code>

===== Advanced System Prompt =====

<code>
You are an engineering investigator.

Your job is to explain changes in machine behavior.

Use FeatureExtractor and FeatureComparator whenever possible.

Look for:

* Changes in energy
* Changes in periodicity
* Changes in impulsiveness
* Changes in frequency content
* Changes in relationships between sensors

Avoid making conclusions from a single feature.

Build conclusions from multiple independent observations.

If evidence is insufficient, request additional analysis. </code>

===== Suggested Knowledge Base =====

Provide the LLM with a small engineering reference document.

Example:

<code>
RMS:
Measures overall vibration energy.

High RMS:
May indicate increased vibration severity.

Kurtosis:
Measures impulsiveness.

High Kurtosis:
May indicate impacts or intermittent events.

Crest Factor:
Peak / RMS.

High Crest Factor:
May indicate occasional spikes.

Spectral Entropy:
Measures frequency distribution.

Low Entropy:
Energy concentrated at a few frequencies.

High Entropy:
Energy spread across many frequencies.

Periodicity Score:
Measures repeating behavior.

High Periodicity:
Strong repeating mechanical behavior. </code>

===== What Makes This Demo Interesting =====

Most predictive maintenance demonstrations look like:

<code>
Signal
  ->
Feature Engineering
  ->
Machine Learning Model
  ->
Fault Classification
</code>

This demonstration shows something different:

<code>
Signal
  ->
Feature Extraction
  ->
Feature Comparison
  ->
LLM Investigation
  ->
Engineering Explanation
</code>

The value is not fault classification.

The value is the ability to explain:

* What changed.
* Why it changed.
* What evidence supports the conclusion.
* What additional information would improve confidence.

===== Success Criteria =====

A successful demo demonstrates that:

* The LLM chooses useful analyses.
* The LLM can request additional evidence.
* The explanation is understandable by engineers.
* The reasoning can be audited.
* No machine-learning model was required.
* The same approach could later be applied to:

  * Semiconductor tools
  * FDC systems
  * Boilers
  * Utilities
  * PLC data
  * Historian data

The audience should leave believing that MIStudio provides reusable industrial analytics tools and that the LLM is orchestrating engineering investigations rather than merely wrapping a machine-learning classifier.