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
2. Clone the Repository
3. Local Setup
4. Test on Local Machine
5. Push to Hugging Face Space
6. Troubleshooting

---

🔧 Prerequisites

Before you begin, ensure you have the following installed:

Required Software:

• Python 3.10 or higher - Download Python
• Git - Download Git
• Hugging Face Account - Sign up here
• Code Editor (VS Code, PyCharm, or any editor)

Verify Installations:

# 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)

# 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:

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate

Mac/Linux:

# 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

# 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

# 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:

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

# 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

# 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)

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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.