{"id":49102264,"url":"https://github.com/eudalabs/healthwithsevgi","last_synced_at":"2026-04-21T00:01:26.700Z","repository":{"id":340189010,"uuid":"1164913450","full_name":"EudaLabs/HealthWithSevgi","owner":"EudaLabs","description":"Browser-based ML education tool for healthcare professionals — 7-step wizard covering 20 medical specialties with explainability, bias detection \u0026 EU AI Act compliance","archived":false,"fork":false,"pushed_at":"2026-04-20T15:24:28.000Z","size":79974,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T17:13:03.618Z","etag":null,"topics":["bias-detection","education","eu-ai-act","explainability","fastapi","healthcare","machine-learning","medical-ai","react","shap"],"latest_commit_sha":null,"homepage":"https://0xbatuhan4-healthwithsevgi.hf.space/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EudaLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T16:13:57.000Z","updated_at":"2026-04-20T15:23:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"80bab1b6-deb6-46df-b9ff-70a393de5af9","html_url":"https://github.com/EudaLabs/HealthWithSevgi","commit_stats":null,"previous_names":["eudalabs/healthwithsevgi"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/EudaLabs/HealthWithSevgi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EudaLabs%2FHealthWithSevgi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EudaLabs%2FHealthWithSevgi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EudaLabs%2FHealthWithSevgi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EudaLabs%2FHealthWithSevgi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EudaLabs","download_url":"https://codeload.github.com/EudaLabs/HealthWithSevgi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EudaLabs%2FHealthWithSevgi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32071013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bias-detection","education","eu-ai-act","explainability","fastapi","healthcare","machine-learning","medical-ai","react","shap"],"created_at":"2026-04-21T00:00:43.719Z","updated_at":"2026-04-21T00:01:26.694Z","avatar_url":"https://github.com/EudaLabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/FastAPI-009688?logo=fastapi\u0026logoColor=white\" alt=\"FastAPI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/React_18-61DAFB?logo=react\u0026logoColor=black\" alt=\"React\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/scikit--learn-F7931E?logo=scikitlearn\u0026logoColor=white\" alt=\"scikit-learn\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-2496ED?logo=docker\u0026logoColor=white\" alt=\"Docker\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python_3.12-3776AB?logo=python\u0026logoColor=white\" alt=\"Python\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/SHAP-blueviolet\" alt=\"SHAP\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green\" alt=\"License: MIT\" /\u003e\n\u003c/p\u003e\n\n# HealthWithSevgi\n\n**An interactive, browser-based machine learning education tool for healthcare professionals.**\n\n\u003e **SENG 430 - Software Quality Assurance**\n\u003e Cankaya University - Spring 2025-2026\n\u003e Instructor: Dr. Sevgi Koyuncu Tunç\n\nHealthWithSevgi guides clinicians through a complete ML pipeline in **7 steps** — from selecting a medical specialty to training a model, interpreting predictions with SHAP, and auditing fairness — all with **zero coding required**.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://0xbatuhan4-healthwithsevgi.hf.space/\"\u003e\u003cstrong\u003eLive Demo\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://berfindurualkan.atlassian.net/jira/software/projects/SCRUM/boards/1\"\u003e\u003cstrong\u003eJira Board\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://www.figma.com/design/1K1Dw8PC6P98NZAa30DzII/430-HealthWithSevgi\"\u003e\u003cstrong\u003eFigma Designs\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"SETUP.md\"\u003e\u003cstrong\u003eSetup Guide\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [The 7-Step Pipeline](#the-7-step-pipeline)\n- [Supported Specialties](#supported-specialties)\n- [ML Models](#ml-models)\n- [Tech Stack](#tech-stack)\n- [Architecture](#architecture)\n- [Project Structure](#project-structure)\n- [Getting Started](#getting-started)\n- [API Reference](#api-reference)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [Branch Strategy](#branch-strategy)\n- [Team](#team)\n- [License](#license)\n\n---\n\n## Overview\n\nHealthcare professionals increasingly encounter AI/ML in clinical settings but rarely get hands-on experience with how these systems work. HealthWithSevgi bridges that gap by providing an intuitive, wizard-style interface that walks users through every stage of the machine learning lifecycle using real clinical datasets.\n\n**Key capabilities:**\n\n- **20 medical specialties** with real-world clinical datasets (Cardiology, Oncology, Nephrology, Neurology, ICU/Sepsis, Dermatology, and more)\n- **8 ML classifiers** with interactive hyperparameter tuning via sliders\n- **SHAP-based explainability** — global feature importance and single-patient waterfall explanations\n- **Fairness auditing** — subgroup performance analysis across demographics with bias detection\n- **EU AI Act compliance checklist** with downloadable PDF certificate\n- **No server-side data storage** — all session data is held in-memory and evicted automatically\n\n---\n\n## The 7-Step Pipeline\n\n| Step | Name | What Happens |\n|:----:|------|-------------|\n| **1** | **Clinical Context** | Introduces the medical problem the AI will address. Displays the clinical question, why it matters, and the 7-step roadmap. |\n| **2** | **Data Exploration** | Upload a CSV file (up to 50 MB) or load a built-in clinical dataset. Inspect column statistics, missing values, and class distribution. Confirm the target variable. |\n| **3** | **Data Preparation** | Configure preprocessing: train/test split ratio, missing value strategy (median/mode/drop), normalization (z-score/min-max), SMOTE for class imbalance, and outlier handling (IQR/z-score clipping). |\n| **4** | **Model \u0026 Parameters** | Choose from 8 ML models. Adjust hyperparameters with intuitive sliders. Optionally enable hyperparameter tuning (RandomizedSearchCV) and feature selection (VarianceThreshold + SelectKBest). |\n| **5** | **Results \u0026 Evaluation** | View accuracy, sensitivity, specificity, precision, F1, AUC-ROC, and MCC. Explore interactive ROC curves, precision-recall curves, and confusion matrices. Detect overfitting via cross-validation comparison. |\n| **6** | **Explainability** | Global feature importance ranking with clinical name mapping. Single-patient SHAP waterfall charts with plain-language summaries (e.g., _\"High glucose increases diabetes risk by 0.23\"_). |\n| **7** | **Ethics \u0026 Bias** | Subgroup fairness audit (by age, gender, ethnicity). Bias warnings for performance gaps \u003e10%. EU AI Act compliance checklist. Real-world case studies of AI bias in healthcare. Downloadable PDF compliance certificate. |\n\n---\n\n## Supported Specialties\n\n| # | Specialty | Prediction Task | Dataset | Samples |\n|---|-----------|-----------------|---------|--------:|\n| 1 | Cardiology | 30-day heart failure mortality | Heart Failure Clinical Records | ~300 |\n| 2 | Radiology | Pneumonia detection (chest X-ray metadata) | NIH Chest X-ray | 100K+ |\n| 3 | Nephrology | Chronic kidney disease detection | UCI CKD | 400 |\n| 4 | Oncology - Breast | Malignant vs. benign biopsy | Wisconsin Breast Cancer | 569 |\n| 5 | Neurology - Parkinson's | Parkinson's from voice biomarkers | UCI Parkinson's | 195 |\n| 6 | Endocrinology - Diabetes | Diabetes onset within 5 years | Pima Indians | 768 |\n| 7 | Hepatology - Liver | Liver disease detection | Indian Liver Patient | 583 |\n| 8 | Cardiology - Stroke | Stroke risk prediction | Kaggle Stroke Prediction | 5,110 |\n| 9 | Mental Health | Depression severity (PHQ-9) | Kaggle Depression | ~1,000 |\n| 10 | Pulmonology - COPD | COPD exacerbation risk | PhysioNet + Kaggle | ~1,000 |\n| 11 | Haematology - Anaemia | Anaemia type classification | Kaggle Anaemia | ~400 |\n| 12 | Dermatology | Benign vs. malignant skin lesion | HAM10000 metadata | ~10K |\n| 13 | Ophthalmology | Diabetic retinopathy detection | UCI Diabetic Retinopathy | 1,151 |\n| 14 | Orthopaedics - Spine | Disc herniation / spondylolisthesis | UCI Vertebral Column | 310 |\n| 15 | ICU / Sepsis | Sepsis onset within 6 hours | PhysioNet Sepsis | ~40K |\n| 16 | Obstetrics - Fetal Health | Fetal health classification (CTG) | UCI Fetal Health | 2,126 |\n| 17 | Cardiology - Arrhythmia | Arrhythmia detection (ECG) | UCI Arrhythmia | 452 |\n| 18 | Oncology - Cervical | Cervical cancer risk | UCI Cervical Cancer | 858 |\n| 19 | Thyroid / Endocrinology | Thyroid function classification | UCI Thyroid | 9,172 |\n| 20 | Pharmacy - Readmission | Hospital readmission risk | UCI Diabetes 130-US | 101,766 |\n\n---\n\n## ML Models\n\n| Model | Category | Key Hyperparameters |\n|-------|----------|---------------------|\n| **K-Nearest Neighbors** | Instance-based | k (1-25), distance metric |\n| **Support Vector Machine** | Boundary-based | C (0.01-100), kernel (linear/rbf/poly) |\n| **Decision Tree** | Tree-based | max_depth (1-20), criterion (gini/entropy) |\n| **Random Forest** | Ensemble | n_estimators (10-500), max_depth |\n| **Logistic Regression** | Linear | C (0.001-100), solver (lbfgs/saga) |\n| **Naive Bayes** | Probabilistic | var_smoothing (1e-12 to 1e-3) |\n| **XGBoost** | Gradient Boosting | n_estimators, max_depth, learning_rate |\n| **LightGBM** | Gradient Boosting | n_estimators, max_depth, learning_rate |\n\nAll models are trained with balanced class weights where supported. Optional hyperparameter tuning uses RandomizedSearchCV (20 iterations, 3-fold CV). Feature selection combines VarianceThreshold with SelectKBest (mutual information).\n\n---\n\n## Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| **Frontend** | React 18, TypeScript, Vite | Single-page wizard application |\n| **UI Components** | Recharts, Lucide Icons, react-dropzone | Charts, icons, file uploads |\n| **State Management** | TanStack React Query | Server state caching and synchronization |\n| **Backend** | FastAPI, Python 3.12 | REST API with auto-generated OpenAPI docs |\n| **ML Engine** | scikit-learn, XGBoost, LightGBM | Model training, evaluation, cross-validation |\n| **Explainability** | SHAP | TreeExplainer (tree models), KernelExplainer (linear), permutation importance |\n| **Data Processing** | pandas, numpy, imbalanced-learn | Data cleaning, normalization, SMOTE |\n| **PDF Generation** | ReportLab | Compliance certificate export |\n| **Containerization** | Docker (multi-stage) | Production deployment |\n| **Hosting** | HuggingFace Spaces | Live demo environment |\n| **Package Manager** | pnpm (frontend), pip (backend) | Dependency management |\n\n---\n\n## Architecture\n\n📐 **[Full Architecture Diagrams (Google Drive)](https://drive.google.com/drive/folders/1AkMxaaPLizfPlfJDjkP7YISSiOEiL9tV?usp=sharing)** — C4 model diagrams (System Context, Container, Component, Code levels), toolchain diagrams, and data flow sequences.\n\n```\n                          +---------------------+\n                          |   Browser (React)   |\n                          |   Wizard UI (SPA)   |\n                          +----------+----------+\n                                     |\n                            HTTP/REST (JSON)\n                                     |\n                          +----------v----------+\n                          |   FastAPI Backend    |\n                          +----------+----------+\n                                     |\n              +----------------------+----------------------+\n              |              |              |                |\n     +--------v---+  +------v-----+  +-----v------+  +-----v--------+\n     | DataService|  | MLService  |  |ExplainSvc  |  | EthicsService|\n     |            |  |            |  |            |  |              |\n     | - Explore  |  | - Train    |  | - SHAP     |  | - Subgroup   |\n     | - Prepare  |  | - Evaluate |  | - Waterfall|  | - Bias detect|\n     | - SMOTE    |  | - Compare  |  | - Clinical |  | - EU AI Act  |\n     +-----+------+  +------+-----+  +------+-----+  +------+-------+\n           |                |                |                |\n           v                v                v                v\n     +-----------+   +------------+   +------------+   +-----------+\n     | In-Memory |   | In-Memory  |   |   SHAP     |   | ReportLab |\n     | Sessions  |   | Models     |   |  Library   |   |  PDF Gen  |\n     | (LRU 50)  |   | (LRU 100+)|   |            |   |           |\n     +-----------+   +------------+   +------------+   +-----------+\n```\n\n**Data flow:** Upload CSV -\u003e Explore columns -\u003e Preprocess (split, normalize, SMOTE) -\u003e Train model -\u003e Evaluate metrics -\u003e SHAP explanations -\u003e Fairness audit -\u003e PDF certificate\n\n---\n\n## Project Structure\n\n```\nHealthWithSevgi/\n|\n+-- frontend/                         # React 18 + Vite + TypeScript\n|   +-- src/\n|   |   +-- pages/                    # Step 1-7 wizard pages\n|   |   |   +-- Step1ClinicalContext.tsx\n|   |   |   +-- Step2DataExploration.tsx\n|   |   |   +-- Step3DataPreparation.tsx\n|   |   |   +-- Step4ModelParameters.tsx\n|   |   |   +-- Step5Results.tsx\n|   |   |   +-- Step6Explainability.tsx\n|   |   |   +-- Step7Ethics.tsx\n|   |   +-- components/               # Reusable UI components\n|   |   |   +-- NavBar.tsx            # Specialty switcher, glossary\n|   |   |   +-- WizardProgress.tsx    # Step progress tracker\n|   |   |   +-- SpecialtySelector.tsx # 20-specialty grid\n|   |   |   +-- ColumnMapperModal.tsx # Target column confirmation\n|   |   |   +-- ErrorModal.tsx       # Error display modal\n|   |   |   +-- charts/              # Visualization components\n|   |   |       +-- ConfusionMatrixChart.tsx  # 2x2 confusion matrix\n|   |   |       +-- KNNScatterCanvas.tsx     # KNN decision boundary\n|   |   |       +-- PRCurveChart.tsx         # Precision-Recall curve\n|   |   |       +-- ROCCurveChart.tsx        # ROC curve with AUC badge\n|   |   +-- api/                      # API client layer\n|   |   |   +-- client.ts            # Axios instance + interceptors\n|   |   |   +-- specialties.ts       # Specialty endpoints\n|   |   |   +-- data.ts              # Explore + Prepare endpoints\n|   |   |   +-- ml.ts                # Train + Compare endpoints\n|   |   |   +-- explain.ts           # Explainability + Ethics + Certificate\n|   |   +-- types/index.ts           # Shared TypeScript interfaces\n|   |   +-- styles/globals.css        # Global CSS + theme variables\n|   |   +-- App.tsx                   # Main wizard state manager\n|   |   +-- main.tsx                  # Application entry point\n|   +-- package.json\n|   +-- vite.config.ts\n|\n+-- backend/                          # FastAPI REST API + ML engine\n|   +-- app/\n|   |   +-- main.py                   # FastAPI setup, CORS, routers\n|   |   +-- routers/\n|   |   |   +-- data_router.py        # /specialties, /explore, /prepare\n|   |   |   +-- ml_router.py          # /train, /compare, /models\n|   |   |   +-- explain_router.py     # /explain/*, /ethics, /certificate\n|   |   +-- services/\n|   |   |   +-- data_service.py       # Dataset loading, exploration, preprocessing\n|   |   |   +-- ml_service.py         # Model building, training, evaluation\n|   |   |   +-- explain_service.py    # SHAP explanations, clinical mapping\n|   |   |   +-- ethics_service.py     # Fairness audit, bias detection\n|   |   |   +-- certificate_service.py # PDF certificate generation\n|   |   |   +-- specialty_registry.py # 20 specialty definitions + datasets\n|   |   +-- models/\n|   |   |   +-- schemas.py            # Data exploration/preparation DTOs\n|   |   |   +-- ml_schemas.py         # Training/evaluation DTOs\n|   |   |   +-- explain_schemas.py    # Explainability/ethics DTOs\n|   |   +-- utils/                    # Utility modules\n|   +-- data_cache/                   # Cached clinical CSV datasets\n|   +-- datasets/                     # Additional dataset storage\n|   +-- tests/                        # pytest test suite (178 tests)\n|   |   +-- conftest.py              # Shared fixtures\n|   |   +-- test_step1_clinical_context.py\n|   |   +-- test_step2_data_exploration.py\n|   |   +-- test_step3_data_preparation.py\n|   |   +-- test_step6_explainability.py\n|   |   +-- test_step7_ethics.py\n|   |   +-- test_certificate.py\n|   +-- pytest.ini\n|   +-- requirements.txt\n|\n+-- hf-space/                         # HuggingFace Spaces deployment\n|   +-- main_hf.py                    # Combined API + SPA entrypoint\n|   +-- Dockerfile                    # HF-specific Docker build\n|   +-- README.md                     # HF Space metadata\n|\n+-- docs/                             # Documentation \u0026 design specs\n|   +-- ML_Tool_User_Guide.md         # Course user manual\n|   +-- Sprint_1_Assignment.md        # Sprint 1 requirements\n|   +-- Clinical_Specialties_Dataset_Collection.pdf\n|   +-- diagrams/                     # C4 architecture + toolchain PDFs\n|   +-- drawio/                       # Editable draw.io source files\n|   +-- mermaid/                      # C4 architecture (Mermaid source)\n|   +-- iso42001/                     # ISO 42001 AI governance report\n|   +-- seng430-sprints/              # Sprint requirements from instructor\n|   +-- qa/                           # QA test reports (PDF)\n|   +-- reports/                      # Progress reports + screenshots\n|\n+-- jira/                             # Jira backlog documentation\n|   +-- JIRA.md                       # Product backlog report\n|   +-- SPRINT_1_TASK_BOARD.md        # Sprint 1 task breakdown\n|\n+-- local/                            # Local-only extensions\n|   +-- model-arena/                  # Model Arena comparison feature\n|       +-- arena/                    # Backend (router, service, schemas)\n|       +-- frontend/                 # Frontend (ArenaPage, charts, hooks)\n|\n+-- .github/\n|   +-- pull_request_template.md      # PR template linked to Jira\n|   +-- workflows/deploy-hf.yml      # Auto-deploy to HuggingFace on release\n|\n+-- Dockerfile                        # Multi-stage build (Node + Python)\n+-- docker-compose.yml                # Local development orchestration\n+-- .dockerignore\n+-- .gitignore\n+-- CLAUDE.md                         # AI coding assistant context\n+-- SETUP.md                          # Local development setup guide\n+-- README.md\n```\n\n---\n\n## Live Demo \u0026 Docker\n\n### 🌐 Live Demo\n\nThe application is deployed on HuggingFace Spaces — no installation required:\n\n**➡️ [0xbatuhan4-healthwithsevgi.hf.space](https://0xbatuhan4-healthwithsevgi.hf.space/)**\n\n### 🐳 Docker (single command)\n\nPull and run the pre-built container image from GitHub Container Registry:\n\n```bash\ndocker run -p 7860:7860 ghcr.io/eudalabs/healthwithsevgi:latest\n```\n\nOpen **http://localhost:7860** — that's it.\n\nAlternatively, build from source:\n\n```bash\ngit clone https://github.com/EudaLabs/HealthWithSevgi.git\ncd HealthWithSevgi\ndocker build -t healthwithsevgi .\ndocker run -p 7860:7860 healthwithsevgi\n```\n\n### Docker Compose (one-command start)\n\n```bash\ngit clone https://github.com/EudaLabs/HealthWithSevgi.git\ncd HealthWithSevgi\ndocker compose up -d\n```\n\n`docker-compose.yml` pulls the pre-built `ghcr.io/eudalabs/healthwithsevgi:latest` image when available and falls back to a local multi-stage build (Node → Vite → Python). Either way, the full stack — React SPA **and** FastAPI — is served from a single container on **http://localhost:7860**.\n\n**Measured startup (pre-built image, warm Docker daemon):** ~**8 seconds** from `docker compose up -d` to HTTP 200 on `/api/specialties` — well inside the Sprint 5 30-second target (see `docs/reports/Sprint5_Docker_Running.png`).\n\n**First-time local build:** ~3–6 minutes (installs pnpm + pip dependencies). Force a rebuild with `docker compose up --build`.\n\nContainer name is `healthwithsevgi`; the compose file also wires a healthcheck that probes `/api/specialties` every 10s.\n\nTo stop: `docker compose down`.\n\n---\n\n## Quick Start\n\n### Prerequisites (for local development)\n\n| Tool | Version | Required For |\n|------|---------|-------------|\n| Python | \u003e= 3.10 | Backend |\n| Node.js | \u003e= 18 | Frontend |\n| Git | latest | Version control |\n\n### Local Development\n\n**Backend:**\n\n```bash\ncd backend\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate        # macOS / Linux\n# venv\\Scripts\\activate         # Windows\n\n# Install dependencies\npip install -r requirements.txt\n\n# Start the API server\nuvicorn app.main:app --reload --port 8001\n```\n\nAPI docs available at: **http://localhost:8001/docs** (Swagger UI)\n\n**Frontend** (in a separate terminal):\n\n```bash\ncd frontend\n\n# Install dependencies\npnpm install\n\n# Start the dev server\npnpm dev\n```\n\nApp available at: **http://localhost:5173** (proxies `/api` requests to port 8001)\n\n### Environment Variables\n\nCreate a `.env` file in the project root:\n\n```env\n# Backend\nBACKEND_PORT=8001\nDEBUG=true\n\n# Frontend (Vite uses VITE_ prefix)\nVITE_API_URL=http://localhost:8001\n```\n\n---\n\n## API Reference\n\nAll endpoints are prefixed with `/api`. Full interactive documentation is available at `/docs` when the backend is running.\n\n### Specialties\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/specialties` | List all 20 specialties |\n| `GET` | `/api/specialties/{id}` | Get specialty details (description, features, clinical context) |\n\n### Data\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/explore` | Upload CSV or load built-in dataset; returns column stats + class distribution |\n| `POST` | `/api/prepare` | Preprocess data (split, normalize, SMOTE); returns `session_id` |\n\n### ML Training\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/train` | Train a model; returns `model_id` + evaluation metrics |\n| `POST` | `/api/compare/{model_id}` | Add model to comparison table |\n| `GET` | `/api/compare/{session_id}` | Get all compared models for a session |\n| `DELETE` | `/api/compare/{session_id}` | Clear comparison table |\n| `GET` | `/api/models/{model_id}` | Get model metadata |\n\n### Explainability\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/explain/global/{model_id}` | Global feature importance (top 10 features + clinical names) |\n| `GET` | `/api/explain/patient/{model_id}/{index}` | Single-patient SHAP waterfall explanation |\n\n### Ethics \u0026 Certificate\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/ethics/{model_id}` | Subgroup fairness audit + bias warnings + checklist |\n| `POST` | `/api/ethics/checklist` | Update EU AI Act checklist item |\n| `POST` | `/api/generate-certificate` | Generate and download PDF compliance certificate |\n\n\u003e Full endpoint reference (request/response schemas, error codes, typical flow) lives on the wiki: **[API](../../wiki/API)**.\n\n### Health\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/` | Status check (`{status: \"ok\"}`) |\n| `GET` | `/health` | Health probe (`{status: \"healthy\"}`) |\n\n---\n\n## Testing\n\nThe project includes a comprehensive pytest suite covering all 7 steps of the pipeline — **191 tests** across 7 test files.\n\n```bash\ncd backend\n\n# Run all tests\npytest -v\n\n# Run a specific test file\npytest -v tests/test_step1_clinical_context.py\n\n# Run only slow tests (domain context validation)\npytest -v -m slow\n```\n\n**Test coverage:**\n\n| Test File | Covers | Key Assertions |\n|-----------|--------|----------------|\n| `test_step1_clinical_context.py` | Specialty registry | All 20 specialties present, required fields non-empty, clinical context \u003e 50 chars, 404 handling |\n| `test_step2_data_exploration.py` | Data exploration | CSV upload validation, missing value detection, class distribution, imbalance warnings |\n| `test_step3_data_preparation.py` | Preprocessing | Missing strategies (median/mode/drop), normalization, train/test split, SMOTE, data leakage prevention |\n| `test_step4_arena_latency.py` | Model Arena | Training latency, cross-model comparison, session consistency |\n| `test_step6_explainability.py` | SHAP explanations | Global importance, patient explanation, What-If analysis, sample patient selection |\n| `test_step7_ethics.py` | Fairness audit | Ethics endpoint, case study severity, checklist toggle, bias detection thresholds |\n| `test_certificate.py` | PDF generation | Certificate content type, PDF magic bytes, checklist state persistence |\n\n**Total: 191 tests — all passing.**\n\n---\n\n## Deployment\n\n### HuggingFace Spaces\n\nThe production deployment runs on HuggingFace Spaces as a Docker container. The multi-stage Dockerfile:\n\n1. **Stage 1** — Builds the React frontend with pnpm\n2. **Stage 2** — Installs Python dependencies\n3. **Stage 3** — Combines both into a slim Python 3.12 runtime serving the SPA + API on port 7860\n\n`hf-space/main_hf.py` serves both the FastAPI backend and the static React build from a single process.\n\n**Live demo:** [0xbatuhan4-healthwithsevgi.hf.space](https://0xbatuhan4-healthwithsevgi.hf.space/)\n\n---\n\n## Branch Strategy\n\n| Branch | Purpose |\n|--------|---------|\n| `main` | Production-ready, protected |\n| `develop` | Integration branch for sprint work |\n| `feature/US-XXX` | One branch per user story |\n\n**Rules:**\n- All changes go through Pull Requests (use the [PR template](.github/pull_request_template.md))\n- PRs require at least 1 approval\n- `main` and `develop` are protected — no direct pushes\n- PR titles follow: `feat/fix/docs(US-XXX): description`\n\n---\n\n## Team\n\n| Role | Name | Student ID |\n|------|------|:----------:|\n| Product Owner + Developer | Efe Çelik | 202128016 |\n| UX Designer | Burak Aydoğmuş | 202128028 |\n| Lead Developer + Scrum Master | Batuhan Bayazıt | 202228008 |\n| Developer | Berat Mert Gökkaya | 202228019 |\n| QA / Documentation Lead | Berfin Duru Alkan | 202228005 |\n\n---\n\n## Links\n\n- **Live Demo:** [0xbatuhan4-healthwithsevgi.hf.space](https://0xbatuhan4-healthwithsevgi.hf.space/)\n- **Jira Board:** [Jira](https://berfindurualkan.atlassian.net/jira/software/projects/SCRUM/boards/1/backlog)\n- **Figma Designs:** [Figma](https://www.figma.com/design/1K1Dw8PC6P98NZAa30DzII/430-HealthWithSevgi?node-id=0-1)\n- **GitHub Wiki:** [Wiki](../../wiki)\n- **API Docs:** `http://localhost:8001/docs` (when running locally)\n\n---\n\n## License\n\nReleased under the [**MIT License**](LICENSE) — you are free to use, copy, modify, and distribute this software with attribution.\n\nDeveloped as part of the **SENG 430 Software Quality Assurance** course at Cankaya University by the EudaLabs team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feudalabs%2Fhealthwithsevgi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feudalabs%2Fhealthwithsevgi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feudalabs%2Fhealthwithsevgi/lists"}