Upload folder using huggingface_hub

ARCHITECTURE.md

@@ -1,13 +1,14 @@
-# HEARTFLOW_OS // System Architecture
+# HEARTFLOW_OS // System Architecture & Engineering Topography
 
-## Overview
-HeartFlow OS is an end-to-end, edge-optimized clinical telemetry pipeline. The system bridges the gap between high-level cloud machine learning and low-level embedded hardware, enabling real-time clinical inference and automated C-code transpilation for resource-constrained microcontrollers (TinyML).
+## 📌 Executive Summary
 
-The architecture adheres to a decoupled, modular design pattern split into three primary planes: **Client (Frontend)**, **Core (Backend)**, and **Edge (Hardware Compilation)**.
+HeartFlow OS is a distributed, edge-optimized telemetry pipeline designed for clinical-grade cardiovascular inference. The architecture addresses the inherent tension between heavy-compute machine learning paradigms and the constrained environments of low-power microcontrollers (TinyML).
+
+By aggressively decoupling the presentation layer (Client), the orchestration and modeling engine (Core), and the physical target execution (Edge), the system achieves strict separation of concerns, high-throughput asynchronous concurrency, and near-zero downtime deployment of predictive models.
 
 ---
 
-## Architecture Diagram
+## 🏗 High-Level Architecture Diagram
 
 ```mermaid
 graph TD
@@ -18,81 +19,86 @@ graph TD
     classDef edge_tech fill:#f3f3f2,stroke:#111,stroke-width:2px,color:#111,font-family:monospace;
     classDef data fill:#94a3b8,stroke:#475569,stroke-width:2px,color:#fff,font-family:monospace;
 
-    subgraph Client [Client Application]
-        UI[Next.js 16 UI / Dashboard]:::frontend
-        WS_Client[WebSocket Client]:::frontend
-        HTTP_Client[HTTP Client]:::frontend
+    subgraph Client [Client Application / Next.js 16]
+        UI[React 19 Dashboard]:::frontend
+        WS_Client[WebSocket Context]:::frontend
+        HTTP_Client[Axios/Fetch HTTP]:::frontend
     end
 
-    subgraph Core [FastAPI Backend]
-        WS_Server[WebSocket Feed / Generator]:::backend
-        REST_API[REST API Router]:::backend
-        Inference[Inference Engine / Preprocessor]:::backend
-        MLOps[MLOps Pipeline]:::backend
-        DB[(aiosqlite)]:::backend
+    subgraph Core [FastAPI Core / Python 3.10+]
+        WS_Server[Async WebSocket Broker]:::backend
+        REST_API[RESTful API Router]:::backend
+        Inference[Stateful Inference Preprocessor]:::backend
+        MLOps[Background MLOps Engine]:::backend
+        DB[(aiosqlite Asynchronous DB)]:::backend
     end
 
-    subgraph ML_Layer [Intelligence Pipeline]
-        Ensemble{Soft-Voting Ensemble}:::ml_node
+    subgraph ML_Layer [Intelligence Pipeline / Scikit-Learn]
+        Ensemble{Soft-Voting Aggregator}:::ml_node
         Models[RF, SVM, KNN, LogReg, MLP]:::ml_node
-        SHAP[SHAP Explainer]:::ml_node
-        EdgeCompiler[INT8 C-Compiler AST]:::ml_node
+        SHAP[SHAP Feature Explainer]:::ml_node
+        EdgeCompiler[INT8 AST C-Compiler]:::ml_node
     end
 
-    subgraph Hardware [Edge Target]
+    subgraph Hardware [Edge Target / Embedded Silicon]
         HEADER((tinyml_model.h)):::edge_tech
-        MCU[ESP32 / Cortex-M]:::edge_tech
+        MCU[ESP32 / Cortex-M Node]:::edge_tech
     end
 
-    subgraph Storage [Persistent Storage]
-        ModelWeights[Trained Weights .pkl]:::data
-        CSV[Patient Dataset .csv]:::data
+    subgraph Storage [Persistent Persistence Layer]
+        ModelWeights[Serialized Weights / LRU .pkl]:::data
+        CSV[Immutable Patient Dataset .csv]:::data
     end
 
-    %% Flow
-    UI -->|React 19 / Framer| WS_Client
-    UI -->|User Interaction| HTTP_Client
+    %% Edge Flows
+    UI -->|Framer Motion Layouts| WS_Client
+    UI -->|Config / Retrain Requests| HTTP_Client
     
-    WS_Client <-->|ws:// Live Telemetry| WS_Server
+    WS_Client <-->|ws:// 60Hz Telemetry Stream| WS_Server
     HTTP_Client -->|POST /retrain, GET /export| REST_API
     
-    WS_Server -->|Evaluates Vitals| Inference
-    REST_API -->|Triggers Retrain| MLOps
-    REST_API -->|Requests Header| EdgeCompiler
+    WS_Server -->|Event Loop Execution| Inference
+    REST_API -->|Threaded Task| MLOps
+    REST_API -->|Triggers Generation| EdgeCompiler
     
-    Inference -->|Predicts| Ensemble
+    Inference -->|Standardized Vector| Ensemble
     Ensemble --> Models
     Ensemble --> SHAP
     
-    MLOps -->|Writes| ModelWeights
-    MLOps -->|Appends| CSV
-    EdgeCompiler -->|Reads| Models
-    Inference -->|Reads| ModelWeights
+    MLOps -->|LRU State Override| ModelWeights
+    MLOps -->|Append Only| CSV
+    EdgeCompiler -->|Parses Structure| Models
+    Inference -->|Reads Memory-Mapped| ModelWeights
     
-    EdgeCompiler -->|Transpiles| HEADER
-    HEADER -.->|Flashed to| MCU
+    EdgeCompiler -->|Emits Dependency-Free C| HEADER
+    HEADER -.->|Flash via UART| MCU
 ```
 
 ---
 
-## 1. Client Plane (Frontend)
-Engineered using **Next.js 16 (App Router)** and **React 19**. 
-- **Design System:** Strict Industrial Brutalist aesthetic utilizing hard grids, monochromatic blueprints (`bg-canvas-cream`, `text-ink`), and high-contrast hazard states.
-- **State Management:** React Context API manages high-frequency telemetry streams.
-- **Data Transport:** Real-time data is ingested via native WebSockets (`ws://`), bypassing HTTP overhead for continuous vital monitoring.
-- **Animations:** Hardware-accelerated SVG manipulations and layout transitions powered by `framer-motion`.
-
-## 2. Core Plane (Backend)
-Built on **FastAPI** (Python 3.10+), maximizing asynchronous throughput.
-- **WebSocket Generator:** A state-machine driven data simulator generates correlated, volatile telemetry streams (simulating clinical episodes like Asthma or Heart Disease).
-- **Inference Preprocessor:** Live patient data is standardized and imputed using a persistent `SimpleImputer` and `StandardScaler` trained on the original dataset, ensuring inference dimensions perfectly match the training phase.
-- **Storage:** Employs `aiosqlite` for non-blocking, asynchronous database writes to track historical patient classifications without stalling the event loop.
-
-## 3. Intelligence Pipeline (MLOps)
-- **Ensemble Architecture:** Achieves clinical-grade precision via a 5-model soft-voting ensemble (`RandomForest`, `SVM`, `KNN`, `LogisticRegression`, `MLPClassifier`).
-- **Batch Retraining:** Exposes a robust `/retrain` pipeline allowing direct CSV uploads. The pipeline safely joins the schemas, automatically updates `patient_dataset.csv`, fits new scalers/imputers, retraining all models in a `BackgroundTask` thread, and hot-swaps the `EnsembleModel` globally with zero downtime.
-
-## 4. Edge Compilation (TinyML)
-- **Zero-Dep C-Headers:** The backend transpiles trained SciKit-Learn tree models directly into standalone `C` functions. 
-- **INT8 Quantization:** Floating-point weights and decision thresholds are algorithmically compressed (quantized) into 8-bit integers, effectively shrinking the flashed payload by ~75%.
-- **Target:** Designed to run strictly on MCU SRAM without dynamic memory allocation (no `malloc`), perfect for resource-constrained nodes like the ESP32 or Cortex-M4.
+## 1. The Presentation Layer (Client Plane)
+Engineered using **Next.js 16 (App Router)** and **React 19**.
+
+- **Rendering Strategy:** Heavily leverages React Server Components (RSC) where applicable, while isolating stateful, high-frequency telemetry updates to optimized Client Components.
+- **WebSocket Triage:** Bypasses standard HTTP overhead by multiplexing telemetry streams via native WebSockets (`ws://`). The stream is mapped into a React Context provider, aggressively memoized using `useMemo` and `useCallback` to prevent unnecessary DOM re-renders and React thrashing at 60Hz.
+- **Visual Engineering:** Implements an Industrial Brutalist design language. All animations and Layout Transitions are hardware-accelerated (`transform`/`opacity` driven) utilizing `framer-motion` to maintain 60fps even under heavy CPU charting loads.
+
+## 2. The Orchestration Engine (Core Plane)
+Built entirely asynchronously on top of **FastAPI** (Python 3.10+).
+
+- **Asynchronous Throughput:** Utilizing the `asyncio` event loop and `uvicorn`, the backend comfortably supports multiple concurrent clinical WebSocket connections. I/O-bound operations (database writes) are completely non-blocking.
+- **Stateful Preprocessing:** Live data must match the exact multi-dimensional space the models were trained on. The backend retains a persistent `SimpleImputer` and `StandardScaler`, ensuring live inference vectors are identical in scale to the offline batch data without runtime data leakage.
+- **Event-Driven Database:** Implements `aiosqlite` for non-blocking audit logging of predictions, ensuring the primary telemetry event loop is never stalled by disk I/O.
+
+## 3. Intelligence Pipeline & MLOps
+Designed for precision and zero-downtime deployment.
+
+- **Distributed Soft-Voting:** Rather than relying on a monolithic architecture, inference is distributed across five orthogonal models (`RandomForest`, `SVM`, `KNN`, `LogisticRegression`, `MLPClassifier`). A soft-voting aggregator calculates the weighted probability distribution, offering a confidence interval rather than a binary black-box output.
+- **Live Background Retraining:** The `/retrain` pipeline exposes an API for ingesting new clinical datasets. Upon payload validation, it spins up a `fastapi.BackgroundTasks` thread. The system dynamically updates imputers, recalculates decision boundaries across all 5 models, serializes the updated weights to disk (`.pkl`), and critically—hot-swaps the active `EnsembleModel` object in RAM. This ensures active patient telemetry sessions are never dropped during model redeployments.
+
+## 4. The Edge Compilation Pipeline (TinyML)
+The most critical engineering bottleneck in telemetry is getting heavy Python models onto $2 silicon.
+
+- **AST-Based C-Transpilation:** Instead of running a heavyweight Python interpreter (like MicroPython) on the edge device, the backend parses the scikit-learn model's internal Abstract Syntax Trees (AST) and transpiles them directly into pure, statically typed `C` functions.
+- **Zero-Dependency Guarantee:** The resulting `tinyml_model.h` file requires no external libraries. It bypasses `malloc()` completely, relying entirely on static stack allocation, eliminating the risk of heap fragmentation or memory leaks in long-running embedded nodes.
+- **INT8 Quantization:** 64-bit floating point weights are mathematically clamped and scaled into 8-bit integers (`int8_t`). This quantization dramatically reduces flash storage requirements by up to ~75% and massively accelerates inference execution time on ALU architectures lacking dedicated floating-point hardware (FPU).

DESIGN.md

@@ -1,55 +0,0 @@
-# Design System: HeartFlow OS
-
-## 1. Visual Theme & Atmosphere
-A restrained, highly dense utilitarian interface engineered for clinical telemetry. The atmosphere is precise, unornamented, and cockpit-dense — like a modern piece of medical hardware. It abandons marketing fluff (drop shadows, massive radii, neon glows) in favor of absolute data legibility, 1px structural hairlines, and muted semantic pastels.
-
-- **DESIGN_VARIANCE: 6** — Asymmetric bento grids, strict baseline rhythms.
-- **MOTION_INTENSITY: 5** — Restrained. Staggered reveals and layout-fluidity for data changes, but no perpetual decorative loops.
-- **VISUAL_DENSITY: 8** — Cockpit-dense. Maximum data visibility without visual collision.
-
-## 2. Color Palette & Roles
-- **Clinical Canvas** (`#FBFBFA`) — Primary background surface for the application root.
-- **Pure Surface** (`#FFFFFF`) — Card and container fill.
-- **Ink Black** (`#141413`) — Primary text, CTAs, and active focus rings.
-- **Slate Gray** (`#696969`) — Secondary text, metadata, tabular headers, and decorative icons.
-- **Whisper Border** (`#EAEAEA`) — Card borders, dividers, 1px structural lines. No shadows.
-- **Risk Pastel** (`#FDEBEC` bg / `#9F2F2D` text) — Semantic warning state (e.g., At-Risk predictions).
-- **Healthy Pastel** (`#EDF3EC` bg / `#346538` text) — Semantic success state.
-- **Soft Bone** (`#F4F4F4`) — Neutral tertiary state or loading badges.
-
-## 3. Typography Rules
-- **Display:** `Geist` or `Outfit` (sans-serif) — Track-tight (`-0.02em`), controlled scale, weight-driven hierarchy (Medium 500 for headers).
-- **Body:** `Geist` or `Outfit` — Relaxed leading (`1.5`), `450` weight, Slate Gray.
-- **Data / Numbers:** `Geist Mono` or Tabular-Nums on the sans font — Mandatory for all live telemetry, timestamps, and confidence percentages to prevent horizontal layout jitter.
-- **Banned:** Generic serifs (`Times New Roman`, `Georgia`) are banned in this software UI. Generic `Inter` is discouraged in favor of `Geist` for a more precise technical aesthetic.
-
-## 4. Component Stylings
-- **Buttons:** Flat, Ink Black fill. Border radius of `6px` or `8px`. Tactile `scale(0.98)` push feedback on active state. No neon outer glows, no massive pills (999px) in the dashboard.
-- **Cards (Bento Grid):** Crisp `12px` or `8px` corners. Strict `1px solid #EAEAEA` border. Absolutely zero drop shadows (`shadow-none`). 
-- **Inputs & Navigation:** Focus states must use a harsh, highly-visible 2px ring (`focus-visible:ring-2 focus-visible:ring-[#141413]`). Label above, error below.
-- **Loaders:** Skeletal shimmer matching exact layout dimensions. No generic circular spinners.
-- **Status Pills:** Small, dense (`text-[11px]`), uppercase with wide tracking (`0.05em`), using the muted semantic pastels above.
-
-## 5. Layout Principles
-- **Macro-Whitespace:** 8-point baseline grid. Generous internal padding inside cards (`p-8`), but tightly packed grids (`gap-6`).
-- **No Overlapping Elements:** Every element occupies its own clear spatial zone. No absolute-positioned content stacking.
-- **Bento Constraints:** The layout must adapt exactly to the number of data panels. No empty slots.
-- **Responsive Strictness:** Multi-column layouts must explicitly collapse to a single column below 768px. No horizontal scroll on mobile.
-- **Height Constraints:** Full-height views must use `min-h-[100dvh]` to avoid iOS Safari address bar jumps.
-
-## 6. Motion & Interaction
-- **Physics Engine:** Spring physics for all interactive layout shifts (`stiffness: 100, damping: 20`). No linear easing.
-- **Staggered Orchestration:** List items and bento cards enter via a subtle `translateY(12px)` + `opacity: 0` staggered cascade. Never mount the full dashboard instantly.
-- **Hardware Acceleration:** Animate exclusively via `transform` and `opacity`. 
-- **Accessibility Sync:** Interactive layout shifts must respect `prefers-reduced-motion`. Live data must have `aria-live="polite"` so motion isn't the only indicator of change.
-
-## 7. Anti-Patterns (BANNED)
-- **NO emojis anywhere.** Use Phosphor, Lucide, or Radix UI icons.
-- **NO generic purple/blue neon glows** or gradient meshes.
-- **NO pure black** (`#000000`).
-- **NO drop shadows** (`shadow-md`, `shadow-lg`, etc.). Elevation is handled by 1px borders.
-- **NO fake placeholder names** (John Doe, Acme).
-- **NO unstyled focus states.** 
-- **NO AI copywriting clichés** ("Elevate", "Seamless", "Unleash").
-- **NO "Inter" font** as the default assumption; enforce Geist/Outfit.
-- **NO non-tabular numbers** for live updating data.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeartFlow OS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,9 +7,9 @@ sdk: docker
 pinned: false
 ---
 
-# HEARTFLOW_OS // TinyML Heart Health Telemetry
+# HEARTFLOW_OS // Edge-Native Cardiovascular Telemetry
 
-A production-ready, edge-optimized application for real-time cardiovascular analytics. It bridges the gap between cloud-scale machine learning and low-level embedded hardware by deploying soft-voting ensembles and automated C-code transpilation for resource-constrained IoT systems.
+A production-grade, edge-optimized application for real-time cardiovascular telemetry and predictive diagnostics. HeartFlow OS bridges cloud-scale machine learning with low-level embedded constraints by transpiling soft-voting ensembles directly into zero-dependency, statically allocated C-code for microcontroller deployment.
 
 ![Next.js](https://img.shields.io/badge/Next.js-16+-black.svg?style=flat&logo=next.js)
 ![React](https://img.shields.io/badge/React-19-61DAFB.svg?style=flat&logo=react)
@@ -19,56 +19,68 @@ A production-ready, edge-optimized application for real-time cardiovascular anal
 
 ---
 
-## Overview
+## 🚀 Overview
 
-HEARTFLOW_OS is designed for clinical telemetry monitoring. It evaluates live patient vitals using an ensemble of classifiers, provides diagnostic probability distributions, and physically compresses these Python-trained models into raw C-code headers ready to be flashed directly onto edge silicon (e.g., ESP32, Arduino Nano).
+HeartFlow OS is engineered for high-frequency clinical telemetry. It ingests live patient vitals via WebSockets, evaluates telemetry against an ensemble of distributed classifiers to compute diagnostic probability distributions, and physically compresses these complex mathematical models into raw C-code headers ready to be flashed onto constrained edge silicon (e.g., ESP32, Cortex-M series).
 
 ### Key Engineering Features
 
-- **Industrial Brutalist Frontend**: A high-performance, cockpit-dense Next.js 16 UI using native WebSockets and React 19 to render 60fps SVG telemetry sweeps without dropping frames.
-- **Edge Computing & TinyML**: Transpiles complex Scikit-Learn models into highly optimized, dependency-free **C-code headers**. Bypasses dynamic memory allocation entirely.
-- **INT8 Quantization Engine**: Mathematically scales 64-bit floating-point weights down to 8-bit integers, shrinking the flash memory payload by **~75%** for constrained microcontrollers.
-- **Soft-Voting Ensemble**: Aggregates predictions across five independent models (Random Forest, SVM, KNN, Logistic Regression, MLP Neural Network) to output robust probability distributions rather than black-box binary answers.
-- **Zero-Downtime MLOps Pipeline**: Features a dedicated `/retrain` pipeline allowing dynamic CSV uploads. It validates schemas, imputes missing data, retrains the entire ensemble in a background thread, and hot-swaps the intelligence engine globally without dropping active WebSocket connections.
+- **High-Throughput Telemetry Interface:** A highly optimized Next.js 16 dashboard utilizing native WebSockets and React 19 to render 60fps SVG telemetry sweeps with near-zero latency or dropped frames.
+- **Edge Inference & TinyML:** Transpiles sophisticated `scikit-learn` models into highly optimized, dependency-free C-code. Designed with strict spatial and temporal constraints in mind, bypassing dynamic memory allocation entirely (`malloc`-free).
+- **INT8 Quantization Engine:** Algorithmically scales 64-bit floating-point weights and biases down to 8-bit integers, effectively shrinking the flashed payload memory footprint by ~75% without significant accuracy degradation.
+- **Soft-Voting Ensemble:** Fuses predictions from five discrete model architectures (Random Forest, SVM, KNN, Logistic Regression, MLP Neural Network) to generate resilient probability distributions, mitigating the variance and biases of individual black-box models.
+- **Zero-Downtime MLOps:** Integrated `/retrain` pipeline allowing for real-time schema validation, data imputation, and background ensemble retraining. Hot-swaps the underlying intelligence engine globally without interrupting active clinical WebSocket streams.
 
-## Architecture
+---
+
+## 🏗 System Architecture
 
-The project follows a decoupled, modular design pattern split between a React Client, a FastAPI Core, and an Edge Compiler.
+The architecture adheres to a strictly decoupled, service-oriented design pattern split across the Client (React), the Core (FastAPI), and the Edge (C-Compiler).
 
-For a comprehensive deep-dive into the data flows and system topography, refer to the [ARCHITECTURE.md](./ARCHITECTURE.md) document.
+For a deep-dive into system topography, data flows, and design rationale, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 
-### Repository Structure
+### Repository Topology
 
 ```text
 HEARTFLOW_OS/
-├── backend/               # FastAPI server, ML pipelines, aiosqlite, Edge C-compiler
-│   ├── ensemble.py        # Core intelligence and prediction aggregations
-│   ├── main.py            # Websocket feeds, REST APIs, and background tasks
-│   └── preprocessing.py   # MLOps data imputation, scaling, and state preservation
-├── frontend/              # Next.js 16 UI, React Context, framer-motion components
-│   ├── src/app/           # Dashboard, Simulator, MLOps, and Architecture routes
-│   └── src/components/    # Reusable brutalist UI components (Vitals, Graphs)
-├── model/                 # Local cache of serialized SciKit-Learn .pkl weights
-└── data/                  # Base patient cohort CSVs for MLOps retraining pipelines
+├── backend/               # FastAPI core, aiosqlite, async ML pipelines, C-compiler
+│   ├── ensemble.py        # Core intelligence and soft-voting aggregations
+│   ├── main.py            # Websocket ingress, REST APIs, and background routines
+│   └── preprocessing.py   # State-preserving MLOps data imputation and scaling
+├── frontend/              # Next.js 16 UI, React Context, Framer Motion
+│   ├── src/app/           # Route segments (Dashboard, Simulator, Architecture)
+│   └── src/components/    # Memoized, brutalist UI components for 60fps rendering
+├── model/                 # Local LRU cache of serialized model states (.pkl)
+└── data/                  # Immutable patient cohort datasets for MLOps
 ```
 
-## Quickstart
+---
+
+## 🛠 Quickstart Guide
 
-### 1. Initialize Backend
+### 1. Initialize the Core (Backend)
+Requires Python 3.10+
 ```bash
 cd backend
-python -m venv venv
-source venv/bin/activate  # Or `.\venv\Scripts\activate` on Windows
+python -m venv .venv
+source .venv/bin/activate  # Windows: `.\.venv\Scripts\activate`
 pip install -r requirements.txt
-python models.py  # Initial train of the base ensemble
+python models.py           # Initialize database and train the baseline ensemble
 uvicorn main:app --reload --port 8000
 ```
 
-### 2. Initialize Frontend
+### 2. Initialize the Client (Frontend)
+Requires Node.js 18+
 ```bash
 cd frontend
 npm install
 npm run dev
 ```
 
-The system will boot on `localhost:3000`. Connect to view the live dashboard streams and access the MLOps retraining interfaces.
+The system will boot on `localhost:3000`. Navigate to the dashboard to monitor live telemetry streams, access MLOps pipelines, and export INT8 TinyML headers.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.