A machine translation project exploring fine-tuning transformer models for translation tasks, with comprehensive documentation and cross-platform support.

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install Jupyter kernel for notebook execution
python -m ipykernel install --user --name=translation --display-name="translation"

# Activate environment
source .venv/bin/activate

# Run training with papermill
./train_with_papermill.sh --epochs 3 --num-samples 1000

# Or with custom parameters
./train_with_papermill.sh --epochs 5 --lr 1e-4 --num-samples 5000

The project uses PyTorch 2.3.1 by default, which supports MPS (Metal Performance Shaders) on macOS 12.3+ (Monterey).

To use newer PyTorch versions on macOS:

Upgrade to latest PyTorch (macOS 13+ only):

pip install --upgrade torch torchvision torchaudio

You can use the latest PyTorch without restrictions:

# Unpin PyTorch in requirements.txt, then:
pip install --upgrade torch torchvision torchaudio

Or edit requirements.txt to use:

torch>=2.8.0  # Latest version
torchvision
torchaudio

PyTorch 2.5+ requires macOS 13.0+ for MPS (GPU acceleration). Since this project was developed on macOS 12.7.6, we pin to 2.3.1 to ensure MPS works. If you have newer macOS or aren't using MPS, feel free to upgrade!

• macOS 12.3-12.7: Uses MPS with PyTorch 2.3.1 (~3-5x faster than CPU)
• macOS 13.0+: Can use MPS with PyTorch 2.8+ (~3-5x faster than CPU)
• Older macOS: Falls back to CPU

• Uses CUDA automatically with any PyTorch version
• Significantly faster than CPU or MPS

• Works on all platforms
• Slower but functional for development/testing

.
├── translating_with_gemma.ipynb  # Main training notebook
├── train_with_papermill.sh       # Automated training script
├── requirements.txt              # Python dependencies
├── article.md                    # Technical article
├── diagrams/                     # Mermaid diagrams

• article.md - Complete technical article on machine translation with Gemma 3
• TRAINING.md - Training guide and configuration reference
• MODEL_CHECKPOINT.md - Model checkpoint management and HuggingFace Hub upload
• CLAUDE.md - Development guide and project architecture

• ✅ CUDA (NVIDIA GPUs) - Automatic quantization
• ✅ MPS (Apple Silicon) - Native acceleration
• ✅ CPU - Universal fallback

• Skips pip installs when running via papermill (faster)
• Runs installs normally in Jupyter/Colab (full compatibility)
• Uses custom %%skip_if_env magic command

• Papermill-based execution with parameters
• Timestamped output notebooks
• TensorBoard logging

• Handles pyenv/venv conflicts automatically
• Correct Jupyter kernel selection
• Explicit binary paths to avoid issues

./train_with_papermill.sh [options]

Options:
  --epochs N              Number of training epochs (default: 3)
  --lr RATE              Learning rate (default: 2e-4)
  --num-samples N        Training samples (default: 1000)
  --lora-r N             LoRA rank (default: 16)
  --lora-alpha N         LoRA alpha (default: 32)
  --skip-install         Skip pip installs (default: true)
  --no-skip-install      Run pip installs

See MPS_TROUBLESHOOTING.md for:

• PyTorch version compatibility matrix
• Diagnostic commands
• Step-by-step solutions

# Verify all packages
python -c "import torch, transformers, datasets, peft; print('OK')"

# Reinstall if needed
pip install -r requirements.txt

See PYENV_VENV_TROUBLESHOOTING.md

This is a research/learning project. Feel free to adapt for your own use!

See LICENSE file for details.

• Article: article.md - Technical writeup on machine translation
• Training Logs: training_runs/ - Executed notebooks with results
• Models: Models saved to specified output directory
• Diagrams: diagrams/ - Visual explanations of concepts