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.

6.8 KB
Raw Blame
"""Pure helpers behind ``soup rewind`` — spike detection and row ranking.

No heavy imports at module scope: ``soup rewind`` is a light command, and the
only thing here that needs the training stack (rebuilding the dataset for row
previews) imports it inside the function.
"""

from __future__ import annotations

import json
import math
from dataclasses import dataclass
from statistics import median
from typing import TYPE_CHECKING, Any, Mapping, Sequence

if TYPE_CHECKING:  # pragma: no cover - typing only
    from soup_cli.monitoring.rewind_log import RewindRun

# A ratio spike needs a baseline that is actually a baseline. Two points is a
# line through any two losses; three is the smallest window whose median is not
# simply one of the two values it sits between.
MIN_BASELINE = 3


@dataclass(frozen=True)
class Spike:
    step: int
    loss: float
    baseline: float
    ratio: float
    severity: str


@dataclass(frozen=True)
class RankedRow:
    row: int
    loss: float
    tokens: int
    share: float


def find_spikes(run: RewindRun, *, window: int = 20, factor: float = 2.0) -> list[Spike]:
    """Steps whose loss went non-finite, or past ``factor`` x the recent median.

    Walks ``run.steps()`` in order and carries a rolling history of the last
    ``window`` MEASURED, finite step losses.

    A step whose ``step_loss`` is ``None`` is unmeasured — no batches, or no
    supervised tokens in the ones it has. It is neither reported as a spike nor
    allowed into the baseline: counting it as ``0.0`` would drag the median
    down and manufacture spikes out of the ordinary steps after it.

    A non-finite loss fires regardless of how much history there is (there is
    no recovering from a NaN), with ``ratio`` at infinity; a ratio spike needs
    at least :data:`MIN_BASELINE` finite values behind it. The comparison is
    strict: a step exactly at ``factor`` x baseline is not a spike.

    Returned worst-first: every critical before every warning, then by ratio
    descending.
    """
    history: list[float] = []
    spikes: list[Spike] = []

    for step in run.steps():
        loss = run.step_loss(step)
        if loss is None:
            continue

        if not math.isfinite(loss):
            recent = history[-window:]
            spikes.append(
                Spike(
                    step=step,
                    loss=loss,
                    baseline=median(recent) if recent else math.nan,
                    ratio=math.inf,
                    severity="critical",
                )
            )
            # Deliberately NOT appended to history: a NaN median would poison
            # every later comparison.
            continue

        recent = history[-window:]
        if len(recent) >= MIN_BASELINE:
            baseline = median(recent)
            if loss > factor * baseline:
                spikes.append(
                    Spike(
                        step=step,
                        loss=loss,
                        baseline=baseline,
                        ratio=(loss / baseline) if baseline else math.inf,
                        severity="warning",
                    )
                )
        history.append(loss)

    spikes.sort(key=lambda s: (0 if s.severity == "critical" else 1, -s.ratio))
    return spikes


def rank_rows(run: RewindRun, step: int) -> list[RankedRow]:
    """Every row of every micro-batch of ``step``, by share of the step's loss.

    ``share`` is ``loss * tokens`` over the step's total, because the row that
    moved the optimizer is the one that carried the loss, not the one with the
    largest per-token mean. A non-finite loss (the log stores one as NaN)
    contributes 0 to the total, so the shares of the finite rows still sum to 1
    and an infinite loss cannot turn every share into NaN; the row is reported
    with its non-finite loss rather than smoothed away, and it is listed FIRST:
    it has no share to rank by, and last place at 0.0% buried the one row the
    step blew up on. A step with no supervised tokens gives every row 0.0.
    """
    entries: list[tuple[int, float, int]] = []
    for batch in run.batches_for(step):
        for row, loss, tokens in zip(batch.rows, batch.row_loss, batch.row_tokens):
            entries.append((int(row), float(loss), int(tokens)))

    weights = [loss * tokens if math.isfinite(loss) else 0.0 for _, loss, tokens in entries]
    total = sum(weights)

    ranked = [
        RankedRow(
            row=row,
            loss=loss,
            tokens=tokens,
            share=(weight / total) if total else 0.0,
        )
        for (row, loss, tokens), weight in zip(entries, weights)
    ]
    ranked.sort(key=lambda r: (math.isfinite(r.loss), -r.share, r.row))
    return ranked


def _preview_text(row: Any, width: int) -> str:
    """One dataset row as a single collapsed line of at most ``width`` chars."""
    text: Any = None
    if isinstance(row, Mapping):
        messages = row.get("messages")
        if isinstance(messages, Sequence) and not isinstance(messages, (str, bytes)):
            if messages and isinstance(messages[-1], Mapping):
                text = messages[-1].get("content")
        if text is None:
            text = row.get("text") or row.get("output")
    if text is None:
        text = json.dumps(row, ensure_ascii=False, default=str)

    collapsed = " ".join(str(text).split())
    if len(collapsed) > width:
        return collapsed[:width] + "…"
    return collapsed


def load_row_previews(
    config: dict,
    row_ids: Sequence[int],
    *,
    expected_fingerprint: str,
    width: int = 80,
) -> dict[int, str] | None:
    """Rebuild this run's training rows and preview the ones in ``row_ids``.

    Returns ``None`` — and previews nothing — when the rebuilt list does not
    fingerprint to ``expected_fingerprint``. The row indices in the log are
    positions in the list the trainer saw; against a dataset that has since
    been edited they point at whatever now sits at that position, which is a
    confident answer about the wrong row.

    Heavy: this is the one function here that loads the data stack, so the
    imports stay inside it.
    """
    from soup_cli.config.schema import SoupConfig
    from soup_cli.data.loader import load_dataset
    from soup_cli.monitoring.rewind_log import dataset_fingerprint

    cfg = SoupConfig.model_validate(config)
    # Exactly what `soup train` calls for an SFT run: preserve_source_columns
    # is GRPO-only, and the rewind log is written for SFT.
    rows = load_dataset(cfg.data)["train"]

    if dataset_fingerprint(rows) != expected_fingerprint:
        return None

    previews: dict[int, str] = {}
    for raw_id in row_ids:
        row_id = int(raw_id)
        if 0 <= row_id < len(rows):
            previews[row_id] = _preview_text(rows[row_id], width)
        else:
            previews[row_id] = "<row not in dataset>"
    return previews