Skip to content

armgit / Soup

Public Imported from GitHub
0

Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.

8.4 KB
Raw Blame
"""soup autopilot — zero-config fine-tuning (Part H of v0.25.0)."""

from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Optional

import typer
from rich.console import Console
from rich.panel import Panel
from rich.prompt import Prompt

from soup_cli.autopilot.analyzer import (
    analyze_dataset,
    analyze_hardware,
    analyze_model,
)
from soup_cli.autopilot.decisions import (
    GOAL_TO_TASK,
    kernel_flag_notes,
    parse_gpu_budget,
)
from soup_cli.autopilot.generate_config import build_soup_config, write_yaml
from soup_cli.config.schema import SFT_KERNEL_AWARE_TASKS
from soup_cli.utils.terminal import for_terminal
from soup_cli.utils.typer_compat import MissingParameter

console = Console()


def _is_under_cwd(path: Path) -> bool:
    """Check whether ``path`` resolves inside the current working directory.

    Uses ``os.path.realpath`` for both sides instead of ``Path.resolve()``.
    On Windows + Python 3.9, ``Path.resolve()`` occasionally leaves 8.3 short
    names (e.g. ``C:\\Users\\RUNNER~1``) in one of the two paths but not the
    other, making ``relative_to`` fail even when the paths refer to the same
    location. ``realpath`` handles the short-name expansion consistently.
    """
    try:
        resolved = os.path.realpath(str(path))
        cwd = os.path.realpath(str(Path.cwd()))
    except (OSError, ValueError):
        return False
    if os.name == "nt":
        resolved = resolved.lower()
        cwd = cwd.lower()
    try:
        common = os.path.commonpath([resolved, cwd])
    except ValueError:
        return False
    return common == cwd


def _kernel_display(enabled: bool, note: str | None) -> str:
    """One Autopilot Decisions kernel entry; name a missing package (#1212).

    The flag alone reads like a decision to skip a speedup; when the GPU
    qualifies and the package simply isn't there, say so instead.
    """
    if not enabled and note:
        return f"off ({for_terminal(note)})"
    return str(enabled)


def _stdin_isatty() -> bool:
    """True when standard input is an interactive terminal."""
    return sys.stdin.isatty()


def _param_by_name(ctx: typer.Context, name: str) -> object | None:
    """Find a Click Parameter on the command by its argument name."""
    for param in ctx.command.params:
        if param.name == name:
            return param
    return None


def autopilot_cmd(
    ctx: typer.Context,
    model: Optional[str] = typer.Option(
        None, "--model", "-m", help="Base model (HF model id)",
    ),
    data: Optional[str] = typer.Option(
        None, "--data", "-d", help="Dataset path (JSONL)",
    ),
    goal: Optional[str] = typer.Option(
        None,
        "--goal",
        "-g",
        help=(
            "Goal: chat | reasoning | code | classification | tool-calling | "
            "alignment | domain-adapt"
        ),
    ),
    gpu_budget: str = typer.Option(
        "", "--gpu-budget", help="VRAM budget, e.g. 24GB (default: auto-detect)",
    ),
    output: str = typer.Option(
        "soup.yaml", "--output", "-o", help="Output config path",
    ),
    dry_run: bool = typer.Option(
        False, "--dry-run", help="Show decisions but don't write the config",
    ),
    yes: bool = typer.Option(
        False, "--yes", "-y", help="Skip confirmation prompts",
    ),
) -> None:
    """Autopilot: give model+data+goal, Soup picks optimal hyperparameters."""
    if not _stdin_isatty():
        if model is None:
            raise MissingParameter(ctx=ctx, param=_param_by_name(ctx, "model"))
        if data is None:
            raise MissingParameter(ctx=ctx, param=_param_by_name(ctx, "data"))
        if goal is None:
            raise MissingParameter(ctx=ctx, param=_param_by_name(ctx, "goal"))

    if model is None:
        model = Prompt.ask("Base model (HF model id)")
    if not model or not model.strip():
        console.print("[red]Base model cannot be empty.[/]")
        raise typer.Exit(1)
    model = model.strip()

    if data is None:
        data = Prompt.ask("Dataset path (JSONL)")
    if not data or not data.strip():
        console.print("[red]Dataset path cannot be empty.[/]")
        raise typer.Exit(1)
    data = data.strip()

    if goal is None:
        goal = Prompt.ask(
            "Goal",
            choices=sorted(GOAL_TO_TASK.keys()),
            default="chat",
        )

    if goal not in GOAL_TO_TASK:
        console.print(
            f"[red]Unknown goal '{goal}'. "
            f"Options: {', '.join(sorted(GOAL_TO_TASK.keys()))}[/]"
        )
        raise typer.Exit(1)

    # Path traversal protection — data must stay under cwd
    data_path = Path(data)
    if not _is_under_cwd(data_path):
        console.print("[red]Data path must be under the current working directory.[/]")
        raise typer.Exit(1)
    data_path = Path(os.path.realpath(str(data_path)))

    if not data_path.exists():
        console.print(f"[red]Data file not found: {data_path}[/]")
        raise typer.Exit(1)

    # GPU budget
    vram_gb: float | None = None
    if gpu_budget:
        try:
            vram_gb = parse_gpu_budget(gpu_budget)
        except ValueError as exc:
            console.print(f"[red]{exc}[/]")
            raise typer.Exit(1)

    # Analyze
    console.print("[dim]Analyzing dataset, model, and hardware...[/]")
    try:
        dataset_profile = analyze_dataset(str(data_path))
    except ValueError as exc:
        console.print(f"[red]{exc}[/]")
        raise typer.Exit(1)
    model_profile = analyze_model(model)
    hardware_profile = analyze_hardware()

    effective_vram = vram_gb if vram_gb is not None else max(hardware_profile.vram_gb, 8.0)

    try:
        cfg = build_soup_config(
            model=model,
            data_path=str(data_path),
            goal=goal,
            vram_gb=effective_vram,
        )
    except ValueError as exc:
        console.print(f"[red]{exc}[/]")
        raise typer.Exit(1)

    # #1212 — when the GPU qualifies but a package is missing, the panel names
    # it. Only the SFT-family tasks read either flag (#806), so a note next to
    # any other task's off-flag would be misleading (it is off by task scope).
    kernel_notes = (
        kernel_flag_notes(hardware_profile.compute_capability)
        if cfg.task in SFT_KERNEL_AWARE_TASKS
        else {"flash_attn": None, "liger": None}
    )

    # Render decision summary
    console.print(
        Panel(
            f"Dataset:    {data_path.name}\n"
            f"  format:   {dataset_profile.format}\n"
            f"  samples:  {dataset_profile.samples:,}\n"
            f"  tokens:   avg {dataset_profile.avg_tokens}, p95 {dataset_profile.p95_tokens}\n"
            f"  quality:  {dataset_profile.quality}\n\n"
            f"Model:      {model_profile.name}\n"
            f"  params:   {model_profile.params_b:.1f}B\n"
            f"  context:  {model_profile.context}\n\n"
            f"Hardware:   {hardware_profile.gpu_name}\n"
            f"  vram:     {hardware_profile.vram_gb:.1f}GB (budget: {effective_vram:.1f}GB)\n\n"
            f"Goal:       {goal} -> task: {cfg.task}",
            title="Soup Autopilot",
        )
    )
    console.print(
        Panel(
            f"Quantization: {cfg.training.quantization}\n"
            f"PEFT: LoRA r={cfg.training.lora.r}, alpha={cfg.training.lora.alpha}\n"
            f"Batch size: {cfg.training.batch_size} x grad_accum "
            f"{cfg.training.gradient_accumulation_steps}\n"
            f"Learning rate: {cfg.training.lr}\n"
            f"Epochs: {cfg.training.epochs}\n"
            f"Max length: {cfg.data.max_length}\n"
            f"Flash Attention: "
            f"{_kernel_display(cfg.training.use_flash_attn, kernel_notes['flash_attn'])}\n"
            f"Liger Kernel: "
            f"{_kernel_display(cfg.training.use_liger, kernel_notes['liger'])}",
            title="Autopilot Decisions",
        )
    )

    if dry_run:
        console.print("[dim]--dry-run: config not written.[/]")
        return

    # Path traversal protection for output
    output_raw = Path(output)
    if not _is_under_cwd(output_raw):
        console.print("[red]Output path must be under the current working directory.[/]")
        raise typer.Exit(1)
    output_path = Path(os.path.realpath(str(output_raw)))

    if output_path.exists() and not yes:
        if not typer.confirm(f"{output_path} exists. Overwrite?"):
            raise typer.Exit()

    write_yaml(cfg, output_path)
    console.print(f"[green]Config written:[/] {output_path}")