LFM Trainer

Fine-tune Liquid LFM 2.5 1.2B for coding tasks on Kaggle multi-GPU — with automatic checkpoint publishing to Hugging Face on errors, and post-training GGUF + MLX quantization.

Features

• 🚀 Multi-GPU training via HuggingFace Accelerate / DDP (Kaggle P100 / 2×T4)
• 🧠 LoRA / PEFT for memory-efficient fine-tuning
• 📦 Structured dataset loading — CSV, Parquet, JSONL, HuggingFace Hub IDs, or direct pd.DataFrame objects
• 🔍 Auto-format detection — Alpaca, prompt/response, conversational/chat (DataClaw), single text column
• 🌬️ AirLLM sharding — run 70B models on 4GB VRAM via layer-by-layer loading; supports MLX
• 🚀 TurboQuant KV cache — 2.5/3.5-bit quantization with outlier preservation for vLLM and MLX
• �️ Tool calling support — LFM 2.5 native <|tool_call_start|> / <|tool_call_end|> tokens; handles OpenAI and DataClaw tool call formats
• �🛡️ Error-resilient training — auto-publishes versioned checkpoints on OOM, SIGTERM (Kaggle timeout), KeyboardInterrupt, or any exception
• 🔑 Flexible HF auth — CLI arg, HF_TOKEN env var, or Kaggle Secrets
• 📐 GGUF export — Q4_K_M, Q6_K, Q8_0 via llama.cpp
• 🍎 MLX export — 4-bit, 6-bit, 8-bit via mlx-lm
• 🏷️ Shared versioning — base model + all quantized variants tagged with the same version
• 🔓 Full fine-tuning — train all parameters (no LoRA) for maximum quality
• 📊 Auto-benchmarking — HumanEval, MBPP, MultiPL-E, BigCodeBench, EvalPlus, Tool Calling, GSM8K, ARC
• 🧠 Reasoning (<think> tags) — train models that think before acting, with <think>...</think> traces
• 🧹 Data quality filters — auto-remove duplicates, empty rows, and length outliers
• 📈 Eval split — hold out a % for validation loss tracking during training
• 📝 Auto model card — generates a HuggingFace README.md with config, benchmarks, and hardware
• 📉 W&B / TensorBoard — optional training metric logging
• 🎯 DPO / PPO / GRPO alignment — preference tuning after SFT via DPO, classic RLHF (PPO), or DeepSeek-style GRPO
• 📚 Continued Pre-Training (CPT) — train on raw text (books, PDFs, code) to inject domain knowledge
• 🔗 LoRA adapter merging — combine multiple adapters into a single model with weighted blending
• 🔍 Auto HP search — try multiple learning rates and pick the best based on eval loss
• ⚡ DeepSpeed ZeRO — ZeRO-2 and ZeRO-3 for multi-GPU training (optimizer + gradient + weight sharding)
• 🎯 Model Distillation — compress a large teacher into a smaller student via KL-divergence
• 📋 Structured Output — train models to generate valid JSON conforming to schemas

Installation

pip install lfm-trainer

Quick Start (Kaggle Notebook)

# Cell 1: Install
!pip install lfm-trainer

# Cell 2: Train on a coding dataset with GGUF export
!lfm-train \
    --dataset peteromallet/dataclaw-peteromallet \
    --hub-repo your-username/lfm-code \
    --export-gguf

# Train on multiple datasets
!lfm-train \
    --dataset code_data.csv \
    --dataset more_code.parquet \
    --dataset sahil2801/CodeAlpaca-20k \
    --hub-repo your-username/lfm-code \
    --epochs 3 \
    --batch-size 2 \
    --export-gguf

The HF token is automatically picked up from Kaggle Secrets (key: HF_TOKEN).

Python API

import pandas as pd
from lfm_trainer import run_training, load_datasets
from lfm_trainer.config import TrainingConfig

# Load multiple sources including DataFrames
df = pd.read_csv("my_code_data.csv")
dataset = load_datasets([
    df,                                    # Direct DataFrame
    "code_data.parquet",                   # Local file
    "peteromallet/dataclaw-peteromallet",   # HuggingFace Hub (conversational)
])

# Or use the full pipeline
cfg = TrainingConfig(
    model_name="liquid/LFM2.5-1.2B-Base",
    dataset_paths=["peteromallet/dataclaw-peteromallet"],
    hub_repo_id="your-username/lfm-code",
    quality_filter=True,
    eval_split=0.1,
    run_benchmark=True,
    benchmark_before_after=True,
    export_gguf=True,
)
run_training(cfg)

CLI Reference

lfm-train --help

Supported Dataset Formats

The data loader auto-detects column layouts:

Tool-Calling Training

Train exclusively on tool-calling examples using --tool-calling-only:

lfm-train \
    --dataset jdaddyalbs/playwright-mcp-toolcalling \
    --tool-calling-only \
    --hub-repo your-username/lfm-tools \
    --max-seq-length 4096

The filter keeps only samples containing tool call patterns (<|tool_call_start|>, tool_calls, function_call, etc.). Works with any dataset — pre-formatted or auto-formatted.

Continual Training

Train iteratively across multiple datasets, saving locally between rounds:

# Round 1: Coding skills → save locally
lfm-train --dataset sahil2801/CodeAlpaca-20k --no-push

# Round 2: Add tool-calling on top → save locally
lfm-train \
    --resume-from ./lfm-checkpoints/final-adapter \
    --dataset jdaddyalbs/playwright-mcp-toolcalling \
    --tool-calling-only \
    --output-dir ./lfm-checkpoints-r2 \
    --no-push

# Round 3: Final round → push to Hub + export
lfm-train \
    --resume-from ./lfm-checkpoints-r2/final-adapter \
    --dataset peteromallet/dataclaw-peteromallet \
    --hub-repo your-username/lfm-final \
    --export-gguf

Each --resume-from loads the prior adapter and continues learning from where it left off.

How Auto-Publish Works

Training is wrapped in an error handler inspired by Unsloth:

1. SIGTERM (Kaggle timeout) → saves + pushes immediately, then exits
2. CUDA OOM → clears cache, saves + pushes
3. KeyboardInterrupt → saves + pushes
4. Any Exception → saves + pushes, then re-raises

Each checkpoint is tagged with a UTC timestamp (e.g., v20260302-153000) so versions never collide.

Post-Training Export

When --export-gguf or --export-mlx is enabled:

1. LoRA adapters are merged into the base model
2. GGUF: Converted via llama.cpp → Q4_K_M, Q6_K, Q8_0 → pushed to {repo}-GGUF
3. MLX: Converted via mlx-lm → 4-bit, 6-bit, 8-bit → pushed to {repo}-MLX-{N}bit
4. All repos (base + quants) share the same version tag

Note: MLX export requires Apple Silicon. Use --export-gguf on Kaggle (Linux), and --export-mlx locally on Mac.

Examples

See the examples/ directory for ready-to-run scripts:

📁 getting_started/ — First steps

📁 training_modes/ — Advanced training techniques

📁 inference/ — High-efficiency inference

📁 domain_specialists/ — Domain-specific fine-tuning

📁 recipes/ — End-to-end model recipes

📁 advanced/ — Benchmarking & export

📚 Documentation

New to LLM fine-tuning? Start here — no prerequisites beyond basic Python:

License

MIT