KBBQ Classifier 2.0

Features

• Transfer learning on a pretrained ViT model? via Hugging Face Transformers + Datasets
• ImageFolder-based local dataset support with train/val split utility
• Proper label mapping persistence for reliable inference and Hub sharing
• Metrics: accuracy, F1 (macro), confusion matrix support
• Early stopping and checkpointing
• FastAPI inference service with an upload page
• Optional push to Hugging Face Hub (model + config)

Project Structure

.
├─ src/kbbq_classifier/          # Package code (shared utilities)
├─ scripts/                      # CLI scripts for train/eval/predict and dataset tools
├─ app/                          # FastAPI backend + minimal UI
│  ├─ templates/
│  └─ static/
├─ configs/                      # YAML configs (training, paths)
├─ data/                         # Put your dataset here (ignored by git)
├─ artifacts/                    # Model outputs/checkpoints (ignored by git)
├─ tests/                        # Basic tests
├─ requirements.txt
├─ README.md
└─ .gitignore

Dataset

data/
  raw/                         # Your raw, unsplit dataset (optional)
    beef_brisket/
      img001.jpg
      ...
    pork_belly/
      img001.jpg
      ...
  kbbq/                        # Train/val split created by split script
    train/
      beef_brisket/
      pork_belly/
    val/
      beef_brisket/
      pork_belly/

Quickstart

1. Create and activate a virtual environment (Windows PowerShell):

python -m venv .venv (Create venv)
.venv\Scripts\Activate.ps1 (activate)
pip install -r requirements.txt (install dependencies)
deactive (when done)

1. split into train/val python scripts/split_dataset.py --source data/raw --target data/kbbq --val-ratio 0.2 --seed 42 (20% go to vali set, 80 to training)
2. Configure training in configs/train.yaml (paths, model name, hyperparameters).
3. Train and evaluate:

1. Run local inference from CLI:

1. Start FastAPI server:

Push to Hugging Face Hub

1. Set your token:

# One-time login, interactive (optional)
huggingface-cli login

# Or via environment variable in the shell session
$env:HUGGINGFACE_HUB_TOKEN = "your_token_here"

1. Use the train script flag to push after training:

python scripts/train.py --config configs/train.yaml
python scripts/predict.py --push-to-hub --hub-repo-id your-username/kbbq-classifier --model-dir artifacts/model

Notes

• With small datasets (<200 images), strong augmentation and transfer learning are key. Might need to collect more data over time if model is weak.
• Can change the base model name (e.g., google/vit-base-patch16-224) in configs/train.yaml. Smaller models may train faster.
• For GPU acceleration, install appropriate PyTorch build (pytorch.org). The default torch in requirements is CPU-friendly.

Roadmap

• Transfer learning image classifier with Hugging Face
• FastAPI inference service + simple UI
• Model monitoring and drift checks
• Dockerization and CI/CD
• Full-stack frontend and cloud deployment

1. scaffold project struct w/ app for website, configs for model & parameters, src for ??, data for image datasets, scripts for running program like splitting dataset, training, and evaulation, and basic stuff like gitignore, readme, requirements.
2. create env and install dependencies
3. split data into train/validation
4. train and evaulate (some small errors but fixed w/ some code)
5. quick prediction (predictions are good only on existing train/val data(obviously?), but will still rank high top-k for random images in either direction, so prob need a lot more data, try testing on real world example w/ only those 2 classes)

• testing on downloaded google images seem to be ok w/ those 2 specific classes, but colors of pb and bb overlap so cant be wrong, need a way to differiante in training between the 2 classes

1. server works locally w/ the 1 function