README.md

metadata

title: HeartCare Risk Prediction System
emoji: 🌡️
colorFrom: red
colorTo: pink
sdk: docker
app_port: 7860
pinned: false

HeartCare Risk Prediction System

An end-to-end machine learning–based web application for predicting cardiovascular disease risk using lifestyle and health attributes. This system provides a production-ready API and a modern web interface to help users assess their heart health through a series of clinically relevant questions.

---

📋 Table of Contents

• Project Overview
• Key Features
• Technology Stack
• Installation Instructions
• Usage Guide
• Project Structure
• Contribution Guidelines
• License

---

🌟 Project Overview

The HeartCare Risk Prediction System is designed to provide quick and accessible heart disease risk assessments. By processing variables such as age, lifestyle habits (smoking, alcohol, diet), and medical history (diabetes, checkups), the underlying machine learning model predicts the probability of heart-related complications.

Key Capabilities

• Real-time Prediction: Immediate risk assessment using a trained Random Forest model.
• Data Validation: Strict input checking via Pydantic schemas to ensure diagnostic accuracy.
• User-Friendly UI: Modern, glassmorphism-inspired design for a premium user experience.
• RESTful API: Fully documented API endpoints for integration with other healthcare systems.

---

🛠 Technology Stack

Component	Technology
Backend Framework	FastAPI
Machine Learning	Scikit-learn (Random Forest)
Data Validation	Pydantic
Frontend	HTML5, Vanilla CSS, JavaScript
Server	Uvicorn (ASGI)
Large File Storage	Git LFS

---

📥 Installation Instructions

System Requirements

• OS: Windows 10/11, macOS, or Linux
• Python: 3.9 or higher
• Disk Space: ~500MB (including the ML model)
• RAM: 2GB minimum

Step-by-Step Setup

1. Clone the Repository (Ensure Git LFS is installed):

   git clone https://github.com/mohsinkp02/HeartCare-Risk-Prediction-System.git
   cd HeartCare-Risk-Prediction-System
   

2. Initialize Git LFS and Pull Model:

   git lfs install
   git lfs pull
   

3. Create a Virtual Environment:

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # macOS/Linux
   python3 -m venv .venv
   source .venv/bin/activate
   

4. Install Dependencies:

   pip install -r requirements.txt
   

---

🚀 Usage Guide

Running the Application

To launch the web server and application, execute the runner script:

python run_app.py

• Website: Access at http://localhost:8000
• API Documentation: Interactive Swagger docs at http://localhost:8000/docs

Configuration Options

Environment Variable	Default	Description
APP_NAME	HeartCare	The display name of the application
API_V1_STR	/api/v1	The prefix for all API endpoints
HOST	0.0.0.0	Network interface to bind to
PORT	8000	Port number for the web server

---

📂 Project Structure

graph TD
    Root[HeartCare-Risk-Prediction-System/] --> App[app/]
    Root --> Config[.gitattributes, .gitignore, README.md, requirements.txt]
    Root --> Runner[run_app.py]
    
    App --> API[api/ - Routes & Endpoints]
    App --> Core[core/ - App Config]
    App --> Models[models/ - Trained .pkl Model]
    App --> Schemas[schemas/ - Pydantic Validation]
    App --> Services[services/ - Business Logic]
    App --> Static[static/ - CSS, JS, Images]
    App --> Templates[templates/ - HTML Files]
    App --> Main[main.py - Entry Point]

---

🤝 Contribution Guidelines

We welcome contributions to HeartCare! To contribute, follow these steps:

Reporting Issues

• Use the GitHub Issues tab to report bugs or request features.
• Provide a clear description and steps to reproduce the issue.

Pull Request Process

1. Fork the repository.
2. Create a new branch (git checkout -b feature/AmazingFeature).
3. Commit your changes following our Coding Standards (PEP 8 for Python).
4. Push to the branch.
5. Open a Pull Request for review.

Coding Standards

• Follow PEP 8 for style.
• Include docstrings for all new functions and classes.
• Ensure all tests pass before submitting.

---

⚖️ License

Copyright © 2024 Mohsin Khan.

Distributed under the MIT License. See LICENSE for more information.

---

This system is intended for informational purposes and should not replace professional medical advice.