DEV Community: Prashant Nigam

The Magic of LoRA Fine-Tuning with MLX (Part 4)

Prashant Nigam — Tue, 11 Nov 2025 23:58:06 +0000

This is where the magic happens! In this part, we will deep dive into LoRA (Low-Rank Adaptation) fine-tuning and use MLX to train our model with incredible efficiency on Apple Silicon.

Understanding LoRA: The Game-Changing Technique

Imagine you are a master chef who wants to learn a new cuisine. Instead of forgetting everything you know and starting from scratch, you add new techniques and flavor profiles to your existing knowledge. That's exactly what LoRA (Low-Rank Adaptation) does for language models.

The Traditional Fine-Tuning Problem

Traditional fine-tuning updates all 1.7 billion parameters of our model. This means:

❌ Massive memory requirements
❌ Slow training
❌ Risk of "catastrophic forgetting" (losing general knowledge)
❌ Large model files

The LoRA Solution

LoRA adds small "adapter" layers that learn new behaviors while keeping the original model frozen:

✅ Minimal memory usage
✅ Fast training
✅ Preserves general knowledge
✅ Tiny adapter file size
✅ Can be combined or switched out easily

How LoRA Works Under the Hood

Think of the original model as a Swiss Army knife with all its tools welded in place. LoRA adds new attachments that can be snapped on or off.

MLX: Apple's Secret Weapon for AI

MLX is Apple's machine learning framework designed specifically for Apple Silicon. It's what makes our local fine-tuning possible and incredibly fast.

Why MLX is good for Local AI

Unified Memory Architecture: M-series chips share memory between CPU and GPU, eliminating data transfer bottlenecks
Optimized Computation: Hand-tuned for Apple Silicon's specific capabilities
Memory Efficiency: Intelligent memory management for maximum model sizes
Python Integration: Easy to use while being incredibly fast

Setting Up Our Fine-Tuning Pipeline

Let us build our fine-tuning system step by step, understanding each component.

Step 1: Configuration and Setup

First, let's create a comprehensive configuration system:

touch fine_tuning_config.py

# Create fine_tuning_config.py
import os
from pathlib import Path
import mlx.core as mx

class FineTuningConfig:
    """Centralized configuration for fine-tuning"""

    def __init__(self):
        # Model configuration
        self.base_model = "HuggingFaceTB/SmolLM2-1.7B-Instruct"
        self.adapter_path = "./adapters/email_sentiment"

        # Data paths
        self.train_data_path = "./data/mlx_format/train.jsonl"
        self.valid_data_path = "./data/mlx_format/valid.jsonl"

        # LoRA parameters
        self.lora_layers = 16  # Number of transformer layers to add LoRA to
        self.lora_rank = 16    # The 'r' in LoRA - higher = more capacity but slower
        self.lora_alpha = 32   # Scaling factor for LoRA adapters

        # Training parameters
        self.batch_size = 2           # Batch size (reduce if out of memory)
        self.learning_rate = 5e-5     # Learning rate
        self.max_iters = 1000         # Maximum training iterations
        self.steps_per_report = 10    # How often to print progress
        self.steps_per_eval = 200     # How often to run validation
        self.save_every = 400         # How often to save checkpoints

        # Hardware optimization
        self.use_gpu = mx.metal.is_available()
        self.max_sequence_length = 2048

        # Create directories
        Path(self.adapter_path).mkdir(parents=True, exist_ok=True)

    def print_config(self):
        """Print current configuration"""
        print("🔧 Fine-tuning Configuration:")
        print(f"  Base model: {self.base_model}")
        print(f"  GPU available: {self.use_gpu}")
        print(f"  LoRA rank: {self.lora_rank}")
        print(f"  LoRA layers: {self.lora_layers}")
        print(f"  Batch size: {self.batch_size}")
        print(f"  Learning rate: {self.learning_rate}")
        print(f"  Max iterations: {self.max_iters}")
        print(f"  Adapter path: {self.adapter_path}")

# Create and test config
if __name__ == "__main__":
    config = FineTuningConfig()
    config.print_config()

Step 2: Memory and Performance Monitoring

Before we start fine-tuning, let's create tools to monitor our system:

touch monitoring.py

# Create monitoring.py
import time
import mlx.core as mx
from typing import Dict, List
import psutil

class PerformanceMonitor:
    """Monitor memory usage and training performance"""

    def __init__(self):
        self.start_time = time.time()
        self.metrics = []

    def log_memory_usage(self, step: int, loss: float = None):
        """Log current memory and performance metrics"""

        # GPU memory (if available)
        gpu_memory = {}
        if mx.metal.is_available():
            gpu_memory = {
                'active_mb': mx.metal.get_active_memory() / 1e6,
                'peak_mb': mx.metal.get_peak_memory() / 1e6
            }

        # System memory
        system_memory = psutil.virtual_memory()

        # Training metrics
        elapsed = time.time() - self.start_time

        metrics = {
            'step': step,
            'elapsed_seconds': elapsed,
            'loss': loss,
            'gpu_active_mb': gpu_memory.get('active_mb', 0),
            'gpu_peak_mb': gpu_memory.get('peak_mb', 0),
            'system_memory_percent': system_memory.percent,
            'system_memory_available_gb': system_memory.available / 1e9
        }

        self.metrics.append(metrics)

        if step % 50 == 0:  # Print every 50 steps
            self.print_status(metrics)

        return metrics

    def print_status(self, metrics: Dict):
        """Print current training status"""

        print(f"Step {metrics['step']:4d} | "
              f"Loss: {metrics['loss']:.4f} | "
              f"GPU: {metrics['gpu_active_mb']:.0f}MB | "
              f"Time: {metrics['elapsed_seconds']:.1f}s")

    def get_training_summary(self):
        """Get summary of training run"""

        if not self.metrics:
            return {}

        peak_gpu = max(m['gpu_peak_mb'] for m in self.metrics)
        total_time = self.metrics[-1]['elapsed_seconds']
        final_loss = self.metrics[-1]['loss']

        return {
            'total_training_time': total_time,
            'peak_gpu_memory_mb': peak_gpu,
            'final_loss': final_loss,
            'steps_completed': len(self.metrics)
        }

Step 3: The Fine-Tuning Engine

Now let's create our main fine-tuning script using MLX-LM:

touch fine_tune_model.py

# Create fine_tune_model.py
import subprocess
import time
import json
import os
from pathlib import Path
from fine_tuning_config import FineTuningConfig
from monitoring import PerformanceMonitor

class MLXFineTuner:
    """Fine-tune models using MLX with LoRA"""

    def __init__(self, config: FineTuningConfig):
        self.config = config
        self.monitor = PerformanceMonitor()

    def validate_data(self):
        """Validate that training data exists and is properly formatted"""

        print("📊 Validating training data...")

        if not os.path.exists(self.config.train_data_path):
            raise FileNotFoundError(f"Training data not found: {self.config.train_data_path}")

        # Count training examples
        train_count = 0
        with open(self.config.train_data_path, 'r') as f:
            for line in f:
                if line.strip():
                    train_count += 1

        print(f"✅ Found {train_count} training examples")

        # Validate format
        with open(self.config.train_data_path, 'r') as f:
            first_line = f.readline()
            try:
                example = json.loads(first_line)
                if 'text' not in example:
                    raise ValueError("Training data must have 'text' field")
                print("✅ Data format validated")
            except json.JSONDecodeError:
                raise ValueError("Training data must be valid JSONL format")

        return train_count

    def build_training_command(self):
        """Build the MLX-LM training command"""

        cmd = [
            "python3", "-m", "mlx_lm", "lora",
            "--model", self.config.base_model,
            "--train",
            "--data", "./data/mlx_format",  # Directory containing train.jsonl
            "--batch-size", str(self.config.batch_size),
            "--iters", str(self.config.max_iters),
            "--learning-rate", str(self.config.learning_rate),
            "--steps-per-report", str(self.config.steps_per_report),
            "--steps-per-eval", str(self.config.steps_per_eval),
            "--adapter-path", self.config.adapter_path,
            "--save-every", str(self.config.save_every)
        ]

        return cmd

    def run_fine_tuning(self):
        """Execute the fine-tuning process"""

        print("🚀 Starting LoRA fine-tuning with MLX...")
        print("=" * 60)

        # Validate everything is ready
        train_count = self.validate_data()
        self.config.print_config()

        # Build command
        cmd = self.build_training_command()
        print(f"\n📝 Command: {' '.join(cmd)}")

        # Start training
        start_time = time.time()

        print(f"\n🏃 Training started at {time.strftime('%H:%M:%S')}")
        print(f"📚 Training on {train_count} examples")
        print("💡 This typically takes 3-10 minutes on Apple Silicon M3")
        print("⏰ Progress will be reported every 10 steps\n")

        try:
            # Run the training command
            result = subprocess.run(cmd, capture_output=True, text=True, check=True)

            training_time = time.time() - start_time

            print("\n" + "="*60)
            print("🎉 Fine-tuning completed successfully!")
            print(f"⏱️  Total training time: {training_time:.1f} seconds")
            print(f"💾 Adapters saved to: {self.config.adapter_path}")

            # Save training metadata
            metadata = {
                'model_name': self.config.base_model,
                'training_time_seconds': training_time,
                'training_examples': train_count,
                'lora_rank': self.config.lora_rank,
                'lora_layers': self.config.lora_layers,
                'batch_size': self.config.batch_size,
                'learning_rate': self.config.learning_rate,
                'max_iters': self.config.max_iters,
                'timestamp': time.time(),
                'command_used': ' '.join(cmd)
            }

            metadata_path = f"{self.config.adapter_path}/training_metadata.json"
            with open(metadata_path, 'w') as f:
                json.dump(metadata, f, indent=2)

            print(f"📊 Training metadata saved to: {metadata_path}")

            # Parse and display training output
            self.parse_training_output(result.stdout)

            return True, metadata

        except subprocess.CalledProcessError as e:
            print("\n❌ Fine-tuning failed!")
            print(f"Error code: {e.returncode}")
            print(f"Error output: {e.stderr}")
            print(f"Standard output: {e.stdout}")
            return False, None

    def parse_training_output(self, output: str):
        """Parse and display key information from training output"""

        print("\n📈 Training Progress Summary:")
        print("-" * 40)

        lines = output.split('\n')

        # Look for key training metrics
        for line in lines:
            if 'Loss:' in line or 'Validation' in line:
                print(f"  {line.strip()}")

        # Look for final metrics
        for line in reversed(lines):
            if 'Loss:' in line:
                print(f"\n🎯 Final training loss: {line.split('Loss:')[-1].strip()}")
                break

    def verify_training_output(self):
        """Verify that training produced the expected files"""

        print("\n🔍 Verifying training output...")

        adapter_path = Path(self.config.adapter_path)

        # Check for adapter files
        adapter_files = list(adapter_path.glob("*.safetensors")) + list(adapter_path.glob("*.npz"))
        if adapter_files:
            print(f"✅ Found adapter files: {[f.name for f in adapter_files]}")
        else:
            print("❌ No adapter files found")
            return False

        # Check for configuration
        config_file = adapter_path / "adapter_config.json"
        if config_file.exists():
            print(f"✅ Found adapter config: {config_file}")

            # Display config contents
            with open(config_file, 'r') as f:
                config_data = json.load(f)
                print(f"   LoRA rank: {config_data.get('r', 'unknown')}")
                print(f"   LoRA alpha: {config_data.get('lora_alpha', 'unknown')}")
        else:
            print("⚠️  No adapter config found")

        # Calculate total size
        total_size = sum(f.stat().st_size for f in adapter_path.rglob('*') if f.is_file())
        print(f"📁 Total adapter size: {total_size / 1e6:.1f} MB")

        return True

def main():
    """Main fine-tuning execution"""

    print("🤖 MLX LoRA Fine-Tuning Pipeline")
    print("=" * 50)

    # Create configuration
    config = FineTuningConfig()

    # Create fine-tuner
    fine_tuner = MLXFineTuner(config)

    # Run fine-tuning
    success, metadata = fine_tuner.run_fine_tuning()

    if success:
        # Verify output
        fine_tuner.verify_training_output()

        print("\n✨ Fine-tuning pipeline completed successfully!")
        print("\n🎯 Next steps:")
        print("  1. Test your fine-tuned model")
        print("  2. Run evaluation to measure performance")
        print("  3. Build your application interface")

        return metadata
    else:
        print("\n💥 Fine-tuning failed. Please check the error messages above.")
        return None

if __name__ == "__main__":
    metadata = main()

Data Preparation and Training Formats (Part 3)

Prashant Nigam — Tue, 11 Nov 2025 23:57:29 +0000

Data is the foundation of any successful AI model. In this part, we'll explore how to create, format, and prepare high-quality training data that will make our email sentiment classifier incredibly accurate.

Why Data Quality Matters More Than Model Size

Here's a truth that might surprise you: A smaller model trained on high-quality, domain-specific data can outperforms a massive general-purpose model on specific tasks.

Think of it this way: would you rather have a Swiss Army knife or a scalpel for surgery? General models are Swiss Army knives - versatile but not optimized. Fine-tuned models are scalpels - precise tools for specific jobs.

Understanding Language Model Training Formats

Language models learn by predicting the next piece of text. For fine-tuning, we need to show them examples of the exact conversations we want them to have.

The Anatomy of a Training Example

Every training example teaches the model a specific pattern. For our email sentiment classifier, each example shows:

The Question: "What's the sentiment of this email?"
The Context: The actual email content
The Expected Answer: The correct sentiment classification

Here's what this looks like in practice:

{
  "prompt": "Classify the sentiment of this email as positive, negative, or neutral.\n\nSubject: Thank you for excellent service\nEmail: I wanted to express my gratitude for the outstanding support I received. The team was helpful and professional.\n\nSentiment:",
  "completion": " positive"
}

Notice the space before "positive" in the completion - this helps the model learn proper tokenization.

Chat Templates: Teaching Models to Converse

Modern language models use chat templates to understand conversation structure. Think of them as formatting rules that help the model distinguish between:

User messages (questions/prompts)
Assistant messages (responses)
System messages (instructions)

Understanding the SmolLM2 Chat Template

Our base model (SmolLM2-1.7B-Instruct) uses this chat template:

<|im_start|>user
{user_message}
<|im_end|>
<|im_start|>assistant
{assistant_response}
<|im_end|>

The <|im_start|> and <|im_end|> tokens are special markers that help the model understand who's speaking.

Why Chat Templates Matter

Without proper formatting, models get confused about who's saying what. It's like having a conversation without knowing when each person starts and stops talking. Chat templates provide this crucial structure.

Creating High-Quality Training Data

Let's build our email sentiment dataset step by step. We'll create examples that cover the full range of scenarios our model might encounter.

Step 1: Define Our Classification Categories

For email sentiment analysis, we'll use three clear categories:

Positive: Grateful, satisfied, complimentary emails
Negative: Complaints, frustration, dissatisfaction
Neutral: Informational, requests, general inquiries

Step 2: Create Diverse Email Examples

Here's our data creation script with detailed examples:

touch data_creation.py

# Create data_creation.py
import json
import random
from typing import List, Dict

def create_training_example(subject: str, email_body: str, sentiment: str) -> Dict[str, str]:
    """Create a properly formatted training example"""

    # Create the prompt in a consistent format
    prompt = f"""Classify the sentiment of this email as positive, negative, or neutral.

Subject: {subject}
Email: {email_body}

Sentiment:"""

    # The completion should start with a space for proper tokenization
    completion = f" {sentiment}"

    return {
        "prompt": prompt,
        "completion": completion
    }

def generate_positive_examples() -> List[Dict[str, str]]:
    """Generate positive sentiment email examples"""

    positive_examples = [
        {
            "subject": "Thank you for excellent service",
            "body": "I wanted to express my gratitude for the outstanding support I received. The team was helpful and professional, and my issue was resolved quickly.",
            "sentiment": "positive"
        },
        {
            "subject": "Great job on the project",
            "body": "The deliverables exceeded our expectations. The attention to detail and quality of work was impressive. Looking forward to future collaborations.",
            "sentiment": "positive"
        },
        {
            "subject": "Wonderful experience",
            "body": "Just wanted to share that our experience with your service has been fantastic. The staff is knowledgeable and always willing to help.",
            "sentiment": "positive"
        },
        {
            "subject": "Love the new features",
            "body": "The latest update is amazing! The new features make everything so much easier. Thank you for listening to user feedback.",
            "sentiment": "positive"
        },
        {
            "subject": "Highly recommend",
            "body": "I've been using your service for months now and I'm consistently impressed. The reliability and quality are top-notch.",
            "sentiment": "positive"
        }
    ]

    return [create_training_example(ex["subject"], ex["body"], ex["sentiment"]) 
            for ex in positive_examples]

def generate_negative_examples() -> List[Dict[str, str]]:
    """Generate negative sentiment email examples"""

    negative_examples = [
        {
            "subject": "Disappointed with service",
            "body": "I'm extremely frustrated with the poor quality of support I received. My issue has been ongoing for weeks without resolution.",
            "sentiment": "negative"
        },
        {
            "subject": "System outage - unacceptable",
            "body": "The constant system failures are disrupting our business operations. This is the third outage this month and it's completely unacceptable.",
            "sentiment": "negative"
        },
        {
            "subject": "Billing error needs immediate attention",
            "body": "I've been charged incorrectly for the third time. This is becoming a serious problem and I'm losing confidence in your billing system.",
            "sentiment": "negative"
        },
        {
            "subject": "Very poor customer experience",
            "body": "The representative was unhelpful and seemed disinterested in solving my problem. I've never experienced such poor customer service.",
            "sentiment": "negative"
        },
        {
            "subject": "Product quality issues",
            "body": "The product arrived damaged and doesn't match the description. I'm disappointed and expect a full refund immediately.",
            "sentiment": "negative"
        }
    ]

    return [create_training_example(ex["subject"], ex["body"], ex["sentiment"]) 
            for ex in negative_examples]

def generate_neutral_examples() -> List[Dict[str, str]]:
    """Generate neutral sentiment email examples"""

    neutral_examples = [
        {
            "subject": "Account information update",
            "body": "Please update my billing address to the new address I provided. Let me know when this has been completed.",
            "sentiment": "neutral"
        },
        {
            "subject": "Question about pricing",
            "body": "Could you provide information about your enterprise pricing plans? We're evaluating options for our team of 50 users.",
            "sentiment": "neutral"
        },
        {
            "subject": "Meeting reschedule request",
            "body": "I need to reschedule our meeting from Tuesday to Thursday due to a scheduling conflict. Please confirm if this works.",
            "sentiment": "neutral"
        },
        {
            "subject": "Documentation request",
            "body": "Can you send me the technical documentation for the API integration? I need this for our development team.",
            "sentiment": "neutral"
        },
        {
            "subject": "Password reset",
            "body": "I'm unable to access my account and need to reset my password. Please send reset instructions to this email address.",
            "sentiment": "neutral"
        }
    ]

    return [create_training_example(ex["subject"], ex["body"], ex["sentiment"]) 
            for ex in neutral_examples]

def create_balanced_dataset() -> List[Dict[str, str]]:
    """Create a balanced dataset with equal representation"""

    print("Creating balanced email sentiment dataset...")

    # Generate examples for each category
    positive_examples = generate_positive_examples()
    negative_examples = generate_negative_examples()
    neutral_examples = generate_neutral_examples()

    # Combine all examples
    all_examples = positive_examples + negative_examples + neutral_examples

    # Shuffle to avoid category clustering
    random.shuffle(all_examples)

    print(f"Created {len(all_examples)} training examples:")
    print(f"  Positive: {len(positive_examples)}")
    print(f"  Negative: {len(negative_examples)}")
    print(f"  Neutral: {len(neutral_examples)}")

    return all_examples

def save_training_data(examples: List[Dict[str, str]], filename: str = "training_data.jsonl"):
    """Save training data in JSONL format"""

    with open(filename, 'w') as f:
        for example in examples:
            f.write(json.dumps(example) + '\n')

    print(f"✅ Saved {len(examples)} examples to {filename}")

def preview_examples(examples: List[Dict[str, str]], num_preview: int = 3):
    """Preview some training examples"""

    print(f"\n📋 Preview of {num_preview} training examples:")
    print("=" * 80)

    for i, example in enumerate(examples[:num_preview]):
        print(f"\nExample {i+1}:")
        print(f"Prompt:\n{example['prompt']}")
        print(f"Expected completion: '{example['completion']}'")
        print("-" * 40)

if __name__ == "__main__":
    # Create the dataset
    training_examples = create_balanced_dataset()

    # Preview some examples
    preview_examples(training_examples)

    # Save to file
    save_training_data(training_examples)

    print("\n🎉 Training data creation complete!")

So, let's examine what data we just created and understand the format

After running python data_creation.py, you will see this output and a new file:

Terminal Output:
Creating balanced email sentiment dataset...
Created 15 training examples:
Positive: 5
Negative: 5 Neutral: 5

✅ Saved 15 examples to training_data.jsonl
🎉 Training data creation complete!

New File Created:

training_data.jsonl (2-3 KB) - Your training dataset

### Understanding JSONL Format

JSONL (JSON Lines) is the standard format for ML training data. Unlike regular JSON, each line is a separate JSON object:

Regular JSON:

  [
    {"prompt": "...", "completion": " positive"},
    {"prompt": "...", "completion": " negative"}
  ]

  JSONL (what we created):
  {"prompt": "...", "completion": " positive"}
  {"prompt": "...", "completion": " negative"}

Why JSONL for training?

Memory efficient: Process one example at a time
Streamable: Handle huge datasets without loading everything
Standard: All ML frameworks expect this format

Your training_data.jsonl contains 15 examples (5 positive, 5 negative, 5 neutral) - each line teaching the model how to classify email sentiment. This file is the foundation for everything that follows.

Converting training data to MLX format

What is MLX?

MLX format refers to the specific data format expected by MLX (Apple'smachine learning framework for Apple Silicon).
Apple's ML framework optimized for M1/M2/M3 chips
Designed to leverage Apple Silicon's unified memory architecture
Efficient for training and running models on Mac hardware

MLX Training Data Format:

Uses JSONL (JSON Lines) where each line contains a single JSON object
Each object has a text field with the complete training example
Format: {"text": "your complete training text here"}

Why the specific format?
MLX's fine-tuning tools expect this simple structure so they can:

Stream data efficiently during training
Apply the model's chat template automatically
Handle tokenization and batching internally

Original Format (JSONL):
{
"prompt": "Classify the sentiment of this email as positive, negative,
or neutral.\n\nSubject: Thank you for excellent service\nEmail: I
wanted to express my gratitude for the outstanding support I received.
The team was helpful and professional.\n\nSentiment:",
"completion": " positive"
}

MLX Format (after conversion):
{
"text": "Classify the sentiment of this email as positive, negative,
or neutral.\n\nSubject: Thank you for excellent service\nEmail: I wanted
to express my gratitude for the outstanding support I received. The
team was helpful and professional.\n\nSentiment: positive"
}

Key Difference:

Original: Separate prompt and completion fields
MLX: Single text field combining both (concatenated together)

The conversion essentially does: text = prompt + completion

touch convert_to_mlx.py

# Create convert_to_mlx.py
import json
import os
from pathlib import Path

def convert_to_mlx_format(input_file: str = "training_data.jsonl", 
                         output_dir: str = "data/mlx_format"):
    """Convert JSONL training data to MLX format"""

    print(f"Converting {input_file} to MLX format...")

    # Create output directory
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    # Read training data
    examples = []
    with open(input_file, 'r') as f:
        for line in f:
            if line.strip():
                example = json.loads(line)
                # MLX format combines prompt and completion into a single text field
                text = example['prompt'] + example['completion']
                examples.append({"text": text})

    # Save training data
    train_file = os.path.join(output_dir, "train.jsonl")
    with open(train_file, 'w') as f:
        for example in examples:
            f.write(json.dumps(example) + '\n')

    print(f"✅ Converted {len(examples)} examples")
    print(f"✅ Saved to {train_file}")

    # Create a small validation set (10% of data)
    val_size = max(1, len(examples) // 10)
    val_examples = examples[:val_size]
    train_examples = examples[val_size:]

    # Save validation data
    val_file = os.path.join(output_dir, "valid.jsonl")
    with open(val_file, 'w') as f:
        for example in val_examples:
            f.write(json.dumps(example) + '\n')

    # Update training data to exclude validation examples
    with open(train_file, 'w') as f:
        for example in train_examples:
            f.write(json.dumps(example) + '\n')

    print(f"✅ Created train set: {len(train_examples)} examples")
    print(f"✅ Created validation set: {len(val_examples)} examples")

    return len(train_examples), len(val_examples)

def preview_mlx_format(output_dir: str = "data/mlx_format"):
    """Preview the MLX formatted data"""

    train_file = os.path.join(output_dir, "train.jsonl")

    print("\n📋 Preview of MLX formatted data:")
    print("=" * 80)

    with open(train_file, 'r') as f:
        for i, line in enumerate(f):
            if i >= 2:  # Show first 2 examples
                break

            example = json.loads(line)
            print(f"\nExample {i+1}:")
            print(f"Text: {example['text'][:200]}...")  # Show first 200 chars
            print("-" * 40)

if __name__ == "__main__":
    # Convert the data
    train_count, val_count = convert_to_mlx_format()

    # Preview the results
    preview_mlx_format()

    print(f"\n🎉 MLX format conversion complete!")
    print(f"Ready for training with {train_count} examples")

Takes 10% of examples for validation and remaining 90% will be used for training

Run the conversion:

python3 convert_to_mlx.py

After running python3 convert_to_mlx.py, you will see two new files created under data/mlx_format/:

valid.jsonl
train.jsonl

Now the data is ready and we will head into the next section, where we will get to the meat of this series, which is executing Fine-Tuning.

Setting Up Your Local Development Environment (Part 2)

Prashant Nigam — Sat, 20 Sep 2025 11:58:22 +0000

In this part, we'll set up everything you need to start fine-tuning Small Language Models on your local machine. We'll focus on Apple Silicon optimization.

Why Your Setup Matters

Setting up your development environment correctly is like having a well-organized workshop - it makes everything else easier and prevents countless headaches down the road. A proper setup ensures:

Optimal Performance: Getting the most out of your hardware
Reproducible Results: Consistent behavior across sessions
Easy Debugging: Clean environments make problems easier to trace
Future Flexibility: Easy to experiment and extend

What are the Hardware Requirements and Recommendations?

Minimum Requirements

RAM: 8GB (though 16GB+ is highly recommended)
Storage: 20GB free space
Processor: Apple Silicon (M1/M2/M3/M4)

Recommended Setup

RAM: 16GB or more (more RAM = larger models you can run)
Storage: 50GB+ free space (SSD recommended)
Processor: Apple Silicon M3 or M4 Pro for optimal performance

I did the fine tuning on a Apple M3 Pro

But, Why Apple Silicon?

First, this is what I have :).

Second, Apple Silicon processors have a unique architecture that's perfect for AI workloads:

Unified Memory: CPU and GPU share the same memory pool
High Memory Bandwidth: Extremely fast data transfer
Efficient Compute: Optimized for matrix operations
MLX Framework: Apple's specialized ML framework

Understanding MLX: Apple's AI Framework

MLX is Apple's machine learning framework specifically designed for Apple Silicon. Think of it as Apple's answer to NVIDIA's CUDA - it unlocks the full potential of M-series chips for AI workloads.

Key MLX Benefits:

Native Apple Silicon optimization
Unified memory utilization
Fast training and inference
Python-friendly API
Growing ecosystem of models

Step-by-Step Environment Setup

Step 1: Create Your Project Directory

Let's start by creating a clean, organized project structure:

# Create main project directory
mkdir email-sentiment-classifier
cd email-sentiment-classifier

# Create subdirectories for organization
mkdir data models adapters results logs scripts

This structure will keep everything organized as our project grows:

data/: Training and evaluation datasets
models/: Downloaded base models
adapters/: Fine-tuned model adapters
results/: Evaluation results and metrics
logs/: Training and evaluation logs
scripts/: All our Python scripts

Step 2: Set Up Python Virtual Environment

Virtual environments are crucial for avoiding dependency conflicts. Think of them as isolated workspaces where each project has its own set of Python packages.

# Create virtual environment
python3 -m venv email_sentiment_env

# Activate the environment
source email_sentiment_env/bin/activate

# Verify you're in the virtual environment
which python3
# Should show: /path/to/email-sentiment-classifier/email_sentiment_env/bin/python3

# Upgrade pip to latest version
pip install --upgrade pip

Important: Always activate your virtual environment before working on the project. You'll know it's active when you see (email_sentiment_env) in your terminal prompt.

Step 3: Install Core Dependencies

Now we'll install the packages we need. I'll explain each one as we go:

# MLX Framework - Apple's ML framework for Apple Silicon
pip install mlx mlx-lm

# Transformers ecosystem - Hugging Face's toolkit
pip install transformers datasets tokenizers

# Data manipulation and analysis
pip install numpy pandas matplotlib seaborn

# Machine learning utilities
pip install scikit-learn

# Web interface framework
pip install gradio

# General utilities
pip install tqdm requests

Let's understand what each package does:

MLX & MLX-LM: The core frameworks for training and running models on Apple Silicon. MLX handles the low-level computations, while MLX-LM provides high-level tools for language models.

Transformers: Hugging Face's library that gives us access to thousands of pre-trained models for tasks like text generation and translation, making it easy to work with language, images, and audio.

Datasets: Makes it easy and helps us find, load, and manage large collections of training data for machine learning, so you don’t have to build datasets from scratch.

Tokenizers - Breaks down text into small pieces called tokens; this is needed to prepare text for AI models and makes them work more efficiently

NumPy & Pandas: Essential for data manipulation and analysis.

Matplotlib & Seaborn: For creating visualizations of our results.

Scikit-learn: gives Python users simple tools to build machine learning models that can classify, predict, and group patterns in data without needing to write everything by hand.

Gradio: creates beautiful web interfaces for testing our models.

Tdqm: shows a progress bar in the terminal while a program runs through a long loop, so users can easily see how much work is left and how fast it's going

Requests: makes it easy to download or send data over the internet from Python—for example, retrieving a webpage, posting data, or working with APIs.

Step 4: Verify Your Installation (Optional)

Let's make sure everything is working correctly:

Create a test script: test_installation.py **

touch test_installation.py


print("Testing MLX installation...")


try:
    import mlx.core as mx
    print("✅ MLX core imported successfully")
    print(f"   MLX version: {mx.__version__}")

    # Test Metal availability (Apple's GPU framework)
    if mx.metal.is_available():
        print("✅ Metal GPU acceleration available")
        print(f"   GPU memory: {mx.metal.get_peak_memory() / 1e9:.1f}GB peak usage")
    else:
        print("⚠️  Metal GPU not available (using CPU)")

except ImportError as e:
    print(f"❌ MLX import failed: {e}")

print("\nTesting MLX-LM...")
try:
    import mlx_lm
    print("✅ MLX-LM imported successfully")
except ImportError as e:
    print(f"❌ MLX-LM import failed: {e}")

print("\nTesting Transformers...")
try:
    import transformers
    print(f"✅ Transformers imported successfully (v{transformers.__version__})")
except ImportError as e:
    print(f"❌ Transformers import failed: {e}")

print("\nTesting other dependencies...")
dependencies = ['numpy', 'pandas', 'sklearn', 'gradio']
for dep in dependencies:
    try:
        __import__(dep)
        print(f"✅ {dep} imported successfully")
    except ImportError:
        print(f"❌ {dep} import failed")

print("\n🎉 Installation test complete!")

Run the test:

python3 test_installation.py

You should see all green checkmarks. If anything fails, revisit the installation steps for that package.

Step 5: Download and Verify the Base Model

Before we start fine-tuning, we need to download the SmolLM2-1.7B-Instruct model. This is a one-time download that will be cached locally for all future use.

#### Model Details:

Model: SmolLM2-1.7B-Instruct (1.7 billion parameters)
Size: ~3.4GB
Download time: 5-15 minutes (depending on internet speed)
Storage location: ~/.cache/huggingface/hub/ (on macOS)

Automatic Download (Recommended):

touch download_model.py

  # download_model.py
  from mlx_lm import load
  import time

  def download_base_model():
      """Download and verify the base model"""

      print("🚀 Downloading SmolLM2-1.7B-Instruct...")
      print("📦 Model size: ~3.4GB")
      print("⏱️ This will take 5-15 minutes depending on your internet speed")
      print("💾 Model will be cached locally for future use")
      print("\nDownload starting...")

      try:
          start_time = time.time()
          model, tokenizer = load("HuggingFaceTB/SmolLM2-1.7B-Instruct")
          download_time = time.time() - start_time

          print(f"\n✅ Model downloaded successfully!")
          print(f"⏱️ Download time: {download_time:.1f} seconds")
          print(f"💾 Model cached at: ~/.cache/huggingface/hub/")
          print(f"🧪 Testing model...")

          # Quick inference test
          from mlx_lm import generate
          test_response = generate(
              model, tokenizer,
              prompt="The weather today is",
              max_tokens=3
          )

          print(f"✅ Model test successful: '{test_response.strip()}'")
          print("\n🎉 Ready to proceed with fine-tuning!")

          return True

      except Exception as e:
          print(f"\n❌ Download failed: {e}")
          print("\n🔧 Troubleshooting:")
          print("  - Check internet connection")
          print("  - Try running again (partial downloads will resume)")
          print("  - Ensure you have 5GB+ free disk space")
          return False

  if __name__ == "__main__":
      download_base_model()

Run the download:
python download_model.py

Manual Download (Alternative):

If automatic download fails, you can download manually:

  # Install huggingface-hub if not already installed
  pip install huggingface-hub

  # Download model manually
  python -c "
  from huggingface_hub import snapshot_download
  snapshot_download('HuggingFaceTB/SmolLM2-1.7B-Instruct', 
                   cache_dir='~/.cache/huggingface/hub')
  print('✅ Manual download complete!')
  "

Verify Download:

touch verify_model.py

  # Create verify_model.py
  import os
  from pathlib import Path

  def verify_model_download():
      """Verify the model was downloaded correctly"""

      # Check cache directory
      cache_dir = Path.home() / ".cache" / "huggingface" / "hub"
      model_dirs = list(cache_dir.glob("*SmolLM2*"))

      if model_dirs:
          model_dir = model_dirs[0]
          model_size = sum(f.stat().st_size for f in model_dir.rglob('*') if f.is_file())
          size_gb = model_size / (1024**3)

          print(f"✅ Model found at: {model_dir}")
          print(f"📦 Model size: {size_gb:.1f}GB")

          if size_gb > 3.0:
              print("✅ Model appears complete")
              return True
          else:
              print("⚠️ Model may be incomplete (too small)")
              return False
      else:
          print("❌ Model not found in cache")
          return False

  if __name__ == "__main__":
      verify_model_download()

Troubleshooting Download Issues:

Issue: Download interrupted
# Resume interrupted download
python download_model.py # Will automatically resume

Issue: Insufficient disk space
# Check available space
df -h ~
# Need at least 5GB free (3.4GB model + temporary files)

Development Best Practices

Environment Management

Always use virtual environments and document your dependencies:

# Save your current environment
pip freeze > requirements.txt

# Later, recreate the environment
pip install -r requirements.txt

Version Control Setup

Initialize git and create a proper .gitignore:

git init

Create .gitignore:

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
email_sentiment_env/

# Models and data (large files)
models/
adapters/
*.bin
*.safetensors

# Logs and results
logs/
*.log
results/

# System files
.DS_Store
Thumbs.db

Verification and Next Steps

Let's create a final verification script to ensure everything is working:

touch final_verification.py

# Create final_verification.py
import mlx.core as mx
from mlx_lm import load
import time

def verify_complete_setup():
    """Verify that our complete setup is working"""

    print("🔍 Final Setup Verification")
    print("=" * 50)

    # Check MLX
    print(f"✅ MLX version: {mx.__version__}")
    print(f"✅ Metal GPU: {'Available' if mx.metal.is_available() else 'Not available'}")

    # Test model loading (this will download the model if needed)
    print("\n📥 Testing model download and loading...")
    try:
        start_time = time.time()
        model, tokenizer = load("HuggingFaceTB/SmolLM2-1.7B-Instruct")
        load_time = time.time() - start_time
        print(f"✅ Model loaded successfully in {load_time:.1f}s")

        # Test inference
        print("\n🧪 Testing inference...")
        from mlx_lm import generate
        response = generate(
            model, tokenizer, 
            prompt="The quick brown fox", 
            max_tokens=5
        )
        print(f"✅ Inference test: '{response.strip()}'")

    except Exception as e:
        print(f"❌ Model loading failed: {e}")
        return False

    print("\n🎉 Complete setup verification passed!")
    print("\nYou're ready to proceed to Part 3!")
    return True

if __name__ == "__main__":
    verify_complete_setup()

Run the final verification:

python3 final_verification.py

What We've Accomplished

Congratulations! You now have a complete, optimized development environment ready for fine-tuning Small Language Models. Here's what we've set up:

✅ Organized project structure
✅ Optimized virtual environment
✅ MLX framework for Apple Silicon acceleration
✅ All necessary dependencies installed
✅ Configuration and utility functions
✅ Performance monitoring tools
✅ Troubleshooting guides

Looking Ahead

With your environment ready, we can now move on to the exciting part - working with data and training our first model!

In Part 3, we'll dive deep into:

Understanding training data formats
Creating high-quality datasets
Data preprocessing and tokenization
Chat templates and prompt engineering

Your development environment is the foundation that makes everything else possible. With this solid base, you're ready to start building amazing AI applications locally!

fine tune model

Prashant Nigam — Wed, 17 Sep 2025 18:32:29 +0000

Small Language Model (SLM) - The future of Local AI (Part 1)

Prashant Nigam — Wed, 17 Sep 2025 18:31:34 +0000

Welcome to the first part of a comprehensive tutorial series on fine-tuning Small Language Models locally. In this multi-part series, we'll explore why Small Language Models (SLMs) will revolutionize AI development and why running AI locally should be the preferred approach.

First - What You'll Learn in This Series

Over the next parts, we'll build a complete email sentiment analysis system from scratch.

An important callout

this series focuses on fine-tuning the SmolLM2-1.7B model on Apple Silicon (M1 and beyond) using Apple's MLX framework. You'll need at least 8GB (though 16GB+ is highly recommended) of RAM and 20GB free space to follow along.

What Are Small Language Models?

To better understand SLM, let's talk about LLM first. If you've been following AI developments, you've probably heard about massive models like OpenAI's GPT-5 or Claude's Opus 4.1 that have hundreds of billions of parameters and cost hundreds of millions of dollars to train. LLM are broad, general-purpose capabilities across many domains due to scale and diverse training data; typically stronger on open-ended and complex tasks
But there's a quieter revolution happening with Small Language Models (SLMs) - compact, efficient AI models that pack surprising intelligence into much smaller packages.

Small Language Models, though no universal definition exists, are AI models typically ranging from a few million to several billion parameters. Many practitioners use ≤7B parameters as a practical threshold for defining SLMs. Designed to be efficient, fast, and capable of running on consumer hardware. Think of them as the "Swiss Army knife" of AI - they may not have every feature of their larger cousins (LLM), but they're incredibly practical and versatile. SLM are often narrower and task-specific, tuned or distilled for particular domains or workflows to achieve competitive performance on those targeted tasks with far less compute.

So, why SLMs Are Game-Changers

Here's what makes SLMs so compelling:

Local Execution: Can run entirely offline in your network including on your laptop, no cloud required
Privacy First: Your data never leaves your device
Cost Effective: No API fees or subscription costs. Reasonable cost to fine-tune them
Low Latency: Instant responses without network delays
Customizable: Easy to fine-tune for specific tasks
Reliable: No downtime or rate limits (as long as your local network is up and running)

The Local AI Revolution

Remember when we had to send every photo to Google Photos for face recognition? Now our iPhone does it locally. The same transformation is happening with language models.

And, why Local Matters More Than Ever

Privacy and Security: In an era where data breaches make headlines frequently, keeping your sensitive information local isn't just nice-to-have - it's essential. Whether you're processing customer emails, medical records, or legal documents, local processing means zero data exposure.

Performance and Reliability: Cloud APIs can be slow, andd expensive. Local models give you sub-second responses with 100% uptime. No more "API rate limit exceeded" errors at crucial moments (looking at you Claude Code ;)).

Cost Economics: A roughly $2,000 MacBook can fine-tune an SLM locally and process thousands of requests for the cost of electricity, while cloud APIs would rack up thousands in usage fees. Imagine the processing that a SML hosted on a local enterprise on-prem server can do. The math is compelling.

Customization Power: LLMs are one-size-fits-all. Local models can be fine-tuned for your exact use case, often achieving better performance than general-purpose giants.

Real-World Applications waiting to take Off

Let me share some exciting applications where local SLMs will be extremely beneficial and where privacy should be a first class citizen:

Email Intelligence

Sentiment analysis for customer service
Automatic email categorization and routing
Smart reply suggestions
Urgent email detection

Enterprise Content Creation

Blog post optimization
Social media caption generation
Product description writing
Marketing copy adaptation

Enterprise Code Intelligence

Code review and bug detection
Documentation generation
Test case creation
Legacy code explanation

Enterprise Document Processing

Contract analysis
Research paper summarization
Meeting note extraction
Report generation

Let's look at the Technology Stack That Makes It Possible

The convergence of several technologies is making local AI practical:

1. Efficient Model Architectures

Modern SLMs use advanced techniques like:

Transformer optimization: Better attention mechanisms
Knowledge distillation: Learning from larger models
Architecture innovations: MobileBERT, DistilBERT, and newer approaches

2. Advanced Training Techniques

LoRA (Low-Rank Adaptation): Fine-tune with minimal compute
QLoRA: Quantized LoRA for even better efficiency
Parameter-efficient methods: Maximum results, minimum resources

3. Hardware Acceleration

Apple Silicon: M1/M2/M3 chips with unified memory
NVIDIA GPUs: Consumer cards becoming AI powerhouses
Specialized frameworks: MLX for Apple, CUDA for NVIDIA

4. Developer-Friendly Tools

MLX: Apple's answer to CUDA for M-series chips
Transformers: Hugging Face's ecosystem
Ollama: Simple model deployment
LM Studio: User-friendly model management

Understanding the Trade-offs

Let's be honest about the trade-offs between small and large models:

Small Language Models excels at:

Focused, domain-specific tasks
Repetitive tasks done by AI Agents
Real-time applications requiring low latency
Privacy-sensitive use cases
Cost-constrained environments
Edge deployment scenarios

Large Language Models still leads in:

Complex reasoning across multiple domains
Creative writing and storytelling
Advanced mathematical problem solving
Handling completely novel scenarios
And many many more

The key insight? Most real-world applications don't need GPT-5 level capabilities. A well-fine-tuned 1.7B parameter model can outperform (response time, cost) much larger general-purpose models on specific tasks.

Getting Ready for the Journey

Before we dive into the technical details in Part 2, take a moment to think about:

What problems could you solve with a locally fine-tuned model?

Email automation and management
Content generation and optimization
Document analysis and processing
Customer service and support

What's your motivation for local AI?

Privacy and security requirements
Cost optimization
Performance and reliability
Learning and experimentation

The Future Is Local

The trend is clear: AI will move from the cloud to the edge. Just as mobile apps revolutionized computing by putting power in everyone's pocket, local AI is democratizing advanced machine learning.

We're entering an era where:

Every developer can fine-tune their own models
Privacy-first AI becomes the standard
Real-time, low-latency AI powers new experiences
Small teams can compete with big tech on AI capabilities

The barriers to entry have never been lower, and the potential impact has never been higher.

Ready to start building? In Part 2, we'll set up your complete development environment and get hands-on with the tools that make local AI development possible.

I will leave you with an interesting fun fact
💡Ever wondered why ChatGPT is called ChatGPT??? It involves late night discussions. Go ahead and take a 2 mins break to read about the name's origin

How to deploy a smart contract to the same address across different blockchains?

Prashant Nigam — Mon, 04 Apr 2022 03:04:00 +0000

Have you ever deployed a smart contract and noticed the deployed address? It seems to be a bunch of random characters, and while it is, that address is deterministic.

A quick primer on account and address in Ethereum - There are two types of accounts in Ethereum: Externally Owned Account (EOA) and Contract Account. Both types of accounts have an address associated with them. An address in Ethereum is a 42-character hexadecimal address.

E.g., Uniswap's UniswapV3Factory smart contract address is 0x1F98431c8aD98523631AE4a59f267346ea31F984 and is the same in Ethereum mainnet, Polygon, Optimism, Arbitrum, and Avalanche. The same is the case for Uniswap's all smart contracts.

How is the smart contract address generated?
The smart contract's address is derived from two values, the EOA user's address and the number of transactions the user has sent. That is the user's wallet address and nonce.

Primer on Nonce - Nonce, simply put, is the number of transactions a user has done in a given blockchain. Every time a user has an outgoing transaction, the nonce increases by one. The nonce is unique for each blockchain, meaning that sending a transaction in Ethereum will increase the account's nonce in Ethereum but not in Polygon.

Please note that we refer to the account nonce, which pertains to the user, and not to the block nonce.

As I mentioned at the start of the article, the smart contract address is deterministic. We can determine the address before the smart contract is actually deployed using the wallet's address from which the user will deploy the contract and their most recent nonce + 1.

Below is the example code using ether.js to compute the address pre-deployment. Verify the output

Finally, to answer the question, "How to deploy a smart contract to the same address across blockchains?"

In our wallet, I use Metamask, we should keep an account, and let's call it the deployment account, only to deploy the smart contracts. We should not do any transactions in it other than smart contract creation. Sending smart contract creation transactions in all the blockchains with the same nonce will result in the same smart contract address everywhere.

Having the same address makes the smart contract much more developer-friendly. It reduces the friction of maintaining addresses for different env (mainnet vs. testnet) and blockchains (Ethereum, Polygon, etc.). It makes it easier to socialize the launch as well.

I hope you found this useful! If you have any questions or feedback, please let me know in the comments, and I will be happy to answer.

How to add auto-update feature in macOS app: Step by Step guide to setup Sparkle framework (Part 2)

Prashant Nigam — Tue, 25 Feb 2020 19:11:24 +0000

Recap of Part 1 - We learned what Sparkle is, and why we need it for apps released outside of the macOS App Store. We added Sparkle in our app via Cocoapods. We also learned few concepts related to Sparkle, how does Sparkle works, appcasts, how to serve appcast XML, and finally, we configured Sparkle to give the location info of our appcast XML, using which it can figure out whether a newer version of our app exists.

Let's begin this part where we left off in the previous. Build and run the app.

The below screenshot is the state of the app where we left off in the previous part.

Go ahead and try to update the app by clicking on the "Install Update" and you should see the following behavior with an error alert generated at the end, captured in video recording below:

Observations from using current version of the app (v1) thus far:

App remains open upon clicking the "Check for Updates" button. This behavior causes the Sparkle update alert hidden behind the App. This behavior is an issue, and we fix it in version 2 of the App. The app updates to version two via Sparkle
When we click on "Install Update," Sparkle downloads "a" version of "some app." We don't have a version two yet (heck, we don't even have the binary of current version one), so what does it download then?
- We are using a default appcast XML from Sparkle, which comes with a test app "https://sparkle-project.org/files/Sparkle%20Test%20App.zip". Once we have a binary for version 2, we replace this test app URL with ours.

Production ready

Releasing a macOS app, which can also be trusted by users, especially if we are distributing the App outside of the App store, means code signing and getting the App notarized by Apple. So let's do it.

For us to be able to test updates via Sparkle, our App should be in binary form and run from within the Applications folder (not via Xcode).

The first step in creating a binary of your macOS app is Archiving it. Archive your App in Xcode by clicking on the "Archive" option under the "Product" menu.

Once the generation of the Archive instance is finished, click Distribute App" Since we are distributing the App directly to our users, select the "Developer ID" option as the method of distribution.

Click "Next." You get an option to upload your App to Apple notary service or proceed without notarizing.

If you are thinking of proceeding without Notarizing your macOS app, then think again. While this tutorial is not about App code signing or Notarization, but I feel Apple notarization is very important and should always be considered, so adding more info about it.

Apple Notarization helps the user know that the App doesn't contain any malicious code

Notarization gives users more confidence that the Developer ID-signed software you distribute has been checked by Apple for malicious components.

Prashant Nigam

@prashantnigam_

It's important for macOS app to be @apple notarized if they are downloaded outside of mac app store. It gives user a peace of mind that app is not malicious. Wish @apple provide a way for devs to embed a label within app that says it is notarized twitter.com/EasyFinderApp/…

23:48 PM - 09 Oct 2019

EasyFinder @EasyFinderApp
@adampymble Hi Adam, thanks.There r certain mandatory requirements in order for app to be available in app store. If followed,EasyFinder wouldn't work the way it is supposed to be.However I want to assure you that app has be dev signed and notarized by apple which means it is safe to be run

EasyFinder

@easyfinderapp

@adampymble Here is the link to apple's dev id signing and notarization developer.apple.com/developer-id/

23:32 PM - 09 Oct 2019

EasyFinder

@easyfinderapp

@adampymble Highlighting the portion which informs users on opening an app downloaded outside of app store,that Apple has checked app for malicious software and none was detected. It's also the reason why mac gatekeeper let an app (notarized by Apple) run. Hope this helps and great question

23:38 PM - 09 Oct 2019

Not only does apple notarization provide confidence for your user, but starting with macOS Catalina, an App distributed outside of App store must be notarized by Apple to run on macOS Catalina

Ok, now that we understood the importance of Apple notarization, let's move on to the next step, which is choosing the option to Upload to Notary service. Click "Next."

Boom, We see an error. Well, we did everything right, then what is causing this error? All comes back to code-signing and Notarization. The Apple notarization process is a topic in itself, and Apple covered it in great detail in WWDC 2019. You can watch the video here.

So let's get to resolving the issue that is causing the failure to upload to Notary service. First, describing the issue in brief. Not only our App code but any deeply nested code withing our App must also be code signed with our Developer ID, for us to be able to get our App Notarized by Apple. In our case, Sparkle code is embedded in our app binary, and also needs to be codesigned by our Developer ID. In the normal codesigning process, it does not automatically codesign embedded code/app, so we need to do it explicitly. In the following part, we add a step to codesign Sparkle and resolve upload to notary issue.

Codesigning and Notarizing Sparkle

In Xcode, head over to your project's Targets "Build Phase" tab. Click on + sign located on the top left and add a "New Run Script Phase." I call my run script Run Script - Deep Signing Sparkle framework

Inside script text field type in the following script:

#For Apple notarization, we need to deep sign Sparkle framework
LOCATION="${BUILT_PRODUCTS_DIR}"/"${FRAMEWORKS_FOLDER_PATH}"
IDENTITY=${EXPANDED_CODE_SIGN_IDENTITY_NAME}

codesign --verbose --force --deep -o runtime --sign "$IDENTITY" "$LOCATION/Sparkle.framework/Versions/A/Resources/AutoUpdate.app"
codesign --verbose --force -o runtime --sign "$IDENTITY" "$LOCATION/Sparkle.framework/Versions/A"

This Run Script build phase should solve our failure to Upload to Notary service issue. Let's see if it did. Start over and Archive again. Once it is archived, click "Distribute App" and choose the "Developer ID" option. Click "Next" and finally the moment of truth. Choose "Upload" (send to Apple notary service) option and click "Next." This upload was the step that gave the error before.

This time upload to notary service works. See screen recording below.

Once Apple successfully notarizes our App, it sends us notifications. For a super simple App like ours, I got it within a couple of minutes.

Apple delivers notarization completion notification via both email and Xcode.

Finally, we are successful in notarizing our App. Now it's time to distribute our App to users. For that, let's export App in the form of the .app file (binary). The version of the Archive that got notarized has "Ready to distribute" under Status.

Click on the "Export App" button and save .app file.

Congrats, you have successfully finished creating a distributable signed and notarized first version of your App.

All that is left is moving the .app file to your Application folder. Go ahead and move it and launch your App by clicking on the App icon.

The App works similar to how it worked when we run it from Xcode. So now, we need to fix the issue we found earlier in this version of the App.

This brings us to the end of Part 2.

In Part 3, we fix this issue and update the App to version 2. Create version 2 binary and upload it to the cloud. Update our appcast XML, with relevant release notes, to notify to the (current) version 1 that a newer version is available for update. Finally, the current version of the App, sitting in our Application folder, gets updated to version 2 via Sparkle.

Well, we did quite some work, and so it's good to take a quick break. For some, a break could be taking a walk or stretch, then go ahead and do that (come back later for this last exciting part). However, if you one of those who find trivia to be exciting and save them for interesting party conversations, then here is one for you.

💡 There is just one letter that's not in ANY of U.S. state name. What is that letter? 🤔 Think about it and then head here to check if your answer was correct

How to add auto-update feature in macOS app: Step by Step guide to setup Sparkle framework (Part 1)

Prashant Nigam — Wed, 13 Nov 2019 22:03:02 +0000

In this multi-part tutorial, I'll walk you step by step on how to add and configure the auto-update framework Sparkle in your macOS app. Sparkle has an excellent basic setup page but in my opinion, it is a bit too advanced and maybe a bit overwhelming to follow along. In this tutorial, my effort will be to make it easy for someone to add and configure Sparkle.

If you are familiar with the macOS app releases and why Sparkle is needed, then you can skip the next section and start here.

Why Sparkle?

To answer this, let's rewind a bit. So you had an idea about a macOS app. You researched and found no perfect app (solution) exists that solves the problem and you decide to solve by building the perfect app. You burn the midnight oil and finally come up with a build of an app, which is in a state that you are not too embarrassed to showcase to the world. You ship your first version.

Post shipping is when work truly begins. User downloads your app and provides their feedback. A cycle begins which starts by listening to the user's feedback, incorporating them and shipping the second version. And third and fourth and it continues. In this cycle, a very critical element and the question is how to provide new versions to users?

One way to do it is via Apple's Mac app store. While it's great option (no hosting fees, no monthly storage and bandwidth fees especially if your app is free and app is auto-updated with new versions) but it comes with mandatory requirements, for e.g. Sandbox should be enabled etc., that one needs to implement in their app and which may not allow your app to work in a way that you think provide the best experience. So the only option left is hosting it outside of mac app store.

How do you then provide new versions of your app to users seamlessly?

This is where Sparkle comes in

"Sparkle is an easy-to-use software update framework for macOS applications."

One should always have an auto-update feature in their app starting with the first release, lest you will be in my shoes 😔.

Personal plug: I released a mac menu bar app EasyFinder and hosted it outside of mac app store.

// Detect dark theme var iframe = document.getElementById('tweet-1101118647169417217-980'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1101118647169417217&theme=dark" }

To provide peace of mind to users and of course assurance to macOS Gatekeeper ☺️ so that it let EasyFinder run, EasyFinder has been dev signed and notarized by apple. It doesn't have an auto-update framework and so I cannot push new versions to users and alert them. The second version of EasyFinder will be a new launch on Product Hunt, something one may not want unless it's a mega update. Thankfully the second version of EasyFinder will bring a whole bunch of new experiences and features which warrant a hard launch instead of a soft launch.

However, lacking the ability to push new version limits me in a way. I would have liked to push a few minor updates to get user's feedback on some new features that I am building before doing a version 2 launch. Thus in my experience, I would strongly advise adding auto-update feature in your macOS app starting with the first release. This is what this tutorial is about. Adding Sparkle to an app before it's first released or in some cases like me post first release.

Getting Started

Let's get started. I will take you step by step on how to setup Sparkle framework in your macOS app and last but not least, configure it properly so that apple agrees to notarize it 😎. Yes, Sparkle needs to be code signed as well or else your app will not be accepted for notarization. Why should we bother about Apple notarization? More on this later.

We will add and configure Sparkle to an existing macOS project. I have created a starter project. Go ahead and download the project. After downloading, build and run the project. If everything goes well you should see a Star icon in your menu bar 👇

Click on the star and it will open a pop up displaying a label "First Version"

Clicking on the button labeled "Check for Updates" doesn't do anything. It's just a placeholder for now and shortly we will add functionality to this button to check if there is a newer version of the app available

Adding Sparkle framework to Xcode project

We will use cocoapods to add Sparkle. So first let's add pod file by opening Xcode project location in Terminal and typing

pod init

Directory content before initiating pod

Directory content after initiating pod

As you can see in the screenshot above, a new file named Podfile has been added to the project directory. In this new file, we will add the Sparkle framework pod name. Open Podfile in your favorite editor and add following in the file

pod 'Sparkle'

Now that we have declared, via Pod, that our project requires Sparkle framework, it's time to install the pod. Close the Xcode project.

Go back to the same location in Terminal and install the Sparkle framework by executing the following command:

pod install

This will add Sparkle framework as a dependency in your Xcode project and will also create a new Xcode project file with extension xcworkspace.

From now on we will use this file SparkleSetupGuide.xcworkspace to open our project. Open your project using this file. Your Xcode project should have a Pod project like in the screenshot below

Build and run your project. The result should be similar to when we built and ran before installing the pod.

Configuring Sparkle

Open Main.storyboard file

Open library window by either clicking "+" above right side pane or by using short cut Command + Shift + L. Search for 'Object' and drag it to Application Scene

Update the class for this newly added Object to SUUpdater in Identity Inspector

SUUpdater - This class is used to configure the update parameters as well as manually and automatically schedule and control checks for updates

Sparkle gives the user an option via an alert, whether they prefer to automatically check for updates or they want to do it manually. This happens usually after the first launch of the app. Since we have added Sparkle updater object, we should see an alert on or after the second run. Run the app, shut it and then re-run it. You should see below alert:

Let's recap what we have done so far. We have added the Sparkle framework in our project via cocoapods. Subsequently, we added an Object in our storyboard's Application Scene and updated that Object's class to SUUpdater. The object will now be able to manually or automatically check for updates

Now, since the user can choose to check for updates manually, we should provide that feature in our app. Remember that dumb button "Check for updates" that did nothing? Well, let's make button intelligent and useful so that the user can use it to check if there is a new version of the app available.

Note: Since checking for updates is not the core functionality of an app, you will usually provide this in the preference section of your app instead of putting it in the main screen as we did

Open VersionDisplayViewController.swift file

Add the Sparkle module by importing it. Add following import

import Sparkle

Now update checkForUpdates function with following code:

    @IBAction func checkForUpdates(_ sender: Any) {
        let updater = SUUpdater.shared()
        updater?.feedURL = URL(string: "some mystery location")
        updater?.checkForUpdates(self)
    }

The above code is getting an instance of class SUUpdater, setting some mystery location to instance's feedURL property and then asking SUUpdater instance to check at that some mystery location if there is any new version of the app available.

Clicking on the button does nothing but it will generate following error in Xcode console:

[General] You must specify the URL of the appcast as the SUFeedURL key in either the Info.plist or the user defaults!

No one likes seeing errors and nor do we. We will get rid of them shortly but there are a couple of new jargon in this error. appcast, SUFeedURL key. Further, you might be wondering about this some mystery location and why are we hard coding (not a best practice)? and how does Sparkle figures out if and when there is a new version of your app is available?

First, let's understand how Sparkle works

Sparkle uses appcasts to get information about app updates. An appcast is an RSS feed with some extra information for Sparkle’s purposes.

In plain words, Sparkle polls "some location" on the internet, a location that we provide to Sparkle either via code (like above) or in app's Info.plist, and determines whether the app version is up to date or if there is a newer version available. If there is a more recent version available, then Sparkle informs the user via an alert. In a moment we will see what this alert looks like.

Now that we know how Sparkle works, let's talk about that some mystery location. It is the location of our appcast file for our app and it has info on app's versions. Sparkle expects an XML file in that some mystery location. Using info in the XML file, Sparkle determines whether the user has the latest version or not.

You can download a sample appcast XML file from Sparkle and go through it.

It is strongly recommended that appcast XML is served via HTTPS URL. I will use Amazon S3 to host the appcast XML file for the purpose of this tutorial. You can choose from a plethora of options available online for e.g. Firebase Storage, your companies own server as long as it is HTTPS, Azure etc.

Following screenshot is from S3 location:

URL of my appcast XML file is:

https://s3.amazonaws.com/com.sparklesetupguide.tutorial/sparkletestcast.xml

This is the URL that Sparkle was expecting on clicking of the button earlier and on not finding it gave above error message.

One of the many and simplest (in my opinion best way too) in which we can let Sparkle knows of appcast location is via app's Info.plist.

Upload the sample appcast XML file that you downloaded from Sparkle to your favorite online location and then add the following key-value pair in Info.plist

key - SUFeedURL
value - URL of XML file which you uploaded online

I have uploaded Sparkle's sample XML file to S3. My Info.plist looks like this with:

Go ahead build and run the app. Click on the "Check for Updates" button now. You see an alert that a new version of your app is available (similar to the screenshot below)

If you see an alert like above 👆

then

Congrats. You have successfully integrated Sparkle in your app.

PS: Any default configuration like appcast URL location should be configured in Info.plist instead of hard coding in code. I added below line

updater?.feedURL = URL(string: "some mystery location")

in the code to explain concept of appcast location. If you notice, even though we are not setting any valid URL updater?.feedURL, Sparkle is still able to get info on app version because Sparkle is getting it from Info.plist. Go ahead and delete that line and Sparkle will still work as long as appcast location is present in Info.plist

Pro tip: If you don't see an alert, then one of the first things you need to check and make sure is that your XML URL is public. This also goes for future debugging as well. For e.g. In Amazon S3, every time you upload a new version of the file (appcast XML), by default URL goes from being public to non-public and we have to make the file public again manually. Knowing this can save a lot of time later trying to debug why the app is unable to find the new version

Stay tuned for the next part, in which we will create our appcast XML and see some of the ways to customize Sparkle to enhance user experience. We will also go through a full cycle of releasing the first version, in which we will see how to correctly code sign app which has Sparkle framework so that it is accepted for Notarization, adding a new feature in next version and updating our current version with a newer version via Sparkle.

It's always a good idea to take a few mins break when working at a stretch. It helps with focus when we come back to the task at hand. If you want to take a few mins to break before your next task, then let me leave you with an interesting trivia

💡 Ever wondered why US Government 🇺🇸 is also referred to as Uncle Sam? 🤔 It's named after a meat packer Samuel Wilson. Go ahead and take a 2 mins break to read on the history of Uncle Sam