How santhosh071/ecg-arrhythmia-detection works
1. Overall shape
- This repo is a layered ECG decision-support system, not just a model project.
- The main runtime path is: raw MIT-BIH ECG data → preprocessing → beat-level inference → session risk scoring → clinical agent/actions → API/dashboard presentation.
- There is a clear split between offline work (data prep, training, evaluation) and online work (FastAPI serving, Streamlit UI, agent tools, persistence).
2. Layer 1: data acquisition
- src/layer1_data/download_mitbih.py handles fetching the MIT-BIH Arrhythmia dataset.
- The raw dataset is the source boundary for the system; everything downstream assumes 360 Hz ECG recordings from PhysioNet/MIT-BIH.
3. Layer 2: preprocessing
- src/layer2_preprocessing/preprocess_mitbih.py converts raw ECG into model-ready beat windows.
- The README describes the key signal-processing steps: bandpass filtering, baseline correction, R-peak detection, beat segmentation, and normalization.
- This is the bridge from continuous ECG waveforms to per-beat tensors used by the classifiers and autoencoder.
4. Layer 3: model inference core
- src/layer3_models/cnn.py is the main 8-class beat classifier.
- src/layer3_models/transformer_ae.py, lstm_ae.py, and vae.py support anomaly-detection research and baselines.
- src/layer3_models/inference/ is the production inference boundary:
- model_loader.py loads trained artifacts,
- preprocess.py prepares incoming beats,
- predict.py runs classification/anomaly scoring,
- result_schema.py standardizes outputs for the API and dashboard.
- The core decision rule is dual-path: CNN class prediction plus autoencoder reconstruction error, then merged into a single anomaly/session result.
5. Model/decision flow
- The system does not stop at classifying one beat.
- Beat outputs are aggregated into a session-level assessment: anomaly rate, dominant arrhythmia patterns, and final risk tier.
- The README’s risk logic is part of the architecture: the classifier/AE feed a rule-based risk layer that escalates to Low/Medium/High/Critical.
6. Layer 4: clinical agent
- src/layer4_agent/agent.py is the orchestration layer for clinical reasoning and action selection.
- agent_tools.py exposes the system’s functional tools, such as risk assessment, history lookup, trend monitoring, sensor-quality checks, alerting, and report generation.
- llm_config.py suggests the LLM backend is configurable, with online Groq/LLaMA3 usage and an offline fallback described in the README.
- memory.py provides short-term conversation state, while long-term context is persisted externally via storage.
7. Layer 5: dashboard/UI
- src/layer5_dashboard/app.py is the Streamlit entrypoint.
- Supporting modules split the UI into focused panels: ECG waveform plotting, alert feed, patient history/trends, and clinician chat.
- This layer is a consumer of backend outputs; it visualizes beat classifications, anomaly flags, risk state, chat responses, and report-ready summaries.
8. API boundary
- api/main.py is the FastAPI backend entrypoint.
- api/dependencies.py likely wires shared objects such as loaded models, the agent, config, and storage access into request handlers.
- api/schemas.py defines request/response contracts for endpoints like prediction, agent query, report generation, signal quality, and history lookup.
- This is the main integration boundary between external clients and the internal model/agent layers.
9. Persistence and artifacts
- The README describes SQLite-backed patient sessions, alerts, trends, and agent logs, plus filesystem outputs for alerts and PDF reports.
- Even though src/layer6_storage/ is minimal in the tree, storage is an explicit architectural concern: long-term state lives outside the request process.
- This separates transient inference/chat memory from durable clinical history.
10. Evaluation and offline experimentation
- evaluation/evaluate_models.py and evaluation/evaluation_report.py are offline analysis tools for model metrics and report generation.
- The notebooks under notebooks/ are training workspaces for CNN, LSTM AE, Transformer AE, and VAE experiments.
- These are not part of the serving path; they produce the model artifacts and metrics that the runtime depends on.
11. Configuration and operational concerns
- config/config.py and config/logger.py centralize environment-driven settings and logging.
- .env.template shows the main runtime dependencies: Groq API key/model, project paths, model paths, and DB location.
- run.py is the top-level orchestration entrypoint for launching the system together.
12. Tests and validation boundaries
- The test suite is organized around the architecture: inference tests, agent tests, and full integration tests.
- tests/test_inference.py, tests/test_agent.py, and tests/test_integration.py verify the critical pipeline seams rather than just isolated functions.
- That makes the repo’s diagram best drawn as a pipeline of distinct layers with explicit integration points at preprocessing, inference, agent tools, API, and storage.
Main entry points: predict.py Predict · main.py FastAPI app · agent.py Clinical agent · app.py Streamlit app
Components 19
Offline work
Data acquisition, preprocessing, training, and evaluation
- MIT-BIH fetch · Downloads the raw MIT-BIH Arrhythmia dataset as the source ECG boundary
src/layer1_data/download_mitbih.py - Beat prep · Filters, detects R-peaks, segments beats, and normalizes ECG windows
src/layer2_preprocessing/preprocess_mitbih.py - CNN classifer · Main multi-class beat classifier used for arrhythmia detection
src/layer3_models/cnn.py - AE models · Alternative anomaly-detection models and baselines: LSTM AE, Transformer AE, and VAE
src/layer3_models/lstm_ae.py - Evaluation · Model evaluation and report generation for trained artifacts
evaluation/evaluate_models.py
Runtime core
Serving-time inference, agent orchestration, and persistence
- Model loader · Loads trained model artifacts for serving
src/layer3_models/inference/model_loader.py - Inference prep · Prepares incoming beats for prediction-time inference
src/layer3_models/inference/preprocess.py - Predict · Runs CNN classification and reconstruction-error scoring to produce beat-level results
src/layer3_models/inference/predict.py - Result schema · Standardizes inference outputs for API and dashboard consumers
src/layer3_models/inference/result_schema.py - Clinical agent · Coordinates clinical reasoning and action selection
src/layer4_agent/agent.py - Agent tools · Exposes risk assessment, history lookup, trend monitoring, alerting, and report generation
src/layer4_agent/agent_tools.py - Memory · Maintains short-term conversational context for the agent
src/layer4_agent/memory.py - Storage · Persists patient sessions, alerts, trends, and logs outside the request process
src/layer6_storage/__init__.py
Presentation
API and dashboard entrypoints
- FastAPI app · Main HTTP serving boundary for prediction, agent, report, and history requests
api/main.py - API schemas · Defines request and response shapes for external clients
api/schemas.py - Streamlit app · Interactive clinician UI for ECG, alerts, history, and chat
src/layer5_dashboard/app.py - UI panels · Waveform plotting, alert feed, history charts, and chat interface components
src/layer5_dashboard/ecg_plot.py
Connections 24
- MIT-BIH fetch → Beat prep: raw ECG · Raw MIT-BIH recordings are converted into model-ready beat windows
- Beat prep → CNN classifer: beat tensors · Preprocessed beat windows feed the main classifier
- Beat prep → AE models: anomaly inputs · The same beat windows support anomaly-detection models
- CNN classifer → Predict: class scores · Classifier outputs are consumed by the serving decision layer
- AE models → Predict: recon error · Autoencoder-style models contribute anomaly scoring signals
- Model loader → Predict: loaded artifacts · Serving uses loaded trained models and associated assets
- Inference prep → Predict: serving features · Incoming ECG data is normalized into inference-ready features
- Predict → Result schema: results · Prediction outputs are standardized for downstream consumers
- Predict → Clinical agent: risk signal · Beat/session risk and anomaly findings are handed to the clinical agent
- Agent tools → Clinical agent: tools · The agent invokes domain tools for reasoning and actions
- Memory → Clinical agent: context · Short-term conversation state informs agent responses
- Clinical agent → Storage: persist state · Clinical interactions and session artifacts are written durably
- FastAPI app → Result schema: contracts · HTTP endpoints expose the shared response shapes
- FastAPI app → Clinical agent: agent query · API requests can trigger clinical reasoning and action selection
- FastAPI app → Predict: prediction · API requests can invoke the serving inference path
- Streamlit app → FastAPI app: client calls · The UI consumes backend services for data and actions
- UI panels → Streamlit app: views · Dashboard is composed of specialized clinical panels
- Config → FastAPI app: settings · Configuration is shared by the backend runtime
- Config → Clinical agent: llm config · Agent behavior depends on configurable LLM/runtime settings
- Config → Streamlit app: ui config · Dashboard behavior depends on shared configuration
- Run entry → FastAPI app: launch · Top-level execution can start the backend service
- Run entry → Streamlit app: launch · Top-level execution can start the clinician dashboard
- Evaluation → CNN classifer: metrics · Offline evaluation assesses trained model quality
- Evaluation → AE models: metrics · Offline evaluation also covers anomaly-model experiments