HOW_TO_SETUP.md

# 🚀 ICD-CPT Frontend Gradio - Setup Guide

This guide will help you set up the ICD-CPT Coding Assistant frontend on your local machine and deploy to Hugging Face Spaces.

---

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Clone the Repository](#clone-the-repository)
3. [Local Setup](#local-setup)
4. [Test on Local Machine](#test-on-local-machine)
5. [Push to Hugging Face Space](#push-to-hugging-face-space)
6. [Troubleshooting](#troubleshooting)

---

## 🔧 Prerequisites

Before you begin, ensure you have the following installed:

### Required Software:

- **Python 3.10 or higher** - [Download Python](https://www.python.org/downloads/)
- **Git** - [Download Git](https://git-scm.com/downloads)
- **Hugging Face Account** - [Sign up here](https://huggingface.co/join)
- **Code Editor** (VS Code, PyCharm, or any editor)

### Verify Installations:

```bash
# Check Python version
python --version
# Should show: Python 3.10.x or higher

# Check Git version
git --version
# Should show: git version 2.x.x

# Check pip
pip --version
```

---

## 📥 Clone the Repository

### Option 1: Clone from Hugging Face (If you have access)

```bash
# Create a project folder
mkdir icd-cpt-project
cd icd-cpt-project

# Clone the Hugging Face Space
git clone https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio

# Navigate into the folder
cd icd-cpt-coding-gradio
```

### Option 2: Download ZIP (If no git access)

1. Go to: `https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio`
2. Click on **"Files and versions"** tab
3. Click **"⋮"** (three dots) → **"Download repository"**
4. Extract the ZIP file
5. Open terminal in extracted folder

---

## 💻 Local Setup

### Step 1: Create Virtual Environment (Recommended)

**Windows:**

```bash
# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate
```

**Mac/Linux:**

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate
```

You should see `(venv)` in your terminal prompt.

### Step 2: Install Dependencies

```bash
# Upgrade pip
pip install --upgrade pip

# Install required packages
pip install -r requirements.txt
```

**Expected output:**

```
Successfully installed gradio-4.16.0 requests-2.31.0 ...
```

### Step 3: Verify Installation

```bash
# Check installed packages
pip list

# Should show:
# gradio        4.16.0
# requests      2.31.0
# ...
```

---

## 🧪 Test on Local Machine

### Step 1: Configure Backend API URL

Before running, ensure the backend API URL is correct in `app.py`.

**Open `app.py` and find line 147:**

```python
value="https://Distopia22-icd-cpt-coding-api.hf.space",
```

**Verify this URL is accessible:**

- Open browser: `https://Distopia22-icd-cpt-coding-api.hf.space/docs`
- Should show FastAPI Swagger docs
- If not accessible, ask for correct backend URL

### Step 2: Run the Application Locally

```bash
# Make sure you're in the frontend-gradio folder
# and virtual environment is activated (venv)

# Run the Gradio app
python app.py
```

**Expected output:**

```
Running on local URL:  http://127.0.0.1:7860

To create a public link, set `share=True` in `launch()`.
```

### Step 3: Open in Browser

1. **Open your browser**
2. **Go to:** `http://127.0.0.1:7860` or `http://localhost:7860`
3. **You should see:** The ICD-10 & CPT Coding Assistant interface

### Step 4: Test the Application

#### Test 1: Check API Status

1. Click **"⚙️ API Configuration"** to expand
2. Verify Backend API URL is correct
3. Click **"🔍 Check API Status"**
4. Should show: ✅ **"API Status: healthy"**

#### Test 2: Load Example

1. Click **"📄 Load Example"** button
2. Provider notes should populate with example text

#### Test 3: Analyze Provider Notes

1. With example loaded, click **"🔬 Analyze & Generate Codes"**
2. Wait 5-10 seconds
3. Check **"📋 Overall Summary"** appears
4. Click **"🏥 ICD-10 Codes"** tab - should show codes
5. Click **"💼 CPT Codes"** tab - should show codes

#### Test 4: Custom Input

1. Click **"🗑️ Clear All"**
2. Enter your own provider notes:
   ```
   Patient with type 2 diabetes mellitus, uncontrolled.
   HbA1c 9.2%. Discussed diet and medication compliance.
   Adjusted insulin dosing.
   ```
3. Click **"🔬 Analyze & Generate Codes"**
4. Verify results appear

### Step 5: Stop the Application

Press `Ctrl + C` in terminal to stop the server.

---

## 🚀 Push to Hugging Face Space

Once you've tested locally and made changes, follow these steps to deploy.

### Step 1: Get Hugging Face Access Token

1. **Log in to Hugging Face:** `https://huggingface.co`
2. **Click your profile** (top right) → **Settings**
3. **Click "Access Tokens"** (left sidebar)
4. **Click "New token"**
5. **Configure:**
   - Name: `icd-cpt-deploy`
   - Role: **Write**
6. **Click "Generate token"**
7. **Copy the token** (starts with `hf_...`)
8. **Save it securely** - you won't see it again!

### Step 2: Configure Git for Hugging Face

```bash
# Set your Hugging Face username
git config --global user.name "YourHuggingFaceUsername"

# Set your email
git config --global user.email "your.email@example.com"
```

### Step 3: Initialize Git (If Not Already Done)

```bash
# Check if git is initialized
git status

# If error "not a git repository", initialize:
git init

# Add all files
git add .

# Make first commit
git commit -m "Initial setup"
```

### Step 4: Add Hugging Face Remote

```bash
# Add Hugging Face Space as remote
git remote add space https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio

# Verify remote
git remote -v
```

**Expected output:**

```
space   https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio (fetch)
space   https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio (push)
```

### Step 5: Push Your Changes

```bash
# Pull latest changes first (if working with team)
git pull space main --allow-unrelated-histories

# If conflicts, resolve them, then:
git add .
git commit -m "Merge remote changes"

# Push your changes
git push space main
```

**If prompted for credentials:**

- **Username:** Your Hugging Face username
- **Password:** Your Hugging Face **Access Token** (not your password!)

### Step 6: Monitor Deployment

1. **Go to your Space:** `https://huggingface.co/spaces/Distopia22/icd-cpt-coding-gradio`
2. **Click "Logs" tab** to see build progress
3. **Wait 1-2 minutes** for deployment
4. **Status changes to** 🟢 **Running**
5. **Click on your Space URL** to test live version

### Step 7: Verify Live Deployment

**Your live app will be at:**

```
https://Distopia22-icd-cpt-coding-gradio.hf.space
```

**Test the same workflow as local testing:**

1. Check API Status ✅
2. Load Example ✅
3. Analyze Provider Notes ✅
4. Verify results ✅

---

## 🔄 Making Updates (Workflow)

### Daily Workflow:

```bash
# 1. Activate virtual environment
venv\Scripts\activate  # Windows
source venv/bin/activate  # Mac/Linux

# 2. Pull latest changes
git pull space main

# 3. Make your code changes in app.py or other files

# 4. Test locally
python app.py
# Test in browser: http://localhost:7860

# 5. If tests pass, commit changes
git add .
git commit -m "Descriptive message about your changes"

# 6. Push to Hugging Face
git push space main

# 7. Monitor deployment in Logs tab
# 8. Test live version
```

---

## 🐛 Troubleshooting

### Issue 1: "ModuleNotFoundError: No module named 'gradio'"

**Solution:**

```bash
# Make sure virtual environment is activated
# Look for (venv) in terminal prompt

# Reinstall dependencies
pip install -r requirements.txt
```

### Issue 2: "Port 7860 already in use"

**Solution:**

```bash
# Find and kill the process using port 7860

# Windows:
netstat -ano | findstr :7860
taskkill /PID <PID_NUMBER> /F

# Mac/Linux:
lsof -ti:7860 | xargs kill -9

# Or change port in app.py:
# demo.launch(server_port=7861)
```

### Issue 3: Backend API not responding

**Solution:**

```python
# In app.py, update the API URL (line 147):
value="https://YOUR-ACTUAL-BACKEND-URL.hf.space",

# Test backend URL in browser:
# Should open: https://YOUR-BACKEND-URL.hf.space/docs
```

### Issue 4: Git push fails - "Permission denied"

**Solution:**

```bash
# Make sure you're using Access Token, not password
# Regenerate token if needed: https://huggingface.co/settings/tokens

# Or use SSH instead of HTTPS:
git remote set-url space git@hf.co:spaces/Distopia22/icd-cpt-coding-gradio
```

### Issue 5: Deployment fails on Hugging Face

**Check these:**

1. **requirements.txt** has correct versions
2. **README.md** has correct header with `sdk: gradio`
3. **app.py** has no syntax errors
4. Check **Logs** tab for specific error messages

---

## 📞 Getting Help

### If you encounter issues:

1. **Check Logs:**

   - Local: Terminal output
   - Hugging Face: Logs tab in Space

2. **Common fixes:**

   - Restart virtual environment
   - Clear pip cache: `pip cache purge`
   - Delete and recreate venv

3. **Contact:**
   - Team Lead: [Your contact]
   - Hugging Face Docs: https://huggingface.co/docs/hub/spaces

---

## ✅ Quick Reference Commands

```bash
# Activate virtual environment
venv\Scripts\activate  # Windows
source venv/bin/activate  # Mac/Linux

# Run locally
python app.py

# Git workflow
git add .
git commit -m "Your message"
git push space main

# Check status
git status
git log --oneline -5

# Pull updates
git pull space main
```

---

## 📚 Additional Resources

- **Gradio Documentation:** https://gradio.app/docs
- **Hugging Face Spaces:** https://huggingface.co/docs/hub/spaces
- **Git Tutorial:** https://git-scm.com/docs/gittutorial
- **Python Virtual Environments:** https://docs.python.org/3/tutorial/venv.html

---

**Good luck! 🚀**

If you follow this guide step-by-step, you'll have the frontend running locally and deployed to Hugging Face in under 30 minutes.