Implementation

Chapter 10 — Implementation

This chapter covers the software architecture that transforms Dibyendu De’s diagnostic philosophy into a production system: the FastAPI service layer, the rule evaluator, the database schema, the API contracts, and the technology stack.

---

Technology Stack

Layer	Technology	Role
Backend API	Python 3.13, FastAPI	Reasoning services, pipeline orchestration
Database	PostgreSQL + pgvector	Relational core + vector similarity for pattern matching
Frontend	SvelteKit, Drizzle ORM	Dashboard UI, asset management
Auth	better-auth	User authentication and session management
Monorepo	Bun workspace	Package management and build tooling
Rule engine	Custom recursive-descent parser	Safe rule evaluation without eval()
Signal processing	NumPy, SciPy	FFT, waveform statistics, spectral analysis
Deployment	Docker + Cloudflare	Containerized services with edge caching

---

The Rule Evaluator

Why Not eval()?

The diagnostic engine evaluates 451+ rules against live sensor data. A naive implementation would parse rule expressions using Python’s eval(). This is a security catastrophe: any rule that contains injected code would execute with full application privileges. It is also an auditability disaster: eval() provides no visibility into what was evaluated or how.

Safe Recursive-Descent Parser

RAPID AI uses a custom recursive-descent parser that handles a restricted expression language:

Supported operations:

• Arithmetic: +, -, *, /
• Comparison: >, >=, <, <=, ==, !=
• Logical: AND, OR, NOT
• Functions: abs(), min(), max(), sqrt(), ln()
• Variables: Named references to sensor features and parameters

Not supported (by design):

• Function calls to arbitrary Python
• Import statements
• Attribute access
• String operations
• Assignment

The parser converts rule expressions from JSON/YAML into Python dictionaries at import time. At evaluation time, it walks the dictionary structure, resolving variable names against the current sensor data context. This ensures:

1. Security: No arbitrary code execution. The worst a malformed rule can do is return an error.
2. Auditability: Every evaluation step is traceable. The system can explain exactly which variables were resolved to which values and which comparisons evaluated to true or false.
3. Performance: Dictionary-based evaluation is fast enough for real-time use. The 119 SENSE rules evaluate in parallel in under 50ms on typical hardware.

Rule Lifecycle

Rule authored (JSON/YAML/CSV)
  -> Parsed at import time (dict structure)
  -> Validated against schema
  -> Stored in rule registry
  -> Evaluated at request time against sensor context
  -> Results include matched rules, scores, and evidence trail

---

FastAPI Service Layer

Project Structure

app/
  api/
    routes.py              # Route handlers
  core/
    config.py              # Environment configuration
  db/
    base.py                # Database models
    session.py             # Connection management
  models/
    normalized_schema.py   # SQLAlchemy models
  repositories/
    reference_repository.py  # Data access layer
  schemas/
    api_models.py          # Pydantic request/response models
  services/
    diagnostics.py         # Module B fault detection logic
    rcm.py                 # Module E RCM decision logic
    maintenance.py         # Module E maintenance planning
    end_to_end.py          # Full pipeline orchestration
main.py                    # Application entry point

Core Endpoints

Endpoint	Method	Purpose
/rapid-ai/evaluate	POST	Flagship — full pipeline (A through E) in one call
/rapid-ai/v2/moduleA	POST	Signal intelligence standalone
/rapid-ai/v2/moduleB	POST	Fault detection standalone
/rapid-ai/v2/moduleC	POST	SSI fusion standalone
/rapid-ai/v2/moduleD	POST	Health staging + RUL standalone
/rapid-ai/v2/moduleE	POST	Maintenance planning standalone
/dashboard/assets/{assetId}/health-card	GET	UI-ready health card payload
/dashboard/plant-overview	GET	Plant-level summary
/reference/failure-modes	GET	Failure mode library browse
/reference/maintenance-tasks	GET	Task catalog browse
/assets/{asset_id}/diagnose	POST	Diagnostic assessment
/assets/{asset_id}/rcm-decision	POST	RCM strategy selection
/assets/{asset_id}/maintenance-plan	POST	Maintenance plan generation
/assets/{asset_id}/end-to-end-evaluate	POST	Complete pipeline evaluation

Flagship Endpoint: POST /rapid-ai/evaluate

The most important endpoint accepts one payload and returns a complete engineering response:

Request:

{
  "asset_id": "P-101A",
  "machine_type": "pump_horizontal",
  "component": "afb",
  "criticality": 0.6,
  "signal": {
    "values": [3.2, 3.1, 3.4],
    "sampling_rate": 2560,
    "signal_type": "velocity",
    "unit": "mm/s",
    "direction": "horizontal"
  },
  "historical_values": [2.8, 2.9, 3.0, 3.1, 3.2],
  "failure_threshold": 7.1
}

Response includes:

• Health stage (Healthy/Degrading/Unstable/Critical)
• Severity level with score 0-1
• Confidence score 0-1
• Fault diagnosis with matched pattern and physics basis
• Priority score 0-100 with action window
• Ranked action plan with justifications
• RUL in days
• 30-day failure probability
• Risk index 0-100
• AI-generated narrative insights

Module-Level Endpoints

The v2 module endpoints allow individual pipeline stages to be called independently. This is valuable for:

• Development: Testing individual modules in isolation
• Debugging: Running Module A to verify data quality before investigating Module B results
• Integration: External systems that only need specific pipeline capabilities
• Performance: Skipping unnecessary pipeline stages when partial results suffice

---

Database Architecture

Three Schema Stacks

The database is organized into three complementary schema stacks:

Stack 1 — Normalized Reference Schema (production runtime)

Eight tables forming the operational backbone, each derived from the IMS:

Table	Purpose	Key Fields
asset_master	Equipment registry	asset_id, class, criticality, location
functional_failures	Function-to-failure mapping	function, performance_standard, functional_failure
failure_modes	Failure mode library (320 modes)	failure_mode, mechanism, detection_method
sensor_evidence_rules	Detection rules per component	sensor_type, evidence_logic, confidence
rcm_rules	RCM decision rules per consequence	consequence_category, strategy, justification
maintenance_tasks	Task catalog (15+ actions)	task_description, skill, duration, tools
dashboard_output_mappings	UI display mapping	widget, message_template, api_field
schema_relation_map	Foreign key relationships	parent_table, child_table, join_column

Stack 2 — Reliability Analysis Schema (analytics)

Sixteen tables for Weibull analysis, survival statistics, and fleet reliability:

Table Group	Purpose
area_master, asset_master	Plant hierarchy context
analysis_request, failure_event	Reliability analysis inputs
runtime_interval, reliability_result	Weibull and survival analysis
metric_result, metric_catalog	MTBF, MTTR, availability computation

Stack 3 — FRETTLSM Causal Schema (causal intelligence)

UUID primary keys designed for causal analysis and failure envelope tracking:

Table	Purpose
analysis_profile	Per-asset FRETTLSM evaluation snapshots
contradiction_frame	Engineering contradictions detected by Module G
failure_envelope	Composite envelope scores and stability trends
imperfection_record	Identified structural weaknesses
resolution_state	Tracking status of recommended actions
causal_propagation_node	Nodes in the causal pathway graph

Seed Data

The database ships with comprehensive seed data:

• 320 failure modes across 19 equipment families (from failure_modes_full_320_seed.sql)
• 100 IMS rows decomposed into normalized schema records
• Equipment type mappings bridging asset categories to rule sets
• Failure mode ID bridges connecting the three schema stacks

All seed data is loaded via 00_run_all_seed_inserts.sql, which executes the individual seed files in dependency order.

pgvector for Pattern Matching

PostgreSQL’s pgvector extension enables vector similarity search for diagnostic pattern matching. When Module B evaluates a new vibration signature, it can compare the feature vector against a library of known fault signatures using cosine similarity. This provides a second opinion alongside the physics-based rules: “This pattern is 94% similar to IMS002 (bearing outer race spalling) based on vector distance.”

---

Service Engines

SEDL Engine (Module B.3)

The SEDL (Spectral-Temporal-Differential Entropy Layer) engine computes the three entropy metrics from raw signal data:

1. Compute FFT of time waveform
2. Normalize power spectral density to probability distribution
3. Compute SE = -Sum(p_i * ln(p_i)) / ln(N)
4. Partition time waveform into amplitude bins
5. Compute TE from amplitude distribution
6. Compute DE from tri-axial energy ratios
7. Compute SI = 1 - (0.5SE + 0.3TE + 0.2*DE)
8. Compute dSE/dt from previous evaluation
9. Evaluate state rules SR01-SR05

Fusion Engine (Module C)

The fusion engine aggregates component blocks into SSI:

1. Load system profile for asset type (e.g., PROFILE_PUMP_A)
2. For each component block, evaluate BSR001-BSR007 (first match wins)
3. Compute block_score for each component
4. Compute SSI = weighted average of block scores
5. Apply Critical_Instability override if B.3 reports critical state
6. Evaluate CST001-CST004 to determine System_State
7. Rank top contributors by block_score * weight

RUL Engine (Module F)

The RUL engine combines trend-based and Weibull-based estimates:

Canonical reference: See Chapter 25 for the authoritative Weibull adjustment formulas.

1. Look up base Weibull parameters for component type
2. Compute condition-adjusted parameters: beta_adj, eta_adj
3. Compute RUL_weibull from adjusted Weibull
4. Compute RUL_trend from Module B.2 slope extrapolation
5. Apply NLI adjustment if non-linearity is high
6. Apply health stage multiplier from Module D
7. Return min(RUL_weibull, RUL_trend) as conservative estimate
8. Compute P_30 and Risk_Index

CDE Engine (Module G)

The CDE engine runs only when triggered:

1. Check trigger conditions (recurrence, sustained alarm, high impact, opposing trends)
2. Evaluate each of the 8 contradiction types (CT01-CT07) against evidence
3. For matched contradictions, classify using IAR model
4. Select resolution pattern from 7 templates
5. Estimate ROI of proposed design change
6. Generate engineering recommendation with evidence trail

Causal Engine (FRETTLSM)

The causal engine evaluates the 88-factor taxonomy:

1. Load asset class template (e.g., centrifugal pump -> 41 active factors)
2. For each active factor, evaluate threshold against available data
3. Classify active factors as I, A, or R based on context
4. Compute factor scores (activation_weight * influence_weight * threshold_exceedance)
5. Build failure envelope (ranked active factors)
6. Identify missing retarders (factors with R classification that are below minimum protection threshold)
7. Generate causal analysis report

---

API Documentation

OpenAPI Specification

The API is documented via an OpenAPI 3.0 YAML specification (openapi_rapid_ai.yaml) with a companion Postman collection (postman_collection_rapid_ai.json) for interactive testing.

Endpoint Contract Summary

Every endpoint follows a consistent contract:

• Authentication: Bearer token (better-auth JWT)
• Content-Type: application/json
• Error responses: Standard HTTP status codes with JSON error body
• Pagination: Offset/limit for list endpoints
• Filtering: Query parameters for reference endpoints (by asset_type, by component, etc.)

API Versioning

The API supports two generations:

• v1 (modular): One endpoint per pipeline module, useful for development
• v2 (consolidated): Production-facing flagship endpoints

Both versions coexist, allowing frontend and integration teams to migrate at their own pace.

---

Configuration and Settings

All threshold values, Weibull parameters, weights, and constants live in a single source of truth: rapid/engine/settings.py. Values are never hardcoded elsewhere. This means:

• Adjusting a threshold requires changing one number in one file
• All modules read from the same source, preventing drift
• Settings can be overridden per-tenant or per-asset via configuration API (Module 0)

The settings file contains: ISO zone boundaries, kurtosis thresholds, crest factor thresholds, entropy thresholds, BSR rule parameters, CST boundaries, HSR boundaries, Weibull base parameters, adjustment coefficients, priority score weights, and all hysteresis parameters.

---

Reference Implementation: FastAPI Diagnostic Endpoint

"""RAPID AI — FastAPI diagnostic endpoint reference.
Shows the API contract for submitting vibration data and receiving diagnosis.
"""
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="RAPID AI Diagnostic Engine", version="2.0.0")

class VibrationInput(BaseModel):
    asset_id: str
    measurement_point: str
    signal_type: str = Field(description="velocity | acceleration | displacement")
    unit: str = Field(description="mm/s | g | µm")
    sampling_rate_hz: float
    values: list[float]
    rpm: float | None = None
    temperature_c: float | None = None

class DiagnosticResponse(BaseModel):
    asset_id: str
    quality_score: float
    iso_zone: str
    faults: list[dict]
    ssi: float
    health_state: str
    rul_hours: float | None
    priority_score: float
    recommended_actions: list[str]
    confidence: float
    timestamp: str

@app.post("/api/v1/diagnose", response_model=DiagnosticResponse)
async def diagnose(input: VibrationInput):
    """Run full RAPID AI diagnostic pipeline on vibration data.

    Pipeline: GUARD → SENSE → FUSE → ACT
    """
    # Module A: GUARD (validate + extract features)
    # Module B: SENSE (detect faults, classify trends)
    # Module B.3: SEDL entropy
    # Module C: SSI fusion
    # Module D: Fault diagnosis
    # Module E: Severity assessment
    # Module F: RUL estimation
    # Module G: Design-out recommendations
    ...

---

The implementation layer transforms the domain frameworks and diagnostic philosophy into production software. The next chapter presents what RAPID AI looks like as a deployed product — the dashboard, the alerts, the workbooks, and the copilot interface.

---

Next: Chapter 11 — Product Vision Previous: Chapter 9 — RCM Framework

---

Standards Alignment

Standard	Relevance to This Chapter
ISO 13374 — Condition monitoring and diagnostics of machines	The software implementation directly realizes ISO 13374’s six processing levels through the FastAPI pipeline modules (A through G), with the rule evaluator providing the computational mechanism for Levels 2-6.
MIMOSA OSA-CBM — Open System Architecture for CBM	The API-first architecture and modular pipeline design align with OSA-CBM’s interoperability requirements, enabling integration with existing plant historians and CMMS systems.
OWASP Top 10 — Web application security	The safe recursive-descent rule parser (no eval()) directly addresses OWASP A03:2021 (Injection). The IP protection boundary enforces data separation consistent with secure API design principles.
IEC 62443 — Industrial cybersecurity	The separation between protected internal logic and exposed client outputs implements defense-in-depth consistent with IEC 62443’s zone and conduit model for industrial control system security.

Changelog

Version	Date	Author	Changes
2.1.0	2026-03-17	Rick D	Added standards alignment, living doc metadata, changelog
2.0.0	2026-03-17	Rick D	Enriched with production codebase content
1.0.0	2026-03-17	Rick D	Initial chapter creation