Finetuner Studio GUI demo (planning mode)

README.md

@@ -1,13 +1,33 @@
 ---
 title: Finetuner Studio
-emoji: 🐨
-colorFrom: gray
-colorTo: green
+emoji: 🎛️
+colorFrom: yellow
+colorTo: red
 sdk: gradio
 sdk_version: 6.17.3
-python_version: '3.13'
 app_file: app.py
-pinned: false
+python_version: "3.12"
+short_description: Low-code MLX fine-tuning studio (GUI demo)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎛️ Finetuner Studio — GUI Demo
+
+**Low-code fine-tuning on Apple Silicon**, powered by
+[mlx-tune](https://github.com/ARahim3/mlx-tune). This Space runs in
+**GUI-only mode** (Spaces have no Apple Silicon): explore the interface, load
+any Hugging Face dataset and watch the **automatic format detection**, and
+generate standalone mlx-tune training scripts with the code generator.
+
+For actual training (12 paradigms: SFT, DPO, ORPO, SimPO, KTO, GRPO, CPT,
+VLM, TTS, STT, Embedding, OCR), run it on a Mac:
+
+```bash
+git clone https://github.com/aykutcayir34/finetuner
+cd finetuner && pip install -e '.[mlx]' && finetuner
+```
+
+🇹🇷 Bu Space, Finetuner Studio arayüzünün canlı demosudur (Spaces'te Apple
+Silicon olmadığı için eğitim devre dışı; format algılama ve kod üretici
+çalışır). Örnek model: [Llama-3.2-1B Turkish-Alpaca](https://huggingface.co/acayir64/Llama-3.2-1B-Instruct-Turkish-Alpaca-mlx)
+
+Source: https://github.com/aykutcayir34/finetuner

app.py

@@ -0,0 +1,16 @@
+"""Finetuner Studio — Hugging Face Space demo (GUI-only mode).
+
+Spaces run on Linux, so MLX training is unavailable here; the Studio runs in
+planning mode: dataset loading + automatic format detection, the code
+generator, recipes and the full UI are live. Clone it on an Apple Silicon
+Mac for actual training: https://github.com/aykutcayir34/finetuner
+"""
+
+import gradio as gr
+
+from finetuner.app import build_app
+
+demo = build_app()
+
+if __name__ == "__main__":
+    demo.launch(theme=gr.themes.Soft(primary_hue="orange", secondary_hue="slate"))

finetuner/__init__.py

@@ -0,0 +1,3 @@
+"""Finetuner Studio — low-code fine-tuning on Apple Silicon, powered by mlx-tune."""
+
+__version__ = "0.1.0"

finetuner/__main__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+main()

finetuner/app.py

@@ -0,0 +1,45 @@
+"""Finetuner Studio — application entry point."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from .core.registry import TASKS, mlx_available
+from .ui import tab_dataset, tab_export, tab_model, tab_monitor, tab_playground, tab_train
+
+BANNER = """
+# 🎛️ Finetuner Studio
+**Low-code fine-tuning on Apple Silicon** · powered by
+[mlx-tune](https://github.com/ARahim3/mlx-tune) · {n_tasks} training paradigms,
+zero boilerplate
+"""
+
+
+def build_app() -> gr.Blocks:
+    ok, reason = mlx_available()
+    health = "🟢 mlx-tune ready" if ok else f"🟡 GUI-only mode — {reason}"
+
+    with gr.Blocks(title="Finetuner Studio") as app:
+        gr.Markdown(BANNER.format(n_tasks=len(TASKS)))
+        gr.Markdown(f"`{health}`")
+        with gr.Tabs():
+            tab_model.build(app)
+            tab_dataset.build(app)
+            tab_train.build(app)
+            tab_monitor.build(app)
+            tab_playground.build(app)
+            tab_export.build(app)
+        gr.Markdown(
+            "<center><small>Finetuner Studio · load a model → drop a dataset → "
+            "press train. The generated Python script is yours to keep.</small></center>"
+        )
+    return app
+
+
+def main():
+    theme = gr.themes.Soft(primary_hue="orange", secondary_hue="slate")
+    build_app().launch(theme=theme)
+
+
+if __name__ == "__main__":
+    main()

finetuner/core/codegen.py

@@ -0,0 +1,105 @@
+"""Low-code → code: generate a standalone, editable mlx-tune training script
+that reproduces exactly what the GUI is configured to do."""
+
+from __future__ import annotations
+
+from .registry import get_task
+from .training import RunConfig, build_trainer_args
+
+
+def _fmt(v) -> str:
+    return repr(v)
+
+
+def generate_script(cfg: RunConfig, dataset_source: str = "",
+                    dataset_is_local: bool = False) -> str:
+    spec = get_task(cfg.task)
+    args = build_trainer_args(cfg)
+    args_body = ",\n        ".join(f"{k}={_fmt(v)}" for k, v in args.items())
+
+    imports = {spec.trainer}
+    if spec.config_module == "mlx_tune":
+        imports.add(spec.config)
+    if spec.collator:
+        imports.add(spec.collator)
+    import_line = f"from mlx_tune import {spec.loader}, {', '.join(sorted(imports))}"
+    extra_import = ""
+    if spec.config_module != "mlx_tune":
+        extra_import = f"\nfrom {spec.config_module} import {spec.config}"
+
+    # --- model loading -------------------------------------------------------
+    load_kwargs = ""
+    if spec.modality == "text":
+        load_kwargs = (f",\n    max_seq_length={cfg.max_seq_length},"
+                       f"\n    load_in_4bit={cfg.load_in_4bit},")
+    handle = "processor" if spec.modality in ("vision", "image") else "tokenizer"
+
+    # --- LoRA ------------------------------------------------------------------
+    lora_block = ""
+    if cfg.use_lora and spec.peft_supported:
+        tm = ""
+        if spec.modality == "text":
+            tm = f"\n    target_modules={cfg.target_modules!r},"
+        lora_block = f"""
+# --- 2. Attach LoRA adapters -------------------------------------------------
+model = {spec.loader}.get_peft_model(
+    model,
+    r={cfg.lora_r},
+    lora_alpha={cfg.lora_alpha},{tm}
+)
+"""
+
+    # --- dataset ------------------------------------------------------------------
+    if dataset_is_local:
+        ds_block = f"""import json
+
+with open({dataset_source!r}) as f:
+    train_dataset = [json.loads(line) for line in f if line.strip()]"""
+    elif dataset_source:
+        ds_block = f"""from datasets import load_dataset
+
+train_dataset = load_dataset({dataset_source!r}, split="train")"""
+    else:
+        ds_block = """train_dataset = [
+    # TODO: fill with rows shaped like: %s
+]""" % (dict.fromkeys(spec.dataset_schema, "..."),)
+
+    collator_line = ""
+    if spec.collator:
+        collator_line = f"\n    data_collator={spec.collator}(model, {handle}),"
+
+    return f'''"""Auto-generated by Finetuner Studio — https://github.com/aykutcayir34/finetuner
+
+Task    : {spec.label}
+Backend : mlx-tune (https://github.com/ARahim3/mlx-tune)
+
+This script is fully standalone: edit it, version it, or move it to a cloud
+GPU box — the mlx-tune API is Unsloth-compatible by design.
+"""
+
+{import_line}{extra_import}
+
+# --- 1. Load the base model ----------------------------------------------------
+model, {handle} = {spec.loader}.from_pretrained(
+    {cfg.model_name!r}{load_kwargs}
+)
+{lora_block}
+# --- 3. Dataset ------------------------------------------------------------------
+{ds_block}
+
+# --- 4. Train ----------------------------------------------------------------------
+trainer = {spec.trainer}(
+    model=model,
+    {handle}={handle},
+    train_dataset=train_dataset,{collator_line}
+    args={spec.config}(
+        {args_body},
+    ),
+)
+trainer.train()
+
+# --- 5. Save -----------------------------------------------------------------------
+model.save_pretrained("lora_model")                      # adapters only
+# model.save_pretrained_merged("merged", {handle})       # merged fp16 model
+# model.push_to_hub("your-username/your-model")          # upload to the Hub
+'''

finetuner/core/data.py

@@ -0,0 +1,69 @@
+"""Dataset loading from the Hugging Face Hub or local files."""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+
+def search_hub_datasets(query: str, limit: int = 20) -> list[str]:
+    if not query.strip():
+        return []
+    api = HfApi()
+    return [d.id for d in api.list_datasets(search=query, limit=limit, sort="downloads")]
+
+
+def load_hub_dataset(name: str, split: str = "train", config: str | None = None,
+                     max_rows: int | None = None) -> list[dict]:
+    from datasets import load_dataset
+
+    ds = load_dataset(name, config or None, split=split)
+    if max_rows:
+        ds = ds.select(range(min(max_rows, len(ds))))
+    return [dict(r) for r in ds]
+
+
+def load_local_dataset(path: str, max_rows: int | None = None) -> list[dict]:
+    """Load a local dataset file: .jsonl, .json, .csv, .tsv or .parquet."""
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"No such file: {p}")
+    suffix = p.suffix.lower()
+
+    rows: list[dict]
+    if suffix == ".jsonl":
+        rows = []
+        with p.open() as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    rows.append(json.loads(line))
+                if max_rows and len(rows) >= max_rows:
+                    break
+    elif suffix == ".json":
+        data = json.loads(p.read_text())
+        if isinstance(data, dict):  # e.g. {"data": [...]} wrappers
+            for v in data.values():
+                if isinstance(v, list):
+                    data = v
+                    break
+        if not isinstance(data, list):
+            raise ValueError("JSON file must contain a list of records.")
+        rows = data
+    elif suffix in (".csv", ".tsv"):
+        delim = "\t" if suffix == ".tsv" else ","
+        with p.open(newline="") as f:
+            rows = list(csv.DictReader(f, delimiter=delim))
+    elif suffix == ".parquet":
+        import pandas as pd
+        rows = pd.read_parquet(p).to_dict("records")
+    else:
+        raise ValueError(f"Unsupported dataset format: {suffix} "
+                         "(supported: .jsonl, .json, .csv, .tsv, .parquet)")
+
+    if max_rows:
+        rows = rows[:max_rows]
+    return rows

finetuner/core/detector.py

@@ -0,0 +1,292 @@
+"""Automatic dataset format detection and normalization.
+
+Given a few sample rows, classify the dataset into one of the canonical
+formats mlx-tune trainers understand, propose a column mapping, and convert
+rows into the exact shape the selected trainer expects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Column-name synonyms (English + Turkish), matched case-insensitively after
+# stripping whitespace — real-world CSV headers are messy.
+SYNONYMS = {
+    "instruction": {"instruction", "question", "query", "instruct", "task",
+                    "talimat", "soru", "görev"},
+    "input": {"input", "context", "system", "giriş", "girdi", "bağlam"},
+    "output": {"output", "response", "answer", "completion", "target",
+               "çıktı", "cevap", "yanıt"},
+    "prompt": {"prompt", "question", "query", "instruction", "istem", "soru"},
+    "chosen": {"chosen", "preferred", "accepted", "good", "seçilen", "tercih"},
+    "rejected": {"rejected", "dispreferred", "bad", "reddedilen"},
+    "completion": {"completion", "response", "output", "answer", "cevap", "yanıt"},
+    "label": {"label", "thumbs_up", "is_good", "score", "etiket"},
+    "conversations": {"conversations", "messages", "dialogue", "dialog", "chat",
+                      "turns", "konuşmalar", "mesajlar"},
+    "text": {"text", "content", "document", "body", "metin", "içerik"},
+    "anchor": {"anchor", "query", "sentence1", "question", "soru"},
+    "positive": {"positive", "passage", "sentence2", "answer", "document"},
+    "audio": {"audio", "audio_path", "audio_filepath", "wav", "file", "path", "ses"},
+    "transcription": {"text", "transcription", "transcript", "sentence", "caption",
+                      "metin", "cümle"},
+    "image": {"image", "images", "image_path", "img", "picture", "görsel", "resim"},
+}
+
+FORMAT_LABELS = {
+    "alpaca": "Alpaca (instruction / input / output)",
+    "sharegpt": "ShareGPT (conversations with from/value turns)",
+    "chatml": "ChatML / OpenAI messages (role/content turns)",
+    "prompt_completion": "Prompt–completion pairs",
+    "preference": "Preference pairs (prompt / chosen / rejected)",
+    "kto": "KTO binary feedback (prompt / completion / label)",
+    "grpo": "GRPO prompts (prompt, optional answer)",
+    "text": "Raw text corpus",
+    "embedding_pairs": "Embedding pairs (anchor / positive)",
+    "audio_text": "Audio + text (TTS / STT)",
+    "vision_chat": "Image + conversation (VLM)",
+    "image_text": "Image + ground-truth text (OCR)",
+    "unknown": "Unknown — manual mapping required",
+}
+
+
+@dataclass
+class Detection:
+    format: str
+    confidence: float                      # 0..1
+    mapping: dict[str, str] = field(default_factory=dict)   # canonical -> actual column
+    suggested_tasks: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def label(self) -> str:
+        return FORMAT_LABELS.get(self.format, self.format)
+
+
+def _find(columns: list[str], canonical: str) -> str | None:
+    """Find the actual column matching a canonical field name."""
+    lowered = {c.strip().lower(): c for c in columns}
+    if canonical in lowered:
+        return lowered[canonical]
+    for syn in SYNONYMS.get(canonical, ()):
+        if syn in lowered:
+            return lowered[syn]
+    return None
+
+
+def _is_turn_list(value) -> str | None:
+    """Classify a list-of-dicts column as 'sharegpt' or 'chatml' turns."""
+    if not isinstance(value, list) or not value or not isinstance(value[0], dict):
+        return None
+    keys = set(value[0].keys())
+    if {"from", "value"} <= keys:
+        return "sharegpt"
+    if {"role", "content"} <= keys:
+        return "chatml"
+    return None
+
+
+def _looks_like_path(value, exts: tuple[str, ...]) -> bool:
+    return isinstance(value, str) and value.lower().endswith(exts)
+
+
+AUDIO_EXTS = (".wav", ".mp3", ".flac", ".m4a", ".ogg")
+IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tiff")
+
+
+def detect(rows: list[dict]) -> Detection:
+    """Detect the dataset format from sample rows (a handful is enough)."""
+    if not rows:
+        return Detection("unknown", 0.0, notes=["Dataset is empty."])
+
+    row = rows[0]
+    columns = list(row.keys())
+    from .registry import tasks_for_format  # local import to avoid cycles
+
+    def done(fmt: str, conf: float, mapping: dict[str, str], notes: list[str] | None = None) -> Detection:
+        tasks = [t.id for t in tasks_for_format(fmt)]
+        return Detection(fmt, conf, mapping, tasks, notes or [])
+
+    # --- multimodal first: presence of media columns dominates -------------
+    img_col = _find(columns, "image")
+    audio_col = _find(columns, "audio")
+    conv_col = _find(columns, "conversations")
+
+    if img_col is not None:
+        sample = row.get(img_col)
+        media_like = _looks_like_path(sample, IMAGE_EXTS) or not isinstance(sample, str)
+        if conv_col is not None:
+            return done("vision_chat", 0.9 if media_like else 0.6,
+                        {"images": img_col, "messages": conv_col})
+        text_col = _find([c for c in columns if c != img_col], "text")
+        if text_col is not None:
+            return done("image_text", 0.85 if media_like else 0.55,
+                        {"image": img_col, "text": text_col},
+                        ["Image + text detected — suitable for OCR SFT or vision tasks."])
+
+    if audio_col is not None:
+        sample = row.get(audio_col)
+        if _looks_like_path(sample, AUDIO_EXTS) or isinstance(sample, dict):
+            text_col = _find([c for c in columns if c != audio_col], "transcription")
+            if text_col is not None:
+                return done("audio_text", 0.9, {"audio": audio_col, "text": text_col},
+                            ["Audio + text detected — choose TTS (synthesis) or STT (recognition)."])
+
+    # --- conversation formats ----------------------------------------------
+    if conv_col is not None:
+        kind = _is_turn_list(row.get(conv_col))
+        if kind == "sharegpt":
+            return done("sharegpt", 0.95, {"conversations": conv_col})
+        if kind == "chatml":
+            return done("chatml", 0.95, {"messages": conv_col})
+
+    # --- preference / feedback ----------------------------------------------
+    chosen = _find(columns, "chosen")
+    rejected = _find(columns, "rejected")
+    prompt = _find(columns, "prompt")
+    if chosen and rejected:
+        mapping = {"chosen": chosen, "rejected": rejected}
+        if prompt:
+            mapping["prompt"] = prompt
+            return done("preference", 0.95, mapping)
+        return done("preference", 0.75, mapping,
+                    ["No explicit prompt column; chosen/rejected may embed the prompt."])
+
+    label = _find(columns, "label")
+    completion = _find(columns, "completion")
+    if prompt and completion and label is not None:
+        if isinstance(row.get(label), (bool, int)):
+            return done("kto", 0.9, {"prompt": prompt, "completion": completion, "label": label})
+
+    # --- instruction tuning ---------------------------------------------------
+    instruction = _find(columns, "instruction")
+    output = _find(columns, "output")
+    if instruction and output:
+        mapping = {"instruction": instruction, "output": output}
+        inp = _find([c for c in columns if c not in (instruction, output)], "input")
+        if inp:
+            mapping["input"] = inp
+        return done("alpaca", 0.95, mapping)
+
+    if prompt and completion:
+        return done("prompt_completion", 0.9, {"prompt": prompt, "completion": completion})
+
+    # --- embeddings -----------------------------------------------------------
+    anchor = _find(columns, "anchor")
+    positive = _find(columns, "positive")
+    if anchor and positive and anchor != positive:
+        return done("embedding_pairs", 0.8, {"anchor": anchor, "positive": positive},
+                    ["Anchor/positive pair detected — embedding contrastive training."])
+
+    # --- GRPO: bare prompts -----------------------------------------------------
+    if prompt and len(columns) <= 2:
+        return done("grpo", 0.6, {"prompt": prompt},
+                    ["Bare prompts — usable for GRPO with a custom reward function."])
+
+    # --- raw text ----------------------------------------------------------------
+    text = _find(columns, "text")
+    if text:
+        return done("text", 0.85, {"text": text},
+                    ["Raw text — suitable for CPT or completion-style SFT."])
+
+    # --- single string column fallback ---------------------------------------------
+    str_cols = [c for c in columns if isinstance(row.get(c), str)]
+    if len(str_cols) == 1:
+        return done("text", 0.5, {"text": str_cols[0]},
+                    [f"Single text column `{str_cols[0]}` assumed to be raw text."])
+
+    return Detection("unknown", 0.0, {},
+                     notes=[f"Could not classify columns: {columns}. Map fields manually."])
+
+
+# ---------------------------------------------------------------------------
+# Normalization: convert detected rows into trainer-ready shape
+# ---------------------------------------------------------------------------
+
+def _format_chat(turns: list[dict], tokenizer=None) -> str:
+    """Render chat turns to text via the tokenizer's chat template when possible."""
+    if tokenizer is not None and hasattr(tokenizer, "apply_chat_template"):
+        try:
+            return tokenizer.apply_chat_template(turns, tokenize=False, add_generation_prompt=False)
+        except Exception:
+            pass
+    return "\n".join(f"<|{t['role']}|>\n{t['content']}" for t in turns) + "\n"
+
+
+SHAREGPT_ROLES = {"human": "user", "user": "user", "gpt": "assistant",
+                  "assistant": "assistant", "system": "system"}
+
+
+def to_messages(row: dict, detection: Detection) -> list[dict]:
+    """Convert a row of any chat-like format into ChatML messages."""
+    m = detection.mapping
+    fmt = detection.format
+    if fmt == "chatml":
+        return row[m["messages"]]
+    if fmt == "sharegpt":
+        return [{"role": SHAREGPT_ROLES.get(t["from"], "user"), "content": t["value"]}
+                for t in row[m["conversations"]]]
+    if fmt == "alpaca":
+        user = row[m["instruction"]]
+        if "input" in m and row.get(m["input"]):
+            user = f"{user}\n\n{row[m['input']]}"
+        return [{"role": "user", "content": user},
+                {"role": "assistant", "content": row[m["output"]]}]
+    if fmt == "prompt_completion":
+        return [{"role": "user", "content": row[m["prompt"]]},
+                {"role": "assistant", "content": row[m["completion"]]}]
+    raise ValueError(f"Cannot build messages from format {fmt!r}")
+
+
+def normalize(rows: list[dict], detection: Detection, task_id: str, tokenizer=None) -> list[dict]:
+    """Convert raw rows into the schema the chosen task's trainer expects."""
+    m = detection.mapping
+    fmt = detection.format
+
+    if task_id in ("sft",):
+        if fmt == "text":
+            return [{"text": r[m["text"]]} for r in rows]
+        return [{"text": _format_chat(to_messages(r, detection), tokenizer)} for r in rows]
+
+    if task_id == "cpt":
+        col = m.get("text")
+        if col is None:
+            raise ValueError("CPT needs a raw text column.")
+        return [{"text": r[col]} for r in rows]
+
+    if task_id in ("dpo", "orpo", "simpo"):
+        out = []
+        for r in rows:
+            item = {"chosen": r[m["chosen"]], "rejected": r[m["rejected"]]}
+            item["prompt"] = r[m["prompt"]] if "prompt" in m else ""
+            out.append(item)
+        return out
+
+    if task_id == "kto":
+        return [{"prompt": r[m["prompt"]], "completion": r[m["completion"]],
+                 "label": bool(r[m["label"]])} for r in rows]
+
+    if task_id == "grpo":
+        return [{"prompt": r[m["prompt"]]} for r in rows]
+
+    if task_id == "embedding":
+        return [{"anchor": r[m["anchor"]], "positive": r[m["positive"]]} for r in rows]
+
+    if task_id in ("tts_sft", "stt_sft"):
+        return [{"audio": r[m["audio"]], "text": r[m["text"]]} for r in rows]
+
+    if task_id == "ocr_sft":
+        return [{"image": r[m["image"]], "text": r[m["text"]]} for r in rows]
+
+    if task_id == "vlm_sft":
+        out = []
+        for r in rows:
+            sub = {"images": r[m["images"]], "messages": r[m["messages"]]}
+            if isinstance(sub["messages"], list) and sub["messages"] \
+                    and "from" in (sub["messages"][0] or {}):
+                sub["messages"] = [{"role": SHAREGPT_ROLES.get(t["from"], "user"),
+                                    "content": t["value"]} for t in sub["messages"]]
+            out.append(sub)
+        return out
+
+    raise ValueError(f"Unknown task {task_id!r}")

finetuner/core/engine.py

@@ -0,0 +1,56 @@
+"""Single persistent MLX engine thread.
+
+MLX streams are thread-local: a model loaded on one thread cannot reliably be
+trained or sampled from another ("There is no Stream(gpu, N) in current
+thread"). Gradio runs every event handler on a different worker thread, so all
+MLX work — model loading, training, generation — is funneled through one
+long-lived engine thread. This also serializes GPU work, which is what a
+single-device machine wants anyway.
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import sys
+import threading
+from pathlib import Path
+
+# mlx-tune's subprocess fallback shells out to `mlx_lm.lora`; make sure the
+# interpreter's bin directory is on PATH even when the venv isn't activated.
+_bin = str(Path(sys.executable).parent)
+if _bin not in os.environ.get("PATH", "").split(os.pathsep):
+    os.environ["PATH"] = _bin + os.pathsep + os.environ.get("PATH", "")
+
+
+class _Engine:
+    def __init__(self):
+        self._q: queue.Queue = queue.Queue()
+        self._thread = threading.Thread(target=self._loop, name="finetuner-mlx-engine",
+                                        daemon=True)
+        self._thread.start()
+
+    def _loop(self):
+        while True:
+            fn, args, kwargs, done, box = self._q.get()
+            try:
+                box["result"] = fn(*args, **kwargs)
+            except BaseException as exc:  # noqa: BLE001 — re-raised on the caller thread
+                box["error"] = exc
+            finally:
+                done.set()
+
+    def call(self, fn, *args, **kwargs):
+        """Run `fn` on the engine thread and block until it returns."""
+        if threading.current_thread() is self._thread:
+            return fn(*args, **kwargs)
+        done = threading.Event()
+        box: dict = {}
+        self._q.put((fn, args, kwargs, done, box))
+        done.wait()
+        if "error" in box:
+            raise box["error"]
+        return box["result"]
+
+
+ENGINE = _Engine()

finetuner/core/export.py

@@ -0,0 +1,28 @@
+"""Export trained models: adapters, merged weights, GGUF, or push to the Hub."""
+
+from __future__ import annotations
+
+
+def save_adapters(model, path: str) -> str:
+    model.save_pretrained(path)
+    return f"LoRA adapters saved to {path}"
+
+
+def save_merged(model, tokenizer, path: str) -> str:
+    model.save_pretrained_merged(path, tokenizer)
+    return f"Merged 16-bit model saved to {path}"
+
+
+def save_gguf(model, tokenizer, path: str) -> str:
+    # mlx-lm limitation: GGUF export requires a non-quantized base model.
+    model.save_pretrained_gguf(path, tokenizer)
+    return f"GGUF model saved to {path}"
+
+
+def push_to_hub(model, repo_id: str, token: str | None = None) -> str:
+    kwargs = {"token": token} if token else {}
+    try:
+        model.push_to_hub(repo_id, **kwargs)
+    except TypeError:
+        model.push_to_hub(repo_id)
+    return f"Pushed to https://huggingface.co/{repo_id}"

finetuner/core/jobs.py

@@ -0,0 +1,135 @@
+"""Background training job manager.
+
+Training runs on a worker thread so the GUI stays responsive. Trainer stdout
+is captured into a ring buffer; loss values are parsed out of the log stream
+for live charting.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import re
+import threading
+import time
+import traceback
+from collections import deque
+from dataclasses import dataclass, field
+
+# Matches lines like "step 10: loss 1.2345", "{'loss': 1.23, 'step': 10}", "10/100 | loss: 1.23"
+_LOSS_RE = re.compile(r"loss[\"']?[:=\s]+([0-9]*\.?[0-9]+(?:e-?\d+)?)", re.IGNORECASE)
+_STEP_RE = re.compile(r"(?:step|it(?:er)?)[\"']?[:=\s/]+(\d+)", re.IGNORECASE)
+
+
+class _Tee(io.TextIOBase):
+    """Write-through stream that feeds the job log and parses metrics."""
+
+    def __init__(self, job: "Job", original):
+        self.job = job
+        self.original = original
+        self._buf = ""
+
+    def write(self, s: str) -> int:
+        self.original.write(s)
+        self._buf += s
+        parts = re.split(r"[\n\r]", self._buf)
+        self._buf = parts.pop()  # keep the unterminated tail
+        for line in parts:
+            if line.strip():
+                self.job.add_log(line)
+        return len(s)
+
+    def flush(self):
+        self.original.flush()
+
+
+@dataclass
+class Job:
+    id: int
+    name: str
+    status: str = "pending"  # pending | running | finished | failed | stopped
+    logs: deque = field(default_factory=lambda: deque(maxlen=2000))
+    metrics: list = field(default_factory=list)  # [(step, loss)]
+    error: str | None = None
+    started_at: float | None = None
+    finished_at: float | None = None
+    stop_event: threading.Event = field(default_factory=threading.Event)
+    _step_guess: int = 0
+
+    def add_log(self, line: str):
+        self.logs.append(line)
+        loss = _LOSS_RE.search(line)
+        if loss:
+            step_m = _STEP_RE.search(line)
+            if step_m:
+                self._step_guess = int(step_m.group(1))
+            else:
+                self._step_guess += 1
+            try:
+                self.metrics.append((self._step_guess, float(loss.group(1))))
+            except ValueError:
+                pass
+
+    def log_text(self, last_n: int = 200) -> str:
+        return "\n".join(list(self.logs)[-last_n:])
+
+    @property
+    def elapsed(self) -> float:
+        if self.started_at is None:
+            return 0.0
+        end = self.finished_at or time.time()
+        return end - self.started_at
+
+
+class JobManager:
+    def __init__(self):
+        self._jobs: dict[int, Job] = {}
+        self._next_id = 1
+        self._lock = threading.Lock()
+
+    def submit(self, name: str, target, *args, **kwargs) -> Job:
+        """Run `target(job, *args, **kwargs)` on a worker thread with log capture."""
+        with self._lock:
+            job = Job(id=self._next_id, name=name)
+            self._jobs[job.id] = job
+            self._next_id += 1
+
+        def runner():
+            job.status = "running"
+            job.started_at = time.time()
+            tee_out = _Tee(job, __import__("sys").stdout)
+            tee_err = _Tee(job, __import__("sys").stderr)
+            from .engine import ENGINE  # local import: keep jobs importable standalone
+            try:
+                with contextlib.redirect_stdout(tee_out), contextlib.redirect_stderr(tee_err):
+                    # All MLX work must run on the single engine thread; the
+                    # stdout redirect is process-wide, so logs still reach us.
+                    ENGINE.call(target, job, *args, **kwargs)
+                job.status = "stopped" if job.stop_event.is_set() else "finished"
+            except Exception:
+                job.error = traceback.format_exc()
+                job.add_log(job.error)
+                job.status = "failed"
+            finally:
+                job.finished_at = time.time()
+
+        threading.Thread(target=runner, name=f"finetuner-job-{job.id}", daemon=True).start()
+        return job
+
+    def get(self, job_id: int) -> Job | None:
+        return self._jobs.get(job_id)
+
+    def all(self) -> list[Job]:
+        return list(self._jobs.values())
+
+    def latest(self) -> Job | None:
+        return self._jobs[max(self._jobs)] if self._jobs else None
+
+    def stop(self, job_id: int):
+        job = self._jobs.get(job_id)
+        if job:
+            job.stop_event.set()
+            job.add_log("⏹ Stop requested — training will halt at the next step boundary.")
+
+
+MANAGER = JobManager()

finetuner/core/models.py

@@ -0,0 +1,69 @@
+"""Model discovery (Hugging Face Hub) and loading via mlx-tune."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+from .engine import ENGINE
+from .registry import get_task, resolve
+
+
+def search_hub_models(query: str, limit: int = 20, mlx_only: bool = True) -> list[str]:
+    """Search the Hub; by default biased to mlx-community / MLX-tagged models."""
+    if not query.strip():
+        return []
+    api = HfApi()
+    kwargs: dict = {"search": query, "limit": limit, "sort": "downloads"}
+    if mlx_only:
+        kwargs["filter"] = "mlx"
+    try:
+        results = [m.id for m in api.list_models(**kwargs)]
+    except TypeError:  # huggingface_hub version drift on the filter kwarg
+        kwargs.pop("filter", None)
+        results = [m.id for m in api.list_models(**kwargs)]
+    if not results and mlx_only:  # fall back to an unrestricted search
+        results = [m.id for m in api.list_models(search=query, limit=limit, sort="downloads")]
+    return results
+
+
+def validate_local_model(path: str) -> str:
+    p = Path(path).expanduser()
+    if not p.is_dir():
+        raise FileNotFoundError(f"Not a directory: {p}")
+    if not (p / "config.json").exists():
+        raise ValueError(f"{p} does not look like a model directory (missing config.json).")
+    return str(p)
+
+
+def load_model(task_id: str, model_name: str, max_seq_length: int = 2048,
+               load_in_4bit: bool = True):
+    """Load a model + tokenizer/processor through the task's mlx-tune loader."""
+    spec = get_task(task_id)
+    loader = resolve(spec.loader)
+    kwargs: dict = {}
+    if spec.modality == "text":
+        kwargs["max_seq_length"] = max_seq_length
+        kwargs["load_in_4bit"] = load_in_4bit
+    # MLX streams are thread-local — load on the engine thread (see engine.py).
+    return ENGINE.call(loader.from_pretrained, model_name, **kwargs)
+
+
+def apply_lora(task_id: str, model, r: int = 16, lora_alpha: int = 16,
+               lora_dropout: float = 0.0, target_modules: list[str] | None = None,
+               **extra):
+    spec = get_task(task_id)
+    loader = resolve(spec.loader)
+    kwargs: dict = {"r": r, "lora_alpha": lora_alpha}
+    if lora_dropout:
+        kwargs["lora_dropout"] = lora_dropout
+    if spec.modality == "text" and target_modules:
+        kwargs["target_modules"] = list(target_modules)
+    kwargs.update(extra)
+    try:
+        return ENGINE.call(loader.get_peft_model, model, **kwargs)
+    except TypeError:
+        # Older mlx-tune versions may not accept every kwarg (e.g. lora_dropout).
+        kwargs.pop("lora_dropout", None)
+        return ENGINE.call(loader.get_peft_model, model, **kwargs)

finetuner/core/recipes.py

@@ -0,0 +1,40 @@
+"""Recipes: save/load complete run configurations as shareable YAML files."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import yaml
+
+from .training import RunConfig
+
+RECIPE_DIR = Path("recipes")
+
+
+def save_recipe(cfg: RunConfig, name: str = "", dataset_source: str = "",
+                dataset_is_local: bool = False) -> Path:
+    RECIPE_DIR.mkdir(exist_ok=True)
+    slug = (name.strip() or f"{cfg.task}-{time.strftime('%Y%m%d-%H%M%S')}").replace(" ", "-")
+    path = RECIPE_DIR / f"{slug}.yaml"
+    payload = {
+        "finetuner_recipe": 1,
+        "dataset": {"source": dataset_source, "local": dataset_is_local},
+        "run": cfg.to_dict(),
+    }
+    path.write_text(yaml.safe_dump(payload, sort_keys=False, allow_unicode=True))
+    return path
+
+
+def load_recipe(path: str) -> tuple[RunConfig, str, bool]:
+    data = yaml.safe_load(Path(path).expanduser().read_text())
+    if not isinstance(data, dict) or "run" not in data:
+        raise ValueError("Not a Finetuner recipe (missing `run` section).")
+    ds = data.get("dataset", {})
+    return RunConfig.from_dict(data["run"]), ds.get("source", ""), bool(ds.get("local", False))
+
+
+def list_recipes() -> list[str]:
+    if not RECIPE_DIR.exists():
+        return []
+    return sorted(str(p) for p in RECIPE_DIR.glob("*.yaml"))

finetuner/core/registry.py

@@ -0,0 +1,232 @@
+"""Task registry: one entry per mlx-tune training paradigm.
+
+Every public trainer interface that mlx-tune exposes is described here so the
+GUI, the code generator and the recipe system all share a single source of
+truth. mlx-tune itself is imported lazily — the Studio runs (for planning,
+dataset inspection, recipe authoring and script generation) even on machines
+where MLX is not installed.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import platform
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class TaskSpec:
+    id: str
+    label: str
+    description: str
+    loader: str                      # mlx_tune Fast*Model class name
+    trainer: str                     # mlx_tune trainer class name
+    config: str                      # mlx_tune config class name
+    config_module: str = "mlx_tune"  # module to import the config from
+    collator: str | None = None      # optional data collator class name
+    dataset_schema: tuple[str, ...] = ()   # canonical required fields
+    detector_formats: tuple[str, ...] = ()  # detector format ids that map to this task
+    default_model: str = ""
+    default_target_modules: tuple[str, ...] = (
+        "q_proj", "k_proj", "v_proj", "o_proj",
+    )
+    peft_supported: bool = True
+    extra_config_defaults: dict = field(default_factory=dict)
+    modality: str = "text"           # text | vision | audio | image
+    notes: str = ""
+
+
+FULL_TARGETS = ("q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj")
+
+TASKS: dict[str, TaskSpec] = {
+    "sft": TaskSpec(
+        id="sft",
+        label="SFT — Supervised Fine-Tuning",
+        description="Instruction tuning of chat/completion LLMs on text or conversation data.",
+        loader="FastLanguageModel",
+        trainer="SFTTrainer",
+        config="SFTConfig",
+        dataset_schema=("text",),
+        detector_formats=("alpaca", "sharegpt", "chatml", "prompt_completion", "text"),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+    ),
+    "dpo": TaskSpec(
+        id="dpo",
+        label="DPO — Direct Preference Optimization",
+        description="Align a model with human preferences from chosen/rejected pairs.",
+        loader="FastLanguageModel",
+        trainer="DPOTrainer",
+        config="DPOConfig",
+        dataset_schema=("prompt", "chosen", "rejected"),
+        detector_formats=("preference",),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+        extra_config_defaults={"beta": 0.1},
+    ),
+    "orpo": TaskSpec(
+        id="orpo",
+        label="ORPO — Odds Ratio Preference Optimization",
+        description="Reference-free preference optimization; combines SFT and alignment in one pass.",
+        loader="FastLanguageModel",
+        trainer="ORPOTrainer",
+        config="ORPOConfig",
+        dataset_schema=("prompt", "chosen", "rejected"),
+        detector_formats=("preference",),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+        extra_config_defaults={"beta": 0.1},
+    ),
+    "simpo": TaskSpec(
+        id="simpo",
+        label="SimPO — Simple Preference Optimization",
+        description="Length-normalized, reference-free preference optimization.",
+        loader="FastLanguageModel",
+        trainer="SimPOTrainer",
+        config="SimPOConfig",
+        dataset_schema=("prompt", "chosen", "rejected"),
+        detector_formats=("preference",),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+    ),
+    "kto": TaskSpec(
+        id="kto",
+        label="KTO — Kahneman-Tversky Optimization",
+        description="Alignment from simple binary thumbs-up/down feedback (no pairs needed).",
+        loader="FastLanguageModel",
+        trainer="KTOTrainer",
+        config="KTOConfig",
+        dataset_schema=("prompt", "completion", "label"),
+        detector_formats=("kto",),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+    ),
+    "grpo": TaskSpec(
+        id="grpo",
+        label="GRPO — Group Relative Policy Optimization",
+        description="Online RL with programmable reward functions (reasoning, math, code).",
+        loader="FastLanguageModel",
+        trainer="GRPOTrainer",
+        config="GRPOConfig",
+        dataset_schema=("prompt",),
+        detector_formats=("grpo",),
+        default_model="mlx-community/Llama-3.2-1B-Instruct-4bit",
+        notes="Reward functions are plain Python callables; edit them in the generated script.",
+    ),
+    "cpt": TaskSpec(
+        id="cpt",
+        label="CPT — Continual Pretraining",
+        description="Inject domain knowledge by continuing pretraining on raw text.",
+        loader="FastLanguageModel",
+        trainer="CPTTrainer",
+        config="CPTConfig",
+        dataset_schema=("text",),
+        detector_formats=("text",),
+        default_model="mlx-community/SmolLM2-360M-Instruct",
+        default_target_modules=FULL_TARGETS,
+        extra_config_defaults={"embedding_learning_rate": 5e-6, "include_embeddings": True},
+    ),
+    "vlm_sft": TaskSpec(
+        id="vlm_sft",
+        label="Vision SFT — Vision-Language Models",
+        description="Fine-tune VLMs (Qwen-VL, LLaVA-style) on image + conversation data.",
+        loader="FastVisionModel",
+        trainer="VLMSFTTrainer",
+        config="VLMSFTConfig",
+        config_module="mlx_tune.vlm",
+        dataset_schema=("images", "messages"),
+        detector_formats=("vision_chat",),
+        default_model="mlx-community/Qwen2.5-VL-3B-Instruct-4bit",
+        modality="vision",
+    ),
+    "tts_sft": TaskSpec(
+        id="tts_sft",
+        label="TTS SFT — Text-to-Speech",
+        description="Fine-tune speech synthesis models (Orpheus, OuteTTS, CSM…) on audio+text pairs.",
+        loader="FastTTSModel",
+        trainer="TTSSFTTrainer",
+        config="TTSSFTConfig",
+        collator="TTSDataCollator",
+        dataset_schema=("audio", "text"),
+        detector_formats=("audio_text",),
+        default_model="mlx-community/orpheus-3b-0.1-ft-bf16",
+        modality="audio",
+        notes="Audio training currently supports batch_size=1 (mlx-tune limitation).",
+    ),
+    "stt_sft": TaskSpec(
+        id="stt_sft",
+        label="STT SFT — Speech-to-Text",
+        description="Fine-tune ASR models (Whisper, Parakeet, Canary…) on audio+transcription pairs.",
+        loader="FastSTTModel",
+        trainer="STTSFTTrainer",
+        config="STTSFTConfig",
+        collator="STTDataCollator",
+        dataset_schema=("audio", "text"),
+        detector_formats=("audio_text",),
+        default_model="mlx-community/whisper-tiny-asr-fp16",
+        modality="audio",
+        notes="Audio training currently supports batch_size=1 (mlx-tune limitation).",
+    ),
+    "embedding": TaskSpec(
+        id="embedding",
+        label="Embedding SFT — Sentence Embeddings",
+        description="Contrastive fine-tuning of embedding models (anchor/positive pairs).",
+        loader="FastEmbeddingModel",
+        trainer="EmbeddingSFTTrainer",
+        config="EmbeddingSFTConfig",
+        dataset_schema=("anchor", "positive"),
+        detector_formats=("embedding_pairs",),
+        default_model="mlx-community/all-MiniLM-L6-v2-bf16",
+        extra_config_defaults={"loss_type": "infonce", "temperature": 0.05},
+    ),
+    "ocr_sft": TaskSpec(
+        id="ocr_sft",
+        label="OCR SFT — Optical Character Recognition",
+        description="Fine-tune OCR models (DeepSeek-OCR, olmOCR…) on image + ground-truth text.",
+        loader="FastOCRModel",
+        trainer="OCRSFTTrainer",
+        config="OCRSFTConfig",
+        dataset_schema=("image", "text"),
+        detector_formats=("image_text",),
+        default_model="mlx-community/DeepSeek-OCR-8bit",
+        modality="image",
+        extra_config_defaults={"learning_rate": 5e-5},
+    ),
+}
+
+
+def get_task(task_id: str) -> TaskSpec:
+    return TASKS[task_id]
+
+
+def task_choices() -> list[tuple[str, str]]:
+    """(label, id) pairs for a Gradio dropdown."""
+    return [(spec.label, spec.id) for spec in TASKS.values()]
+
+
+def tasks_for_format(format_id: str) -> list[TaskSpec]:
+    return [spec for spec in TASKS.values() if format_id in spec.detector_formats]
+
+
+# ---------------------------------------------------------------------------
+# Lazy mlx-tune access
+# ---------------------------------------------------------------------------
+
+def mlx_available() -> tuple[bool, str]:
+    """Whether mlx-tune is importable on this machine, plus a human reason."""
+    if platform.machine() != "arm64" or platform.system() != "Darwin":
+        return False, "mlx-tune requires an Apple Silicon Mac (arm64/macOS)."
+    if importlib.util.find_spec("mlx_tune") is None:
+        return False, "mlx-tune is not installed. Run: pip install 'finetuner[mlx]'"
+    return True, "mlx-tune is available."
+
+
+def resolve(name: str, module: str = "mlx_tune"):
+    """Import `name` from an mlx_tune module, raising a friendly error if missing."""
+    ok, reason = mlx_available()
+    if not ok:
+        raise RuntimeError(reason)
+    mod = importlib.import_module(module)
+    try:
+        return getattr(mod, name)
+    except AttributeError as exc:
+        raise RuntimeError(
+            f"`{name}` not found in `{module}`. Your mlx-tune version may be too old; "
+            "try: pip install -U mlx-tune"
+        ) from exc

finetuner/core/state.py

@@ -0,0 +1,35 @@
+"""Shared application state for the (single-user, local) Studio session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .detector import Detection
+from .training import RunConfig
+
+
+@dataclass
+class AppState:
+    # Model
+    model = None
+    tokenizer = None
+    model_name: str = ""
+    model_loaded_for_task: str = ""
+    lora_attached: bool = False
+    # Dataset
+    raw_rows: list[dict] = field(default_factory=list)
+    detection: Detection | None = None
+    dataset_source: str = ""
+    dataset_is_local: bool = False
+    # Run configuration
+    config: RunConfig = field(default_factory=RunConfig)
+
+    def reset_model(self):
+        self.model = None
+        self.tokenizer = None
+        self.model_name = ""
+        self.model_loaded_for_task = ""
+        self.lora_attached = False
+
+
+STATE = AppState()

finetuner/core/training.py

@@ -0,0 +1,105 @@
+"""Build and run mlx-tune trainers from a flat GUI config dict."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .jobs import Job
+from .registry import get_task, resolve
+
+
+@dataclass
+class RunConfig:
+    """Everything the GUI collects, flattened into one serializable object."""
+    task: str = "sft"
+    model_name: str = ""
+    max_seq_length: int = 2048
+    load_in_4bit: bool = True
+    # LoRA
+    use_lora: bool = True
+    lora_r: int = 16
+    lora_alpha: int = 16
+    lora_dropout: float = 0.0
+    target_modules: list[str] = field(default_factory=lambda: ["q_proj", "k_proj", "v_proj", "o_proj"])
+    # Training hyperparameters
+    output_dir: str = "outputs"
+    batch_size: int = 2
+    gradient_accumulation_steps: int = 1
+    learning_rate: float = 2e-4
+    max_steps: int = 100
+    num_train_epochs: float | None = None
+    warmup_steps: int = 5
+    gradient_checkpointing: bool = False
+    seed: int = 42
+    # Task-specific extras (beta for DPO, temperature for embeddings, ...)
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        from dataclasses import asdict
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RunConfig":
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+def _filtered_kwargs(config_cls, kwargs: dict) -> dict:
+    """Drop kwargs the dataclass config doesn't accept (version drift safety)."""
+    fields = getattr(config_cls, "__dataclass_fields__", None)
+    if fields is None:
+        return kwargs
+    return {k: v for k, v in kwargs.items() if k in fields}
+
+
+def build_trainer_args(cfg: RunConfig) -> dict:
+    spec = get_task(cfg.task)
+    args: dict = {
+        "output_dir": cfg.output_dir,
+        "per_device_train_batch_size": cfg.batch_size,
+        "gradient_accumulation_steps": cfg.gradient_accumulation_steps,
+        "learning_rate": cfg.learning_rate,
+        "warmup_steps": cfg.warmup_steps,
+        "seed": cfg.seed,
+    }
+    if cfg.num_train_epochs:
+        args["num_train_epochs"] = cfg.num_train_epochs
+    else:
+        args["max_steps"] = cfg.max_steps
+    if cfg.gradient_checkpointing:
+        args["gradient_checkpointing"] = True
+    args.update(spec.extra_config_defaults)
+    args.update(cfg.extra)
+    return args
+
+
+def run_training(job: Job, cfg: RunConfig, model, tokenizer, dataset: list[dict]):
+    """Job target: construct the task's trainer and train. Runs on a worker thread."""
+    spec = get_task(cfg.task)
+    trainer_cls = resolve(spec.trainer)
+    config_cls = resolve(spec.config, spec.config_module)
+
+    args = config_cls(**_filtered_kwargs(config_cls, build_trainer_args(cfg)))
+
+    trainer_kwargs: dict = {"model": model, "train_dataset": dataset, "args": args}
+    if spec.modality == "vision" or spec.id == "ocr_sft":
+        trainer_kwargs["processor"] = tokenizer
+    else:
+        trainer_kwargs["tokenizer"] = tokenizer
+    if spec.collator:
+        collator_cls = resolve(spec.collator)
+        trainer_kwargs["data_collator"] = collator_cls(model, tokenizer)
+
+    try:
+        trainer = trainer_cls(**trainer_kwargs)
+    except TypeError:
+        # Some trainers take `processor` instead of `tokenizer` or vice versa.
+        if "tokenizer" in trainer_kwargs:
+            trainer_kwargs["processor"] = trainer_kwargs.pop("tokenizer")
+        else:
+            trainer_kwargs["tokenizer"] = trainer_kwargs.pop("processor")
+        trainer = trainer_cls(**trainer_kwargs)
+
+    job.add_log(f"▶ {spec.label} started — {len(dataset)} samples, output → {cfg.output_dir}")
+    trainer.train()
+    job.add_log("✅ Training finished.")

finetuner/ui/tab_dataset.py

@@ -0,0 +1,117 @@
+"""Dataset tab: load from the Hub, a local path, or upload — then auto-detect the format."""
+
+from __future__ import annotations
+
+import pandas as pd
+import gradio as gr
+
+from ..core import data as datalib
+from ..core.detector import detect
+from ..core.registry import get_task
+from ..core.state import STATE
+
+PREVIEW_ROWS = 8
+
+
+def _preview_df(rows: list[dict]) -> pd.DataFrame:
+    if not rows:
+        return pd.DataFrame()
+    df = pd.DataFrame(rows[:PREVIEW_ROWS])
+    return df.map(lambda v: str(v)[:300] if not isinstance(v, (int, float, bool)) else v)
+
+
+def _detection_md() -> str:
+    det = STATE.detection
+    if det is None:
+        return ""
+    bar = "🟩" * round(det.confidence * 10) + "⬜" * (10 - round(det.confidence * 10))
+    lines = [
+        f"### 🔎 Detected format: **{det.label}**",
+        f"Confidence: {bar} **{det.confidence:.0%}**",
+    ]
+    if det.mapping:
+        mapped = ", ".join(f"`{k}` ← `{v}`" for k, v in det.mapping.items())
+        lines.append(f"Column mapping: {mapped}")
+    if det.suggested_tasks:
+        tasks = ", ".join(f"**{get_task(t).label}**" for t in det.suggested_tasks)
+        lines.append(f"Compatible trainers: {tasks}")
+    for note in det.notes:
+        lines.append(f"> 💡 {note}")
+    return "\n\n".join(lines)
+
+
+def _ingest(rows: list[dict], source: str, is_local: bool) -> tuple[str, pd.DataFrame, str]:
+    STATE.raw_rows = rows
+    STATE.detection = detect(rows)
+    STATE.dataset_source = source
+    STATE.dataset_is_local = is_local
+    return (f"✅ Loaded **{len(rows)}** rows from `{source}`.",
+            _preview_df(rows), _detection_md())
+
+
+def build(app):
+    with gr.Tab("📚 Dataset", id="dataset"):
+        gr.Markdown("### Load a dataset — the format is detected automatically")
+        source = gr.Radio(["Hugging Face Hub", "Local file", "Upload"],
+                          value="Hugging Face Hub", label="Source")
+
+        with gr.Group() as hub_group:
+            with gr.Row():
+                query = gr.Textbox(label="Search Hub datasets", placeholder="e.g. alpaca turkish", scale=3)
+                search_btn = gr.Button("🔍 Search", scale=1)
+            with gr.Row():
+                ds_name = gr.Dropdown(label="Dataset", allow_custom_value=True, choices=[],
+                                      info="Pick a result or type any dataset id.", scale=3)
+                split = gr.Textbox(value="train", label="Split", scale=1)
+                subset = gr.Textbox(value="", label="Config (optional)", scale=1)
+
+        local_path = gr.Textbox(label="Local dataset path", visible=False,
+                                placeholder="~/data/train.jsonl  (.jsonl/.json/.csv/.tsv/.parquet)")
+        upload = gr.File(label="Upload dataset", visible=False,
+                         file_types=[".jsonl", ".json", ".csv", ".tsv", ".parquet"])
+
+        with gr.Row():
+            max_rows = gr.Number(value=0, precision=0, label="Max rows (0 = all)")
+            load_btn = gr.Button("📥 Load dataset", variant="primary", scale=2)
+
+        status = gr.Markdown()
+        detection_panel = gr.Markdown()
+        preview = gr.Dataframe(label=f"Preview (first {PREVIEW_ROWS} rows)", interactive=False, wrap=True)
+
+        # ----- events -------------------------------------------------------
+        def on_source(src):
+            return (gr.update(visible=src == "Hugging Face Hub"),
+                    gr.update(visible=src == "Local file"),
+                    gr.update(visible=src == "Upload"))
+
+        source.change(on_source, source, [hub_group, local_path, upload])
+
+        def on_search(q):
+            results = datalib.search_hub_datasets(q)
+            if not results:
+                gr.Warning(f"No Hub datasets found for {q!r}")
+                return gr.update()
+            return gr.update(choices=results, value=results[0])
+
+        search_btn.click(on_search, query, ds_name)
+        query.submit(on_search, query, ds_name)
+
+        def on_load(src, name, split_v, subset_v, path, file, n, progress=gr.Progress()):
+            limit = int(n) or None
+            try:
+                if src == "Hugging Face Hub":
+                    if not name:
+                        return "❌ Choose a dataset first.", gr.update(), ""
+                    progress(0.2, desc=f"Downloading {name} …")
+                    rows = datalib.load_hub_dataset(name, split_v or "train", subset_v or None, limit)
+                    return _ingest(rows, name, is_local=False)
+                target = path if src == "Local file" else (file.name if file else "")
+                if not target:
+                    return "❌ Provide a file first.", gr.update(), ""
+                rows = datalib.load_local_dataset(target, limit)
+                return _ingest(rows, target, is_local=True)
+            except Exception as exc:
+                return f"❌ Failed to load dataset: {exc}", gr.update(), ""
+
+        load_btn.click(on_load, [source, ds_name, split, subset, local_path, upload, max_rows],
+                       [status, preview, detection_panel])

finetuner/ui/tab_export.py

@@ -0,0 +1,62 @@
+"""Export tab: adapters, merged weights, GGUF, and Hugging Face Hub upload."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from ..core import export
+from ..core.state import STATE
+
+
+def _guard():
+    if STATE.model is None:
+        raise gr.Error("No model in memory — load and train one first.")
+
+
+def build(app):
+    with gr.Tab("📦 Export", id="export"):
+        gr.Markdown("### Save or publish the fine-tuned model")
+
+        with gr.Group():
+            gr.Markdown("**LoRA adapters** — small, fast to share")
+            with gr.Row():
+                adapter_path = gr.Textbox(value="lora_model", label="Directory", scale=3)
+                adapter_btn = gr.Button("💾 Save adapters", scale=1)
+
+        with gr.Group():
+            gr.Markdown("**Merged model** — base weights + adapters fused to 16-bit")
+            with gr.Row():
+                merged_path = gr.Textbox(value="merged", label="Directory", scale=3)
+                merged_btn = gr.Button("🔗 Save merged", scale=1)
+
+        with gr.Group():
+            gr.Markdown("**GGUF** — for llama.cpp / Ollama. "
+                        "⚠️ Requires a *non-quantized* base model (mlx-lm limitation).")
+            with gr.Row():
+                gguf_path = gr.Textbox(value="model_gguf", label="Directory", scale=3)
+                gguf_btn = gr.Button("🦙 Export GGUF", scale=1)
+
+        with gr.Group():
+            gr.Markdown("**Hugging Face Hub** — publish the model to your account")
+            with gr.Row():
+                repo_id = gr.Textbox(label="Repo id", placeholder="username/my-finetuned-model", scale=2)
+                hf_token = gr.Textbox(label="HF token (optional if logged in)", type="password", scale=2)
+                push_btn = gr.Button("🤗 Push to Hub", variant="primary", scale=1)
+
+        status = gr.Markdown()
+
+        def run(fn, *args):
+            _guard()
+            try:
+                return f"✅ {fn(*args)}"
+            except Exception as exc:
+                return f"❌ {exc}"
+
+        adapter_btn.click(lambda p: run(export.save_adapters, STATE.model, p),
+                          adapter_path, status)
+        merged_btn.click(lambda p: run(export.save_merged, STATE.model, STATE.tokenizer, p),
+                         merged_path, status)
+        gguf_btn.click(lambda p: run(export.save_gguf, STATE.model, STATE.tokenizer, p),
+                       gguf_path, status)
+        push_btn.click(lambda r, t: run(export.push_to_hub, STATE.model, r, t or None),
+                       [repo_id, hf_token], status)

finetuner/ui/tab_model.py

@@ -0,0 +1,122 @@
+"""Model tab: pick a task, find a model (Hub search or local path), load it, attach LoRA."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from ..core import models
+from ..core.registry import get_task, mlx_available, task_choices
+from ..core.state import STATE
+
+
+def _task_info(task_id: str) -> str:
+    spec = get_task(task_id)
+    lines = [f"**{spec.label}**", "", spec.description, "",
+             f"- Backend: `mlx_tune.{spec.trainer}` + `{spec.config}`",
+             f"- Dataset schema: `{', '.join(spec.dataset_schema)}`"]
+    if spec.notes:
+        lines.append(f"- ⚠️ {spec.notes}")
+    return "\n".join(lines)
+
+
+def build(app):
+    with gr.Tab("🧠 Model", id="model"):
+        gr.Markdown("### 1 · Choose a task and a base model")
+        with gr.Row():
+            with gr.Column(scale=1):
+                task = gr.Dropdown(choices=task_choices(), value="sft", label="Training task",
+                                   info="Every mlx-tune trainer is available here.")
+                task_info = gr.Markdown(_task_info("sft"))
+            with gr.Column(scale=2):
+                source = gr.Radio(["Hugging Face Hub", "Local path"], value="Hugging Face Hub",
+                                  label="Model source")
+                with gr.Group() as hub_group:
+                    with gr.Row():
+                        query = gr.Textbox(label="Search the Hub",
+                                           placeholder="e.g. llama 3.2 instruct 4bit", scale=3)
+                        search_btn = gr.Button("🔍 Search", scale=1)
+                    model_name = gr.Dropdown(label="Model", allow_custom_value=True,
+                                             value=get_task("sft").default_model,
+                                             choices=[get_task("sft").default_model],
+                                             info="Pick a search result or type any repo id.")
+                local_path = gr.Textbox(label="Local model directory", visible=False,
+                                        placeholder="/path/to/converted-mlx-model")
+                with gr.Row():
+                    max_seq = gr.Slider(256, 32768, value=2048, step=256, label="Max sequence length")
+                    four_bit = gr.Checkbox(value=True, label="Load in 4-bit")
+
+        gr.Markdown("### 2 · LoRA adapters")
+        with gr.Row():
+            use_lora = gr.Checkbox(value=True, label="Attach LoRA", scale=1)
+            lora_r = gr.Slider(1, 256, value=16, step=1, label="Rank (r)", scale=2)
+            lora_alpha = gr.Slider(1, 256, value=16, step=1, label="Alpha", scale=2)
+            lora_dropout = gr.Slider(0.0, 0.5, value=0.0, step=0.01, label="Dropout", scale=2)
+        target_modules = gr.CheckboxGroup(
+            choices=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
+            value=["q_proj", "k_proj", "v_proj", "o_proj"],
+            label="Target modules (text models)")
+
+        load_btn = gr.Button("⚡ Load model", variant="primary")
+        status = gr.Markdown()
+
+        # ----- events -------------------------------------------------------
+        def on_task(task_id):
+            spec = get_task(task_id)
+            return (_task_info(task_id),
+                    gr.update(value=spec.default_model, choices=[spec.default_model]),
+                    gr.update(value=list(spec.default_target_modules)))
+
+        task.change(on_task, task, [task_info, model_name, target_modules])
+
+        def on_source(src):
+            hub = src == "Hugging Face Hub"
+            return gr.update(visible=hub), gr.update(visible=not hub)
+
+        source.change(on_source, source, [hub_group, local_path])
+
+        def on_search(q):
+            results = models.search_hub_models(q)
+            if not results:
+                gr.Warning(f"No Hub models found for {q!r}")
+                return gr.update()
+            return gr.update(choices=results, value=results[0])
+
+        search_btn.click(on_search, query, model_name)
+        query.submit(on_search, query, model_name)
+
+        def on_load(task_id, src, name, path, seq, fourbit,
+                    lora, r, alpha, dropout, targets, progress=gr.Progress()):
+            ok, reason = mlx_available()
+            if not ok:
+                return f"❌ {reason}"
+            resolved = name
+            try:
+                if src == "Local path":
+                    resolved = models.validate_local_model(path)
+                progress(0.1, desc=f"Loading {resolved} …")
+                model, tok = models.load_model(task_id, resolved, int(seq), bool(fourbit))
+                if lora and get_task(task_id).peft_supported:
+                    progress(0.7, desc="Attaching LoRA adapters …")
+                    model = models.apply_lora(task_id, model, int(r), int(alpha),
+                                              float(dropout), list(targets))
+                STATE.model, STATE.tokenizer = model, tok
+                STATE.model_name = resolved
+                STATE.model_loaded_for_task = task_id
+                STATE.lora_attached = bool(lora)
+                cfg = STATE.config
+                cfg.task, cfg.model_name = task_id, resolved
+                cfg.max_seq_length, cfg.load_in_4bit = int(seq), bool(fourbit)
+                cfg.use_lora, cfg.lora_r, cfg.lora_alpha = bool(lora), int(r), int(alpha)
+                cfg.lora_dropout, cfg.target_modules = float(dropout), list(targets)
+                return (f"✅ **{resolved}** loaded for **{get_task(task_id).label}**"
+                        + (" with LoRA attached." if lora else "."))
+            except Exception as exc:  # surfaced to the user, not crashed
+                return f"❌ Load failed: {exc}"
+
+        load_btn.click(
+            on_load,
+            [task, source, model_name, local_path, max_seq, four_bit,
+             use_lora, lora_r, lora_alpha, lora_dropout, target_modules],
+            status)
+
+    return {"task": task}

finetuner/ui/tab_monitor.py

@@ -0,0 +1,60 @@
+"""Monitor tab: live logs, loss curve and job control, refreshed by a timer."""
+
+from __future__ import annotations
+
+import pandas as pd
+import gradio as gr
+
+from ..core.jobs import MANAGER
+
+STATUS_ICONS = {"pending": "⏳", "running": "🏃", "finished": "✅",
+                "failed": "❌", "stopped": "⏹"}
+
+
+def _job_choices() -> list[tuple[str, int]]:
+    return [(f"#{j.id} {STATUS_ICONS.get(j.status, '')} {j.name}", j.id)
+            for j in reversed(MANAGER.all())]
+
+
+def _snapshot(job_id):
+    job = MANAGER.get(int(job_id)) if job_id else MANAGER.latest()
+    if job is None:
+        return ("*No jobs yet — start one from the 🚀 Train tab.*", "",
+                pd.DataFrame({"step": [], "loss": []}))
+    header = (f"**Job #{job.id}** · {job.name} · "
+              f"{STATUS_ICONS.get(job.status, '')} **{job.status}** · "
+              f"⏱ {job.elapsed:.0f}s · {len(job.metrics)} loss points")
+    df = pd.DataFrame(job.metrics, columns=["step", "loss"]) if job.metrics \
+        else pd.DataFrame({"step": [], "loss": []})
+    return header, job.log_text(), df
+
+
+def build(app):
+    with gr.Tab("📈 Monitor", id="monitor"):
+        with gr.Row():
+            job_pick = gr.Dropdown(label="Job", choices=_job_choices(), scale=3)
+            refresh_btn = gr.Button("🔄 Refresh list", scale=1)
+            stop_btn = gr.Button("⏹ Stop job", variant="stop", scale=1)
+        header = gr.Markdown("*No jobs yet — start one from the 🚀 Train tab.*")
+        with gr.Row():
+            with gr.Column(scale=1):
+                loss_plot = gr.LinePlot(x="step", y="loss", label="Training loss",
+                                        value=pd.DataFrame({"step": [], "loss": []}))
+            with gr.Column(scale=1):
+                logs = gr.Textbox(label="Live logs", lines=20, max_lines=20,
+                                  autoscroll=True, interactive=False)
+
+        timer = gr.Timer(2.0)
+        timer.tick(_snapshot, job_pick, [header, logs, loss_plot])
+
+        refresh_btn.click(lambda: gr.update(choices=_job_choices()), None, job_pick)
+        job_pick.change(_snapshot, job_pick, [header, logs, loss_plot])
+
+        def on_stop(job_id):
+            job = MANAGER.get(int(job_id)) if job_id else MANAGER.latest()
+            if job is None:
+                return gr.update()
+            MANAGER.stop(job.id)
+            return gr.update(choices=_job_choices())
+
+        stop_btn.click(on_stop, job_pick, job_pick)

finetuner/ui/tab_playground.py

@@ -0,0 +1,56 @@
+"""Playground tab: chat with the currently loaded (and freshly tuned) model."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from ..core.engine import ENGINE
+from ..core.state import STATE
+
+
+def _generate(message: str, history: list[dict], max_tokens: int, temperature: float) -> str:
+    # MLX generation must run on the engine thread (streams are thread-local).
+    return ENGINE.call(_generate_inner, message, history, max_tokens, temperature)
+
+
+def _generate_inner(message: str, history: list[dict], max_tokens: int, temperature: float) -> str:
+    if STATE.model is None or STATE.tokenizer is None:
+        return "⚠️ No model loaded — load one in the 🧠 Model tab first."
+
+    messages = [{"role": h["role"], "content": h["content"]} for h in history]
+    messages.append({"role": "user", "content": message})
+
+    tok = STATE.tokenizer
+    try:
+        prompt = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    except Exception:
+        prompt = "\n".join(m["content"] for m in messages)
+
+    # mlx-tune models are mlx-lm compatible; prefer its generate().
+    try:
+        from mlx_lm import generate as mlx_generate
+        from mlx_lm.sample_utils import make_sampler
+        return mlx_generate(STATE.model, tok, prompt=prompt, max_tokens=int(max_tokens),
+                            sampler=make_sampler(temp=float(temperature)), verbose=False)
+    except Exception:
+        pass
+    try:  # older mlx-lm signature
+        from mlx_lm import generate as mlx_generate
+        return mlx_generate(STATE.model, tok, prompt=prompt,
+                            max_tokens=int(max_tokens), verbose=False)
+    except Exception as exc:
+        return f"⚠️ Generation failed: {exc}"
+
+
+def build(app):
+    with gr.Tab("💬 Playground", id="playground"):
+        gr.Markdown("### Test the loaded model — before and after fine-tuning")
+        with gr.Row():
+            max_tokens = gr.Slider(16, 4096, value=512, step=16, label="Max new tokens")
+            temperature = gr.Slider(0.0, 2.0, value=0.7, step=0.05, label="Temperature")
+        gr.ChatInterface(
+            fn=_generate,
+            additional_inputs=[max_tokens, temperature],
+            examples=[["Merhaba! Kendini tanıtır mısın?"],
+                      ["Explain LoRA fine-tuning in two sentences."]],
+        )

finetuner/ui/tab_train.py

@@ -0,0 +1,140 @@
+"""Train tab: hyperparameters, recipes, the code generator, and the launch button."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from ..core import recipes
+from ..core.codegen import generate_script
+from ..core.detector import normalize
+from ..core.jobs import MANAGER
+from ..core.registry import get_task, mlx_available
+from ..core.state import STATE
+from ..core.training import run_training
+
+
+def _collect(cfg_fields: dict) -> None:
+    cfg = STATE.config
+    cfg.output_dir = cfg_fields["output_dir"]
+    cfg.batch_size = int(cfg_fields["batch_size"])
+    cfg.gradient_accumulation_steps = int(cfg_fields["grad_accum"])
+    cfg.learning_rate = float(cfg_fields["lr"])
+    cfg.max_steps = int(cfg_fields["max_steps"])
+    cfg.num_train_epochs = float(cfg_fields["epochs"]) or None
+    cfg.warmup_steps = int(cfg_fields["warmup"])
+    cfg.gradient_checkpointing = bool(cfg_fields["grad_ckpt"])
+    cfg.seed = int(cfg_fields["seed"])
+    extra = {}
+    if cfg.task in ("dpo", "orpo") and cfg_fields["beta"]:
+        extra["beta"] = float(cfg_fields["beta"])
+    cfg.extra = extra
+
+
+def build(app):
+    with gr.Tab("🚀 Train", id="train"):
+        gr.Markdown("### Hyperparameters")
+        with gr.Row():
+            output_dir = gr.Textbox(value="outputs", label="Output directory")
+            batch_size = gr.Slider(1, 32, value=2, step=1, label="Batch size")
+            grad_accum = gr.Slider(1, 64, value=1, step=1, label="Gradient accumulation")
+        with gr.Row():
+            lr = gr.Number(value=2e-4, label="Learning rate")
+            max_steps = gr.Slider(10, 10000, value=100, step=10, label="Max steps")
+            epochs = gr.Number(value=0, label="Epochs (0 → use max steps)")
+        with gr.Row():
+            warmup = gr.Slider(0, 500, value=5, step=5, label="Warmup steps")
+            seed = gr.Number(value=42, precision=0, label="Seed")
+            grad_ckpt = gr.Checkbox(value=False, label="Gradient checkpointing (saves memory)")
+            beta = gr.Number(value=0.1, label="β (DPO/ORPO only)")
+
+        with gr.Row():
+            start_btn = gr.Button("🏁 Start training", variant="primary", scale=2)
+            gen_btn = gr.Button("🧾 Generate Python script", scale=1)
+        status = gr.Markdown()
+
+        with gr.Accordion("Generated script (standalone mlx-tune code)", open=False):
+            script_out = gr.Code(language="python", label="train.py")
+            gr.Markdown("Copy this script anywhere — it reproduces this run without the GUI.")
+
+        with gr.Accordion("Recipes (save / load runs as YAML)", open=False):
+            with gr.Row():
+                recipe_name = gr.Textbox(label="Recipe name", placeholder="my-sft-run")
+                save_recipe_btn = gr.Button("💾 Save recipe")
+            with gr.Row():
+                recipe_pick = gr.Dropdown(label="Saved recipes", choices=recipes.list_recipes(),
+                                          allow_custom_value=True)
+                load_recipe_btn = gr.Button("📂 Load recipe")
+            recipe_status = gr.Markdown()
+
+        hp_inputs = [output_dir, batch_size, grad_accum, lr, max_steps, epochs,
+                     warmup, seed, grad_ckpt, beta]
+
+        def _fields(*vals) -> dict:
+            keys = ["output_dir", "batch_size", "grad_accum", "lr", "max_steps",
+                    "epochs", "warmup", "seed", "grad_ckpt", "beta"]
+            return dict(zip(keys, vals))
+
+        # ----- start training -------------------------------------------------
+        def on_start(*vals):
+            _collect(_fields(*vals))
+            cfg = STATE.config
+            ok, reason = mlx_available()
+            if not ok:
+                return f"❌ {reason}"
+            if STATE.model is None:
+                return "❌ Load a model first (🧠 Model tab)."
+            if not STATE.raw_rows:
+                return "❌ Load a dataset first (📚 Dataset tab)."
+            if STATE.model_loaded_for_task != cfg.task:
+                cfg.task = STATE.model_loaded_for_task
+            try:
+                dataset = normalize(STATE.raw_rows, STATE.detection, cfg.task, STATE.tokenizer)
+            except Exception as exc:
+                return (f"❌ Dataset incompatible with **{get_task(cfg.task).label}**: {exc}\n\n"
+                        f"Detected format: {STATE.detection.label if STATE.detection else '—'}")
+            job = MANAGER.submit(f"{cfg.task} · {cfg.model_name}", run_training,
+                                 cfg, STATE.model, STATE.tokenizer, dataset)
+            return (f"🏃 **Job #{job.id}** started ({len(dataset)} samples). "
+                    "Follow it in the **📈 Monitor** tab.")
+
+        start_btn.click(on_start, hp_inputs, status)
+
+        # ----- codegen --------------------------------------------------------
+        def on_generate(*vals):
+            _collect(_fields(*vals))
+            cfg = STATE.config
+            if STATE.model_loaded_for_task:
+                cfg.task = STATE.model_loaded_for_task
+            if not cfg.model_name:
+                cfg.model_name = get_task(cfg.task).default_model
+            return generate_script(cfg, STATE.dataset_source, STATE.dataset_is_local)
+
+        gen_btn.click(on_generate, hp_inputs, script_out)
+
+        # ----- recipes ---------------------------------------------------------
+        def on_save_recipe(name, *vals):
+            _collect(_fields(*vals))
+            path = recipes.save_recipe(STATE.config, name, STATE.dataset_source,
+                                       STATE.dataset_is_local)
+            return f"💾 Saved `{path}`", gr.update(choices=recipes.list_recipes())
+
+        save_recipe_btn.click(on_save_recipe, [recipe_name, *hp_inputs],
+                              [recipe_status, recipe_pick])
+
+        def on_load_recipe(path):
+            if not path:
+                return ["❌ Pick a recipe."] + [gr.update()] * len(hp_inputs)
+            try:
+                cfg, src, is_local = recipes.load_recipe(path)
+            except Exception as exc:
+                return [f"❌ {exc}"] + [gr.update()] * len(hp_inputs)
+            STATE.config = cfg
+            STATE.dataset_source, STATE.dataset_is_local = src, is_local
+            return [f"📂 Loaded `{path}` — task **{cfg.task}**, model `{cfg.model_name}`. "
+                    "Reload model/dataset to run it.",
+                    cfg.output_dir, cfg.batch_size, cfg.gradient_accumulation_steps,
+                    cfg.learning_rate, cfg.max_steps, cfg.num_train_epochs or 0,
+                    cfg.warmup_steps, cfg.seed, cfg.gradient_checkpointing,
+                    cfg.extra.get("beta", 0.1)]
+
+        load_recipe_btn.click(on_load_recipe, recipe_pick, [recipe_status, *hp_inputs])

requirements.txt

@@ -0,0 +1,3 @@
+datasets>=3.0
+pandas>=2.0
+pyyaml>=6.0