Hybrid Quantum–Classical Machine Learning Platform

A runnable research/education MVP for comparing a classical SVM with a simulator-backed Variational Quantum Classifier (VQC) on biomedical classification data. This is not a medical diagnosis application.

This platform is intended for research and educational experimentation. Predictions are not medical diagnoses.

Quick start (Python 3.11+)

From the project directory:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python run.py

Open http://127.0.0.1:3000. The launcher runs Streamlit privately on port 8502 and places a small HTTP/WebSocket gateway on port 3000. The gateway also serves GET /manus-routes.json. For another port or network binding, set APP_HOST, APP_PORT, and STREAMLIT_PORT, for example:

APP_HOST=127.0.0.1 APP_PORT=3100 STREAMLIT_PORT=8503 .venv/bin/python run.py

For a managed Web Preview, the gateway must listen on 0.0.0.0 at the port declared by that workspace (3000 here):

APP_HOST=0.0.0.0 APP_PORT=3000 STREAMLIT_PORT=8502 .venv/bin/python run.py

Stop the local process with Ctrl+C. Uploaded CSVs and fitted models are held in the active Streamlit session; the app does not save uploads to a database or external file store.

Research workflow

1. Use the included Breast Cancer Wisconsin Diagnostic Dataset or choose a CSV from the sidebar. The sample is bundled from scikit-learn's real dataset and has 569 observations, 30 numeric predictors, and a Diagnosis target. Diabetes and Heart Disease appear as Planned / Dataset Required catalog entries; no such datasets or pretrained models are bundled.
2. Preview the data, choose the target column, review missing values, duplicates and data types.
3. The default settings are a 30% stratified test holdout, top 10 features, 4 PCA components / VQC qubits, 12 optimizer steps, 2 variational layers, positive class Malignant for the sample, and seed 42. These controls remain adjustable; dimensions are clamped to feasible input/training sizes.
4. Start an experiment. It creates one stratified split. Imputation, StandardScaler, SelectKBest feature selection and PCA fit on training data only; both models use the same split and PCA features. Dataset profiles specify target-column hints and feature-selection policy; user CSVs derive their candidate predictors and ranking from the active schema and chosen target.
5. Inspect actual held-out predictions, metrics, confusion matrices, ROC curves, PCA variance, per-feature scores, measured training and per-sample inference time, and the trained circuit across the workflow sections.

Models and experimental transparency

• The classical baseline is an RBF Support Vector Classifier; its class predictions and signed decision-function scores are from the fitted scikit-learn estimator. The decision score is not a calibrated probability.
• The quantum path uses PennyLane's default.qubit analytic statevector simulator: PCA values are bounded as Y-rotation angles; trainable rotation gates, entanglement, Pauli-Z measurement and a classical Adam optimizer train a binary VQC. No physical quantum hardware is used.
• Accuracy, precision, recall/sensitivity, specificity, F1, ROC-AUC, fit time and measured holdout inference time are derived from executed models and the actual shared held-out partition. Unavailable or undefined values are labeled Not available; values are not illustrative or hard-coded.
• If VQC installation, optimization or execution fails, the actual error is shown and quantum results are marked unavailable; the SVM results remain available. No quantum benchmark is synthesized.
• Uploads require binary targets and numeric predictor values. Missing numeric features are median-imputed from the training partition. Missing targets/duplicates are removed with counts reported. Invalid text predictor values, empty columns and unsupported class counts receive explicit errors rather than silent conversion.
• Positive-class sensitivity/specificity are shown for the selected class. The bundled sample defaults to Malignant.

Dataset registry and feature profiles

• Breast Cancer · Wisconsin Diagnostic: bundled demonstration data. Its profile targets Diagnosis and recomputes ANOVA F rankings over the active numeric tumor-morphometry columns on each training partition.
• Diabetes and Heart Disease: planned / dataset required. Their disease-specific feature lists and model profiles remain unconfigured; selecting a catalog entry does not fabricate data or switch the active training dataset.
• Other compatible medical CSV: schema-driven numeric predictors and a user-selected binary target. Selected features are recalculated from that dataset’s training partition for each run; no pretrained disease model is implied.

Limitations and safety

This is an educational prototype, not a clinically validated model or a medical device. A model prediction is not a confirmed diagnosis, medical advice, or evidence that either approach is suitable for patient care. Feature scores and PCA-component perturbations are limited model-space explanations, not causal/biological findings. Quantum circuit and encoded-feature displays are not complete clinical explainability. Do not upload identifiable patient information to a shared Preview; use data you are authorized to process. The default configuration retains uploads only in the running app session.

Project structure

app.py                       Streamlit research dashboard
run.py                       local/Preview launcher
modules/gateway.py           route manifest + Streamlit HTTP/WebSocket proxy
modules/data_loader.py       CSV validation and preprocessing summary
modules/dataset_registry.py  disease catalog, target hints and feature profiles
modules/preprocessing.py     reproducible stratified split
modules/feature_selection.py median imputation, scaling and SelectKBest
modules/dimensionality_reduction.py training-only PCA and angle encoding
modules/classical_model.py   SVM baseline
modules/quantum_model.py     PennyLane VQC training and prediction
modules/evaluation.py        real holdout metrics, confusion and ROC data
modules/explainability.py    selection, PCA and local component explanation
modules/visualization.py     Plotly research charts and circuit diagram
modules/pipeline.py          shared experiment orchestration
data/sample_dataset.csv     bundled Wisconsin dataset
assets/                      project brand mark
requirements.txt              Python dependencies
manus-routes.json             current Web route manifest