Metadata-Version: 2.4
Name: oncoshift
Version: 0.1.1
Summary: Enterprise Multi-Modal Health AI Foundation Model Safety & Robustness Auditing Engine
Author-email: Sharon Melhi <sharonmelhi365@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Sharon-codes/Onco-Shift
Project-URL: Bug Tracker, https://github.com/Sharon-codes/Onco-Shift/issues
Project-URL: Documentation, https://github.com/Sharon-codes/Onco-Shift#readme
Project-URL: Dashboard, https://webplatform-nu.vercel.app
Keywords: health-ai,foundation-models,distribution-shift,optimal-transport,brier-score,decision-curve-analysis,pathology,radiology,ehr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.22.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: POT>=0.9.0
Requires-Dist: tiatoolbox>=1.4.0

# 🧬 OncoShift (`oncoshift`)

### Enterprise Safety & Robustness Auditing Engine for Multi-Modal Health AI Foundation Models

[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/oncoshift/)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![ML4H](https://img.shields.io/badge/ML4H-2026-green.svg)](https://ml4h.net)
[![Vercel Dashboard](https://img.shields.io/badge/Dashboard-Live-black.svg)](https://webplatform-nu.vercel.app)

**OncoShift** is a Python library for quantifying representation collapse, calibration degradation, and clinical decision utility failure in multi-modal health foundation models under real-world distribution shift.

---

## ⚡ Installation

Install the package via `pip`:

```bash
pip install oncoshift
```

Or install from source in editable mode:

```bash
git clone https://github.com/Sharon-codes/Onco-Shift.git
cd Onco-Shift
pip install -e oncoshift_sdk/
```

---

## 🚀 Quickstart

Audit any PyTorch model backbone or Hugging Face model repository in 3 lines of code:

```python
import torch
import torch.nn as nn
from oncoshift import OncoAuditor

# 1. Instantiate auditor for your target medical backbone
auditor = OncoAuditor(model=my_foundation_model, modality="pathology")

# 2. Input baseline clean tensors
x_clean = torch.randn(32, 3, 224, 224)

# 3. Run automated robustness audit
results = auditor.audit(baseline_tensor=x_clean, epsilon=0.5)

# Inspect empirical metric scores
print(f"Wasserstein Distance W₁  : {results['w1_distance']:.4f}")
print(f"Gromov-Wasserstein GW₂   : {results['gromov_wasserstein']:.4f}")
print(f"Feature Leakage Ratio η  : {results['leakage_ratio']:.4f}")
print(f"SVCCA Alignment          : {results['svcca_alignment']:.4f}")
print(f"Brier Reliability Error  : {results['brier_reliability']:.4f}")
print(f"Net Benefit (at pt=0.30) : {results['net_benefit_at_30']:.4f}")
```

---

## 📐 Mathematical Auditing Modules

### 1. Optimal Transport Geometry (`oncoshift.math_engine`)

- **1st Wasserstein Distance ($W_1$)**: Linear programming exact solver (`ot.emd2`) over ground metric $M_{ij} = \|z_P^{(i)} - z_Q^{(j)}\|_2$.
- **Gromov-Wasserstein Alignment ($GW_2$)**: Topological distance divergence solver (`ot.gromov.gromov_wasserstein2`).
- **SVD Feature Leakage Ratio ($\eta_{\text{leakage}}$)**: Quantifies off-manifold feature drift via orthogonal singular vector projection.
- **Singular Vector CCA ($\text{SVCCA}$)**: Subspace canonical correlation between baseline and shifted feature representations.

```python
from oncoshift import (
    compute_wasserstein_nd,
    compute_gromov_wasserstein,
    compute_feature_leakage_ratio,
    compute_svcca
)

w1 = compute_wasserstein_nd(z_baseline, z_shifted)
gw2 = compute_gromov_wasserstein(z_baseline, z_shifted)
leakage = compute_feature_leakage_ratio(z_baseline, z_shifted)
svcca = compute_svcca(z_baseline, z_shifted)
```

### 2. Clinical Decision Analysis (`oncoshift.auditor`)

- **Murphy (1973) Brier Score Decomposition**: Exact decomposition into Reliability ($\text{Rel}$), Resolution ($\text{Res}$), and Uncertainty ($\text{Unc}$).
- **Decision Curve Analysis (DCA Net Benefit)**: Measures net clinical utility at decision threshold $p_t = 0.30$.

```python
from oncoshift import decompose_brier_score, compute_decision_curve

brier_metrics = decompose_brier_score(y_true, p_pred, n_bins=10)
print(f"Reliability Penalty: {brier_metrics['reliability']:.4f}")

dca_results = compute_decision_curve(y_true, p_pred, thresholds=[0.30])
print(f"Net Benefit at 0.30: {dca_results['net_benefit_model'][0]:.4f}")
```

### 3. Multi-Modal Distribution Shift Perturbations (`oncoshift.shifts`)

Generate realistic clinical perturbations across 3 primary health modalities:

- **Pathology**: Stain variation, defocus blur ($\sigma_{\text{blur}}$), and geometric tissue folds.
- **Radiology**: Acquisition motion blur and additive Gaussian sensor noise.
- **EHR**: Hawkes self-exciting process missingness cascades and irregular observation sampling.

```python
from oncoshift import apply_pathology_shift, apply_radiology_shift, apply_ehr_shift

x_path_shifted = apply_pathology_shift(x_tiles, epsilon=0.5)
x_rad_shifted = apply_radiology_shift(x_cxr, epsilon=0.5)
x_ehr_shifted = apply_ehr_shift(x_seq, epsilon=0.5)
```

---

## 📜 Author & License

Developed by **Sharon Melhi** ([@Sharon-codes](https://github.com/Sharon-codes)).  
Distributed under the **MIT License**.
