coach = aicoach.Coach()

coach.observe(
    epoch=0,
    train_loss=0.85,
    val_loss=0.90,    # optional
    lr=1e-3,          # optional
    accuracy=0.72,    # optional
)

coach.get_metric("train_loss")           # all values
coach.get_metric("val_loss", window=5)   # last 5 only
coach.get_observations()                 # list[Observation]
coach.reset()                            # clear for a new run
len(coach)                               # number of recorded epochs

Validation rules:

• epoch must be a non-negative, strictly increasing int
• All metric values must be int or float (booleans rejected)
• None is accepted for optional fields

from aicoach.overfitting import check_overfitting

advice = check_overfitting(coach, patience=3)

Triggers when (both conditions must hold over the last patience + 1 epochs):

1. val_loss rises on every consecutive step
2. train_loss shows a net decrease over the same window

Default: patience=3 — sensible middle ground between sensitivity and noise-resistance. Increase for noisy validation curves.

from aicoach.plateau import check_plateau

advice = check_plateau(coach, metric="train_loss", window=5, threshold=0.01)

Triggers when:

(max(window) - min(window)) / mean(abs(window)) < threshold

Uses relative range so it scales correctly across all loss magnitudes (a flat loss at 0.01 and a flat loss at 100 are both detected equally).

Defaults: window=5, threshold=0.01 (1%)

from aicoach.learning_rate import check_learning_rate

advice = check_learning_rate(coach, window=5)

Three-zone design (mutually exclusive with plateau):

Oscillation is checked first and takes priority over the zone check.

Defaults: window=5, oscillation_threshold=0.40, plateau_threshold=0.01, healthy_rate_threshold=0.05

from aicoach.imbalance import check_class_imbalance

label_counts = {"cat": 800, "dog": 750, "bird": 90}
advice = check_class_imbalance(label_counts, ratio_threshold=4.0)

Triggers when: max(counts) / min(counts) >= ratio_threshold

Standalone — does not require a Coach instance. Call before or during training.

Default: ratio_threshold=4.0 — flags when the dominant class has at least 4× as many samples as the rarest class.

from aicoach.divergence import check_divergence

advice = check_divergence(coach, window=5, growth_threshold=10.0)

Three sub-checks, in priority order:

Returns CRITICAL severity. When divergence fires via get_advice(), all other checks are suppressed.

Default: window=5, growth_threshold=10.0 (10× growth within the window)