README.md

---
title: Pathora Colposcopy Assistant
emoji: 🔬
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
app_port: 7860
---
<!-- Updated: 2026-03-06 -->

# Pathora Colposcopy Assistant

A comprehensive React-based colposcopy assistant application with image annotation, patient history tracking, Swede Score assessment, and AI-powered chatbot features.

## Local Development

The app has two parts that need to run at the same time:
- **Backend** – FastAPI (Python) on `http://localhost:8000`
- **Frontend** – Vite dev server (React) on `http://localhost:5173`

Vite is pre-configured to proxy all `/api/*` and `/infer/*` requests to the backend.

### Step 1 – Set up your Gemini API key

Copy `.env.example` to `.env` and fill in your key:

```bash
cp .env.example .env   # or rename a copy manually on Windows
```

Edit `.env`:
```
GEMINI_API_KEY=your_actual_gemini_api_key_here
```

Get a free key at: https://makersuite.google.com/app/apikey

### Step 2 – Install Python dependencies (backend)

It is recommended to use a virtual environment:

```bash
# Create and activate a virtual environment (Windows)
python -m venv .venv
.venv\Scripts\activate

# Install backend packages
pip install -r backend/requirements.txt
```

### Step 3 – Start the FastAPI backend

From the **project root folder**, run:

```bash
uvicorn backend.app:app --host 0.0.0.0 --port 8000 --reload
```

The API will be available at `http://localhost:8000`.
You can test the health endpoint: `http://localhost:8000/health`

### Step 4 – Install Node.js dependencies (frontend)

```bash
npm install
```

### Step 5 – Start the Vite dev server

In a **separate terminal**, from the project root:

```bash
npm run dev
```

The app will be available at `http://localhost:5173`.

### Step 6 – Build for production

```bash
npm run build
```


## Deploy to Hugging Face Spaces

This project is configured for deployment on Hugging Face Spaces using Docker runtime.

### Step-by-Step Deployment Instructions

#### Step 1: Install Git and Git LFS

If you don't have Git installed:
- Download and install Git from https://git-scm.com/download/win
- Restart your terminal after installation

Install Git LFS (Large File Storage):
```bash
git lfs install
```

#### Step 2: Initialize Git Repository

Navigate to your project folder and initialize Git:
```bash
cd "c:\Users\FARRUKH SAYEED\OneDrive\Desktop\Manalife Internship\Pathora_colpo"
git init
```

#### Step 3: Add Hugging Face Remote

Add your Hugging Face Space as the remote repository:
```bash
git remote add origin https://huggingface.co/spaces/ManalifeAI/Pathora_Colposcopy_Assistant
```

#### Step 4: Stage All Files

Add all files to Git:
```bash
git add .
```

#### Step 5: Commit Your Changes

Create your first commit:
```bash
git commit -m "Initial deployment of Pathora Colposcopy Assistant"
```

#### Step 6: Push to Hugging Face

Push your code to Hugging Face Spaces:
```bash
git push -u origin main
```

**Note:** You'll be prompted for your Hugging Face credentials:
- Username: Your Hugging Face username
- Password: Use a **Hugging Face Access Token** (not your password)
  - Get token from: https://huggingface.co/settings/tokens
  - Create a new token with "write" access if you don't have one

#### Step 7: Wait for Build

After pushing:
1. Go to https://huggingface.co/spaces/ManalifeAI/Pathora_Colposcopy_Assistant
2. The Space will automatically start building from the Dockerfile
3. Wait 2-5 minutes for the build to complete
4. Your app will be live at the Space URL

### Updating Your Space

To push updates after making changes:
```bash
git add .
git commit -m "Description of your changes"
git push
```

## Local Docker Testing (Optional)

Test the Docker build locally before deploying:

```bash
# Build the image
docker build -t pathora-colposcopy .

# Run the container
docker run --rm -e PORT=7860 -p 7860:7860 pathora-colposcopy

# Open http://localhost:7860 in your browser
```

## Project Structure

- `src/` - React TypeScript source code
  - `components/` - Reusable UI components
  - `pages/` - Page components
- `public/` - Static assets
- `Dockerfile` - Docker configuration for Hugging Face Spaces
- `vite.config.ts` - Vite build configuration

## Technologies Used

- React 18
- TypeScript
- Vite
- Tailwind CSS
- Lucide React Icons
- html2pdf.js

## Space URL

🚀 Live at: https://huggingface.co/spaces/ManalifeAI/Pathora_Colposcopy_Assistant