MLX Foundry

A professional CLI pipeline for converting, benchmarking, and publishing HuggingFace models to Apple MLX format with publication-grade model cards.

---

Features

• ⚡ Multi-Quantization in One Run: Convert any HuggingFace model to 4-bit, 8-bit, and 16-bit MLX format.
• 📊 Automated Benchmarking: Profile tokens/second, time to first token (TTFT), and peak memory usage on Apple Silicon unified memory.
• 📝 Professional Model Cards: Generate publication-ready HuggingFace model cards featuring reproducible commands, benchmark tables, and hardware guides.
• 🤗 One-Command Hub Publishing: Create repositories, assign appropriate tags (mlx, safetensors, conversational, etc.), and upload with automatic cleanup.
• 📣 Social Post Generation: Instantly create ready-to-share summaries formatted for X/Twitter and Reddit (r/LocalLLaMA).

---

Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Python >= 3.10
• mlx-lm and HuggingFace credentials (hf auth login)

---

Installation

pip install mlx-foundry

Or install from source for development:

git clone https://github.com/SirSahOl/mlx-foundry.git
cd mlx-foundry
pip install -e ".[dev]"

---

Quick Start

Run the end-to-end pipeline to convert, benchmark, generate model cards, and publish:

mlx-foundry pipeline \
    --model Qwen/Qwen3-0.6B \
    --author SirSahOl \
    --quants 4,8,16

Dry Run (Local only, skip publishing)

mlx-foundry pipeline \
    --model Qwen/Qwen3-0.6B \
    --author SirSahOl \
    --quants 4,8 \
    --skip-publish \
    --no-cleanup

---

Commands Reference

1. pipeline

Runs the complete workflow: conversion, benchmark, card generation, publish, and social posts.

mlx-foundry pipeline --model <HF_MODEL_ID> [OPTIONS]

Options:

• -m, --model: HuggingFace model ID (required).
• -a, --author: HuggingFace username/org (default: SirSahOl).
• -q, --quants: Comma-separated quantizations (default: 4,8,16).
• -o, --output: Base output directory (default: ./output).
• --skip-benchmark: Skip performance benchmarking.
• --skip-publish: Skip HuggingFace upload.
• --skip-social: Skip social post generation.
• --no-cleanup: Keep local converted weights after upload.
• --private: Mark HuggingFace repository as private.
• -f, --force: Overwrite existing output directories.

2. convert

Convert models to specified quantization levels.

mlx-foundry convert --model Qwen/Qwen3-0.6B --quants 4,8,16 --output ./output

3. benchmark

Measure throughput (tokens/sec), first-token latency, and memory footprint.

mlx-foundry benchmark --model ./output/Qwen3-0.6B-mlx-4bit --runs 5

4. card

Generate a rich README.md model card using Jinja2 templates.

mlx-foundry card \
    --model ./output/Qwen3-0.6B-mlx-4bit \
    --source Qwen/Qwen3-0.6B \
    --repo SirSahOl/Qwen3-0.6B-chat-mlx-4bit

5. publish

Upload a converted model folder to HuggingFace Hub with complete tags and metadata.

mlx-foundry publish \
    --model ./output/Qwen3-0.6B-mlx-4bit \
    --repo SirSahOl/Qwen3-0.6B-chat-mlx-4bit \
    --source Qwen/Qwen3-0.6B \
    --quant 4

6. social

Generate formatted announcements for Twitter and Reddit.

mlx-foundry social \
    --model-name Qwen3-0.6B \
    --repo SirSahOl/Qwen3-0.6B-chat-mlx-4bit \
    --source Qwen/Qwen3-0.6B \
    --quant 4

---

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

---

License

Distributed under the MIT License. See LICENSE for more information.