PERSON_B_TASKS.md

👩‍💻 Person B — Standalone Task Guide

PneumoOps: Backend Verification, Model Registry & Monitoring

This guide is self-contained. You only need the GitHub repository link and the HF Token that Person A will share with you privately. You do NOT need access to Person A's machine.

---

🔑 What You Need From Person A (Ask Before Starting)

Item	How to Get It
GitHub repository URL	https://github.com/Prakhar54-byte/PneumoOps
Hugging Face Access Token	Person A will share privately (WhatsApp/DM) — do NOT share publicly
HF Model Repo name	Prakhar54-byte/pneumoops-chestmnist (or whatever Person A created)

---

⚙️ Step 0: One-Time Environment Setup

Open a terminal on your machine and run these commands:

# 1. Clone the GitHub repository
git clone https://github.com/Prakhar54-byte/PneumoOps.git
cd PneumoOps

# 2. Create a Python virtual environment
python3 -m venv .venv
source .venv/bin/activate    # On Windows: .venv\Scripts\activate

# 3. Install all dependencies (CPU-only torch is fine for testing)
pip install -r requirements.txt

# 4. Login to Hugging Face using the token Person A gave you
pip install huggingface_hub
huggingface-cli login
# → Paste the token when prompted. Press Enter.

---

📦 Task B1: Download the Model Files From HF Hub

The .pth and .onnx model files are too large for Git. They live on Hugging Face Model Hub.

# Set the model repo (ask Person A for the exact name)
export HF_MODEL_REPO="Prakhar54-byte/pneumoops-chestmnist"

# Download all model artifacts to the correct local folder
python3 - <<'PY'
from huggingface_hub import snapshot_download
import shutil, os

local_dir = snapshot_download(
    repo_id=os.environ["HF_MODEL_REPO"],
    repo_type="model",
    local_dir="models/chestmnist_mobilenetv3",
    ignore_patterns=["*.md"],
)
print(f"✅ Downloaded to: {local_dir}")
PY

After this runs, confirm the files exist:

ls models/chestmnist_mobilenetv3/
# Expected:  mobilenetv3_chestmnist.pth  mobilenetv3_chestmnist.onnx
#            training_metrics.json  baseline_stats.json  onnx_export_report.json

---

🐳 Task B2: Start the App Locally With Docker

# Make sure Docker Desktop is installed and running first
docker compose up --build -d app

# Wait ~30 seconds for startup, then check health
curl http://127.0.0.1:7860/health

Expected output (both models should show true):

{
  "status": "ok",
  "pytorch_model_loaded": true,
  "onnx_model_loaded": true,
  "class_count": 14
}

---

🧪 Task B3: Run the Automated Tests

# Run all tests with verbose output
python -m pytest tests/ -v

# Expected output should show all PASSED:
# tests/test_api.py::test_health_check PASSED
# tests/test_api.py::test_metrics_endpoint PASSED
# tests/test_api.py::test_predict_with_synthetic_image PASSED
# tests/test_api.py::test_drift_on_non_xray PASSED

---

🖥️ Task B4: Verify the Gradio UI

1. Open your browser and go to: http://localhost:7860/ui
2. Upload any image (a chest X-ray from Google Images is fine for testing)
3. Click "Run Screening"
4. Verify that ALL five output fields are displayed:
   • ✅ Top-3 Predictions bar chart
   • ✅ Model Used (shows "Baseline PyTorch" OR "Optimized ONNX")
   • ✅ Inference Latency (e.g., "12.3 ms")
   • ✅ All Findings Detected
   • ✅ Data Drift Alert (green "NORMAL" for a real X-ray)
5. Upload a non-X-ray (e.g., a photo of a dog or landscape)
   • ✅ You should see a red "⚠️ DRIFT DETECTED" badge

Take a screenshot of both tests (normal + drift) — these are needed for the poster and final report.

---

📊 Task B5: Production Monitoring

These endpoints let you observe how the model is performing without looking at individual images:

# Recent request history (last 20 predictions)
curl http://127.0.0.1:7860/history | python3 -m json.tool

# Per-class prediction rates
# (which diseases are predicted most often)
curl http://127.0.0.1:7860/metrics/class-rates | python3 -m json.tool

# AUROC / AUPRC per disease class (from training)
curl http://127.0.0.1:7860/metrics/calibration | python3 -m json.tool

# Prometheus metrics (raw counters/histograms for monitoring tools)
curl http://127.0.0.1:7860/metrics | grep pneumoops

The Prometheus /metrics endpoint can be connected to Grafana in a real production setup for dashboards. For this project, reading the raw text output is sufficient.

---

✍️ Task B6: Documentation (Poster & Report)

• Copy the text from POSTER_CONTENT.md into the Canva poster template
• Read ETHICS.md — you may need to explain the ethical considerations in your presentation
• Update the README.md with your name in the contributors section:

  # In the README, find "Contributors" and add your name
  git add README.md
  git commit -m "docs: add contributors section"
  git push
  

---

🚨 Troubleshooting

Problem	Fix
docker: command not found	Install Docker Desktop from docker.com
models/*.pth not found	Run Task B1 again — the download may have failed
curl: (7) Failed to connect	The Docker container isn't running. Run docker compose up -d app
pytest: command not found	Run pip install pytest httpx inside your virtual environment
Test test_predict fails	Check docker logs pneumo_ops-app-1 for error messages

---

📞 Contact

If you are stuck, message Person A with:

1. The exact error message (copy-paste it)
2. Which Task step you are on
3. The output of docker logs pneumo_ops-app-1