IDKHowToCodeFr/tinyml-backend

1# HeartFlow OS Architecture2 3HeartFlow OS is a distributed Edge AI platform. It bridges the gap between high-level Python MLOps and low-level embedded systems (ESP32/Arduino) by orchestrating live telemetry, automated model training, and zero-dependency C transpilation.4 5## Core Flow Diagrams6 7### 1. Data Cleaning & Feature Selection Pipeline8 9```mermaid10graph TD11    A[Raw CSV Dataset] --> B{Drop Redundant Columns}12    B -->|Remove| C[Patient Number, Alert Flags]13    B --> D[Sanitize Encodings]14    D -->|Fix \ufffd -> °| E[Feature Engineering]15    E -->|Create Risk_Severity| F[Risk_Severity = HR > 105 + SpO2 < 94]16    F --> G[Imputation]17    G -->|SimpleImputer: Mean| H[Scaling]18    H -->|StandardScaler| I[Clean Feature Matrix]19    I --> J[Train / Test Split 80:20]20```21 22### 2. MLOps Background Retraining23 24```mermaid25graph TD26    A[New CSV Upload via UI] --> B(FastAPI /retrain)27    B --> C[Background Thread: train_models]28    C --> D[Preprocess Data & Fit Transformers]29    D --> E[Train 5 Models: KNN, SVM, LogReg, RF, MLP]30    E --> F[Calculate Weighted F1 Score]31    F --> G{Is F1 > Active Version?}32    G -->|Yes| H[Save .pkl files, Update registry.json]33    G -->|No| I[Rollback, Discard Models]34    H --> J[Hot-Reload Live Inference Pipeline]35```36 37### 3. Edge Compilation (TinyML)38 39```mermaid40graph TD41    A[Export Request /export_tinyml] --> B[Load Active .pkl Random Forest]42    B --> C[Traverse AST Trees Recursively]43    C --> D{Quantization Enabled?}44    D -->|Yes| E[Map Float64 to INT8 thresholds]45    D -->|No| F[Keep Float32 thresholds]46    E --> G[Generate C Header: model.h]47    F --> G48    G -->|Zero-Malloc| H[PlatformIO / ESP32 Compile]49```50 51## Detailed Explanations52 53### Data Cleaning and Feature Selection54Raw patient data is noisy and often contains missing or invalid readings. The preprocessing pipeline (`backend/preprocessing.py`) handles this systematically:551. **Dimensionality Reduction**: Redundant or target-leakage columns (like `Heart Rate Alert` or `Patient Number`) are dropped to prevent the model from overfitting on administrative flags.562. **Encoding Fixes**: Unicode corruption (e.g., `\ufffd` instead of `°`) is sanitized.573. **Imputation**: Missing sensor readings are populated using a `SimpleImputer(strategy='mean')`. The imputer is fitted on the training set and serialized to `imputer.pkl` to prevent data leakage during live inference.584. **Feature Engineering**: A custom `Risk_Severity` feature is synthesized by combining critical thresholds: `(Heart Rate > 105) + (SpO2 < 94)`. This gives the decision trees a powerful non-linear hint.595. **Standardization**: All continuous features are scaled to a standard normal distribution via `StandardScaler`, ensuring distance-based algorithms (like KNN and SVM) compute correctly.60 61### Intelligence Pipeline (Ensemble)62HeartFlow doesn't rely on a single algorithm. It trains five distinct models:63- **K-Nearest Neighbors (KNN)**64- **Support Vector Machine (SVM)**65- **Logistic Regression (LogReg)**66- **Random Forest (RF)**67- **Multilayer Perceptron (MLP Neural Network)**68 69During live telemetry inference (`backend/ensemble.py`), the system aggregates the probability vectors from all five models. It performs a **soft-vote**, returning the highest confidence average as the final diagnosis. 70 71### Fault-Tolerant Retraining (MLOps)72When a clinician uploads a new batch of data via the `/mlops` UI, the system trains the entire ensemble in a background thread without dropping live WebSocket connections. 73It evaluates the newly trained models against a 20% holdout test set. If the new `weighted F1-Score` is higher than the `active_version` tracked in `registry.json`, the `.pkl` files are hot-swapped. If the score degrades, the new models are destroyed (Automated Rollback).74 75### Edge Transpilation76Running Python on an ESP32 is too heavy. The `backend/export.py` script traverses the AST (Abstract Syntax Tree) of the trained Scikit-Learn Random Forest and writes pure, `if/else` C++ code into a `model.h` file. 77To shrink the firmware size by 75%, it applies **INT8 Quantization**, scaling floating-point sensor thresholds into 8-bit integers. The resulting inference function uses zero dynamic memory (`malloc`/`free`), ensuring the microcontroller never crashes from heap fragmentation.78