feat: add early stopping recommendation engine

- EarlyStopping class with configurable patience and min_delta
- Supports min/max mode optimization
- recommend_patience() heuristic for loss curves
- 22 new tests (150 total)

Closes #2

Author: 1

src/trainpulse/__init__.py

@@ -10,16 +10,20 @@
     TrainpulseError,
 )
 from trainpulse.callbacks import TrainingCallback
+from trainpulse.early_stopping import EarlyStopping, EarlyStopResult, recommend_patience
 from trainpulse.monitor import Monitor
 
 __all__ = [
     "Alert",
     "AlertSeverity",
+    "EarlyStopping",
+    "EarlyStopResult",
     "MetricSnapshot",
     "MetricType",
     "Monitor",
     "MonitorConfig",
     "TrainingCallback",
     "TrainingReport",
     "TrainpulseError",
+    "recommend_patience",
 ]

src/trainpulse/early_stopping.py

@@ -0,0 +1,162 @@
+"""Early stopping recommendation engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Literal
+
+
+@dataclass
+class EarlyStopResult:
+    """Result from a single early-stopping step."""
+
+    step: int
+    value: float
+    should_stop: bool
+    improved: bool
+    best_value: float
+    best_step: int
+
+
+class EarlyStopping:
+    """Track a metric and recommend when to stop training.
+
+    Parameters
+    ----------
+    patience:
+        Number of steps without improvement before recommending stop.
+    min_delta:
+        Minimum change from the best value to count as an improvement.
+    metric:
+        Name of the metric being tracked (informational).
+    mode:
+        ``"min"`` treats lower values as better; ``"max"`` treats higher as better.
+    """
+
+    def __init__(
+        self,
+        patience: int = 5,
+        min_delta: float = 0.001,
+        metric: str = "loss",
+        mode: Literal["min", "max"] = "min",
+    ) -> None:
+        if patience < 1:
+            raise ValueError("patience must be >= 1")
+        if mode not in ("min", "max"):
+            raise ValueError("mode must be 'min' or 'max'")
+        self._patience = patience
+        self._min_delta = abs(min_delta)
+        self._metric = metric
+        self._mode = mode
+
+        self._best_value: float | None = None
+        self._best_step: int = 0
+        self._current_step: int = 0
+        self._steps_without_improvement: int = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def step(self, value: float) -> EarlyStopResult:
+        """Record a new metric value and return the stop recommendation."""
+        step_idx = self._current_step
+        self._current_step += 1
+
+        improved = self._is_improvement(value)
+        if improved:
+            self._best_value = value
+            self._best_step = step_idx
+            self._steps_without_improvement = 0
+        else:
+            self._steps_without_improvement += 1
+
+        return EarlyStopResult(
+            step=step_idx,
+            value=value,
+            should_stop=self._steps_without_improvement >= self._patience,
+            improved=improved,
+            best_value=self._best_value,  # type: ignore[arg-type]
+            best_step=self._best_step,
+        )
+
+    @property
+    def should_stop(self) -> bool:
+        """``True`` if patience has been exhausted."""
+        return self._steps_without_improvement >= self._patience
+
+    @property
+    def best_value(self) -> float | None:
+        """Best metric value observed so far, or ``None`` if no values logged."""
+        return self._best_value
+
+    @property
+    def best_step(self) -> int:
+        """Step index where the best value was recorded."""
+        return self._best_step
+
+    @property
+    def steps_without_improvement(self) -> int:
+        return self._steps_without_improvement
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _is_improvement(self, value: float) -> bool:
+        if self._best_value is None:
+            return True
+        if self._mode == "min":
+            return value < self._best_value - self._min_delta
+        return value > self._best_value + self._min_delta
+
+
+def recommend_patience(loss_history: List[float]) -> int:
+    """Heuristic that recommends a patience value from a loss curve.
+
+    The recommendation is based on the typical gap (in steps) between
+    successive improvements and the relative amplitude of those
+    improvements.  A noisier curve with infrequent improvements gets a
+    higher patience so the run isn't killed prematurely.
+
+    Parameters
+    ----------
+    loss_history:
+        Sequence of loss values (one per step), assumed to be in temporal
+        order.
+
+    Returns
+    -------
+    int
+        Recommended patience (always >= 1).
+    """
+    if len(loss_history) < 2:
+        return 5  # sensible default
+
+    # Find steps where a new minimum was reached.
+    improvement_gaps: list[int] = []
+    best = loss_history[0]
+    last_improvement_step = 0
+
+    for i in range(1, len(loss_history)):
+        if loss_history[i] < best:
+            gap = i - last_improvement_step
+            improvement_gaps.append(gap)
+            best = loss_history[i]
+            last_improvement_step = i
+
+    if not improvement_gaps:
+        # No improvements at all — recommend a conservative patience equal
+        # to half the history length (at least 5).
+        return max(5, len(loss_history) // 2)
+
+    mean_gap = sum(improvement_gaps) / len(improvement_gaps)
+    max_gap = max(improvement_gaps)
+
+    # Blend average and max gap so patience tolerates occasional long dry
+    # spells.  The multiplier (1.5×) provides a safety margin.
+    patience = int(0.5 * mean_gap + 0.5 * max_gap) + 1
+    patience = int(patience * 1.5)
+
+    # Clamp to a reasonable range.
+    return max(3, min(patience, len(loss_history)))

tests/test_early_stopping.py

@@ -0,0 +1,190 @@
+"""Tests for the early stopping recommendation engine."""
+
+from __future__ import annotations
+
+import pytest
+
+from trainpulse.early_stopping import EarlyStopping, EarlyStopResult, recommend_patience
+
+
+# ──────────────────────────────────────────────────────────────────────
+# EarlyStopResult dataclass
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestEarlyStopResult:
+    def test_fields(self):
+        r = EarlyStopResult(step=0, value=0.5, should_stop=False, improved=True, best_value=0.5, best_step=0)
+        assert r.step == 0
+        assert r.value == 0.5
+        assert r.should_stop is False
+        assert r.improved is True
+        assert r.best_value == 0.5
+        assert r.best_step == 0
+
+
+# ──────────────────────────────────────────────────────────────────────
+# EarlyStopping — core behaviour
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestEarlyStoppingMinMode:
+    def test_first_step_always_improves(self):
+        es = EarlyStopping(patience=3, min_delta=0.0)
+        r = es.step(1.0)
+        assert r.improved is True
+        assert r.should_stop is False
+        assert r.best_value == 1.0
+        assert r.best_step == 0
+
+    def test_monotonic_decrease_never_stops(self):
+        es = EarlyStopping(patience=3, min_delta=0.0)
+        for i in range(20):
+            r = es.step(1.0 - i * 0.01)
+        assert r.should_stop is False
+        assert es.should_stop is False
+
+    def test_patience_exhausted(self):
+        es = EarlyStopping(patience=3, min_delta=0.0)
+        es.step(1.0)  # best
+        es.step(1.1)
+        es.step(1.2)
+        r = es.step(1.3)  # 3rd non-improvement → stop
+        assert r.should_stop is True
+        assert es.should_stop is True
+
+    def test_improvement_resets_counter(self):
+        es = EarlyStopping(patience=3, min_delta=0.0)
+        es.step(1.0)
+        es.step(1.1)  # +1
+        es.step(1.2)  # +2
+        es.step(0.5)  # improvement → reset
+        assert es.steps_without_improvement == 0
+        assert es.best_value == 0.5
+
+    def test_min_delta_respected(self):
+        es = EarlyStopping(patience=3, min_delta=0.1)
+        es.step(1.0)
+        r = es.step(0.95)  # only 0.05 better, below delta
+        assert r.improved is False
+        r = es.step(0.89)  # 0.11 better than best (1.0) → improved
+        assert r.improved is True
+
+    def test_best_step_tracks_correctly(self):
+        es = EarlyStopping(patience=5, min_delta=0.0)
+        es.step(1.0)  # step 0
+        es.step(0.8)  # step 1
+        es.step(0.9)  # step 2
+        es.step(0.7)  # step 3
+        assert es.best_step == 3
+        assert es.best_value == 0.7
+
+
+class TestEarlyStoppingMaxMode:
+    def test_max_mode_improves_upward(self):
+        es = EarlyStopping(patience=3, min_delta=0.0, mode="max")
+        es.step(0.5)
+        r = es.step(0.8)
+        assert r.improved is True
+        assert es.best_value == 0.8
+
+    def test_max_mode_stops_on_decline(self):
+        es = EarlyStopping(patience=2, min_delta=0.0, mode="max")
+        es.step(0.9)
+        es.step(0.8)
+        r = es.step(0.7)
+        assert r.should_stop is True
+
+    def test_max_mode_min_delta(self):
+        es = EarlyStopping(patience=3, min_delta=0.1, mode="max")
+        es.step(1.0)
+        r = es.step(1.05)  # only +0.05, below delta
+        assert r.improved is False
+
+
+# ──────────────────────────────────────────────────────────────────────
+# EarlyStopping — edge cases & validation
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestEarlyStoppingEdgeCases:
+    def test_patience_one(self):
+        es = EarlyStopping(patience=1, min_delta=0.0)
+        es.step(1.0)
+        r = es.step(1.0)  # no improvement
+        assert r.should_stop is True
+
+    def test_invalid_patience_raises(self):
+        with pytest.raises(ValueError, match="patience"):
+            EarlyStopping(patience=0)
+
+    def test_invalid_mode_raises(self):
+        with pytest.raises(ValueError, match="mode"):
+            EarlyStopping(mode="average")  # type: ignore[arg-type]
+
+    def test_properties_before_any_step(self):
+        es = EarlyStopping()
+        assert es.best_value is None
+        assert es.best_step == 0
+        assert es.should_stop is False
+        assert es.steps_without_improvement == 0
+
+    def test_step_indices_increment(self):
+        es = EarlyStopping(patience=10)
+        results = [es.step(float(i)) for i in range(5)]
+        assert [r.step for r in results] == [0, 1, 2, 3, 4]
+
+    def test_equal_values_are_not_improvement_min(self):
+        es = EarlyStopping(patience=3, min_delta=0.0)
+        es.step(1.0)
+        r = es.step(1.0)
+        assert r.improved is False
+
+    def test_equal_values_are_not_improvement_max(self):
+        es = EarlyStopping(patience=3, min_delta=0.0, mode="max")
+        es.step(1.0)
+        r = es.step(1.0)
+        assert r.improved is False
+
+
+# ──────────────────────────────────────────────────────────────────────
+# recommend_patience
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestRecommendPatience:
+    def test_returns_default_for_short_history(self):
+        assert recommend_patience([]) == 5
+        assert recommend_patience([0.5]) == 5
+
+    def test_monotonically_decreasing_loss(self):
+        history = [1.0 - 0.01 * i for i in range(100)]
+        p = recommend_patience(history)
+        # Every step improves → gaps are all 1 → patience should be small.
+        assert 3 <= p <= 10
+
+    def test_flat_loss_gives_high_patience(self):
+        history = [1.0] * 50
+        p = recommend_patience(history)
+        # No improvements at all → conservative patience.
+        assert p >= 5
+
+    def test_noisy_loss_with_occasional_drops(self):
+        # Spiky loss that drops every ~20 steps.
+        import random
+
+        rng = random.Random(42)
+        history: list[float] = []
+        base = 1.0
+        for i in range(100):
+            if i > 0 and i % 20 == 0:
+                base -= 0.1
+            history.append(base + rng.uniform(-0.02, 0.02))
+        p = recommend_patience(history)
+        # Gaps ~20 steps → patience should be at least 10.
+        assert p >= 10
+
+    def test_result_is_always_positive_int(self):
+        p = recommend_patience([10.0, 9.0, 8.0])
+        assert isinstance(p, int)
+        assert p >= 1