Envelope-spectrum analysis of a stored signal (bearing fault screening).

THE unified envelope tool: bandpass filter -> Hilbert
envelope -> mean subtraction + Hann window -> FFT -> top peaks.
The mean subtraction/window step is an intentional U9 fix: the
envelope's DC leakage used to bury the low-frequency FTF zone.
Requires the signal loaded via load_signal() first; the sampling
rate comes from the stored signal metadata.

The requested band must fit the signal: an invalid band (low <= 0,
low >= high, high > Nyquist) raises a ValueError — it is NEVER
silently clamped. The band used is echoed in the result.

By default analyzes the LEADING 1.0-second segment (deterministic:
two identical calls return identical results). Set
segment_duration=None to analyze the entire signal, or pass
random_seed to sample a seeded random segment position instead.

No reference bearing frequencies are assumed: compare the returned
peaks against frequencies computed for the actual bearing and
shaft speed (check_bearing_faults or
calculate_bearing_characteristic_frequencies).

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal (from load_signal).
    filter_low: Bandpass low edge in Hz (default: 500).
    filter_high: Bandpass high edge in Hz (default: 5000). Must
        not exceed the signal's Nyquist frequency.
    num_peaks: Number of top peaks to return (default: 5).
    segment_duration: Duration in seconds to analyze (default:
        leading 1.0 s). None analyzes the full signal.
    random_seed: Seed for random segment position (default: None =
        deterministic leading segment).

Returns:
    EnvelopeResult with the band actually used, top peaks, and
    comparison guidance.

Raises:
    ValueError: If the signal_id is not loaded, the stored signal
        has no sampling rate, or the band is invalid vs Nyquist.

Perform FFT (Fast Fourier Transform) analysis on a stored signal.

FFT analysis converts the signal from time domain to frequency domain,
allowing identification of harmonic components and faults that manifest
at specific frequencies. Requires the signal loaded via load_signal()
first; the sampling rate comes from the stored signal metadata.

By default analyzes the LEADING 1.0-second segment (deterministic:
two identical calls return identical results). Set
segment_duration=None to analyze the entire signal, or pass
random_seed to sample a seeded random segment position instead.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal (from load_signal).
    max_frequency: Maximum frequency to analyze (default: Nyquist frequency)
    segment_duration: Duration in seconds to analyze (default: leading
        1.0 s). Set to None to analyze the full signal.
    random_seed: Seed for random segment position (default: None =
        deterministic leading segment).

Returns:
    FFTResult with top peaks, dominant peak, and spectrum stats.

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate.

THE unified screening tool: feature trend AND degradation
onset in one call. Segments a single recording
(seconds of data), extracts the requested feature per segment,
tests whether the per-segment values show a statistically
significant trend (slope p < 0.05), and detects the first segment
AFTER the baseline window (first half of the series) whose value
exceeds baseline mean + onset_threshold_sigma standard deviations.
Onset inside the baseline window cannot be detected (the baseline
defines "normal"). Requires the signal loaded via load_signal()
first; the sampling rate comes from the stored signal metadata.

This is a SCREENING tool, not a prognosis: a trend inside seconds
of signal says whether the recording is stationary, not how long
the machine will live. For Remaining Useful Life, collect repeated
measurements over days/weeks (one recording per session) and pass
them to estimate_rul — this tool returns the per-segment feature
series so each recording can be reduced to one measurement point.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal (from load_signal).
    feature_name: Time-domain feature to analyze (default: "rms").
    segment_duration: Duration of each segment in seconds.
    overlap_ratio: Overlap between segments (0-1).
    onset_threshold_sigma: Baseline standard deviations above the
        baseline mean that trigger onset detection (default: 3.0).

Returns:
    TrendAnalysisResult with slope, direction (p-value based),
    fit quality, the (truncated) per-segment feature series, and
    the onset-detection outcome (onset_detected,
    onset_segment_index, onset_time_s, baseline_segments).

Raises:
    ValueError: If the signal_id is not loaded, or the stored
        signal has no sampling rate.

Calculate statistical parameters of a stored signal for diagnostics.

Statistical parameters are key indicators for diagnostics:
- RMS: Effective value, correlated to signal energy
- Crest Factor: Indicates presence of impulses (high = possible faults)
- Kurtosis: Measures impulsiveness (excess kurtosis; >0 = non-Gaussian, >3 = strong impulses)
- Peak-to-Peak: Signal range

Requires the signal loaded via load_signal() first. Statistical
parameters are screening indicators, not definitive diagnostics —
combine with frequency-domain evidence.

**Signal units:** all values are in the signal's native unit. The unit
is reported only when DECLARED — load_signal(signal_unit=...) or the
companion _metadata.json — and never guessed from signal amplitude.
ISO 20816-3 severity tools refuse to produce a verdict until the unit
is declared.

Args:
    signal_id: ID of the stored signal (from load_signal).

Returns:
    StatisticalResult with all statistical parameters

Raises:
    ValueError: If the signal_id is not loaded.

THE unified severity tool: ISO zone assessment and alert
classification in one call. Zone boundary values are those of
ISO 10816-3:2009 (ISO 20816-3:2022 merges zones A/B — provenance is
noted in the result). Scope: machines rated above 15 kW; a declared
machine_power_kw below 15 kW is refused.

Input routes (exactly ONE required):
- signal_id: a stored signal (load_signal first). Sampling rate AND
  declared unit come from the stored metadata; an undeclared unit is
  refused, never guessed from amplitude.
- rms_velocity_mm_s: a direct broadband RMS velocity reading in mm/s
  (e.g. from a portable instrument) — no unit declaration needed.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal (mutually exclusive with
        rms_velocity_mm_s).
    rms_velocity_mm_s: Direct broadband RMS velocity in mm/s
        (mutually exclusive with signal_id).
    machine_group: 1 (large, >300 kW) or 2 (medium, 15-300 kW).
        Ignored when custom thresholds are given. Default 2.
    support_type: 'rigid' or 'flexible'. Ignored when custom
        thresholds are given. Default 'rigid'.
    thresholds: Optional custom zone boundaries {'warning': A/B,
        'alarm': B/C, 'danger': C/D} in mm/s, strictly increasing —
        replaces the ISO table for this call.
    machine_power_kw: Rated machine power, if known. Declared values
        below 15 kW are refused (out of ISO scope); None means
        unknown and is not refused.
    rpm: Operating speed in RPM (signal route only: selects the 2 Hz
        band lower edge below 600 RPM).

Returns:
    VibrationSeverityResult (status='assessed') with zone, severity,
    boundaries, derived alert_level/exceeded_threshold, and threshold
    provenance.

Raises:
    ValueError: On route misuse (both/neither inputs), undeclared
        signal unit, missing sampling rate, Nyquist below the ISO
        band, declared power below 15 kW, negative RMS, or invalid
        custom thresholds.

Calculate bearing characteristic frequencies from geometry.

Standard rolling-element kinematic formulas (Randall & Antoni 2011,
"Rolling element bearing diagnostics — A tutorial", MSSP 25(2)).
Requires the EXACT geometry — from the manual, the catalog
(search_bearing_catalog), or the user; never guessed. Deep-groove
ball bearings have contact_angle_deg = 0.

Args:
    num_balls: Number of rolling elements (Z)
    ball_diameter_mm: Ball/roller diameter (Bd) in mm
    pitch_diameter_mm: Pitch circle diameter (Pd) in mm
    contact_angle_deg: Contact angle (alpha) in degrees
    rpm: Shaft rotation speed in RPM
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with BPFO, BPFI, BSF, FTF in Hz.

Example:
    >>> # 6205 geometry (CWRU Bearing Data Center) at 1797 RPM
    >>> freqs = calculate_bearing_characteristic_frequencies(
    ...     num_balls=9, ball_diameter_mm=7.94,
    ...     pitch_diameter_mm=39.04, rpm=1797
    ... )
    >>> round(freqs['BPFO'], 2)
    107.36

THE unified bearing-check tool: catalog lookup, explicit
frequencies, or explicit geometry in one call. Requires the signal
loaded via load_signal() first.

Expected-frequency routes (exactly ONE required):
- bearing_id: catalog lookup (verified entries only) — BPFO/BPFI/BSF/
  FTF computed from the catalog geometry; the entry's source citation
  is echoed in the result.
- frequencies: explicit {label: hz} dict — for bearings not in the
  catalog or non-bearing checks such as a gearbox GMF
  (e.g. {"GMF": 350.0}). Labels BPFO/BPFI/BSF/FTF map to the
  canonical fault vocabulary; other labels have no canonical form.
- explicit geometry: num_balls + ball_diameter_mm + pitch_diameter_mm
  (+ contact_angle_deg) — frequencies computed from user-provided
  geometry (out-of-catalog path).

Each check reports fault_type_canonical (outer_race / inner_race /
ball / cage) alongside the acronym.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal.
    rpm: Shaft speed in RPM.
    bearing_id: Bearing designation (e.g. '6205', 'SKF 6205-2RS').
    frequencies: Explicit expected frequencies {label: hz}, all > 0.
    num_balls: Number of rolling elements (explicit-geometry route).
    ball_diameter_mm: Ball/roller diameter Bd in mm.
    pitch_diameter_mm: Pitch circle diameter Pd in mm.
    contact_angle_deg: Contact angle in degrees (default 0.0).
    tolerance_pct: Frequency matching tolerance in percent (default 5).

Returns:
    BearingFaultsSummary with one check per expected frequency,
    overall assessment, most likely fault (+ canonical form), and the
    provenance of the expected frequencies (`source`).

Raises:
    ValueError: If the signal is not loaded / has no sampling rate, if
        not exactly one route is given, if the geometry is incomplete,
        if the bearing is not in the catalog, or if frequencies is
        empty / non-positive.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID to remove; None (default) clears the whole cache.

Returns:
    Dict with cleared_count, plus signal_id and status ('removed' or
    'not_found') for single-signal calls.

Requires signal loaded via load_signal() first.

Args:
    signal_id: ID of the stored signal.
    nperseg: Samples per FFT segment (default 256).
    noverlap: Overlap between segments (default 128).
    window: Window function (default 'hann').

Returns time-frequency summary (no full 2D array). Use for detecting
time-varying frequency content (transient faults, speed changes).

Args:
    signal_id: ID of the stored signal.
    nperseg: Samples per STFT segment (default 256).
    noverlap: Overlap between segments (default 128).
    window: Window function (default 'hann').

Comprehensive vibration diagnostic pipeline. Loads signal from repository,
runs all analyses, and synthesizes results into an actionable report.
The ISO severity block uses ISO 20816-3 machine group/support type
(zone boundaries from ISO 10816-3:2009, provenance noted in output).

The diagnosis DEGRADES instead of failing when the ISO verdict cannot
be produced honestly: if the stored signal has no declared unit (or
the sampling rate cannot cover the ISO evaluation band), the
iso_severity block is a structured refusal (status='refused' with
reason and remedy) while the spectral, bearing, and anomaly blocks
still run. Units are never guessed from amplitude — declare them via
load_signal(signal_unit=...) or the companion _metadata.json.

Args:
    signal_id: ID of the stored signal.
    rpm: Machine operating speed in RPM.
    bearing_id: Bearing designation for fault detection (optional).
    machine_group: 1 (large, >300 kW) or 2 (medium, 15-300 kW).
        Default 2.
    support_type: 'rigid' or 'flexible'. Default 'rigid'.

Raises:
    ValueError: If the stored signal has no sampling rate.

RUL is only physically meaningful when fitted on a degradation trend
across MULTIPLE measurements of the same machine taken at different
times (days/weeks/months apart). This tool refuses a single
recording or single point — for within-recording screening use
analyze_signal_trend instead.

Two mutually exclusive input routes (both need `timestamps`, one
entry per measurement, strictly increasing, in `time_unit`):
1. `feature_values`: the degradation indicator already measured
   externally (e.g. RMS velocity trended by a data collector).
2. `signal_ids`: one stored signal per measurement session (loaded
   via load_signal); each recording is reduced to a single
   `feature_name` value.

The degradation indicator is assumed to RISE toward
`failure_threshold`. A statistically significant increasing trend
(slope p-value < 0.05) is required before any RUL is computed; a
flat/insignificant series returns status 'no_degradation_trend'
with no RUL number.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    failure_threshold: Indicator value considered as failure, in the
        same units as the feature values. No universal default is
        imposed — but when the indicator is broadband VELOCITY RMS
        in mm/s, the standard choice is the ISO 10816-3:2009 zone
        C/D boundary that assess_severity / get_zone_boundaries()
        reports for the machine's group and support (single source
        of truth — no boundaries restated here).
    timestamps: Measurement times in `time_unit`, strictly
        increasing (e.g. hours since first measurement).
    feature_values: Indicator values, one per measurement
        (mutually exclusive with signal_ids).
    signal_ids: Stored signal IDs, one per measurement session
        (mutually exclusive with feature_values).
    feature_name: Time-domain feature used to reduce each signal
        (default: "rms"). Ignored for feature_values input.
    method: "linear" (default), "exponential", or "kalman"
        (kalman needs approximately uniform measurement spacing).
    time_unit: Label for the time axis; RUL and
        observation_horizon are expressed in this unit.

Returns:
    RULEstimationResult with status, rul (only when estimated),
    fit_r_squared (goodness of fit — NOT a confidence),
    observation_horizon, and a plain-language message.

Extract time-domain features from a stored signal using sliding windows.

Segments the signal into overlapping windows and extracts 17 statistical features
from each segment. Features include: mean, std, RMS, kurtosis, crest factor, entropy, etc.
Requires the signal loaded via load_signal() first; the sampling rate
comes from the stored signal metadata. Returns an in-memory summary
only — no CSV is written to data/signals/.

Args:
    signal_id: ID of the stored signal (from load_signal).
    segment_duration: Duration of each segment in seconds (default: 0.1)
    overlap_ratio: Overlap between segments, 0-1 (default: 0.5 = 50%)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    FeatureExtractionResult with features matrix and metadata

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate.

Example:
    extract_features_from_signal(
        "healthy_motor",
        segment_duration=0.2,
        overlap_ratio=0.5
    )

Extract machine specifications from an equipment manual (PDF).

Extracts bearing designations (e.g. SKF 6205), operating speeds
(RPM), power ratings (kW/HP/MW), and a text excerpt. Results are
cached. If a bearing's geometry is not in the manual, follow up
with search_bearing_catalog(bearing_id=...); if it is not in the
catalog either, ask the user for the geometry — never invent it.

Args:
    file_name: Manual filename in resources/machine_manuals/
    use_cache: Use cached extraction if available (default: True)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with extracted specifications and text excerpt.

Raises:
    FileNotFoundError: If the manual does not exist (the message
        lists the available manuals).

Runs the full diagnosis, then renders signal overview, ISO severity,
anomaly state, characteristic-frequency matching, spectral energy, an
annotated envelope spectrum, and recommended actions into a single
self-contained document.

AUTHORSHIP CONTRACT — this matters more than it may appear. Every
evaluative sentence in the returned ``statements`` list was written by
this server. Reuse them verbatim when presenting the result. Do NOT coin
standard names, machine classes, severity zones, or confidence levels of
your own: this server deliberately publishes no confidence figure, and
the standards caveat that travels with every severity verdict must not be
dropped or paraphrased. If a question is not answered by these
statements, say so rather than filling the gap.

Unlike ``generate_diagnostic_report_docx``, this tool takes no content
sections from the caller. Supply the analysis inputs; the wording is the
server's.

Args:
    signal_id: ID of the stored signal (from load_signal).
    rpm: Machine operating speed in RPM.
    bearing_id: Bearing designation for characteristic-frequency
        matching. Omitted means the matching section states why it was
        not attempted rather than disappearing.
    machine_group: ISO 20816-3 group — 1 (large, >300 kW) or 2 (medium,
        15-300 kW). Default 2.
    support_type: 'rigid' or 'flexible'. Default 'rigid'.
    baseline_signal_id: Optional stored signal from the same machine in a
        known-good state. Supplying it turns absolute readings into
        deltas, which is what tells a reader whether a condition is new
        or stable.
    formats: Renderings to produce — any of 'html', 'pdf'. Defaults to
        ['html']. 'pdf' requires
        ``pip install predictive-maintenance-mcp[pdf]``.
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dict with ``statements`` (every authored sentence, in document
    order), ``files`` (one entry per rendering), ``verdict``,
    ``evidence_strength``, and ``provenance``.

Raises:
    ValueError: If a signal id is not loaded, has no sampling rate, or an
        unsupported format is requested.

Generate a structured Word (.docx) diagnostic report for a stored signal.

Requires: ``pip install predictive-maintenance-mcp[docx]``

``sections`` is a dict whose keys define what to include (all optional):
  - statistics:           dict  (RMS, Kurtosis, Crest Factor …)
  - fft_peaks:            list  [{frequency, magnitude_db, note}, …]
  - envelope_peaks:       list  [{frequency, magnitude_db, match}, …]
  - bearing_frequencies:  dict  {BPFO, BPFI, BSF, FTF}
  - iso:                  dict  (mapped from assess_severity output)
  - diagnosis:            str   (free-text diagnostic summary)

Args:
    signal_id: ID of the stored signal (from load_signal); used for
        the report title / filename.
    sections: Content sections to include (see above)
    title: Optional custom report title
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file_path, file_name, and per-section summary.

Raises:
    ValueError: If the signal_id is not loaded, or python-docx is
        not installed.

Generate professional envelope analysis report (HTML) for a stored signal.

Generates a professional HTML report file instead of inline content.
Saves to reports/ directory. Requires the signal loaded via
load_signal() first; the sampling rate comes from the stored signal
metadata. Reference bearing frequencies (BPFO/BPFI/BSF/FTF) can be
passed explicitly or, if omitted, are read from the source file's
companion _metadata.json when present.

Args:
    signal_id: ID of the stored signal (from load_signal).
    filter_low: Bandpass filter low cutoff (Hz). Default 500 Hz
    filter_high: Bandpass filter high cutoff (Hz). Default (None)
        adapts to the signal: min(5000, Nyquist-1). An explicit value
        above Nyquist is rejected, never clamped.
    max_freq: Max envelope spectrum frequency to display. Default 500 Hz
    num_peaks: Number of peaks to detect. Default 15
    bearing_freqs: Optional dict with BPFO, BPFI, BSF, FTF
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file path, metadata, and summary (NO HTML content)

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate.

Example:
    >>> # Bearing frequencies computed for YOUR bearing/rpm (here: 6205
    >>> # per CWRU geometry at 1797 RPM)
    >>> result = generate_envelope_report(
    ...     "real_train_OuterRaceFault_1",
    ...     bearing_freqs={"BPFO": 107.36, "BPFI": 162.19, "BSF": 70.58, "FTF": 11.93}
    ... )

Generate feature comparison report with violin plots comparing time-domain features.

Creates interactive HTML report with violin plots showing distribution of 17
time-domain features across different signal groups (e.g., Healthy vs Faulty).
Requires every signal loaded via load_signal() first; each signal's
sampling rate comes from its stored metadata.

**Strategy**: Same HTML report approach as other reports. Useful for understanding
which features are most discriminative for fault detection.

Args:
    signal_groups: Dictionary mapping group names to lists of stored
                  signal IDs.
                  Example: {"Healthy": ["real_train_baseline_1"],
                           "Faulty": ["real_train_OuterRaceFault_1"]}
    segment_duration: Segment duration in seconds (default: 0.1s for ML)
    overlap_ratio: Overlap ratio 0-1 (default: 0.5)
    features_to_plot: List of feature names to plot (default: all 17 features)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file path, metadata, and summary

Raises:
    ValueError: If a signal_id is not loaded or has no sampling rate.

Example:
    >>> generate_feature_comparison_report(
    ...     signal_groups={
    ...         "Healthy": ["real_train_baseline_1", "real_train_baseline_2"],
    ...         "Inner Fault": ["real_train_InnerRaceFault_vload_1"],
    ...         "Outer Fault": ["real_train_OuterRaceFault_1"]
    ...     }
    ... )

Generate an interactive FFT spectrum report (HTML) for a stored signal.

Saves a self-contained Plotly HTML report (spectrum in dB, automatic
peak detection, harmonic labels) to the reports/ directory with a
timestamped filename — consecutive runs produce distinct files.
Requires the signal loaded via load_signal() first; the sampling
rate comes from the stored signal metadata.

Args:
    signal_id: ID of the stored signal (from load_signal).
    max_freq: Maximum frequency to display (Hz). Default 5000 Hz
    num_peaks: Number of peaks to detect and label. Default 15
    rpm: Optional shaft speed in RPM — peaks at integer multiples
        of rpm/60 Hz are labeled as 1x/2x/... harmonics.
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file path, metadata, and summary (NO HTML content)

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate.

Generate an ISO 20816-3 evaluation report (HTML) for a stored signal.

Saves a self-contained Plotly HTML report (color-coded A-D zone
chart with the measured RMS marker, boundaries, severity text) to
the reports/ directory with a timestamped filename. The evaluation
itself is delegated to assess_severity — requires the signal loaded
via load_signal() first with sampling rate AND a declared unit
(units are never guessed).

Args:
    signal_id: ID of the stored signal (from load_signal).
    machine_group: 1 (large, >300 kW) or 2 (medium, 15-300 kW)
    support_type: 'rigid' or 'flexible'
    rpm: Operating speed in RPM (optional; selects the ISO band's
        lower edge below 600 RPM)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file path, metadata, and summary (NO HTML content)

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate or no declared unit.

Combines ISO zone-based urgency with fault-specific maintenance
actions. This tool intentionally does NOT accept a confidence
value: any number supplied by the caller would be echoed into
advisory output without evidential basis.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    severity_zone: ISO zone letter — "A", "B", "C", or "D".
    fault_types: Detected fault types from the closed canonical
        vocabulary — outer_race/inner_race/ball/cage for bearings
        (NOT the BPFO/BPFI/BSF/FTF acronyms) plus misalignment/
        unbalance/looseness. None for zone-only advice.

Returns:
    Formatted string listing all maintenance recommendations.

Raises:
    ValueError: If any fault type is outside the canonical
        vocabulary (the message lists the allowed values —
        unknown values are never dropped silently).

Generate PCA visualization HTML report showing test data in 2D PCA space.

Creates interactive scatter plot with:
- Test/prediction data (green = predicted healthy, red = predicted anomaly)
- PC1 vs PC2 axes with variance explained
- Hover information showing segment details and prediction status

**IMPORTANT**: Labels show MODEL PREDICTIONS, not ground truth. Use `true_labels`
parameter to provide actual labels for validation visualization.

Requires the test signals loaded via load_signal() first; each
signal's sampling rate comes from its stored metadata.

Args:
    model_name: Name of trained model (e.g., 'bearing_health_model')
    test_signal_ids: Optional list of stored signal IDs to predict and visualize
    true_labels: Optional dict mapping signal_ids to true labels.
                Format: {"real_test_baseline_3": "healthy",
                         "real_test_InnerRaceFault_vload_6": "faulty"}
                When provided, legend shows both true and predicted labels for validation.
    segment_duration: Segment duration in seconds (default: 0.1s for ML)
    overlap_ratio: Overlap ratio 0-1 (default: 0.5)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with file path, metadata, and summary (includes validation metrics if true_labels provided)

Raises:
    FileNotFoundError: If the model does not exist.
    ValueError: If a signal_id is not loaded or has no sampling rate.

Example (with validation):
    >>> generate_pca_visualization_report(
    ...     model_name="bearing_health_model",
    ...     test_signal_ids=["real_test_baseline_3", "real_test_InnerRaceFault_vload_6"],
    ...     true_labels={"real_test_baseline_3": "healthy",
    ...                  "real_test_InnerRaceFault_vload_6": "faulty"}
    ... )

The signal is written to data/signals/ with a timestamped filename and a
companion _metadata.json declaring sampling_rate and signal_unit='g'
(synthetic acceleration), then auto-registered in the repository — the
returned signal_id is immediately usable by every analysis, diagnosis,
and ISO severity tool with no manual steps.

Signal content: 'bearing_fault' = 10 Hz impacts modulating a 1 kHz
carrier; 'gear_fault' = 200 Hz mesh tone + harmonics; 'imbalance' =
25 Hz (1500 RPM) tone; 'normal' = broadband noise.

Args:
    signal_type: Synthetic fault pattern to generate.
    duration: Signal duration in seconds (10 s gives 0.1 Hz resolution).
    sampling_rate: Sampling frequency in Hz.
    noise_level: Additive white-noise amplitude.
    random_seed: Seed for reproducible noise (None = non-deterministic).
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    StoredSignalInfo of the auto-loaded signal (signal_id, declared
    sampling_rate and unit 'g').

Includes the COMPLETE companion-metadata dict (source_metadata: rpm/
shaft_speed, reference frequencies, ...) alongside the repository
fields (sampling_rate, declared signal_unit, shape, timestamps).

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of a signal previously loaded via load_signal.

Returns:
    StoredSignalInfo with source_metadata populated from the companion
    _metadata.json (empty dict when the file has none).

Raises:
    ValueError: If the signal_id is not in the repository.

List HTML reports, or get one report's embedded metadata.

Without file_name: lists every report in reports/ with file name,
type, signal, and size. With file_name: returns that report's
embedded metadata block (absorbed get_report_info). Never returns
HTML content — metadata only, to avoid token consumption.

Args:
    file_name: Optional report filename inside reports/ — returns
        its metadata instead of the listing.

Returns:
    List of report summaries (no file_name), or a dict with the
    single report's metadata (file_name given).

Raises:
    ValueError: If file_name escapes the reports directory, does
        not exist, or carries no metadata block.

List all machine manuals in resources/machine_manuals/ (PDF/TXT).

Use before read_manual_excerpt / extract_manual_specs, and pass the
returned filenames exactly as-is.

Returns:
    List of dicts with filename, size_mb, modified, and path.

scope='disk' (default): files under data/signals/ that load_signal can
open — use before loading. scope='memory': signals currently cached in
the in-memory repository with their metadata (signal_id, sampling_rate,
declared unit) — use to see which signal_ids are available for analysis.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    scope: 'disk' for loadable files, 'memory' for loaded signal_ids.

Returns:
    Dict with scope, count, and either 'files' (relative paths, disk)
    or 'signals' (StoredSignalInfo entries, memory).

Once loaded, reference the signal by its signal_id in every analysis,
diagnosis, report, and prognostics tool (the load -> analyze ->
diagnose -> report flow uses signal_id as the single handle).

Batch form: pass a LIST of file paths (e.g. for training sets). The
batch is fail-fast and atomic — all paths and derived ids are
validated up front, and on the first problem ONE error names the
offending entries and nothing is loaded. One declared sampling_rate/
signal_unit applies to all files; per-file metadata wins only when
the parameter is omitted. Custom signal_id is not allowed for a
batch (ids derive from each file's relative path).

signal_id default: the path relative to data/signals/ with separators
replaced by underscores — 'real_train/baseline_1.csv' loads as
'real_train_baseline_1', so same-named files in different folders
never collide silently. Re-loading a path whose id already exists is
an explicit error unless overwrite=True.

Signal unit discipline: ISO 20816-3 severity verdicts require a
DECLARED unit — either via this parameter or a 'signal_unit' field in
the companion _metadata.json (explicit parameter wins). Units are
never guessed from signal amplitude; without a declared unit the ISO
severity block is refused with a structured reason and remedy.

Raw binary files (.bin/.raw/.dat): a headerless raw waveform loads
only with a declared decode contract — sample_format AND
sampling_rate are REQUIRED, either as explicit parameters here or as
fields of the companion <stem>_metadata.json next to the file
(explicit parameter wins). The other raw parameters carry documented
defaults, applied by the repository after that merge: byte_order
'little', n_channels 1, channel_index 0, header_offset 0, no
scale_factor. Integer sample formats (int16/int32) decode to raw ADC
counts — declare scale_factor to convert counts into the declared
physical unit (there is no implicit normalization). In a batch the
raw parameters broadcast to ALL files, exactly like sampling_rate.
Declaring raw parameters for a self-describing format (.csv, .npy,
...) is refused as a contradiction. With n_channels > 1 each load
extracts ONE channel and the DERIVED id gains a _ch<channel_index>
suffix; an explicit signal_id is used verbatim — no suffix applies.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    filepath: Filename relative to data/signals/ or absolute path —
        or a list of such paths for an atomic batch load.
    signal_id: Custom ID (single-file loads only; default derives
        from the relative path).
    sampling_rate: Sampling rate in Hz (overrides metadata file).
        Required for raw binary files (here or in the companion).
    signal_unit: Declared signal unit — 'g' or 'm/s2' (acceleration),
        'mm/s' or 'm/s' (velocity). Overrides the metadata file.
    overwrite: Replace existing entries on signal_id collision
        instead of raising.
    sample_format: Raw files only — declared sample dtype ('float32',
        'float64', 'int16', 'int32'). REQUIRED for .bin/.raw/.dat
        (here or in the companion metadata).
    byte_order: Raw files only — declared endianness ('little' or
        'big'); documented default 'little'.
    n_channels: Raw files only — interleaved channel count in the
        file; documented default 1.
    channel_index: Raw files only — 0-based channel to extract;
        documented default 0.
    header_offset: Raw files only — bytes to skip before the first
        sample; documented default 0.
    scale_factor: Raw files only — optional multiplier applied after
        decoding (e.g. ADC counts -> physical unit); default: no
        scaling.

Returns:
    StoredSignalInfo for a single load; a list of StoredSignalInfo
    (input order) for a batch. Raw loads record the effective decode
    parameters under raw_format.

Raises:
    ValueError: If signal_unit is invalid, the signal data cannot be
        loaded, a signal_id collides without overwrite=True, a batch
        contains any invalid entry (nothing is loaded), a raw binary
        file is missing a required declaration (ONE message names
        everything missing plus both remedies), or raw parameters
        are declared for a self-describing format.

Generate interactive time-domain plot for a stored signal.

Creates an interactive HTML plot showing the signal in the time domain.
Useful for inspecting signal quality, identifying anomalies, and
visualizing transients. Requires the signal loaded via load_signal()
first; the sampling rate comes from the stored signal metadata.

Args:
    signal_id: ID of the stored signal (from load_signal).
    time_range: [start_time, end_time] in seconds to zoom on a portion (optional)
    show_statistics: Show RMS, peak levels as horizontal lines (default: True)
    title: Custom plot title (optional)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Path to generated HTML file

Raises:
    ValueError: If the signal_id is not loaded, or the stored signal
        has no sampling rate.

Example:
    plot_signal(
        "bearing_signal",
        time_range=[0.1, 0.3],  # Zoom on 100-300 ms
        show_statistics=True
    )

Predict anomalies in a stored signal using a trained model.

Requires the signal loaded via load_signal() first and a model
trained via train_anomaly_model (its result echoes the model_name
to pass here). Pipeline: segment -> features -> scaler -> PCA ->
predict -> aggregate.

Output is BOUNDED: counts, anomaly ratio, score percentiles, and
up to 10 worst segments — never per-segment arrays, regardless of
signal length.

Args:
    signal_id: ID of the stored signal to analyze (from load_signal)
    model_name: Name of trained model (default: 'anomaly_model')
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    AnomalyPredictionResult with aggregate statistics and health
    assessment.

Raises:
    FileNotFoundError: If the model does not exist (the message
        lists the models actually on disk).
    ValueError: If the signal_id is not loaded, or no sampling rate
        is available for segmentation.

Read a text excerpt from a machine manual (PDF or TXT).

Use for consecutive-page reading; for targeted questions prefer
search_documentation. Start with max_pages=10 and increase only if
needed (pages consume tokens).

Args:
    file_name: Manual filename in resources/machine_manuals/
        (PDF or TXT)
    max_pages: Maximum pages to extract (ignored for TXT files)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Extracted text from the manual.

Raises:
    FileNotFoundError: If the manual does not exist.

Search for bearing specifications in the local verified catalog.

Fallback for when the machine manual names a bearing but not its
geometry. The catalog is small BY DESIGN: only entries whose
geometry is traceable to a public source (mandatory `source`
citation). A miss is a legitimate negative outcome — ask the user
for the geometry; never guess it.

Args:
    bearing_id: Bearing designation (e.g. "6205", "SKF 6205-2RS")
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with bearing specifications if found, or a
    BearingCatalogMiss (status='not_found', suggestion,
    catalog_contains) when the bearing is not in the catalog.

Raises:
    Exception: If the catalog itself cannot be read (missing or
        malformed common_bearings_catalog.json).

Semantic search across all machine manuals and bearing catalogs.

Uses vector retrieval (RAG) to find the most relevant passages from
PDFs, text files, and JSON catalogs in resources/.

Backends (chosen automatically):
  - FAISS + sentence-transformers  (pip install predictive-maintenance-mcp[vector-search])
  - TF-IDF keyword search          (default, zero extra deps)

The index is built lazily on first call and cached on disk.  It is
automatically rebuilt when source files change.

Args:
    query: Natural-language question or keywords
           (e.g. "bearing 6205 geometry", "maintenance interval pump")
    top_k: Number of passages to return (default: 5)
    force_reindex: Rebuild the index even if cache is fresh (default: False)
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    Dictionary with ranked results, each containing text passage, source
    file, relevance score, and chunk index.

Train ML-based anomaly detection model on healthy data (UNSUPERVISED/SEMI-SUPERVISED).

All signals are referenced by signal_id: load them first with
load_signal — its batch form accepts a list of file paths, e.g.
load_signal(filepath=["real_train/baseline_1.csv", ...]). Each
signal's sampling rate comes from its stored metadata.

Complete pipeline:
1. Extract features from healthy signals (segmentation + time-domain features)
2. Standardize features (StandardScaler - fitted on training data only)
3. Dimensionality reduction (PCA with specified variance explained)
4. Train novelty detection model (OneClassSVM or LocalOutlierFactor) on HEALTHY DATA ONLY
5. Optional hyperparameter tuning using validation data (semi-supervised)
6. Save model, scaler, and PCA transformer

**Training Mode:**
- UNSUPERVISED: Train only on healthy data with automatic hyperparameters
- SEMI-SUPERVISED: Train on healthy data, tune hyperparameters using validation set (healthy + fault)

**Note:** This is NOT supervised learning. OneClassSVM/LOF are trained ONLY on healthy data.
Fault data (if provided) is used ONLY for hyperparameter tuning after training.

**Validation Strategy:**
- If healthy_validation_ids provided: Use those explicitly (no split)
- If healthy_validation_ids NOT provided: Automatic 80/20 split of training data
- If fault_signal_ids provided: Enable semi-supervised mode (hyperparameter tuning)

Args:
    healthy_signal_ids: Stored signal IDs with healthy machine data (for training)
    segment_duration: Segment duration in seconds (default: 0.1)
    overlap_ratio: Overlap ratio 0-1 (default: 0.5)
    model_type: 'OneClassSVM' or 'LocalOutlierFactor' (default: 'OneClassSVM')
    pca_variance: Cumulative variance to explain with PCA (default: 0.95)
    fault_signal_ids: Optional stored signal IDs for HYPERPARAMETER TUNING (semi-supervised)
    healthy_validation_ids: Optional stored healthy signal IDs for validation (specificity check).
                              If not provided, 20% of training data will be used.
    model_name: Name for saved model files (default: 'anomaly_model')
    ctx: MCP context. Unused — see this module's docstring on logging.

Returns:
    AnomalyModelResult with model paths and performance metrics

Raises:
    ValueError: If a signal_id is not loaded or has no sampling rate,
        or model_name/model_type is invalid.