pAIrate

A project to fine-tune language models using Apple's MLX framework to respond like a pirate.

Setup

1. Configure environment variables:

cp .env.example .env

Edit the .env file to customize paths and model settings:

# Model Configuration
MODEL_NAME=mlx-community/Mistral-7B-Instruct-v0.3-4bit

# Directory Paths
MODEL_PATH=./model
DATA_PATH=./data
ADAPTERS_PATH=./adapters

2. Install dependencies:

# Install runtime dependencies
uv sync

# Install with development dependencies (for contributing)
uv sync --extra dev

Usage

You can run the CLI in two ways:

Option 1: Using uv run (recommended for development)

uv run src/main.py COMMAND

Option 2: Using the installed script (after uv sync)

pairate COMMAND

Complete Pipeline

Run the entire process (download model and train):

uv run src/main.py all
# or
pairate all

Individual Steps

1. Download model:

uv run src/main.py download
# or
pairate download

2. Train the model:

uv run src/main.py train
# or
pairate train

3. Generate pirate responses (requires model download first):

uv run src/main.py generate "Hello, how are you?"
# or
pairate generate "Hello, how are you?"

Note: For generation to work, you must download the model first using download or all.

CLI Commands

The project uses Click for a clean command-line interface:

• download - Download model from Hugging Face
• train [OPTIONS] - Train the model using MLX
• generate PROMPT - Generate pirate response for prompt
• all [OPTIONS] - Run complete pipeline

Global Options

• --model TEXT - Specify model (default: from MODEL_NAME env var)

Training Options

• --iterations INTEGER - Number of training iterations (default: 100)
• --batch-size INTEGER - Training batch size (default: 2)

The model will be fine-tuned to respond like a pirate with "Arrr" and nautical language!

Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Python 3.8.1+
• MLX framework (installed via pyproject.toml)

Configuration

The project uses environment variables for configuration. All paths and model settings can be customized by editing the .env file:

• MODEL_NAME: The Hugging Face model to download and fine-tune
• MODEL_PATH: Directory where the downloaded model will be stored
• DATA_PATH: Directory containing training data files (train.jsonl, valid.jsonl, test.jsonl)
• ADAPTERS_PATH: Directory where LoRA adapters will be saved after training

This makes it easy to switch between different models or organize files in different directories without modifying code.

Data Files

The project includes three data files:

• train.jsonl: Training examples for fine-tuning the model
• valid.jsonl: Validation examples used during training
• test.jsonl: Test examples for evaluating model performance after training

Each file contains JSON lines with prompt and completion fields showing how the model should respond in pirate style.

Development

Code Quality

The project includes a comprehensive CI/CD pipeline that runs on every push and pull request:

• Black: Code formatting
• isort: Import sorting
• Flake8: Linting and style checking
• MyPy: Static type checking

Running Quality Checks Locally

# Install development dependencies
uv sync --extra dev

# Format code
uv run black .
uv run isort .

# Check code quality
uv run black --check .
uv run isort --check-only .
uv run flake8 .
uv run mypy .