docs/06-setup-guide.md

# Setup Guide

## Step 1: Create a Virtual Environment

```bash
cd /path/to/spam-classifier-liquid
python3 -m venv venv
source venv/bin/activate
```

You should see `(venv)` at the start of your terminal prompt.

## Step 2: Install Dependencies

```bash
pip install -r requirements.txt
```

This installs PyTorch, HuggingFace Transformers, TRL, PEFT, Gradio, and other packages. It may take a few minutes.

## Step 3: Copy Training Data

The training data comes from the MLX sibling project. Copy it:

```bash
mkdir -p training_data
cp ../spam-classifier-mlx/training_data/train.jsonl training_data/
cp ../spam-classifier-mlx/training_data/test.jsonl training_data/
```

Verify the files:
```bash
wc -l training_data/train.jsonl training_data/test.jsonl
```

You should see ~3,200 lines in train.jsonl and ~800 in test.jsonl.

## Step 4: Fine-Tune the Model

```bash
python3 fine_tune.py
```

This will:
1. Download the Liquid AI model from HuggingFace (~2.4 GB, first run only)
2. Train LoRA adapters on the spam/ham data (3 epochs, ~2-2.5 hours on Apple Silicon)
3. Save the trained adapter to `adapters/`

**Tip:** The notebook (`spam_classifier_liquid.ipynb`) runs only 1 epoch (~45 minutes) for a quicker demo. Use `fine_tune.py` for the full 3-epoch training when you have time.

## Step 5: Launch the Web App

```bash
python3 app.py
```

Open http://127.0.0.1:7860 in your browser.

## Alternative: Double-Click Launchers

On macOS, you can double-click these files in Finder instead of using the terminal:
- `retrain.command` — runs fine_tune.py
- `launch UI.command` — starts the web app

## Verifying Your Setup

Run this quick check to make sure everything is installed correctly:

```python
python3 -c "
import torch
import transformers
import peft
import trl
print(f'PyTorch:      {torch.__version__}')
print(f'MPS available: {torch.backends.mps.is_available()}')
print(f'Transformers: {transformers.__version__}')
print(f'PEFT:         {peft.__version__}')
print(f'TRL:          {trl.__version__}')
print('All good!')
"
```