adds interface and dataset and auto push and demo

interface.py

@@ -0,0 +1,444 @@
+#!/usr/bin/env python3
+"""
+Voxtral ASR Fine-tuning Interface
+
+Features:
+- Collect a personal voice dataset (upload WAV/FLAC + transcripts or record mic audio)
+- Build a JSONL dataset ({audio_path, text}) at 16kHz
+- Fine-tune Voxtral (LoRA or full) with streamed logs
+- Push model to Hugging Face Hub
+- Deploy a Voxtral ASR demo Space
+
+Env tokens (optional):
+- HF_WRITE_TOKEN or HF_TOKEN: write access token
+- HF_READ_TOKEN: optional read token
+- HF_USERNAME: fallback username if not derivable from token
+"""
+
+from __future__ import annotations
+
+import os
+import json
+from pathlib import Path
+from datetime import datetime
+from typing import Any, Dict, Generator, Optional, Tuple
+
+import gradio as gr
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+
+
+def get_python() -> str:
+    import sys
+    return sys.executable or "python"
+
+
+def get_username_from_token(token: str) -> Optional[str]:
+    try:
+        from huggingface_hub import HfApi  # type: ignore
+        api = HfApi(token=token)
+        info = api.whoami()
+        if isinstance(info, dict):
+            return info.get("name") or info.get("username")
+        if isinstance(info, str):
+            return info
+    except Exception:
+        return None
+    return None
+
+
+def run_command_stream(args: list[str], env: Dict[str, str], cwd: Optional[Path] = None) -> Generator[str, None, int]:
+    import subprocess
+    import shlex
+    yield f"$ {' '.join(shlex.quote(a) for a in ([get_python()] + args))}"
+    process = subprocess.Popen(
+        [get_python()] + args,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        env=env,
+        cwd=str(cwd or PROJECT_ROOT),
+        bufsize=1,
+        universal_newlines=True,
+    )
+    assert process.stdout is not None
+    for line in iter(process.stdout.readline, ""):
+        yield line.rstrip()
+    process.stdout.close()
+    code = process.wait()
+    yield f"[exit_code={code}]"
+    return code
+
+
+def detect_nvidia_driver() -> Tuple[bool, str]:
+    """Detect NVIDIA driver/GPU presence with multiple strategies.
+
+    Returns (available, human_message).
+    """
+    # 1) Try torch CUDA
+    try:
+        import torch  # type: ignore
+        if torch.cuda.is_available():
+            try:
+                num = torch.cuda.device_count()
+                names = [torch.cuda.get_device_name(i) for i in range(num)]
+                return True, f"NVIDIA GPU detected: {', '.join(names)}"
+            except Exception:
+                return True, "NVIDIA GPU detected (torch.cuda available)"
+    except Exception:
+        pass
+
+    # 2) Try NVML via pynvml
+    try:
+        import pynvml  # type: ignore
+        try:
+            pynvml.nvmlInit()
+            cnt = pynvml.nvmlDeviceGetCount()
+            names = []
+            for i in range(cnt):
+                h = pynvml.nvmlDeviceGetHandleByIndex(i)
+                names.append(pynvml.nvmlDeviceGetName(h).decode("utf-8", errors="ignore"))
+            drv = pynvml.nvmlSystemGetDriverVersion().decode("utf-8", errors="ignore")
+            pynvml.nvmlShutdown()
+            if cnt > 0:
+                return True, f"NVIDIA driver {drv}; GPUs: {', '.join(names)}"
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+    # 3) Try nvidia-smi
+    try:
+        import subprocess
+        res = subprocess.run(["nvidia-smi", "-L"], capture_output=True, text=True, timeout=3)
+        if res.returncode == 0 and res.stdout.strip():
+            return True, res.stdout.strip().splitlines()[0]
+    except Exception:
+        pass
+
+    return False, "No NVIDIA driver/GPU detected"
+
+
+def duplicate_space_hint() -> str:
+    space_id = os.environ.get("SPACE_ID") or os.environ.get("HF_SPACE_ID")
+    if space_id:
+        space_url = f"https://huggingface.co/spaces/{space_id}"
+        dup_url = f"{space_url}?duplicate=true"
+        return (
+            f"ℹ️ No NVIDIA driver detected. If you're on Hugging Face Spaces, "
+            f"please duplicate this Space to GPU hardware: [Duplicate this Space]({dup_url})."
+        )
+    return (
+        "ℹ️ No NVIDIA driver detected. To enable training, run on a machine with an NVIDIA GPU/driver "
+        "or duplicate this Space on Hugging Face with GPU hardware."
+    )
+
+
+def _write_jsonl(rows: list[dict], path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        for r in rows:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    return path
+
+
+def _save_uploaded_dataset(files: list, transcripts: list[str]) -> str:
+    dataset_dir = PROJECT_ROOT / "datasets" / "voxtral_user"
+    dataset_dir.mkdir(parents=True, exist_ok=True)
+    rows: list[dict] = []
+    for i, fpath in enumerate(files or []):
+        if i >= len(transcripts):
+            break
+        rows.append({"audio_path": fpath, "text": transcripts[i] or ""})
+    jsonl_path = dataset_dir / "data.jsonl"
+    _write_jsonl(rows, jsonl_path)
+    return str(jsonl_path)
+
+
+def _save_recordings(recordings: list[tuple[int, list]], transcripts: list[str]) -> str:
+    import soundfile as sf
+    dataset_dir = PROJECT_ROOT / "datasets" / "voxtral_user"
+    wav_dir = dataset_dir / "wavs"
+    wav_dir.mkdir(parents=True, exist_ok=True)
+    rows: list[dict] = []
+    for i, rec in enumerate(recordings or []):
+        if rec is None:
+            continue
+        if i >= len(transcripts):
+            break
+        sr, data = rec
+        out_path = wav_dir / f"rec_{i:04d}.wav"
+        sf.write(str(out_path), data, sr)
+        rows.append({"audio_path": str(out_path), "text": transcripts[i] or ""})
+    jsonl_path = dataset_dir / "data.jsonl"
+    _write_jsonl(rows, jsonl_path)
+    return str(jsonl_path)
+
+
+def start_voxtral_training(
+    use_lora: bool,
+    base_model: str,
+    repo_short: str,
+    jsonl_path: str,
+    train_count: int,
+    eval_count: int,
+    batch_size: int,
+    grad_accum: int,
+    learning_rate: float,
+    epochs: float,
+    lora_r: int,
+    lora_alpha: int,
+    lora_dropout: float,
+    freeze_audio_tower: bool,
+    push_to_hub: bool,
+    deploy_demo: bool,
+) -> Generator[str, None, None]:
+    env = os.environ.copy()
+    write_token = env.get("HF_WRITE_TOKEN") or env.get("HF_TOKEN")
+    read_token = env.get("HF_READ_TOKEN")
+    username = get_username_from_token(write_token or "") or env.get("HF_USERNAME") or ""
+    output_dir = PROJECT_ROOT / "outputs" / repo_short
+
+    # 1) Train
+    script = PROJECT_ROOT / ("scripts/train_lora.py" if use_lora else "scripts/train.py")
+    args = [str(script)]
+    if jsonl_path:
+        args += ["--dataset-jsonl", jsonl_path]
+    args += [
+        "--model-checkpoint", base_model,
+        "--train-count", str(train_count),
+        "--eval-count", str(eval_count),
+        "--batch-size", str(batch_size),
+        "--grad-accum", str(grad_accum),
+        "--learning-rate", str(learning_rate),
+        "--epochs", str(epochs),
+        "--output-dir", str(output_dir),
+        "--save-steps", "50",
+    ]
+    if use_lora:
+        args += [
+            "--lora-r", str(lora_r),
+            "--lora-alpha", str(lora_alpha),
+            "--lora-dropout", str(lora_dropout),
+        ]
+        if freeze_audio_tower:
+            args += ["--freeze-audio-tower"]
+    for line in run_command_stream(args, env):
+        yield line
+
+    # 2) Push to Hub
+    if push_to_hub:
+        repo_name = f"{username}/{repo_short}" if username else repo_short
+        push_args = [
+            str(PROJECT_ROOT / "scripts/push_to_huggingface.py"),
+            str(output_dir),
+            repo_name,
+        ]
+        for line in run_command_stream(push_args, env):
+            yield line
+
+    # 3) Deploy demo Space
+    if deploy_demo and username:
+        deploy_args = [
+            str(PROJECT_ROOT / "scripts/deploy_demo_space.py"),
+            "--hf-token", write_token or "",
+            "--hf-username", username,
+            "--model-id", f"{username}/{repo_short}",
+            "--demo-type", "voxtral",
+            "--space-name", f"{repo_short}-demo",
+        ]
+        for line in run_command_stream(deploy_args, env):
+            yield line
+
+
+PHRASES = [
+    "The quick brown fox jumps over the lazy dog.",
+    "Please say your full name.",
+    "Today is a good day to learn something new.",
+    "Artificial intelligence helps with many tasks.",
+    "I enjoy reading books and listening to music.",
+    "This is a sample sentence for testing speech.",
+    "Speak clearly and at a normal pace.",
+    "Numbers like one, two, three are easy to say.",
+    "The weather is sunny with a chance of rain.",
+    "Thank you for taking the time to help.",
+]
+
+with gr.Blocks(title="Voxtral ASR Fine-tuning") as demo:
+    has_gpu, gpu_msg = detect_nvidia_driver()
+    if has_gpu:
+        gr.HTML(
+            f"""
+            <div style="background-color: rgba(59, 130, 246, 0.1); border: 1px solid rgba(59, 130, 246, 0.3); border-radius: 8px; padding: 12px; margin-bottom: 16px; text-align: center;">
+                <p style="color: rgb(59, 130, 246); margin: 0; font-size: 14px; font-weight: 600;">
+                    ✅ NVIDIA GPU ready — {gpu_msg}
+                </p>
+                <p style="color: rgb(59, 130, 246); margin: 6px 0 0; font-size: 12px;">
+                    Set HF_WRITE_TOKEN/HF_TOKEN in environment to enable Hub push.
+                </p>
+            </div>
+            """
+        )
+    else:
+        hint_md = duplicate_space_hint()
+        gr.HTML(
+            f"""
+            <div style="background-color: rgba(245, 158, 11, 0.1); border: 1px solid rgba(245, 158, 11, 0.3); border-radius: 8px; padding: 12px; margin-bottom: 16px; text-align: center;">
+                <p style="color: rgb(234, 88, 12); margin: 0; font-size: 14px; font-weight: 600;">
+                    ⚠️ No NVIDIA GPU/driver detected — training requires a GPU runtime
+                </p>
+                <p style="color: rgb(234, 88, 12); margin: 6px 0 0; font-size: 12px;">
+                    {hint_md}
+                </p>
+            </div>
+            """
+        )
+
+    gr.Markdown("""
+    # 🎙️ Voxtral ASR Fine-tuning
+    Read the phrases below and record them. Then start fine-tuning.
+    """)
+
+    jsonl_out = gr.Textbox(label="Dataset JSONL path", interactive=False, visible=True)
+
+    # Recording grid with dynamic text readouts
+    phrase_texts_state = gr.State(PHRASES)
+    phrase_markdowns: list[gr.Markdown] = []
+    rec_components = []
+    with gr.Column():
+        for idx, phrase in enumerate(PHRASES):
+            md = gr.Markdown(f"**{idx+1}. {phrase}**")
+            phrase_markdowns.append(md)
+            comp = gr.Audio(sources="microphone", type="numpy", label=f"Recording {idx+1}")
+            rec_components.append(comp)
+
+    # Advanced options accordion
+    with gr.Accordion("Advanced options", open=False):
+        base_model = gr.Textbox(value="mistralai/Voxtral-Mini-3B-2507", label="Base Voxtral model")
+        use_lora = gr.Checkbox(value=True, label="Use LoRA (parameter-efficient)")
+        with gr.Row():
+            batch_size = gr.Number(value=2, precision=0, label="Batch size")
+            grad_accum = gr.Number(value=4, precision=0, label="Grad accum")
+        with gr.Row():
+            learning_rate = gr.Number(value=5e-5, precision=6, label="Learning rate")
+            epochs = gr.Number(value=3.0, precision=2, label="Epochs")
+        with gr.Accordion("LoRA settings", open=False):
+            lora_r = gr.Number(value=8, precision=0, label="LoRA r")
+            lora_alpha = gr.Number(value=32, precision=0, label="LoRA alpha")
+            lora_dropout = gr.Number(value=0.0, precision=3, label="LoRA dropout")
+            freeze_audio_tower = gr.Checkbox(value=True, label="Freeze audio tower")
+        with gr.Row():
+            train_count = gr.Number(value=100, precision=0, label="Train samples")
+            eval_count = gr.Number(value=50, precision=0, label="Eval samples")
+        repo_short = gr.Textbox(value=f"voxtral-finetune-{datetime.now().strftime('%Y%m%d_%H%M%S')}", label="Model repo (short)")
+        push_to_hub = gr.Checkbox(value=True, label="Push to HF Hub after training")
+        deploy_demo = gr.Checkbox(value=True, label="Deploy demo Space after push")
+
+        gr.Markdown("### Upload audio + transcripts (optional)")
+        upload_audio = gr.File(file_count="multiple", type="filepath", label="Upload WAV/FLAC files (optional)")
+        transcripts_box = gr.Textbox(lines=6, label="Transcripts (one per line, aligned with files)")
+        save_upload_btn = gr.Button("Save uploaded dataset")
+
+        def _collect_upload(files, txt):
+            lines = [s.strip() for s in (txt or "").splitlines() if s.strip()]
+            return _save_uploaded_dataset(files or [], lines)
+
+        save_upload_btn.click(_collect_upload, [upload_audio, transcripts_box], [jsonl_out])
+
+    # Save recordings button
+    save_rec_btn = gr.Button("Save recordings as dataset")
+
+    def _collect_preloaded_recs(*recs_and_texts):
+        import soundfile as sf
+        dataset_dir = PROJECT_ROOT / "datasets" / "voxtral_user"
+        wav_dir = dataset_dir / "wavs"
+        wav_dir.mkdir(parents=True, exist_ok=True)
+        rows: list[dict] = []
+        if not recs_and_texts:
+            jsonl_path = dataset_dir / "data.jsonl"
+            _write_jsonl(rows, jsonl_path)
+            return str(jsonl_path)
+        texts = recs_and_texts[-1]
+        recs = recs_and_texts[:-1]
+        for i, rec in enumerate(recs):
+            if rec is None:
+                continue
+            sr, data = rec
+            out_path = wav_dir / f"rec_{i:04d}.wav"
+            sf.write(str(out_path), data, sr)
+            label_text = (texts[i] if isinstance(texts, list) and i < len(texts) else (PHRASES[i] if i < len(PHRASES) else ""))
+            rows.append({"audio_path": str(out_path), "text": label_text})
+        jsonl_path = dataset_dir / "data.jsonl"
+        _write_jsonl(rows, jsonl_path)
+        return str(jsonl_path)
+
+    save_rec_btn.click(_collect_preloaded_recs, rec_components + [phrase_texts_state], [jsonl_out])
+
+    # Quick sample from VoxPopuli (few random rows)
+    with gr.Row():
+        vp_lang = gr.Dropdown(choices=["en", "de", "fr", "es", "it", "pl", "ro", "hu", "cs", "nl", "fi", "hr", "sk", "sl", "et", "lt"], value="en", label="VoxPopuli language")
+        vp_samples = gr.Number(value=20, precision=0, label="Num samples")
+        vp_split = gr.Dropdown(choices=["train", "validation", "test"], value="train", label="Split")
+        vp_btn = gr.Button("Use VoxPopuli sample")
+
+        def _collect_voxpopuli(lang_code: str, num_samples: int, split: str):
+            import sys
+            # Workaround for dill on Python 3.13 expecting __main__ during import
+            if "__main__" not in sys.modules:
+                sys.modules["__main__"] = sys.modules[__name__]
+            from datasets import load_dataset, Audio  # type: ignore
+            import random
+            ds = load_dataset("facebook/voxpopuli", lang_code, split=split)
+            ds = ds.cast_column("audio", Audio(sampling_rate=16000))
+            # shuffle and select
+            total = len(ds)
+            k = max(1, min(int(num_samples or 1), total))
+            ds = ds.shuffle(seed=random.randint(1, 10_000))
+            ds_sel = ds.select(range(k))
+
+            dataset_dir = PROJECT_ROOT / "datasets" / "voxtral_user"
+            rows: list[dict] = []
+            texts: list[str] = []
+            for ex in ds_sel:
+                audio = ex.get("audio") or {}
+                path = audio.get("path")
+                text = ex.get("normalized_text") or ex.get("raw_text") or ""
+                if path and text is not None:
+                    rows.append({"audio_path": path, "text": text})
+                    texts.append(str(text))
+            jsonl_path = dataset_dir / "data.jsonl"
+            _write_jsonl(rows, jsonl_path)
+            # Build markdown content updates for on-screen prompts
+            md_updates = []
+            for i in range(len(phrase_markdowns)):
+                t = texts[i] if i < len(texts) else ""
+                md_updates.append(f"**{i+1}. {t}**")
+            return (str(jsonl_path), texts, *md_updates)
+
+        vp_btn.click(
+            _collect_voxpopuli,
+            [vp_lang, vp_samples, vp_split],
+            [jsonl_out, phrase_texts_state] + phrase_markdowns,
+        )
+
+    start_btn = gr.Button("Start Fine-tuning")
+    logs_box = gr.Textbox(label="Logs", lines=20)
+
+    start_btn.click(
+        start_voxtral_training,
+        inputs=[
+            use_lora, base_model, repo_short, jsonl_out, train_count, eval_count,
+            batch_size, grad_accum, learning_rate, epochs,
+            lora_r, lora_alpha, lora_dropout, freeze_audio_tower,
+            push_to_hub, deploy_demo,
+        ],
+        outputs=[logs_box],
+    )
+
+
+if __name__ == "__main__":
+    server_port = int(os.environ.get("INTERFACE_PORT", "7860"))
+    server_name = os.environ.get("INTERFACE_HOST", "0.0.0.0")
+    demo.queue().launch(server_name=server_name, server_port=server_port, mcp_server=True)
+
+

scripts/deploy_demo_space.py

@@ -0,0 +1,952 @@
+#!/usr/bin/env python3
+"""
+Demo Space Deployment Script
+Deploys a Gradio demo space to Hugging Face Spaces for testing the fine-tuned model.
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+import subprocess
+import requests
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Optional, Dict, Any
+import time
+
+# Import Hugging Face Hub API
+try:
+    from huggingface_hub import HfApi, create_repo, upload_file
+    HF_HUB_AVAILABLE = True
+except ImportError:
+    HF_HUB_AVAILABLE = False
+    print("Warning: huggingface_hub not available. Install with: pip install huggingface_hub")
+
+# Add src to path for imports
+sys.path.append(str(Path(__file__).parent.parent / "src"))
+
+from config import SmolLM3Config
+
+# Setup logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class DemoSpaceDeployer:
+    """Deploy demo space to Hugging Face Spaces"""
+    
+    def __init__(
+        self,
+        hf_token: str,
+        # Token used for API actions that create/update the Space (write perms)
+        hf_username: str,
+        model_id: str,
+        subfolder: str = "int4",
+        space_name: Optional[str] = None,
+        demo_type: Optional[str] = None,
+        config_file: Optional[str] = None,
+        # Optional token used as the Space's HF_TOKEN secret (read-only recommended)
+        space_secret_token: Optional[str] = None,
+        # Examples configuration
+        examples_type: Optional[str] = None,
+        disable_examples: Optional[bool] = None,
+        examples_json: Optional[str] = None,
+        # Branding overrides
+        brand_owner_name: Optional[str] = None,
+        brand_team_name: Optional[str] = None,
+        brand_discord_url: Optional[str] = None,
+        brand_hf_org: Optional[str] = None,
+        brand_hf_label: Optional[str] = None,
+        brand_hf_url: Optional[str] = None,
+        brand_gh_org: Optional[str] = None,
+        brand_gh_label: Optional[str] = None,
+        brand_gh_url: Optional[str] = None,
+        brand_project_name: Optional[str] = None,
+        brand_project_url: Optional[str] = None,
+    ):
+        self.hf_token = hf_token
+        # The token we will store in the Space secrets. Defaults to hf_token if not provided
+        self.space_secret_token = space_secret_token or hf_token
+        self.hf_username = hf_username
+        # Allow passing just a repo name without username and auto-prefix
+        self.model_id = model_id if "/" in model_id else f"{hf_username}/{model_id}"
+        self.subfolder = subfolder
+        self.space_name = space_name or f"{self.model_id.split('/')[-1]}-demo"
+        self.space_id = f"{hf_username}/{self.space_name}"
+        self.space_url = f"https://huggingface.co/spaces/{self.space_id}"
+        self.config_file = config_file
+
+        # Config-derived context
+        self.system_message: Optional[str] = None
+        self.developer_message: Optional[str] = None
+        self.model_identity: Optional[str] = None
+        self.reasoning_effort: Optional[str] = None
+        # Examples context
+        self.examples_type: Optional[str] = (examples_type or None)
+        self.disable_examples: Optional[bool] = (disable_examples if disable_examples is not None else None)
+        self.examples_json: Optional[str] = (examples_json or None)
+        
+        # Determine demo type from model_id if not provided
+        if demo_type is None:
+            demo_type = self._detect_demo_type(model_id)
+        
+        # Template paths based on model type
+        self.demo_type = demo_type
+        self.template_dir = Path(__file__).parent.parent / "templates" / "spaces" / f"demo_{demo_type}"
+        self.workspace_dir = Path.cwd()
+        
+        # Initialize HF API
+        if HF_HUB_AVAILABLE:
+            self.api = HfApi(token=self.hf_token)
+        else:
+            self.api = None
+            logger.warning("huggingface_hub not available, using CLI fallback")
+
+        # Load optional config-specified messages
+        try:
+            self._load_config_messages()
+        except Exception as e:
+            logger.warning(f"Could not load config messages: {e}")
+
+        # Branding defaults (can be overridden via CLI)
+        self.brand_owner_name = brand_owner_name or self.hf_username or "Tonic"
+        self.brand_team_name = brand_team_name or f"Team{self.brand_owner_name}"
+        self.brand_discord_url = brand_discord_url or "https://discord.gg/qdfnvSPcqP"
+        # HF org/link
+        _default_hf_org = brand_hf_org or self.hf_username or "MultiTransformer"
+        self.brand_hf_org = _default_hf_org
+        self.brand_hf_label = brand_hf_label or self.brand_hf_org
+        self.brand_hf_url = brand_hf_url or f"https://huggingface.co/{self.brand_hf_org}"
+        # GitHub org/link
+        _default_gh_org = brand_gh_org or self.hf_username or "tonic-ai"
+        self.brand_gh_org = _default_gh_org
+        self.brand_gh_label = brand_gh_label or self.brand_gh_org
+        self.brand_gh_url = brand_gh_url or f"https://github.com/{self.brand_gh_org}"
+        # Project link
+        self.brand_project_name = brand_project_name or "MultiTonic"
+        self.brand_project_url = brand_project_url or "https://github.com/MultiTonic"
+
+    def _load_config_messages(self) -> None:
+        """Load system/developer/model_identity from a training config file if provided."""
+        if not self.config_file:
+            return
+        cfg_path = Path(self.config_file)
+        if not cfg_path.exists():
+            logger.warning(f"Config file not found: {cfg_path}")
+            return
+
+        # Ensure project root and config dir are importable for relative imports inside config
+        project_root = Path(__file__).parent.parent
+        if str(project_root) not in sys.path:
+            sys.path.insert(0, str(project_root))
+        cfg_dir = project_root / "config"
+        if str(cfg_dir) not in sys.path:
+            sys.path.insert(0, str(cfg_dir))
+
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("config_module", str(cfg_path))
+        if not spec or not spec.loader:
+            return
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore
+        cfg = getattr(module, "config", None)
+        if cfg is None:
+            return
+        self.system_message = getattr(cfg, "system_message", None)
+        self.developer_message = getattr(cfg, "developer_message", None)
+        chat_kwargs = getattr(cfg, "chat_template_kwargs", None)
+        if isinstance(chat_kwargs, dict):
+            self.model_identity = chat_kwargs.get("model_identity")
+            self.reasoning_effort = chat_kwargs.get("reasoning_effort")
+    
+    def _detect_demo_type(self, model_id: str) -> str:
+        """Detect the appropriate demo type based on model ID"""
+        model_id_lower = model_id.lower()
+        
+        # Voxtral ASR models
+        if "voxtral" in model_id_lower:
+            logger.info(f"Detected Voxtral model, using demo_voxtral template")
+            return "voxtral"
+        
+        # Check for GPT-OSS models
+        if "gpt-oss" in model_id_lower or "gpt_oss" in model_id_lower:
+            logger.info(f"Detected GPT-OSS model, using demo_gpt template")
+            return "gpt"
+        
+        # Check for SmolLM models (default)
+        elif "smollm" in model_id_lower or "smol" in model_id_lower:
+            logger.info(f"Detected SmolLM model, using demo_smol template")
+            return "smol"
+        
+        # Default to SmolLM for unknown models
+        else:
+            logger.info(f"Unknown model type, defaulting to demo_smol template")
+            return "smol"
+    
+    def _generate_env_setup(self) -> str:
+        """Generate environment variable setup based on demo type and model"""
+        if self.demo_type == "gpt":
+            # For GPT-OSS models, we need more sophisticated environment setup
+            model_name = self.model_id.split("/")[-1] if "/" in self.model_id else self.model_id
+            import json as _json
+            env_setup = f"""
+# Environment variables for GPT-OSS model configuration
+import os
+os.environ['HF_MODEL_ID'] = {_json.dumps(self.model_id)}
+os.environ['LORA_MODEL_ID'] = {_json.dumps(self.model_id)}
+os.environ['BASE_MODEL_ID'] = 'openai/gpt-oss-20b'
+os.environ['MODEL_SUBFOLDER'] = {_json.dumps(self.subfolder if self.subfolder else "")}
+os.environ['MODEL_NAME'] = {_json.dumps(model_name)}
+os.environ['MODEL_IDENTITY'] = {_json.dumps(self.model_identity or "")}
+os.environ['SYSTEM_MESSAGE'] = {_json.dumps(self.system_message or (self.model_identity or ""))}
+os.environ['DEVELOPER_MESSAGE'] = {_json.dumps(self.developer_message or "")}
+os.environ['REASONING_EFFORT'] = {_json.dumps((self.reasoning_effort or "medium"))}
+{"os.environ['EXAMPLES_TYPE'] = " + _json.dumps(self.examples_type) + "\n" if self.examples_type else ''}
+{"os.environ['DISABLE_EXAMPLES'] = 'true'\n" if self.disable_examples else ("os.environ['DISABLE_EXAMPLES'] = 'false'\n" if self.disable_examples is not None else '')}
+{"os.environ['EXAMPLES_JSON'] = " + _json.dumps(self.examples_json) + "\n" if self.examples_json else ''}
+
+# Branding/owner variables
+os.environ['HF_USERNAME'] = {_json.dumps(self.hf_username)}
+os.environ['BRAND_OWNER_NAME'] = {_json.dumps(self.brand_owner_name)}
+os.environ['BRAND_TEAM_NAME'] = {_json.dumps(self.brand_team_name)}
+os.environ['BRAND_DISCORD_URL'] = {_json.dumps(self.brand_discord_url)}
+os.environ['BRAND_HF_ORG'] = {_json.dumps(self.brand_hf_org)}
+os.environ['BRAND_HF_LABEL'] = {_json.dumps(self.brand_hf_label)}
+os.environ['BRAND_HF_URL'] = {_json.dumps(self.brand_hf_url)}
+os.environ['BRAND_GH_ORG'] = {_json.dumps(self.brand_gh_org)}
+os.environ['BRAND_GH_LABEL'] = {_json.dumps(self.brand_gh_label)}
+os.environ['BRAND_GH_URL'] = {_json.dumps(self.brand_gh_url)}
+os.environ['BRAND_PROJECT_NAME'] = {_json.dumps(self.brand_project_name)}
+os.environ['BRAND_PROJECT_URL'] = {_json.dumps(self.brand_project_url)}
+
+"""
+        elif self.demo_type == "voxtral":
+            import json as _json
+            env_setup = f"""
+# Environment variables for Voxtral ASR demo
+import os
+os.environ['HF_MODEL_ID'] = {_json.dumps(self.model_id)}
+os.environ['MODEL_NAME'] = {_json.dumps(self.model_id.split('/')[-1])}
+os.environ['HF_USERNAME'] = {_json.dumps(self.hf_username)}
+"""
+        else:
+            # For SmolLM models, use simpler setup
+            import json as _json
+            env_setup = f"""
+# Environment variables for model configuration
+import os
+os.environ['HF_MODEL_ID'] = {_json.dumps(self.model_id)}
+os.environ['MODEL_SUBFOLDER'] = {_json.dumps(self.subfolder if self.subfolder else "")}
+os.environ['MODEL_NAME'] = {_json.dumps(self.model_id.split("/")[-1])}
+os.environ['MODEL_IDENTITY'] = {_json.dumps(self.model_identity or "")}
+os.environ['SYSTEM_MESSAGE'] = {_json.dumps(self.system_message or (self.model_identity or ""))}
+os.environ['DEVELOPER_MESSAGE'] = {_json.dumps(self.developer_message or "")}
+os.environ['REASONING_EFFORT'] = {_json.dumps((self.reasoning_effort or "medium"))}
+{"os.environ['EXAMPLES_TYPE'] = " + _json.dumps(self.examples_type) + "\n" if self.examples_type else ''}
+{"os.environ['DISABLE_EXAMPLES'] = 'true'\n" if self.disable_examples else ("os.environ['DISABLE_EXAMPLES'] = 'false'\n" if self.disable_examples is not None else '')}
+{"os.environ['EXAMPLES_JSON'] = " + _json.dumps(self.examples_json) + "\n" if self.examples_json else ''}
+
+# Branding/owner variables
+os.environ['HF_USERNAME'] = {_json.dumps(self.hf_username)}
+os.environ['BRAND_OWNER_NAME'] = {_json.dumps(self.brand_owner_name)}
+os.environ['BRAND_TEAM_NAME'] = {_json.dumps(self.brand_team_name)}
+os.environ['BRAND_DISCORD_URL'] = {_json.dumps(self.brand_discord_url)}
+os.environ['BRAND_HF_ORG'] = {_json.dumps(self.brand_hf_org)}
+os.environ['BRAND_HF_LABEL'] = {_json.dumps(self.brand_hf_label)}
+os.environ['BRAND_HF_URL'] = {_json.dumps(self.brand_hf_url)}
+os.environ['BRAND_GH_ORG'] = {_json.dumps(self.brand_gh_org)}
+os.environ['BRAND_GH_LABEL'] = {_json.dumps(self.brand_gh_label)}
+os.environ['BRAND_GH_URL'] = {_json.dumps(self.brand_gh_url)}
+os.environ['BRAND_PROJECT_NAME'] = {_json.dumps(self.brand_project_name)}
+os.environ['BRAND_PROJECT_URL'] = {_json.dumps(self.brand_project_url)}
+
+"""
+        return env_setup
+    
+    def _set_model_variables(self):
+        """Set model-specific environment variables in the space"""
+        try:
+            # Common variables for all models
+            self.api.add_space_variable(
+                repo_id=self.space_id,
+                key="HF_MODEL_ID",
+                value=self.model_id,
+                description="Model ID for the demo"
+            )
+            logger.info(f"✅ Successfully set HF_MODEL_ID variable: {self.model_id}")
+            
+            if self.subfolder and self.subfolder.strip():
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="MODEL_SUBFOLDER",
+                    value=self.subfolder,
+                    description="Model subfolder for the demo"
+                )
+                logger.info(f"✅ Successfully set MODEL_SUBFOLDER variable: {self.subfolder}")
+            else:
+                logger.info("ℹ️ No subfolder specified, using main model")
+            
+            # GPT-OSS specific variables
+            if self.demo_type == "gpt":
+                model_name = self.model_id.split("/")[-1] if "/" in self.model_id else self.model_id
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="LORA_MODEL_ID",
+                    value=self.model_id,
+                    description="LoRA/Fine-tuned model ID"
+                )
+                logger.info(f"✅ Successfully set LORA_MODEL_ID variable: {self.model_id}")
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="BASE_MODEL_ID",
+                    value="openai/gpt-oss-20b",
+                    description="Base model ID for GPT-OSS"
+                )
+                logger.info("✅ Successfully set BASE_MODEL_ID variable: openai/gpt-oss-20b")
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="MODEL_NAME",
+                    value=model_name,
+                    description="Display name for the model"
+                )
+                logger.info(f"✅ Successfully set MODEL_NAME variable: {model_name}")
+
+            # Voxtral-specific variables
+            elif self.demo_type == "voxtral":
+                # HF_MODEL_ID was already set above; set a readable MODEL_NAME
+                vox_model_name = self.model_id.split("/")[-1] if "/" in self.model_id else self.model_id
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="MODEL_NAME",
+                    value=vox_model_name,
+                    description="Display name for the Voxtral model"
+                )
+                logger.info(f"✅ Set Voxtral MODEL_NAME variable: {vox_model_name}")
+
+            # Optional context variables
+            if self.model_identity:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="MODEL_IDENTITY",
+                    value=self.model_identity,
+                    description="Default model identity/system persona"
+                )
+                logger.info("✅ Set MODEL_IDENTITY variable")
+            if self.system_message or self.model_identity:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="SYSTEM_MESSAGE",
+                    value=self.system_message or self.model_identity or "",
+                    description="Default system message"
+                )
+                logger.info("✅ Set SYSTEM_MESSAGE variable")
+            if self.developer_message:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="DEVELOPER_MESSAGE",
+                    value=self.developer_message,
+                    description="Default developer message"
+                )
+                logger.info("✅ Set DEVELOPER_MESSAGE variable")
+            if self.reasoning_effort:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="REASONING_EFFORT",
+                    value=self.reasoning_effort,
+                    description="Default reasoning effort (low|medium|high)"
+                )
+                logger.info("✅ Set REASONING_EFFORT variable")
+
+            # Branding variables
+            branding_vars = {
+                "HF_USERNAME": self.hf_username,
+                "BRAND_OWNER_NAME": self.brand_owner_name,
+                "BRAND_TEAM_NAME": self.brand_team_name,
+                "BRAND_DISCORD_URL": self.brand_discord_url,
+                "BRAND_HF_ORG": self.brand_hf_org,
+                "BRAND_HF_LABEL": self.brand_hf_label,
+                "BRAND_HF_URL": self.brand_hf_url,
+                "BRAND_GH_ORG": self.brand_gh_org,
+                "BRAND_GH_LABEL": self.brand_gh_label,
+                "BRAND_GH_URL": self.brand_gh_url,
+                "BRAND_PROJECT_NAME": self.brand_project_name,
+                "BRAND_PROJECT_URL": self.brand_project_url,
+            }
+            for key, value in branding_vars.items():
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key=key,
+                    value=value,
+                    description=f"Branding: {key}"
+                )
+            logger.info("✅ Set branding variables")
+
+            # Examples variables
+            if self.examples_type:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="EXAMPLES_TYPE",
+                    value=self.examples_type,
+                    description="Examples pack type (e.g., general|medical)"
+                )
+                logger.info(f"✅ Set EXAMPLES_TYPE={self.examples_type}")
+            if self.disable_examples is not None:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="DISABLE_EXAMPLES",
+                    value=("true" if self.disable_examples else "false"),
+                    description="Disable built-in examples"
+                )
+                logger.info(f"✅ Set DISABLE_EXAMPLES={self.disable_examples}")
+            if self.examples_json:
+                self.api.add_space_variable(
+                    repo_id=self.space_id,
+                    key="EXAMPLES_JSON",
+                    value=self.examples_json,
+                    description="Custom examples JSON override"
+                )
+                logger.info("✅ Set EXAMPLES_JSON override")
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to set model variables: {e}")
+    
+    def validate_model_exists(self) -> bool:
+        """Validate that the model exists on Hugging Face Hub"""
+        try:
+            logger.info(f"Validating model: {self.model_id}")
+            
+            if HF_HUB_AVAILABLE:
+                # Use HF Hub API
+                try:
+                    model_info = self.api.model_info(self.model_id)
+                    logger.info(f"✅ Model {self.model_id} exists and is accessible")
+                    return True
+                except Exception as e:
+                    logger.error(f"❌ Model {self.model_id} not found via API: {e}")
+                    return False
+            else:
+                # Fallback to requests
+                url = f"https://huggingface.co/api/models/{self.model_id}"
+                headers = {"Authorization": f"Bearer {self.hf_token}"}
+                response = requests.get(url, headers=headers, timeout=30)
+                
+                if response.status_code == 200:
+                    logger.info(f"✅ Model {self.model_id} exists and is accessible")
+                    return True
+                else:
+                    logger.error(f"❌ Model {self.model_id} not found or not accessible")
+                    return False
+                
+        except Exception as e:
+            logger.error(f"❌ Error validating model: {e}")
+            return False
+    
+    def create_space_repository(self) -> bool:
+        """Create the space repository on Hugging Face Hub"""
+        try:
+            logger.info(f"Creating Space: {self.space_name}")
+            
+            if not HF_HUB_AVAILABLE:
+                logger.warning("huggingface_hub not available, falling back to CLI")
+                return self._create_space_cli()
+            
+            # Use the latest HF Hub API to create space
+            try:
+                # Create the space using the API
+                create_repo(
+                    repo_id=self.space_id,
+                    token=self.hf_token,
+                    repo_type="space",
+                    exist_ok=True,
+                    private=False,  # Spaces are typically public
+                    space_sdk="gradio",  # Specify Gradio SDK
+                    space_hardware="cpu-basic"  # Use basic CPU
+                )
+                
+                logger.info(f"✅ Space created successfully: {self.space_url}")
+                return True
+                
+            except Exception as api_error:
+                logger.error(f"API creation failed: {api_error}")
+                logger.info("Falling back to CLI method...")
+                return self._create_space_cli()
+                
+        except Exception as e:
+            logger.error(f"❌ Error creating space: {e}")
+            return False
+    
+    def _create_space_cli(self) -> bool:
+        """Fallback method using CLI commands"""
+        try:
+            logger.info("Using CLI fallback method...")
+            
+            # Set HF token for CLI
+            os.environ['HF_TOKEN'] = self.hf_token
+            
+            # Create space using Hugging Face CLI
+            cmd = [
+                "hf", "repo", "create",
+                self.space_id,
+                "--type", "space"
+            ]
+            
+            logger.info(f"Running command: {' '.join(cmd)}")
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            
+            if result.returncode != 0:
+                logger.warning(f"First attempt failed: {result.stderr}")
+                # Try alternative approach without space-specific flags
+                logger.info("Retrying with basic space creation...")
+                cmd = [
+                    "hf", "repo", "create",
+                    self.space_id
+                ]
+                result = subprocess.run(cmd, capture_output=True, text=True)
+            
+            if result.returncode == 0:
+                logger.info(f"✅ Space created successfully: {self.space_url}")
+                return True
+            else:
+                logger.error(f"❌ Failed to create space: {result.stderr}")
+                return False
+                
+        except Exception as e:
+            logger.error(f"❌ Error creating space with CLI: {e}")
+            return False
+    
+    def prepare_space_files(self) -> str:
+        """Prepare all necessary files for the Space in a temporary directory"""
+        try:
+            logger.info("Preparing Space files...")
+            
+            # Create temporary directory
+            temp_dir = tempfile.mkdtemp()
+            logger.info(f"Created temporary directory: {temp_dir}")
+            
+            # Copy template files
+            copied_files = []
+            for file_path in self.template_dir.iterdir():
+                if file_path.is_file():
+                    dest_path = Path(temp_dir) / file_path.name
+                    shutil.copy2(file_path, dest_path)
+                    copied_files.append(file_path.name)
+                    logger.info(f"✅ Copied {file_path.name} to temp directory")
+            
+            # Update app.py with environment variables
+            app_file = Path(temp_dir) / "app.py"
+            if app_file.exists():
+                with open(app_file, 'r', encoding='utf-8') as f:
+                    content = f.read()
+                
+                # Add environment variable setup at the top
+                env_setup = self._generate_env_setup()
+                
+                # Insert after imports
+                lines = content.split('\n')
+                import_end = 0
+                for i, line in enumerate(lines):
+                    if line.startswith('import ') or line.startswith('from '):
+                        import_end = i + 1
+                    elif line.strip() == '' and import_end > 0:
+                        break
+                
+                lines.insert(import_end, env_setup)
+                content = '\n'.join(lines)
+                
+                with open(app_file, 'w', encoding='utf-8') as f:
+                    f.write(content)
+                
+                logger.info("✅ Updated app.py with model configuration")
+            
+            # YAML front matter required by Hugging Face Spaces
+            yaml_front_matter = (
+                f"---\n"
+                f"title: {'GPT-OSS Demo' if self.demo_type == 'gpt' else 'SmolLM3 Demo'}\n"
+                f"emoji: {'🌟' if self.demo_type == 'gpt' else '💃🏻'}\n"
+                f"colorFrom: {'blue' if self.demo_type == 'gpt' else 'green'}\n"
+                f"colorTo: {'pink' if self.demo_type == 'gpt' else 'purple'}\n"
+                f"sdk: gradio\n"
+                f"sdk_version: 5.40.0\n"
+                f"app_file: app.py\n"
+                f"pinned: false\n"
+                f"short_description: Interactive demo for {self.model_id}\n"
+                + ("license: mit\n" if self.demo_type != 'gpt' else "") +
+                f"---\n\n"
+            )
+
+            # Create README.md for the space (include configuration details)
+            readme_content = (
+                yaml_front_matter
+                + f"# Demo: {self.model_id}\n\n"
+                + f"This is an interactive demo for the fine-tuned model {self.model_id}.\n\n"
+                + "## Features\n"
+                  "- Interactive chat interface\n"
+                  "- Customizable system & developer prompts\n"
+                  "- Advanced generation parameters\n"
+                  "- Thinking mode support\n\n"
+                + "## Model Information\n"
+                  f"- **Model ID**: {self.model_id}\n"
+                  f"- **Subfolder**: {self.subfolder if self.subfolder and self.subfolder.strip() else 'main'}\n"
+                  f"- **Deployed by**: {self.hf_username}\n"
+                  + ("- **Base Model**: openai/gpt-oss-20b\n" if self.demo_type == 'gpt' else "")
+                  + "\n"
+                + "## Configuration\n"
+                  "- **Model Identity**:\n\n"
+                  f"```\n{self.model_identity or 'Not set'}\n```\n\n"
+                  "- **System Message** (default):\n\n"
+                  f"```\n{(self.system_message or self.model_identity) or 'Not set'}\n```\n\n"
+                  "- **Developer Message** (default):\n\n"
+                  f"```\n{self.developer_message or 'Not set'}\n```\n\n"
+                  "These defaults come from the selected training configuration and can be adjusted in the UI when you run the demo.\n\n"
+                + "## Usage\n"
+                  "Simply start chatting with the model using the interface below!\n\n"
+                + "---\n"
+                  "*This demo was automatically deployed by the SmolFactory Fine-tuning Pipeline*\n"
+            )
+            
+            with open(Path(temp_dir) / "README.md", 'w', encoding='utf-8') as f:
+                f.write(readme_content)
+            
+            logger.info(f"✅ Prepared {len(copied_files)} files in temporary directory")
+            return temp_dir
+            
+        except Exception as e:
+            logger.error(f"❌ Error preparing files: {e}")
+            return None
+    
+    def upload_files_to_space(self, temp_dir: str) -> bool:
+        """Upload files to the Space using HF Hub API directly"""
+        try:
+            logger.info("Uploading files to Space using HF Hub API...")
+            
+            if not HF_HUB_AVAILABLE:
+                logger.error("❌ huggingface_hub not available for file upload")
+                return self._upload_files_cli(temp_dir)
+            
+            # Upload each file using the HF Hub API
+            temp_path = Path(temp_dir)
+            uploaded_files = []
+            
+            for file_path in temp_path.iterdir():
+                if file_path.is_file():
+                    try:
+                        # Upload file to the space
+                        upload_file(
+                            path_or_fileobj=str(file_path),
+                            path_in_repo=file_path.name,
+                            repo_id=self.space_id,
+                            repo_type="space",
+                            token=self.hf_token
+                        )
+                        uploaded_files.append(file_path.name)
+                        logger.info(f"✅ Uploaded {file_path.name}")
+                    except Exception as e:
+                        logger.error(f"❌ Failed to upload {file_path.name}: {e}")
+                        return False
+            
+            logger.info(f"✅ Successfully uploaded {len(uploaded_files)} files to Space")
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Error uploading files: {e}")
+            return self._upload_files_cli(temp_dir)
+    
+    def _upload_files_cli(self, temp_dir: str) -> bool:
+        """Fallback method using CLI for file upload"""
+        try:
+            logger.info("Using CLI fallback for file upload...")
+            
+            # Set HF token for CLI
+            os.environ['HF_TOKEN'] = self.hf_token
+            
+            # Initialize git repository
+            subprocess.run(["git", "init"], cwd=temp_dir, check=True)
+            subprocess.run(["git", "config", "user.name", "Demo Deployer"], cwd=temp_dir, check=True)
+            subprocess.run(["git", "config", "user.email", "[email protected]"], cwd=temp_dir, check=True)
+            
+            # Add files
+            subprocess.run(["git", "add", "."], cwd=temp_dir, check=True)
+            subprocess.run(["git", "commit", "-m", f"Deploy demo for {self.model_id}"], cwd=temp_dir, check=True)
+            
+            # Add remote and push
+            remote_url = f"https://{self.hf_token}@huggingface.co/spaces/{self.space_id}"
+            subprocess.run(["git", "remote", "add", "origin", remote_url], cwd=temp_dir, check=True)
+            subprocess.run(["git", "push", "-u", "origin", "main"], cwd=temp_dir, check=True)
+            
+            logger.info(f"✅ Successfully pushed files to space: {self.space_id}")
+            return True
+            
+        except subprocess.CalledProcessError as e:
+            logger.error(f"❌ Git operation failed: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"❌ Error pushing to space: {e}")
+            return False
+    
+    def set_space_secrets(self) -> bool:
+        """Set environment variables/secrets for the Space using HF Hub API"""
+        try:
+            logger.info("Setting Space secrets using HF Hub API...")
+            
+            if not HF_HUB_AVAILABLE:
+                logger.warning("❌ huggingface_hub not available for setting secrets")
+                return self._manual_secret_setup()
+            
+            # Set the HF_TOKEN secret for the space using the API
+            try:
+                self.api.add_space_secret(
+                    repo_id=self.space_id,
+                    key="HF_TOKEN",
+                    value=self.space_secret_token,
+                    description="Hugging Face token for model access"
+                )
+                logger.info("✅ Successfully set HF_TOKEN secret via API")
+                
+                # Set model-specific environment variables
+                self._set_model_variables()
+                
+                return True
+                
+            except Exception as api_error:
+                logger.error(f"❌ Failed to set secrets via API: {api_error}")
+                logger.info("Falling back to manual setup...")
+                return self._manual_secret_setup()
+            
+        except Exception as e:
+            logger.error(f"❌ Error setting space secrets: {e}")
+            return self._manual_secret_setup()
+    
+    def _manual_secret_setup(self) -> bool:
+        """Fallback method for manual secret setup"""
+        logger.info("📝 Manual Space Secrets Configuration:")
+        logger.info(f"   HF_TOKEN=<hidden>")
+        logger.info(f"   HF_MODEL_ID={self.model_id}")
+        if self.subfolder and self.subfolder.strip():
+            logger.info(f"   MODEL_SUBFOLDER={self.subfolder}")
+        else:
+            logger.info("   MODEL_SUBFOLDER=(empty - using main model)")
+        
+        # GPT-OSS specific variables
+        if self.demo_type == "gpt":
+            model_name = self.model_id.split("/")[-1] if "/" in self.model_id else self.model_id
+            logger.info(f"   LORA_MODEL_ID={self.model_id}")
+            logger.info(f"   BASE_MODEL_ID=openai/gpt-oss-20b")
+            logger.info(f"   MODEL_NAME={model_name}")
+        if self.model_identity:
+            logger.info(f"   MODEL_IDENTITY={self.model_identity}")
+        if self.system_message:
+            logger.info(f"   SYSTEM_MESSAGE={self.system_message}")
+        if self.developer_message:
+            logger.info(f"   DEVELOPER_MESSAGE={self.developer_message}")
+        # Branding variables
+        logger.info(f"   HF_USERNAME={self.hf_username}")
+        logger.info(f"   BRAND_OWNER_NAME={self.brand_owner_name}")
+        logger.info(f"   BRAND_TEAM_NAME={self.brand_team_name}")
+        logger.info(f"   BRAND_DISCORD_URL={self.brand_discord_url}")
+        logger.info(f"   BRAND_HF_ORG={self.brand_hf_org}")
+        logger.info(f"   BRAND_HF_LABEL={self.brand_hf_label}")
+        logger.info(f"   BRAND_HF_URL={self.brand_hf_url}")
+        logger.info(f"   BRAND_GH_ORG={self.brand_gh_org}")
+        logger.info(f"   BRAND_GH_LABEL={self.brand_gh_label}")
+        logger.info(f"   BRAND_GH_URL={self.brand_gh_url}")
+        logger.info(f"   BRAND_PROJECT_NAME={self.brand_project_name}")
+        logger.info(f"   BRAND_PROJECT_URL={self.brand_project_url}")
+
+        # Examples variables
+        if self.examples_type:
+            logger.info(f"   EXAMPLES_TYPE={self.examples_type}")
+        if self.disable_examples is not None:
+            logger.info(f"   DISABLE_EXAMPLES={'true' if self.disable_examples else 'false'}")
+        if self.examples_json:
+            logger.info(f"   EXAMPLES_JSON={self.examples_json}")
+        
+        logger.info(f"\n🔧 To set secrets in your Space:")
+        logger.info(f"1. Go to your Space settings: {self.space_url}/settings")
+        logger.info("2. Navigate to the 'Repository secrets' section")
+        logger.info("3. Add the following secrets:")
+        logger.info(f"   Name: HF_TOKEN")
+        logger.info(f"   Value: <your token>")
+        logger.info(f"   Name: HF_MODEL_ID")
+        logger.info(f"   Value: {self.model_id}")
+        if self.subfolder and self.subfolder.strip():
+            logger.info(f"   Name: MODEL_SUBFOLDER")
+            logger.info(f"   Value: {self.subfolder}")
+        else:
+            logger.info("   Name: MODEL_SUBFOLDER")
+            logger.info("   Value: (leave empty)")
+        
+        # GPT-OSS specific variables
+        if self.demo_type == "gpt":
+            model_name = self.model_id.split("/")[-1] if "/" in self.model_id else self.model_id
+            logger.info(f"   Name: LORA_MODEL_ID")
+            logger.info(f"   Value: {self.model_id}")
+            logger.info(f"   Name: BASE_MODEL_ID")
+            logger.info(f"   Value: openai/gpt-oss-20b")
+            logger.info(f"   Name: MODEL_NAME")
+            logger.info(f"   Value: {model_name}")
+        
+        logger.info("4. Save the secrets")
+        
+        return True
+    
+    def test_space(self) -> bool:
+        """Test if the Space is working correctly"""
+        try:
+            logger.info("Testing Space...")
+            
+            # Wait a bit for the space to build
+            logger.info("Waiting 180 seconds for Space to build...")
+            time.sleep(180)
+            
+            # Try to access the space
+            response = requests.get(self.space_url, timeout=30)
+            
+            if response.status_code == 200:
+                logger.info(f"✅ Space is accessible: {self.space_url}")
+                return True
+            else:
+                logger.warning(f"⚠️  Space returned status code: {response.status_code}")
+                logger.warning(f"Response: {response.text[:500]}...")
+                return False
+                
+        except Exception as e:
+            logger.error(f"❌ Error testing space: {e}")
+            return False
+    
+    def deploy(self) -> bool:
+        """Main deployment method"""
+        logger.info(f"🚀 Starting demo space deployment for {self.model_id}")
+        
+        # Step 1: Validate model exists
+        if not self.validate_model_exists():
+            return False
+        
+        # Step 2: Create space repository
+        if not self.create_space_repository():
+            return False
+        
+        # Step 3: Prepare files
+        temp_dir = self.prepare_space_files()
+        if not temp_dir:
+            return False
+        
+        # Step 4: Upload files
+        if not self.upload_files_to_space(temp_dir):
+            return False
+        
+        # Step 5: Set space secrets
+        if not self.set_space_secrets():
+            return False
+        
+        # Step 6: Clean up temp directory
+        try:
+            shutil.rmtree(temp_dir)
+            logger.info("✅ Cleaned up temporary directory")
+        except Exception as e:
+            logger.warning(f"⚠️  Warning: Could not clean up temp directory: {e}")
+        
+        # Step 7: Test space
+        if not self.test_space():
+            logger.warning("⚠️  Space created but may need more time to build")
+            logger.info("Please check the Space manually in a few minutes")
+        
+        logger.info(f"🎉 Demo space deployment completed!")
+        logger.info(f"📊 Space URL: {self.space_url}")
+        logger.info(f"🔧 Space configuration: {self.space_url}/settings")
+        
+        return True
+
+def main():
+    """Main function for command line usage"""
+    print("Demo Space Deployment Script")
+    print("=" * 40)
+    
+    parser = argparse.ArgumentParser(description="Deploy demo space to Hugging Face Spaces")
+    parser.add_argument("--hf-token", required=True, help="Hugging Face token")
+    parser.add_argument(
+        "--space-secret-token",
+        required=False,
+        help="Token to store as Space secret HF_TOKEN (defaults to --hf-token). Use a READ token here for least privilege.",
+    )
+    parser.add_argument("--hf-username", required=True, help="Hugging Face username")
+    parser.add_argument("--model-id", required=True, help="Model ID to deploy demo for")
+    parser.add_argument("--subfolder", default="int4", help="Model subfolder (default: int4)")
+    parser.add_argument("--space-name", help="Custom space name (optional)")
+    parser.add_argument("--demo-type", choices=["smol", "gpt"], help="Demo type: 'smol' for SmolLM, 'gpt' for GPT-OSS (auto-detected if not specified)")
+    parser.add_argument("--config-file", help="Path to the training config file to import context (system/developer/model_identity)")
+    # Examples configuration
+    parser.add_argument("--examples-type", choices=["general", "medical"], help="Examples pack to enable in the demo UI")
+    parser.add_argument("--disable-examples", action="store_true", help="Disable rendering of example prompts in the UI")
+    parser.add_argument("--examples-json", help="Custom examples JSON (list[str]) to override built-in examples")
+    # Branding customization
+    parser.add_argument("--brand-owner-name", help="Owner name shown in the UI title (defaults to HF username)")
+    parser.add_argument("--brand-team-name", help="Team name shown in Join Us (defaults to Team<owner>)")
+    parser.add_argument("--brand-discord-url", help="Discord invite URL for Join Us section")
+    parser.add_argument("--brand-hf-org", help="Hugging Face org/username to link in Join Us")
+    parser.add_argument("--brand-hf-label", help="Label for the HF link (defaults to org)")
+    parser.add_argument("--brand-hf-url", help="Custom HF link URL (defaults to https://huggingface.co/<org>)")
+    parser.add_argument("--brand-gh-org", help="GitHub org/username to link in Join Us")
+    parser.add_argument("--brand-gh-label", help="Label for the GitHub link (defaults to org)")
+    parser.add_argument("--brand-gh-url", help="Custom GitHub link URL (defaults to https://github.com/<org>)")
+    parser.add_argument("--brand-project-name", help="Project name to link in Join Us")
+    parser.add_argument("--brand-project-url", help="Project URL to link in Join Us")
+    
+    args = parser.parse_args()
+    
+    deployer = DemoSpaceDeployer(
+        hf_token=args.hf_token,
+        space_secret_token=(args.space_secret_token or None),
+        hf_username=args.hf_username,
+        model_id=args.model_id,
+        subfolder=args.subfolder,
+        space_name=args.space_name,
+        demo_type=args.demo_type,
+        config_file=args.config_file,
+        examples_type=args.examples_type,
+        disable_examples=(True if getattr(args, 'disable_examples', False) else None),
+        examples_json=args.examples_json,
+        brand_owner_name=args.brand_owner_name,
+        brand_team_name=args.brand_team_name,
+        brand_discord_url=args.brand_discord_url,
+        brand_hf_org=args.brand_hf_org,
+        brand_hf_label=args.brand_hf_label,
+        brand_hf_url=args.brand_hf_url,
+        brand_gh_org=args.brand_gh_org,
+        brand_gh_label=args.brand_gh_label,
+        brand_gh_url=args.brand_gh_url,
+        brand_project_name=args.brand_project_name,
+        brand_project_url=args.brand_project_url,
+    )
+    
+    success = deployer.deploy()
+    
+    if success:
+        print("\n✅ Deployment successful!")
+        print(f"🌐 Your Demo Space: {deployer.space_url}")
+        print(f"👤 Username: {deployer.hf_username}")
+        print(f"🤖 Model: {deployer.model_id}")
+        print("\nNext steps:")
+        print("1. Wait for the Space to build (usually 2-5 minutes)")
+        print("2. Secrets have been automatically set via API")
+        print("3. Test the interface by visiting the Space URL")
+        print("4. Share your demo with others!")
+        print("\nIf the Space doesn't work immediately, check:")
+        print("- The Space logs at the Space URL")
+        print("- That all files were uploaded correctly")
+        print("- That the HF token has write permissions")
+        print("- That the secrets were set correctly in Space settings")
+    else:
+        print("\n❌ Deployment failed!")
+        print("Check the error messages above and try again.")
+        print("\nTroubleshooting:")
+        print("1. Verify your HF token has write permissions")
+        print("2. Check that the space name is available")
+        print("3. Verify the model exists and is accessible")
+        print("4. Try creating the space manually on HF first")
+    
+    sys.exit(0 if success else 1)
+
+if __name__ == "__main__":
+    main() 

scripts/generate_model_card.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+Generate unified model card from template
+Handles template variables and conditional sections for quantized models
+"""
+
+import os
+import re
+import argparse
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+class ModelCardGenerator:
+    """Generate unified model cards from templates"""
+    
+    def __init__(self, template_path: str = "templates/model_card.md"):
+        self.template_path = Path(template_path)
+        if not self.template_path.exists():
+            raise FileNotFoundError(f"Template not found: {self.template_path}")
+    
+    def load_template(self) -> str:
+        """Load the model card template"""
+        with open(self.template_path, 'r', encoding='utf-8') as f:
+            return f.read()
+    
+    def process_conditionals(self, content: str, variables: Dict[str, Any]) -> str:
+        """Process conditional sections in the template"""
+        # Handle {{#if variable}}...{{/if}} blocks
+        pattern = r'\{\{#if\s+(\w+)\}\}(.*?)\{\{/if\}\}'
+        
+        def replace_conditional(match):
+            variable_name = match.group(1)
+            conditional_content = match.group(2)
+            
+            # Check if variable exists and is truthy
+            if variable_name in variables and variables[variable_name]:
+                return conditional_content
+            else:
+                return ""
+        
+        return re.sub(pattern, replace_conditional, content, flags=re.DOTALL)
+    
+    def replace_variables(self, content: str, variables: Dict[str, Any]) -> str:
+        """Replace template variables with actual values"""
+        for key, value in variables.items():
+            placeholder = f"{{{{{key}}}}}"
+            content = content.replace(placeholder, str(value))
+        
+        return content
+    
+    def generate_model_card(self, variables: Dict[str, Any]) -> str:
+        """Generate the complete model card"""
+        # Load template
+        content = self.load_template()
+        
+        # Process conditionals first
+        content = self.process_conditionals(content, variables)
+        
+        # Replace variables
+        content = self.replace_variables(content, variables)
+        
+        return content
+    
+    def save_model_card(self, content: str, output_path: str) -> bool:
+        """Save the generated model card"""
+        try:
+            output_file = Path(output_path)
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(output_file, 'w', encoding='utf-8') as f:
+                f.write(content)
+            
+            logger.info(f"✅ Model card saved to: {output_file}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to save model card: {e}")
+            return False
+
+def create_default_variables() -> Dict[str, Any]:
+    """Create default variables for the model card"""
+    return {
+        "model_name": "SmolLM3 Fine-tuned Model",
+        "model_description": "A fine-tuned version of SmolLM3-3B for improved text generation and conversation capabilities.",
+        "repo_name": "your-username/model-name",
+        "base_model": "HuggingFaceTB/SmolLM3-3B",
+        "dataset_name": "OpenHermes-FR",
+        "training_config_type": "Custom Configuration",
+        "trainer_type": "SFTTrainer",
+        "batch_size": "8",
+        "gradient_accumulation_steps": "16",
+        "learning_rate": "5e-6",
+        "max_epochs": "3",
+        "max_seq_length": "2048",
+        "hardware_info": "GPU (H100/A100)",
+        "experiment_name": "smollm3-experiment",
+        "trackio_url": "https://trackio.space/experiment",
+        "dataset_repo": "tonic/trackio-experiments",
+        "dataset_size": "~80K samples",
+        "dataset_format": "Chat format",
+        "author_name": "Your Name",
+        "model_name_slug": "smollm3-fine-tuned",
+        "quantized_models": False,
+        "dataset_sample_size": None,
+        "training_loss": "N/A",
+        "validation_loss": "N/A",
+        "perplexity": "N/A"
+    }
+
+def parse_args():
+    """Parse command line arguments"""
+    parser = argparse.ArgumentParser(description="Generate unified model card")
+    parser.add_argument("--template", default="templates/model_card.md", 
+                       help="Path to model card template")
+    parser.add_argument("--output", default="README.md", 
+                       help="Output path for generated model card")
+    parser.add_argument("--repo-name", required=True, 
+                       help="Hugging Face repository name")
+    parser.add_argument("--model-name", help="Model name")
+    parser.add_argument("--experiment-name", help="Experiment name")
+    parser.add_argument("--dataset-name", help="Dataset name")
+    parser.add_argument("--training-config", help="Training configuration type")
+    parser.add_argument("--trainer-type", help="Trainer type")
+    parser.add_argument("--batch-size", help="Batch size")
+    parser.add_argument("--learning-rate", help="Learning rate")
+    parser.add_argument("--max-epochs", help="Maximum epochs")
+    parser.add_argument("--max-seq-length", help="Maximum sequence length")
+    parser.add_argument("--hardware-info", help="Hardware information")
+    parser.add_argument("--trackio-url", help="Trackio URL")
+    parser.add_argument("--dataset-repo", help="Dataset repository")
+    parser.add_argument("--author-name", help="Author name")
+    parser.add_argument("--quantized-models", action="store_true", 
+                       help="Include quantized models")
+    parser.add_argument("--dataset-sample-size", help="Dataset sample size")
+    parser.add_argument("--training-loss", help="Training loss value")
+    parser.add_argument("--validation-loss", help="Validation loss value")
+    parser.add_argument("--perplexity", help="Perplexity value")
+    
+    return parser.parse_args()
+
+def main():
+    """Main function"""
+    args = parse_args()
+    
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+    
+    try:
+        # Create generator
+        generator = ModelCardGenerator(args.template)
+        
+        # Create variables dictionary
+        variables = create_default_variables()
+        
+        # Override with command line arguments
+        if args.repo_name:
+            variables["repo_name"] = args.repo_name
+        if args.model_name:
+            variables["model_name"] = args.model_name
+        if args.experiment_name:
+            variables["experiment_name"] = args.experiment_name
+        if args.dataset_name:
+            variables["dataset_name"] = args.dataset_name
+        if args.training_config:
+            variables["training_config_type"] = args.training_config
+        if args.trainer_type:
+            variables["trainer_type"] = args.trainer_type
+        if args.batch_size:
+            variables["batch_size"] = args.batch_size
+        if args.learning_rate:
+            variables["learning_rate"] = args.learning_rate
+        if args.max_epochs:
+            variables["max_epochs"] = args.max_epochs
+        if args.max_seq_length:
+            variables["max_seq_length"] = args.max_seq_length
+        if args.hardware_info:
+            variables["hardware_info"] = args.hardware_info
+        if args.trackio_url:
+            variables["trackio_url"] = args.trackio_url
+        if args.dataset_repo:
+            variables["dataset_repo"] = args.dataset_repo
+        if args.author_name:
+            variables["author_name"] = args.author_name
+        if args.quantized_models:
+            variables["quantized_models"] = True
+        if args.dataset_sample_size:
+            variables["dataset_sample_size"] = args.dataset_sample_size
+        if args.training_loss:
+            variables["training_loss"] = args.training_loss
+        if args.validation_loss:
+            variables["validation_loss"] = args.validation_loss
+        if args.perplexity:
+            variables["perplexity"] = args.perplexity
+        
+        # Generate model card
+        print("🔄 Generating model card...")
+        content = generator.generate_model_card(variables)
+        
+        # Save model card
+        if generator.save_model_card(content, args.output):
+            print("✅ Model card generated successfully!")
+            print(f"📄 Output: {args.output}")
+        else:
+            print("❌ Failed to generate model card")
+            return 1
+        
+        return 0
+        
+    except Exception as e:
+        logger.error(f"❌ Error generating model card: {e}")
+        return 1
+
+if __name__ == "__main__":
+    exit(main()) 

scripts/push_to_huggingface.py

@@ -0,0 +1,700 @@
+#!/usr/bin/env python3
+"""
+Push Trained Model and Results to Hugging Face Hub
+Integrates with Trackio monitoring and HF Datasets for complete model deployment
+"""
+
+import os
+import json
+import argparse
+import logging
+import time
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+from datetime import datetime
+import subprocess
+import shutil
+import platform
+
+# Set timeout for HF operations to prevent hanging
+os.environ['HF_HUB_DOWNLOAD_TIMEOUT'] = '300'
+os.environ['HF_HUB_UPLOAD_TIMEOUT'] = '600'
+
+try:
+    from huggingface_hub import HfApi, create_repo, upload_file
+    from huggingface_hub import snapshot_download, hf_hub_download
+    HF_AVAILABLE = True
+except ImportError:
+    HF_AVAILABLE = False
+    print("Warning: huggingface_hub not available. Install with: pip install huggingface_hub")
+
+try:
+    import sys
+    import os
+    sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', 'src'))
+    from monitoring import SmolLM3Monitor
+    MONITORING_AVAILABLE = True
+except ImportError:
+    MONITORING_AVAILABLE = False
+    print("Warning: monitoring module not available")
+
+logger = logging.getLogger(__name__)
+
+class TimeoutError(Exception):
+    """Custom timeout exception"""
+    pass
+
+def timeout_handler(signum, frame):
+    """Signal handler for timeout"""
+    raise TimeoutError("Operation timed out")
+
+class HuggingFacePusher:
+    """Push trained models and results to Hugging Face Hub with HF Datasets integration"""
+    
+    def __init__(
+        self,
+        model_path: str,
+        repo_name: str,
+        token: Optional[str] = None,
+        private: bool = False,
+        trackio_url: Optional[str] = None,
+        experiment_name: Optional[str] = None,
+        dataset_repo: Optional[str] = None,
+        hf_token: Optional[str] = None,
+        author_name: Optional[str] = None,
+        model_description: Optional[str] = None,
+        training_config_type: Optional[str] = None,
+        model_name: Optional[str] = None,
+        dataset_name: Optional[str] = None,
+        batch_size: Optional[str] = None,
+        learning_rate: Optional[str] = None,
+        max_epochs: Optional[str] = None,
+        max_seq_length: Optional[str] = None,
+        trainer_type: Optional[str] = None
+    ):
+        self.model_path = Path(model_path)
+        # Original user input (may be just the repo name without username)
+        self.repo_name = repo_name
+        self.token = token or hf_token or os.getenv('HF_TOKEN')
+        self.private = private
+        self.trackio_url = trackio_url
+        self.experiment_name = experiment_name
+        self.author_name = author_name
+        self.model_description = model_description
+        
+        # Training configuration details for model card generation
+        self.training_config_type = training_config_type
+        self.model_name = model_name  
+        self.dataset_name = dataset_name
+        self.batch_size = batch_size
+        self.learning_rate = learning_rate
+        self.max_epochs = max_epochs
+        self.max_seq_length = max_seq_length
+        self.trainer_type = trainer_type
+        
+        # HF Datasets configuration
+        self.dataset_repo = dataset_repo or os.getenv('TRACKIO_DATASET_REPO', 'tonic/trackio-experiments')
+        self.hf_token = hf_token or os.getenv('HF_TOKEN')
+        
+        # Initialize HF API
+        if HF_AVAILABLE:
+            self.api = HfApi(token=self.token)
+        else:
+            raise ImportError("huggingface_hub is required. Install with: pip install huggingface_hub")
+        
+        # Resolve the full repo id (username/repo) if user only provided repo name
+        self.repo_id = self._resolve_repo_id(self.repo_name)
+
+        # Initialize monitoring if available
+        self.monitor = None
+        if MONITORING_AVAILABLE:
+            self.monitor = SmolLM3Monitor(
+                experiment_name=experiment_name or "model_push",
+                trackio_url=trackio_url,
+                enable_tracking=bool(trackio_url),
+                hf_token=self.hf_token,
+                dataset_repo=self.dataset_repo
+            )
+        
+        logger.info(f"Initialized HuggingFacePusher for {self.repo_id}")
+        logger.info(f"Dataset repository: {self.dataset_repo}")
+
+    def _resolve_repo_id(self, repo_name: str) -> str:
+        """Return a fully-qualified repo id in the form username/repo.
+
+        If the provided name already contains a '/', it is returned unchanged.
+        Otherwise, we attempt to derive the username from the authenticated token
+        or from the HF_USERNAME environment variable.
+        """
+        try:
+            if "/" in repo_name:
+                return repo_name
+
+            # Need a username. Prefer API whoami(), fallback to env HF_USERNAME
+            username: Optional[str] = None
+            if self.token:
+                try:
+                    user_info = self.api.whoami()
+                    username = user_info.get("name") or user_info.get("username")
+                except Exception:
+                    username = None
+
+            if not username:
+                username = os.getenv("HF_USERNAME")
+
+            if not username:
+                raise ValueError(
+                    "Username could not be determined. Provide a token or set HF_USERNAME, "
+                    "or pass a fully-qualified repo id 'username/repo'."
+                )
+
+            return f"{username}/{repo_name}"
+        except Exception as resolve_error:
+            logger.error(f"Failed to resolve full repo id for '{repo_name}': {resolve_error}")
+            # Fall back to provided value (may fail later at create/upload)
+            return repo_name
+    
+    def create_repository(self) -> bool:
+        """Create the Hugging Face repository"""
+        try:
+            logger.info(f"Creating repository: {self.repo_id}")
+            
+            # Create repository with timeout handling
+            try:
+                # Create repository
+                create_repo(
+                    repo_id=self.repo_id,
+                    token=self.token,
+                    private=self.private,
+                    exist_ok=True
+                )
+                
+                logger.info(f"✅ Repository created: https://huggingface.co/{self.repo_id}")
+                return True
+                
+            except Exception as e:
+                logger.error(f"❌ Repository creation failed: {e}")
+                return False
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to create repository: {e}")
+            return False
+    
+    def validate_model_path(self) -> bool:
+        """Validate that the model path contains required files"""
+        # Support both safetensors and pytorch formats
+        required_files = [
+            "config.json",
+            "tokenizer.json",
+            "tokenizer_config.json"
+        ]
+        
+        # Check for model files (either safetensors or pytorch)
+        model_files = [
+            "model.safetensors.index.json",  # Safetensors format
+            "pytorch_model.bin"  # PyTorch format
+        ]
+        
+        missing_files = []
+        for file in required_files:
+            if not (self.model_path / file).exists():
+                missing_files.append(file)
+        
+        # Check if at least one model file exists
+        model_file_exists = any((self.model_path / file).exists() for file in model_files)
+        if not model_file_exists:
+            missing_files.extend(model_files)
+        
+        if missing_files:
+            logger.error(f"❌ Missing required files: {missing_files}")
+            return False
+        
+        logger.info("✅ Model files validated")
+        return True
+    
+    def create_model_card(self, training_config: Dict[str, Any], results: Dict[str, Any]) -> str:
+        """Create a comprehensive model card using the generate_model_card.py script"""
+        try:
+            # Import the model card generator
+            import sys
+            sys.path.append(os.path.join(os.path.dirname(__file__)))
+            from generate_model_card import ModelCardGenerator, create_default_variables
+            
+            # Create generator
+            generator = ModelCardGenerator()
+            
+            # Create variables for the model card
+            variables = create_default_variables()
+            
+            # Update with actual values
+            variables.update({
+                "repo_name": self.repo_id,
+                "model_name": self.repo_id.split('/')[-1],
+                "experiment_name": self.experiment_name or "model_push",
+                "dataset_repo": self.dataset_repo,
+                "author_name": self.author_name or "Model Author",
+                "model_description": self.model_description or "A fine-tuned version of SmolLM3-3B for improved text generation capabilities.",
+                "training_config_type": self.training_config_type or "Custom Configuration",
+                "base_model": self.model_name or "HuggingFaceTB/SmolLM3-3B",
+                "dataset_name": self.dataset_name or "Custom Dataset",
+                "trainer_type": self.trainer_type or "SFTTrainer",
+                "batch_size": str(self.batch_size) if self.batch_size else "8",
+                "learning_rate": str(self.learning_rate) if self.learning_rate else "5e-6",
+                "max_epochs": str(self.max_epochs) if self.max_epochs else "3",
+                "max_seq_length": str(self.max_seq_length) if self.max_seq_length else "2048",
+                "hardware_info": self._get_hardware_info(),
+                "trackio_url": self.trackio_url or "N/A",
+                "training_loss": str(results.get('train_loss', 'N/A')),
+                "validation_loss": str(results.get('eval_loss', 'N/A')),
+                "perplexity": str(results.get('perplexity', 'N/A')),
+                "quantized_models": False  # Set to True if quantized models are available
+            })
+            
+            # Generate the model card
+            model_card_content = generator.generate_model_card(variables)
+            
+            logger.info("✅ Model card generated using generate_model_card.py")
+            return model_card_content
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to generate model card with generator: {e}")
+            logger.info("🔄 Falling back to simple model card")
+            return self._create_simple_model_card(training_config, results)
+    
+    def _create_simple_model_card(self, training_config: Dict[str, Any], results: Dict[str, Any]) -> str:
+        """Create a simple model card without complex YAML to avoid formatting issues"""
+        return f"""---
+language:
+- en
+- fr
+license: apache-2.0
+tags:
+- smollm3
+- fine-tuned
+- causal-lm
+- text-generation
+pipeline_tag: text-generation
+base_model: HuggingFaceTB/SmolLM3-3B
+---
+
+# {self.repo_id.split('/')[-1]}
+
+This is a fine-tuned SmolLM3 model based on the HuggingFaceTB/SmolLM3-3B architecture.
+
+## Model Details
+
+- **Base Model**: HuggingFaceTB/SmolLM3-3B
+- **Fine-tuning Method**: Supervised Fine-tuning
+- **Training Date**: {datetime.now().strftime('%Y-%m-%d')}
+- **Model Size**: {self._get_model_size():.1f} GB
+- **Dataset Repository**: {self.dataset_repo}
+- **Hardware**: {self._get_hardware_info()}
+
+## Training Configuration
+
+```json
+{json.dumps(training_config, indent=2)}
+```
+
+## Training Results
+
+```json
+{json.dumps(results, indent=2)}
+```
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# Load model and tokenizer
+model = AutoModelForCausalLM.from_pretrained("{self.repo_id}")
+tokenizer = AutoTokenizer.from_pretrained("{self.repo_id}")
+
+# Generate text
+inputs = tokenizer("Hello, how are you?", return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=100)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+## Training Information
+
+- **Base Model**: HuggingFaceTB/SmolLM3-3B
+- **Hardware**: {self._get_hardware_info()}
+- **Training Time**: {results.get('training_time_hours', 'Unknown')} hours
+- **Final Loss**: {results.get('final_loss', 'Unknown')}
+- **Final Accuracy**: {results.get('final_accuracy', 'Unknown')}
+- **Dataset Repository**: {self.dataset_repo}
+
+## Model Performance
+
+- **Training Loss**: {results.get('train_loss', 'Unknown')}
+- **Validation Loss**: {results.get('eval_loss', 'Unknown')}
+- **Training Steps**: {results.get('total_steps', 'Unknown')}
+
+## Experiment Tracking
+
+This model was trained with experiment tracking enabled. Training metrics and configuration are stored in the HF Dataset repository: `{self.dataset_repo}`
+
+## Limitations and Biases
+
+This model is fine-tuned for specific tasks and may not generalize well to all use cases. Please evaluate the model's performance on your specific task before deployment.
+
+## License
+
+This model is licensed under the Apache 2.0 License.
+"""
+    
+    def _get_model_size(self) -> float:
+        """Get model size in GB"""
+        try:
+            total_size = 0
+            for file in self.model_path.rglob("*"):
+                if file.is_file():
+                    total_size += file.stat().st_size
+            return total_size / (1024**3)  # Convert to GB
+        except:
+            return 0.0
+    
+    def _get_hardware_info(self) -> str:
+        """Get hardware information"""
+        try:
+            import torch
+            if torch.cuda.is_available():
+                gpu_name = torch.cuda.get_device_name(0)
+                return f"GPU: {gpu_name}"
+            else:
+                return "CPU"
+        except:
+            return "Unknown"
+    
+    def upload_model_files(self) -> bool:
+        """Upload model files to Hugging Face Hub with timeout protection"""
+        try:
+            logger.info("Uploading model files...")
+            
+            # Upload all files in the model directory
+            for file_path in self.model_path.rglob("*"):
+                if file_path.is_file():
+                    relative_path = file_path.relative_to(self.model_path)
+                    remote_path = str(relative_path)
+                    
+                    logger.info(f"Uploading {relative_path}")
+                    
+                    try:
+                        upload_file(
+                            path_or_fileobj=str(file_path),
+                            path_in_repo=remote_path,
+                            repo_id=self.repo_id,
+                            token=self.token
+                        )
+                        logger.info(f"✅ Uploaded {relative_path}")
+                        
+                    except Exception as e:
+                        logger.error(f"❌ Failed to upload {relative_path}: {e}")
+                        return False
+            
+            logger.info("✅ Model files uploaded successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to upload model files: {e}")
+            return False
+    
+    def upload_training_results(self, results_path: str) -> bool:
+        """Upload training results and logs"""
+        try:
+            logger.info("Uploading training results...")
+            
+            results_files = [
+                "train_results.json",
+                "eval_results.json",
+                "training_config.json",
+                "training.log"
+            ]
+            
+            for file_name in results_files:
+                file_path = Path(results_path) / file_name
+                if file_path.exists():
+                    logger.info(f"Uploading {file_name}")
+                    upload_file(
+                        path_or_fileobj=str(file_path),
+                        path_in_repo=f"training_results/{file_name}",
+                        repo_id=self.repo_id,
+                        token=self.token
+                    )
+            
+            logger.info("✅ Training results uploaded successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to upload training results: {e}")
+            return False
+    
+    def create_readme(self, training_config: Dict[str, Any], results: Dict[str, Any]) -> bool:
+        """Create and upload README.md"""
+        try:
+            logger.info("Creating README.md...")
+            
+            readme_content = f"""# {self.repo_id.split('/')[-1]}
+
+A fine-tuned SmolLM3 model for text generation tasks.
+
+## Quick Start
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("{self.repo_id}")
+tokenizer = AutoTokenizer.from_pretrained("{self.repo_id}")
+
+# Generate text
+text = "Hello, how are you?"
+inputs = tokenizer(text, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=100)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+## Model Information
+
+- **Base Model**: HuggingFaceTB/SmolLM3-3B
+- **Fine-tuning Date**: {datetime.now().strftime('%Y-%m-%d')}
+- **Model Size**: {self._get_model_size():.1f} GB
+- **Training Steps**: {results.get('total_steps', 'Unknown')}
+- **Final Loss**: {results.get('final_loss', 'Unknown')}
+- **Dataset Repository**: {self.dataset_repo}
+
+## Training Configuration
+
+```json
+{json.dumps(training_config, indent=2)}
+```
+
+## Performance Metrics
+
+```json
+{json.dumps(results, indent=2)}
+```
+
+## Experiment Tracking
+
+Training metrics and configuration are stored in the HF Dataset repository: `{self.dataset_repo}`
+
+## Files
+
+- `model.safetensors.index.json`: Model weights (safetensors format)
+- `config.json`: Model configuration
+- `tokenizer.json`: Tokenizer configuration
+- `training_results/`: Training logs and results
+
+## License
+
+MIT License
+"""
+            
+            # Write README to temporary file
+            readme_path = Path("temp_readme.md")
+            with open(readme_path, "w") as f:
+                f.write(readme_content)
+            
+            # Upload README
+            upload_file(
+                path_or_fileobj=str(readme_path),
+                path_in_repo="README.md",
+                token=self.token,
+                repo_id=self.repo_id
+            )
+            
+            # Clean up
+            readme_path.unlink()
+            
+            logger.info("✅ README.md uploaded successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to create README: {e}")
+            return False
+    
+    def log_to_trackio(self, action: str, details: Dict[str, Any]):
+        """Log push action to Trackio and HF Datasets"""
+        if self.monitor:
+            try:
+                # Log to Trackio
+                self.monitor.log_metrics({
+                    "push_action": action,
+                    "repo_name": self.repo_id,
+                    "model_size_gb": self._get_model_size(),
+                    "dataset_repo": self.dataset_repo,
+                    **details
+                })
+                
+                # Log training summary
+                self.monitor.log_training_summary({
+                    "model_push": True,
+                    "model_repo": self.repo_id,
+                    "dataset_repo": self.dataset_repo,
+                    "push_date": datetime.now().isoformat(),
+                    **details
+                })
+                
+                logger.info(f"✅ Logged {action} to Trackio and HF Datasets")
+            except Exception as e:
+                logger.error(f"❌ Failed to log to Trackio: {e}")
+    
+    def push_model(self, training_config: Optional[Dict[str, Any]] = None, 
+                   results: Optional[Dict[str, Any]] = None) -> bool:
+        """Complete model push process with HF Datasets integration"""
+        logger.info(f"🚀 Starting model push to {self.repo_id}")
+        logger.info(f"📊 Dataset repository: {self.dataset_repo}")
+        
+        # Validate model path
+        if not self.validate_model_path():
+            return False
+        
+        # Create repository
+        if not self.create_repository():
+            return False
+        
+        # Load training config and results if not provided
+        if training_config is None:
+            training_config = self._load_training_config()
+        
+        if results is None:
+            results = self._load_training_results()
+        
+        # Create and upload model card
+        model_card = self.create_model_card(training_config, results)
+        model_card_path = Path("temp_model_card.md")
+        with open(model_card_path, "w") as f:
+            f.write(model_card)
+        
+        try:
+            upload_file(
+                path_or_fileobj=str(model_card_path),
+                path_in_repo="README.md",
+                repo_id=self.repo_id,
+                token=self.token
+            )
+        finally:
+            model_card_path.unlink()
+        
+        # Upload model files
+        if not self.upload_model_files():
+            return False
+        
+        # Upload training results
+        if results:
+            self.upload_training_results(str(self.model_path))
+        
+        # Log to Trackio and HF Datasets
+        self.log_to_trackio("model_push", {
+            "model_path": str(self.model_path),
+            "repo_name": self.repo_name,
+            "private": self.private,
+            "training_config": training_config,
+            "results": results
+        })
+        
+        logger.info(f"🎉 Model successfully pushed to: https://huggingface.co/{self.repo_id}")
+        logger.info(f"📊 Experiment data stored in: {self.dataset_repo}")
+        return True
+    
+    def _load_training_config(self) -> Dict[str, Any]:
+        """Load training configuration"""
+        config_path = self.model_path / "training_config.json"
+        if config_path.exists():
+            with open(config_path, "r") as f:
+                return json.load(f)
+        return {"model_name": "HuggingFaceTB/SmolLM3-3B"}
+    
+    def _load_training_results(self) -> Dict[str, Any]:
+        """Load training results"""
+        results_path = self.model_path / "train_results.json"
+        if results_path.exists():
+            with open(results_path, "r") as f:
+                return json.load(f)
+        return {"final_loss": "Unknown", "total_steps": "Unknown"}
+
+def parse_args():
+    """Parse command line arguments"""
+    parser = argparse.ArgumentParser(description='Push trained model to Hugging Face Hub')
+    
+    # Required arguments
+    parser.add_argument('model_path', type=str, help='Path to trained model directory')
+    parser.add_argument('repo_name', type=str, help='Hugging Face repository name (repo-name). Username will be auto-detected from your token.')
+    
+    # Optional arguments
+    parser.add_argument('--token', type=str, default=None, help='Hugging Face token')
+    parser.add_argument('--hf-token', type=str, default=None, help='Hugging Face token (alternative to --token)')
+    parser.add_argument('--private', action='store_true', help='Make repository private')
+    parser.add_argument('--trackio-url', type=str, default=None, help='Trackio Space URL for logging')
+    parser.add_argument('--experiment-name', type=str, default=None, help='Experiment name for Trackio')
+    parser.add_argument('--dataset-repo', type=str, default=None, help='HF Dataset repository for experiment storage')
+    parser.add_argument('--author-name', type=str, default=None, help='Author name for model card')
+    parser.add_argument('--model-description', type=str, default=None, help='Model description for model card')
+    parser.add_argument('--training-config-type', type=str, default=None, help='Training configuration type')
+    parser.add_argument('--model-name', type=str, default=None, help='Base model name')
+    parser.add_argument('--dataset-name', type=str, default=None, help='Dataset name')
+    parser.add_argument('--batch-size', type=str, default=None, help='Batch size')
+    parser.add_argument('--learning-rate', type=str, default=None, help='Learning rate')
+    parser.add_argument('--max-epochs', type=str, default=None, help='Maximum epochs')
+    parser.add_argument('--max-seq-length', type=str, default=None, help='Maximum sequence length')
+    parser.add_argument('--trainer-type', type=str, default=None, help='Trainer type')
+    
+    return parser.parse_args()
+
+def main():
+    """Main function"""
+    args = parse_args()
+    
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+    
+    logger.info("Starting model push to Hugging Face Hub")
+    
+    # Initialize pusher
+    try:
+        pusher = HuggingFacePusher(
+            model_path=args.model_path,
+            repo_name=args.repo_name,
+            token=args.token,
+            private=args.private,
+            trackio_url=args.trackio_url,
+            experiment_name=args.experiment_name,
+            dataset_repo=args.dataset_repo,
+            hf_token=args.hf_token,
+            author_name=args.author_name,
+            model_description=args.model_description,
+            training_config_type=args.training_config_type,
+            model_name=args.model_name,
+            dataset_name=args.dataset_name,
+            batch_size=args.batch_size,
+            learning_rate=args.learning_rate,
+            max_epochs=args.max_epochs,
+            max_seq_length=args.max_seq_length,
+            trainer_type=args.trainer_type
+        )
+        
+        # Push model
+        success = pusher.push_model()
+        
+        if success:
+            logger.info("✅ Model push completed successfully!")
+            logger.info(f"🌐 View your model at: https://huggingface.co/{args.repo_name}")
+            if args.dataset_repo:
+                logger.info(f"📊 View experiment data at: https://huggingface.co/datasets/{args.dataset_repo}")
+        else:
+            logger.error("❌ Model push failed!")
+            return 1
+            
+    except Exception as e:
+        logger.error(f"❌ Error during model push: {e}")
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit(main()) 

train_lora.py → scripts/train.py

@@ -1,14 +1,16 @@
 #!/usr/bin/env python3
 
+import argparse
+import json
+from pathlib import Path
 import torch
-from datasets import load_dataset, Audio
+from datasets import load_dataset, Audio, Dataset
 from transformers import (
     VoxtralForConditionalGeneration,
     VoxtralProcessor,
     Trainer,
     TrainingArguments,
 )
-from peft import LoraConfig, get_peft_model
 
 
 class VoxtralDataCollator:
@@ -95,82 +97,114 @@ class VoxtralDataCollator:
 
         return batch
 
-def load_and_prepare_dataset():
-    """Load and prepare dataset for training."""
-    dataset_name = "hf-audio/esb-datasets-test-only-sorted"
-    dataset_config = "voxpopuli"
-    
-    print(f"Loading dataset: {dataset_name}/{dataset_config}")
-    dataset = load_dataset(dataset_name, dataset_config, split="test")
-    
-    # Cast audio to 16kHz (required for Voxtral)
-    dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))
-    
-    train_dataset = dataset.select(range(100))
-    eval_dataset = dataset.select(range(100, 150))
-    
+def _load_jsonl_dataset(jsonl_path: str) -> Dataset:
+    """Load local JSONL with fields {audio_path, text} into a Dataset with audio column."""
+    records = []
+    jsonl_file = Path(jsonl_path)
+    if not jsonl_file.exists():
+        raise FileNotFoundError(f"Dataset jsonl not found: {jsonl_path}")
+    with open(jsonl_file, "r", encoding="utf-8") as f:
+        for line in f:
+            if not line.strip():
+                continue
+            obj = json.loads(line)
+            audio_path = obj.get("audio_path") or obj.get("audio")
+            text = obj.get("text")
+            if not audio_path or text is None:
+                continue
+            records.append({"audio": audio_path, "text": text})
+    if not records:
+        raise ValueError("No valid records found in JSONL. Expect keys: audio_path, text")
+    ds = Dataset.from_list(records)
+    # Cast the audio column from file paths and resample to 16kHz
+    ds = ds.cast_column("audio", Audio(sampling_rate=16000))
+    return ds
+
+
+def load_and_prepare_dataset(dataset_jsonl: str | None, dataset_name: str | None, dataset_config: str | None,
+                             train_count: int, eval_count: int):
+    """Load and prepare dataset for training.
+
+    Priority: local JSONL > HF dataset name/config > fallback tiny sample.
+    """
+    if dataset_jsonl:
+        print(f"Loading local JSONL dataset: {dataset_jsonl}")
+        ds = _load_jsonl_dataset(dataset_jsonl)
+    else:
+        ds_name = dataset_name or "hf-audio/esb-datasets-test-only-sorted"
+        ds_cfg = dataset_config or "voxpopuli"
+        print(f"Loading dataset: {ds_name}/{ds_cfg}")
+        ds = load_dataset(ds_name, ds_cfg, split="test")
+        ds = ds.cast_column("audio", Audio(sampling_rate=16000))
+
+    total = len(ds)
+    train_end = min(train_count, total)
+    eval_end = min(train_end + eval_count, total)
+    train_dataset = ds.select(range(train_end))
+    eval_dataset = ds.select(range(train_end, eval_end)) if eval_end > train_end else None
     return train_dataset, eval_dataset
 
 
 def main():
-    # Configuration
-    model_checkpoint = "mistralai/Voxtral-Mini-3B-2507"
-    output_dir = "./voxtral-finetuned"
-    
-    # Set device
+    parser = argparse.ArgumentParser(description="Full fine-tune Voxtral for ASR")
+    parser.add_argument("--dataset-jsonl", type=str, default=None, help="Path to local JSONL with {audio_path, text}")
+    parser.add_argument("--dataset-name", type=str, default=None, help="HF dataset repo (if not using JSONL)")
+    parser.add_argument("--dataset-config", type=str, default=None, help="HF dataset config/subset")
+    parser.add_argument("--train-count", type=int, default=100, help="Number of training samples to use")
+    parser.add_argument("--eval-count", type=int, default=50, help="Number of eval samples to use")
+    parser.add_argument("--model-checkpoint", type=str, default="mistralai/Voxtral-Mini-3B-2507")
+    parser.add_argument("--output-dir", type=str, default="./voxtral-finetuned")
+    parser.add_argument("--batch-size", type=int, default=2)
+    parser.add_argument("--eval-batch-size", type=int, default=4)
+    parser.add_argument("--grad-accum", type=int, default=4)
+    parser.add_argument("--learning-rate", type=float, default=5e-5)
+    parser.add_argument("--epochs", type=float, default=3)
+    parser.add_argument("--logging-steps", type=int, default=10)
+    parser.add_argument("--save-steps", type=int, default=50)
+    args = parser.parse_args()
+
+    model_checkpoint = args.model_checkpoint
+    output_dir = args.output_dir
+
     torch_device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
     print(f"Using device: {torch_device}")
-    
-    # Load processor and model
+
     print("Loading processor and model...")
     processor = VoxtralProcessor.from_pretrained(model_checkpoint)
-    # Load model with LoRA configuration
-    config = LoraConfig( 
-        r=8,  # Rank of LoRA
-        lora_alpha=32,
-        lora_dropout=0.0,
-        bias="none",
-        target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
-        task_type="SEQ_2_SEQ_LM",
-    )
-    # print number of parameters in model
     model = VoxtralForConditionalGeneration.from_pretrained(
         model_checkpoint,
         torch_dtype=torch.bfloat16,
         device_map="auto"
     )
-    # Freeze the audio encoder model.audio_tower
-    for param in model.audio_tower.parameters():
-        param.requires_grad = False
-    
-    model = get_peft_model(model, config) 
-    model.print_trainable_parameters()
-    # Load and prepare dataset
-    train_dataset, eval_dataset = load_and_prepare_dataset()
-    
-    # Setup data collator
+
+    train_dataset, eval_dataset = load_and_prepare_dataset(
+        dataset_jsonl=args.dataset_jsonl,
+        dataset_name=args.dataset_name,
+        dataset_config=args.dataset_config,
+        train_count=args.train_count,
+        eval_count=args.eval_count,
+    )
+
     data_collator = VoxtralDataCollator(processor, model_checkpoint)
-    
-    # Simple training arguments
+
     training_args = TrainingArguments(
         output_dir=output_dir,
-        per_device_train_batch_size=2,
-        per_device_eval_batch_size=4,
-        gradient_accumulation_steps=4,
-        learning_rate=5e-5,
-        num_train_epochs=3,
+        per_device_train_batch_size=args.batch_size,
+        per_device_eval_batch_size=args.eval_batch_size,
+        gradient_accumulation_steps=args.grad_accum,
+        learning_rate=args.learning_rate,
+        num_train_epochs=args.epochs,
         bf16=True,
-        logging_steps=10,
-        eval_steps=50 if eval_dataset else None,
-        save_steps=50,
+        logging_steps=args.logging_steps,
+        eval_steps=args.save_steps if eval_dataset else None,
+        save_steps=args.save_steps,
         eval_strategy="steps" if eval_dataset else "no",
         save_strategy="steps",
         report_to="none",
         remove_unused_columns=False,
         dataloader_num_workers=1,
     )
-    
-    # Setup trainer
+
     trainer = Trainer(
         model=model,
         args=training_args,
@@ -178,22 +212,18 @@ def main():
         eval_dataset=eval_dataset,
         data_collator=data_collator,
     )
-    
-    # Start training
+
     print("Starting training...")
     trainer.train()
 
-    
-    # Save model and processor
     print(f"Saving model to {output_dir}")
     trainer.save_model()
     processor.save_pretrained(output_dir)
-    
-    # Final evaluation
+
     if eval_dataset:
         results = trainer.evaluate()
         print(f"Final evaluation results: {results}")
-    
+
     print("Training completed successfully!")
 
 if __name__ == "__main__":

train.py → scripts/train_lora.py

@@ -1,13 +1,17 @@
 #!/usr/bin/env python3
 
+import argparse
+import json
+from pathlib import Path
 import torch
-from datasets import load_dataset, Audio
+from datasets import load_dataset, Audio, Dataset
 from transformers import (
     VoxtralForConditionalGeneration,
     VoxtralProcessor,
     Trainer,
     TrainingArguments,
 )
+from peft import LoraConfig, get_peft_model
 
 
 class VoxtralDataCollator:
@@ -94,68 +98,128 @@ class VoxtralDataCollator:
 
         return batch
 
-def load_and_prepare_dataset():
-    """Load and prepare dataset for training."""
-    dataset_name = "hf-audio/esb-datasets-test-only-sorted"
-    dataset_config = "voxpopuli"
-    
-    print(f"Loading dataset: {dataset_name}/{dataset_config}")
-    dataset = load_dataset(dataset_name, dataset_config, split="test")
-    
-    # Cast audio to 16kHz (required for Voxtral)
-    dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))
-    
-    train_dataset = dataset.select(range(100))
-    eval_dataset = dataset.select(range(100, 150))
-    
+def _load_jsonl_dataset(jsonl_path: str) -> Dataset:
+    """Load local JSONL with fields {audio_path, text} into a Dataset with audio column."""
+    records = []
+    jsonl_file = Path(jsonl_path)
+    if not jsonl_file.exists():
+        raise FileNotFoundError(f"Dataset jsonl not found: {jsonl_path}")
+    with open(jsonl_file, "r", encoding="utf-8") as f:
+        for line in f:
+            if not line.strip():
+                continue
+            obj = json.loads(line)
+            audio_path = obj.get("audio_path") or obj.get("audio")
+            text = obj.get("text")
+            if not audio_path or text is None:
+                continue
+            records.append({"audio": audio_path, "text": text})
+    if not records:
+        raise ValueError("No valid records found in JSONL. Expect keys: audio_path, text")
+    ds = Dataset.from_list(records)
+    # Cast the audio column from file paths and resample to 16kHz
+    ds = ds.cast_column("audio", Audio(sampling_rate=16000))
+    return ds
+
+
+def load_and_prepare_dataset(dataset_jsonl: str | None, dataset_name: str | None, dataset_config: str | None,
+                             train_count: int, eval_count: int):
+    """Load and prepare dataset for training (JSONL or HF hub)."""
+    if dataset_jsonl:
+        print(f"Loading local JSONL dataset: {dataset_jsonl}")
+        ds = _load_jsonl_dataset(dataset_jsonl)
+    else:
+        ds_name = dataset_name or "hf-audio/esb-datasets-test-only-sorted"
+        ds_cfg = dataset_config or "voxpopuli"
+        print(f"Loading dataset: {ds_name}/{ds_cfg}")
+        ds = load_dataset(ds_name, ds_cfg, split="test")
+        ds = ds.cast_column("audio", Audio(sampling_rate=16000))
+
+    total = len(ds)
+    train_end = min(train_count, total)
+    eval_end = min(train_end + eval_count, total)
+    train_dataset = ds.select(range(train_end))
+    eval_dataset = ds.select(range(train_end, eval_end)) if eval_end > train_end else None
     return train_dataset, eval_dataset
 
 
 def main():
-    # Configuration
-    model_checkpoint = "mistralai/Voxtral-Mini-3B-2507"
-    output_dir = "./voxtral-finetuned"
-    
-    # Set device
+    parser = argparse.ArgumentParser(description="LoRA fine-tune Voxtral for ASR")
+    parser.add_argument("--dataset-jsonl", type=str, default=None, help="Path to local JSONL with {audio_path, text}")
+    parser.add_argument("--dataset-name", type=str, default=None, help="HF dataset repo (if not using JSONL)")
+    parser.add_argument("--dataset-config", type=str, default=None, help="HF dataset config/subset")
+    parser.add_argument("--train-count", type=int, default=100, help="Number of training samples to use")
+    parser.add_argument("--eval-count", type=int, default=50, help="Number of eval samples to use")
+    parser.add_argument("--model-checkpoint", type=str, default="mistralai/Voxtral-Mini-3B-2507")
+    parser.add_argument("--output-dir", type=str, default="./voxtral-finetuned")
+    parser.add_argument("--batch-size", type=int, default=2)
+    parser.add_argument("--eval-batch-size", type=int, default=4)
+    parser.add_argument("--grad-accum", type=int, default=4)
+    parser.add_argument("--learning-rate", type=float, default=5e-5)
+    parser.add_argument("--epochs", type=float, default=3)
+    parser.add_argument("--logging-steps", type=int, default=10)
+    parser.add_argument("--save-steps", type=int, default=50)
+    parser.add_argument("--lora-r", type=int, default=8)
+    parser.add_argument("--lora-alpha", type=int, default=32)
+    parser.add_argument("--lora-dropout", type=float, default=0.0)
+    parser.add_argument("--freeze-audio-tower", action="store_true", help="Freeze audio encoder parameters")
+    args = parser.parse_args()
+
+    model_checkpoint = args.model_checkpoint
+    output_dir = args.output_dir
+
     torch_device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
     print(f"Using device: {torch_device}")
-    
-    # Load processor and model
+
     print("Loading processor and model...")
     processor = VoxtralProcessor.from_pretrained(model_checkpoint)
-
+    lora_cfg = LoraConfig(
+        r=args.lora_r,
+        lora_alpha=args.lora_alpha,
+        lora_dropout=args.lora_dropout,
+        bias="none",
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
+        task_type="SEQ_2_SEQ_LM",
+    )
     model = VoxtralForConditionalGeneration.from_pretrained(
         model_checkpoint,
         torch_dtype=torch.bfloat16,
         device_map="auto"
     )
-    
-    # Load and prepare dataset
-    train_dataset, eval_dataset = load_and_prepare_dataset()
-    
-    # Setup data collator
+    if args.freeze_audio_tower:
+        for param in model.audio_tower.parameters():
+            param.requires_grad = False
+    model = get_peft_model(model, lora_cfg)
+    model.print_trainable_parameters()
+
+    train_dataset, eval_dataset = load_and_prepare_dataset(
+        dataset_jsonl=args.dataset_jsonl,
+        dataset_name=args.dataset_name,
+        dataset_config=args.dataset_config,
+        train_count=args.train_count,
+        eval_count=args.eval_count,
+    )
+
     data_collator = VoxtralDataCollator(processor, model_checkpoint)
-    
-    # Simple training arguments
+
     training_args = TrainingArguments(
         output_dir=output_dir,
-        per_device_train_batch_size=2,
-        per_device_eval_batch_size=4,
-        gradient_accumulation_steps=4,
-        learning_rate=5e-5,
-        num_train_epochs=3,
+        per_device_train_batch_size=args.batch_size,
+        per_device_eval_batch_size=args.eval_batch_size,
+        gradient_accumulation_steps=args.grad_accum,
+        learning_rate=args.learning_rate,
+        num_train_epochs=args.epochs,
         bf16=True,
-        logging_steps=10,
-        eval_steps=50 if eval_dataset else None,
-        save_steps=50,
+        logging_steps=args.logging_issues if hasattr(args, 'logging_issues') else args.logging_steps,
+        eval_steps=args.save_steps if eval_dataset else None,
+        save_steps=args.save_steps,
         eval_strategy="steps" if eval_dataset else "no",
         save_strategy="steps",
         report_to="none",
         remove_unused_columns=False,
         dataloader_num_workers=1,
     )
-    
-    # Setup trainer
+
     trainer = Trainer(
         model=model,
         args=training_args,
@@ -163,22 +227,18 @@ def main():
         eval_dataset=eval_dataset,
         data_collator=data_collator,
     )
-    
-    # Start training
+
     print("Starting training...")
     trainer.train()
 
-    
-    # Save model and processor
     print(f"Saving model to {output_dir}")
     trainer.save_model()
     processor.save_pretrained(output_dir)
-    
-    # Final evaluation
+
     if eval_dataset:
         results = trainer.evaluate()
         print(f"Final evaluation results: {results}")
-    
+
     print("Training completed successfully!")
 
 if __name__ == "__main__":

templates/datasets/readme.md

@@ -0,0 +1,171 @@
+---
+dataset_info:
+  features:
+  - name: experiment_id
+    dtype: string
+  - name: name
+    dtype: string
+  - name: description
+    dtype: string
+  - name: created_at
+    dtype: string
+  - name: status
+    dtype: string
+  - name: metrics
+    dtype: string
+  - name: parameters
+    dtype: string
+  - name: artifacts
+    dtype: string
+  - name: logs
+    dtype: string
+  - name: last_updated
+    dtype: string
+  splits:
+  - name: train
+    num_bytes: 4945
+    num_examples: 2
+  download_size: 15529
+  dataset_size: 4945
+configs:
+- config_name: default
+  data_files:
+  - split: train
+    path: data/train-*
+tags:
+- track tonic
+- tonic
+- experiment tracking
+- smollm3
+- fine-tuning
+- legml
+- hermes
+---
+
+# Trackio Experiments Dataset
+
+This dataset stores experiment tracking data for ML training runs, particularly focused on SmolLM3 fine-tuning experiments with comprehensive metrics tracking.
+
+## Dataset Structure
+
+The dataset contains the following columns:
+
+- **experiment_id**: Unique identifier for each experiment
+- **name**: Human-readable name for the experiment
+- **description**: Detailed description of the experiment
+- **created_at**: Timestamp when the experiment was created
+- **status**: Current status (running, completed, failed, paused)
+- **metrics**: JSON string containing training metrics over time
+- **parameters**: JSON string containing experiment configuration
+- **artifacts**: JSON string containing experiment artifacts
+- **logs**: JSON string containing experiment logs
+- **last_updated**: Timestamp of last update
+
+## Metrics Structure
+
+The metrics field contains JSON arrays with the following structure:
+
+```json
+[
+  {
+    "timestamp": "2025-07-20T11:20:01.780908",
+    "step": 25,
+    "metrics": {
+      "loss": 1.1659,
+      "accuracy": 0.759,
+      "learning_rate": 7e-08,
+      "grad_norm": 10.3125,
+      "epoch": 0.004851130919895701,
+      
+      // Advanced Training Metrics
+      "total_tokens": 1642080.0,
+      "truncated_tokens": 128,
+      "padding_tokens": 256,
+      "throughput": 3284160.0,
+      "step_time": 0.5,
+      "batch_size": 8,
+      "seq_len": 2048,
+      "token_acc": 0.759,
+      
+      // Custom Losses
+      "train/gate_ortho": 0.0234,
+      "train/center": 0.0156,
+      
+      // System Metrics
+      "gpu_memory_allocated": 17.202261447906494,
+      "gpu_memory_reserved": 75.474609375,
+      "gpu_utilization": 85.2,
+      "cpu_percent": 2.7,
+      "memory_percent": 10.1
+    }
+  }
+]
+```
+
+## Supported Metrics
+
+### Core Training Metrics
+- **loss**: Training loss value
+- **accuracy**: Model accuracy
+- **learning_rate**: Current learning rate
+- **grad_norm**: Gradient norm
+- **epoch**: Current epoch progress
+
+### Advanced Token Metrics
+- **total_tokens**: Total tokens processed in the batch
+- **truncated_tokens**: Number of tokens truncated during processing
+- **padding_tokens**: Number of padding tokens added
+- **throughput**: Tokens processed per second
+- **step_time**: Time taken for the current training step
+- **batch_size**: Current batch size
+- **seq_len**: Sequence length
+- **token_acc**: Token-level accuracy
+
+### Custom Losses (SmolLM3-specific)
+- **train/gate_ortho**: Gate orthogonality loss
+- **train/center**: Center loss component
+
+### System Performance Metrics
+- **gpu_memory_allocated**: GPU memory currently allocated (GB)
+- **gpu_memory_reserved**: GPU memory reserved (GB)
+- **gpu_utilization**: GPU utilization percentage
+- **cpu_percent**: CPU usage percentage
+- **memory_percent**: System memory usage percentage
+
+## Usage
+
+This dataset is automatically used by the Trackio monitoring system to store and retrieve experiment data. It provides persistent storage for experiment tracking across different training runs.
+
+## Integration
+
+The dataset is used by:
+- Trackio Spaces for experiment visualization
+- Training scripts for logging metrics and parameters
+- Monitoring systems for experiment tracking
+- SmolLM3 fine-tuning pipeline for comprehensive metrics capture
+
+## Privacy
+
+This dataset is private by default to ensure experiment data security. Only users with appropriate permissions can access the data.
+
+## Examples
+
+### Sample Experiment Entry
+```json
+{
+  "experiment_id": "exp_20250720_130853",
+  "name": "smollm3_finetune",
+  "description": "SmolLM3 fine-tuning experiment with comprehensive metrics",
+  "created_at": "2025-07-20T11:20:01.780908",
+  "status": "running",
+  "metrics": "[{\"timestamp\": \"2025-07-20T11:20:01.780908\", \"step\": 25, \"metrics\": {\"loss\": 1.1659, \"accuracy\": 0.759, \"total_tokens\": 1642080.0, \"throughput\": 3284160.0, \"train/gate_ortho\": 0.0234, \"train/center\": 0.0156}}]",
+  "parameters": "{\"model_name\": \"HuggingFaceTB/SmolLM3-3B\", \"batch_size\": 8, \"learning_rate\": 3.5e-06, \"max_seq_length\": 12288}",
+  "artifacts": "[]",
+  "logs": "[]",
+  "last_updated": "2025-07-20T11:20:01.780908"
+}
+```
+
+## License
+
+This dataset is part of the Trackio experiment tracking system and follows the same license as the main project.

templates/model_card.md

@@ -0,0 +1,345 @@
+---
+language:
+- en
+- fr
+license: apache-2.0
+library_name: transformers
+tags:
+- smollm3
+- fine-tuned
+- causal-lm
+- text-generation
+- tonic
+- legml
+{{#if quantized_models}}- quantized{{/if}}
+pipeline_tag: text-generation
+base_model: {{base_model}}
+{{#if dataset_name}}
+datasets:
+- {{dataset_name}}
+{{/if}}
+{{#if quantized_models}}
+model-index:
+- name: {{model_name}}
+  results:
+  - task:
+      type: text-generation
+    dataset:
+      name: {{dataset_name}}
+      type: {{dataset_name}}
+    metrics:
+    - name: Training Loss
+      type: loss
+      value: "{{training_loss|default:'N/A'}}"
+    - name: Validation Loss
+      type: loss
+      value: "{{validation_loss|default:'N/A'}}"
+    - name: Perplexity
+      type: perplexity
+      value: "{{perplexity|default:'N/A'}}"
+- name: {{model_name}} (int8 quantized)
+  results:
+  - task:
+      type: text-generation
+    dataset:
+      name: {{dataset_name}}
+      type: {{dataset_name}}
+    metrics:
+    - name: Memory Reduction
+      type: memory_efficiency
+      value: "~50%"
+    - name: Inference Speed
+      type: speed
+      value: "Faster"
+- name: {{model_name}} (int4 quantized)
+  results:
+  - task:
+      type: text-generation
+    dataset:
+      name: {{dataset_name}}
+      type: {{dataset_name}}
+    metrics:
+    - name: Memory Reduction
+      type: memory_efficiency
+      value: "~75%"
+    - name: Inference Speed
+      type: speed
+      value: "Significantly Faster"
+{{else}}
+model-index:
+- name: {{model_name}}
+  results:
+  - task:
+      type: text-generation
+    dataset:
+      name: {{dataset_name}}
+      type: {{dataset_name}}
+    metrics:
+    - name: Training Loss
+      type: loss
+      value: "{{training_loss|default:'N/A'}}"
+    - name: Validation Loss
+      type: loss
+      value: "{{validation_loss|default:'N/A'}}"
+    - name: Perplexity
+      type: perplexity
+      value: "{{perplexity|default:'N/A'}}"
+{{/if}}
+{{#if author_name}}
+author: {{author_name}}
+{{/if}}
+{{#if experiment_name}}
+experiment_name: {{experiment_name}}
+{{/if}}
+{{#if trackio_url}}
+trackio_url: {{trackio_url}}
+{{/if}}
+{{#if dataset_repo}}
+dataset_repo: {{dataset_repo}}
+{{/if}}
+{{#if hardware_info}}
+hardware: "{{hardware_info}}"
+{{/if}}
+{{#if training_config_type}}
+training_config: {{training_config_type}}
+{{/if}}
+{{#if trainer_type}}
+trainer_type: {{trainer_type}}
+{{/if}}
+{{#if batch_size}}
+batch_size: {{batch_size}}
+{{/if}}
+{{#if learning_rate}}
+learning_rate: {{learning_rate}}
+{{/if}}
+{{#if max_epochs}}
+max_epochs: {{max_epochs}}
+{{/if}}
+{{#if max_seq_length}}
+max_seq_length: {{max_seq_length}}
+{{/if}}
+{{#if dataset_sample_size}}
+dataset_sample_size: {{dataset_sample_size}}
+{{/if}}
+{{#if dataset_size}}
+dataset_size: {{dataset_size}}
+{{/if}}
+{{#if dataset_format}}
+dataset_format: {{dataset_format}}
+{{/if}}
+{{#if gradient_accumulation_steps}}
+gradient_accumulation_steps: {{gradient_accumulation_steps}}
+{{/if}}
+---
+
+# {{model_name}}
+
+{{model_description}}
+
+## Model Details
+
+- **Base Model**: SmolLM3-3B
+- **Model Type**: Causal Language Model
+- **Languages**: English, French
+- **License**: Apache 2.0
+- **Fine-tuned**: Yes
+{{#if quantized_models}}
+- **Quantized Versions**: Available in subdirectories
+{{/if}}
+
+## Usage
+
+### Main Model
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# Load the main model
+model = AutoModelForCausalLM.from_pretrained(
+    "{{repo_name}}",
+    device_map="auto",
+    torch_dtype=torch.bfloat16
+)
+tokenizer = AutoTokenizer.from_pretrained("{{repo_name}}")
+
+# Generate text
+input_text = "What are we having for dinner?"
+input_ids = tokenizer(input_text, return_tensors="pt").to(model.device.type)
+output = model.generate(**input_ids, max_new_tokens=50)
+print(tokenizer.decode(output[0], skip_special_tokens=True))
+```
+
+## Training Information
+
+### Training Configuration
+- **Base Model**: {{base_model}}
+- **Dataset**: {{dataset_name}}
+- **Training Config**: {{training_config_type}}
+- **Trainer Type**: {{trainer_type}}
+{{#if dataset_sample_size}}
+- **Dataset Sample Size**: {{dataset_sample_size}}
+{{/if}}
+
+### Training Parameters
+- **Batch Size**: {{batch_size}}
+- **Gradient Accumulation**: {{gradient_accumulation_steps}}
+- **Learning Rate**: {{learning_rate}}
+- **Max Epochs**: {{max_epochs}}
+- **Sequence Length**: {{max_seq_length}}
+
+### Training Infrastructure
+- **Hardware**: {{hardware_info}}
+- **Monitoring**: Trackio integration
+- **Experiment**: {{experiment_name}}
+
+## Model Architecture
+
+This is a fine-tuned version of the SmolLM3-3B model with the following specifications:
+
+- **Base Model**: SmolLM3-3B
+- **Parameters**: ~3B
+- **Context Length**: {{max_seq_length}}
+- **Languages**: English, French
+- **Architecture**: Transformer-based causal language model
+
+## Performance
+
+The model provides:
+- **Text Generation**: High-quality text generation capabilities
+- **Conversation**: Natural conversation abilities
+- **Multilingual**: Support for English and French
+{{#if quantized_models}}
+- **Quantized Versions**: Optimized for different deployment scenarios
+{{/if}}
+
+## Limitations
+
+1. **Context Length**: Limited by the model's maximum sequence length
+2. **Bias**: May inherit biases from the training data
+3. **Factual Accuracy**: May generate incorrect or outdated information
+4. **Safety**: Should be used responsibly with appropriate safeguards
+{{#if quantized_models}}
+5. **Quantization**: Quantized versions may have slightly reduced accuracy
+{{/if}}
+
+## Training Data
+
+The model was fine-tuned on:
+- **Dataset**: {{dataset_name}}
+- **Size**: {{dataset_size}}
+- **Format**: {{dataset_format}}
+- **Languages**: English, French
+
+## Evaluation
+
+The model was evaluated using:
+- **Metrics**: Loss, perplexity, and qualitative assessment
+- **Monitoring**: Real-time tracking via Trackio
+- **Validation**: Regular validation during training
+
+## Citation
+
+If you use this model in your research, please cite:
+
+```bibtex
+@misc{{{model_name_slug}},
+  title={{{{model_name}}}},
+  author={{{author_name}}},
+  year={2024},
+  url={https://huggingface.co/{{repo_name}}}
+}
+```
+
+## License
+
+This model is licensed under the Apache 2.0 License.
+
+## Acknowledgments
+
+- **Base Model**: SmolLM3-3B by HuggingFaceTB
+- **Training Framework**: PyTorch, Transformers, PEFT
+- **Monitoring**: Trackio integration
+- **Quantization**: torchao library
+
+## Support
+
+For questions and support:
+- Open an issue on the Hugging Face repository
+- Check the model documentation
+- Review the training logs and configuration
+
+## Repository Structure
+
+```
+{{repo_name}}/
+├── README.md (this file)
+├── config.json
+├── pytorch_model.bin
+├── tokenizer.json
+└── tokenizer_config.json
+```
+
+## Usage Examples
+
+### Text Generation
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("{{repo_name}}")
+tokenizer = AutoTokenizer.from_pretrained("{{repo_name}}")
+
+text = "The future of artificial intelligence is"
+inputs = tokenizer(text, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=100)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+### Conversation
+```python
+def chat_with_model(prompt, max_length=100):
+    inputs = tokenizer(prompt, return_tensors="pt")
+    outputs = model.generate(**inputs, max_new_tokens=max_length)
+    return tokenizer.decode(outputs[0], skip_special_tokens=True)
+
+response = chat_with_model("Hello, how are you today?")
+print(response)
+```
+
+### Advanced Usage
+```python
+# With generation parameters
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=100,
+    temperature=0.7,
+    top_p=0.9,
+    do_sample=True,
+    pad_token_id=tokenizer.eos_token_id
+)
+```
+
+## Monitoring and Tracking
+
+This model was trained with comprehensive monitoring:
+- **Trackio Space**: {{trackio_url}}
+- **Experiment**: {{experiment_name}}
+- **Dataset Repository**: https://huggingface.co/datasets/{{dataset_repo}}
+- **Training Logs**: Available in the experiment data
+
+## Deployment
+
+### Requirements
+```bash
+pip install torch transformers accelerate
+{{#if quantized_models}}
+pip install torchao  # For quantized models
+{{/if}}
+```
+
+### Hardware Requirements
+- **Main Model**: GPU with 8GB+ VRAM recommended
+
+## Changelog
+
+- **v1.0.0**: Initial release with fine-tuned model

templates/spaces/demo_voxtral/README.md

@@ -0,0 +1,23 @@
+---
+title: Voxtral ASR Demo
+emoji: 🎙️
+colorFrom: indigo
+colorTo: cyan
+sdk: gradio
+sdk_version: 5.42.0
+app_file: app.py
+pinned: false
+short_description: Interactive ASR demo for a fine-tuned Voxtral model
+---
+This Space serves a Voxtral ASR model for speech-to-text transcription.
+Usage:
+
+- Click Record and read the displayed phrase aloud.
+- Stop recording to see the transcription.
+- Works best with ~16 kHz audio; internal processing follows Voxtral's processor expectations.
+
+Environment variables expected:
+
+- `HF_MODEL_ID`: The model repo to load (e.g., `username/voxtral-finetune-YYYYMMDD_HHMMSS`)
+- `MODEL_NAME`: Display name
+- `HF_USERNAME`: For branding

templates/spaces/demo_voxtral/app.py

@@ -0,0 +1,35 @@
+import os
+import gradio as gr
+import torch
+from transformers import AutoProcessor, AutoModelForSeq2SeqLM
+
+HF_MODEL_ID = os.getenv("HF_MODEL_ID", "mistralai/Voxtral-Mini-3B-2507")
+MODEL_NAME = os.getenv("MODEL_NAME", HF_MODEL_ID.split("/")[-1])
+HF_USERNAME = os.getenv("HF_USERNAME", "")
+
+processor = AutoProcessor.from_pretrained(HF_MODEL_ID)
+model = AutoModelForSeq2SeqLM.from_pretrained(HF_MODEL_ID, device_map="auto", torch_dtype=torch.bfloat16)
+
+def transcribe(audio_tuple):
+    if audio_tuple is None:
+        return "No audio provided"
+    sr, data = audio_tuple
+    inputs = processor.apply_transcription_request(language="en", model_id=HF_MODEL_ID, audio=[data], format=["WAV"], return_tensors="pt")
+    inputs = {k: (v.to(model.device) if hasattr(v, 'to') else v) for k, v in inputs.items()}
+    with torch.no_grad():
+        output_ids = model.generate(**inputs, max_new_tokens=256)
+    # Voxtral returns full sequence; decode and strip special tokens
+    text = processor.tokenizer.decode(output_ids[0], skip_special_tokens=True)
+    return text
+
+with gr.Blocks() as demo:
+    gr.Markdown(f"# 🎙️ Voxtral ASR Demo — {MODEL_NAME}")
+    audio = gr.Audio(sources="microphone", type="numpy", label="Record or upload audio")
+    btn = gr.Button("Transcribe")
+    out = gr.Textbox(label="Transcription", lines=4)
+    btn.click(transcribe, inputs=[audio], outputs=[out])
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)
+
+

templates/spaces/demo_voxtral/requirements.txt

@@ -0,0 +1,7 @@
+gradio>=5.38.2
+torch
+transformers
+datasets
+soundfile
+librosa
+