Setup Guide

Step 1: Create a Virtual Environment

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

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:

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:

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

python3 fine_tune.py

This will:

Download the Liquid AI model from HuggingFace (~2.4 GB, first run only)
Train LoRA adapters on the spam/ham data (3 epochs, ~2-2.5 hours on Apple Silicon)
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

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:

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!')
"