SETUP.md

# Setup Instructions

## Prerequisites
- Python 3.11+
- Virtual environment (already created in `venv/`)

## Quick Start

### Option 1: Using the run script (Recommended)
```bash
./run.sh
```

### Option 2: Manual setup

1. **Create a `.env` file** in the root directory with your HuggingFace read token:
```bash
echo "READ_TOKEN=your_huggingface_read_token_here" > .env
```

To get a HuggingFace token:
1. Go to https://huggingface.co/settings/tokens
2. Create a new token with "Read" permissions
3. Copy the token and paste it in your `.env` file

2. **Activate the virtual environment:**
```bash
source venv/bin/activate
```

3. **Run the application:**
```bash
python app.py
```

## What Happens on First Run

The app will automatically download:
- **Models** to `model_classification/` directory (from `Serrelab/fossil_classification_models`)
- **SAM Model** to `model/` directory (from `Serrelab/SAM_Leaves`)
- **Datasets** to `dataset/` and `images/` directories (from `Serrelab/Fossils` and `Serrelab/image_examples_gradio`)

**Note:** These downloads require a valid `READ_TOKEN` in your `.env` file.

## Accessing the App

Once running, the app will be available at:
- **Local URL:** http://localhost:7860
- The URL will be displayed in the terminal when the app starts

## Troubleshooting

### "401 Unauthorized" Error
- Make sure you have created a `.env` file with a valid `READ_TOKEN`
- Verify your token has "Read" permissions at https://huggingface.co/settings/tokens

### Models Already Downloaded
- If models are already present in `model_classification/` and `model/` directories, the app will skip downloading
- You can still run the app without a token if models are already present