Retraining

retrain.lexical.retrain_gate()

One gate retrain pass; returns the journaled one-line verdict.

Usage

Source

retrain.lexical.retrain_gate(
    *,
    force=False,
    fresh_epoch=False,
    dataset_dir=None,
    eval_root=None,
    registry_root=None,
    state_dir=None
)

fresh_epoch gates the candidate through the no-incumbent promotion path (~cc_steer.retrain.promotion.gate_promotable() with no incumbent), ignoring the incumbent’s metrics for the one-shot clean-slate cutover. The gate lane keeps no probs store, so there is no reuse guard here (unlike the watcher lane).

retrain.watcher.retrain_watcher()

One watcher retrain pass; returns the journaled one-line verdict.

Usage

Source

retrain.watcher.retrain_watcher(
    *,
    force=False,
    fresh_epoch=False,
    recipe,
    dataset_dir=None,
    eval_root=None,
    registry_root=None,
    state_dir=None,
    adapters_dir=None
)

Skips when the watcher train view is unchanged and not forced. Otherwise translates the recipe into a ~athome.train.spec.TrainSpec, hands training, checkpoint selection, and materialization to athome.train.retrain(), scores the frozen frame through the served artifact, and gates on those served probs — on a pass registering, promoting, and seeding the new version’s served probs before kicking the live watch agent. Every branch — skip, spend-cap reject, gate reject, promote — journals exactly once, and a serving-drift diagnostic persists beside the artifacts for every candidate that materializes, behind a boundary that keeps its own failure off the gate outcome. Every incumbent-relative comparison also persists both arms’ per-row probs and the paired-DeLong record (delta, 95% CI, measured rho, and the instrument-card verdict) beside the artifacts, so a reject leaves the comparison auditable.

fresh_epoch is the one-shot clean-slate cutover: the incumbent-relative gate (~cc_steer.retrain.promotion.corrected_gate()) is skipped entirely — the candidate promotes on the served AUC floor alone (finite and above chance on the clean frame). It first refuses via FreshEpochError if any registered version already carries probs for the current frozen frame, so it can only run once per frame.

retrain.watcher.WatcherRecipe

Every knob of one watcher LoRA retrain, validated at parse so no degenerate value trains.

Usage

Source

retrain.watcher.WatcherRecipe(
    tinker_model,
    mlx_id,
    rank,
    learning_rate,
    batch_size,
    epochs,
    checkpoint_fracs,
    max_tokens,
    render_version,
    val_n,
    oversample_corrective,
    budget_fires_per_100,
    spend_cap_usd,
    diagnostic_rows,
    diagnostic_tolerance,
    seed
)

The packaged default (cc_steer/assets/watcher_recipe.json, via default()) is the E8-winner recipe. An override JSON must carry every field (missing or extra keys crash) and clears the same validation bar.

Attributes

tinker_model: str

The Tinker base model id to train the LoRA over.

mlx_id: str

The local 4-bit MLX id the converted adapter serves against.

rank: int

The LoRA rank.

learning_rate: float

The AdamW learning rate.

batch_size: int

The datums per optimizer step.

epochs: int

The passes over the pool; steps derive from it.

checkpoint_fracs: tuple[float, …]

Fractions of the run to checkpoint and score at.

max_tokens: int

Datums longer than this are dropped before batching.

render_version: int

The prompt-rendering contract stamped into the registry metadata.

val_n: int

The target size of the carved val slice that ranks checkpoints.

oversample_corrective: float

The factor corrective positives are oversampled to.

budget_fires_per_100: float

The alert budget the served threshold is fitted at.

spend_cap_usd: float

The hard Tinker spend cap; a projected overspend never launches.

diagnostic_rows: int

The label-stratified rows the serving-drift diagnostic samples Tinker-vs-served.

diagnostic_tolerance: float

The absolute nosteer-prob gap above which a diagnostic row counts as drifted (never blocks).

seed: int

The seed threaded through every deterministic step.

Methods

Name	Description
default()	Parse the packaged E8-winner recipe shipped in the wheel (cc_steer/assets/watcher_recipe.json).
from_json()	Parse an override recipe; missing or extra keys crash, and every value is validated.

default()

Parse the packaged E8-winner recipe shipped in the wheel (cc_steer/assets/watcher_recipe.json).

Usage

Source

default()

from_json()

Parse an override recipe; missing or extra keys crash, and every value is validated.

Usage

Source

from_json(path)

retrain.watcher.register_watcher_adapter()

Register (and by default promote) a built mlx-lm adapter as the watcher component.

Usage

Source

retrain.watcher.register_watcher_adapter(
    adapter_dir, *, metadata, promote=True, root=None
)

adapter_dir must hold the mlx-lm pair (adapters.safetensors + adapter_config.json); metadata must carry the keys cc_steer.watcher.drafter_mlx serves from: base_model, thresholds, and render_version.

retrain.watcher.seed_incumbent_probs()

Validate an external incumbent probs cache against the frozen frame, then write it through the store.

Usage

Source

retrain.watcher.seed_incumbent_probs(
    path, *, version, expected_render, eval_root=None
)

The cache is the lab’s flat {row_id: P(NO_STEER)} map. It must cover the current frame exactly — a missing row is incomplete, a foreign row means it was scored against a drifted eval. Its render is expected_render, the incumbent’s OWN contract from its registry metadata: a migrated incumbent is scored under the render it serves (the E12 precedent), and the next retrain’s ~cc_steer.retrain.evalset.load_probs() verifies against the same metadata. On success it is written through ~cc_steer.retrain.evalset.write_probs(), stamped with the frame digest.

retrain.evalset.freeze_eval()

Copy the exported <view>/test.parquet into the eval root and merge its sha256 manifest.

Usage

Source

retrain.evalset.freeze_eval(view="watcher", *, dataset_dir=None, root=None)

Freezes either the gate or the watcher eval into <view>_eval.parquet, keeping the sibling view’s manifest entry intact. Idempotent for identical bytes; raises FrozenViolationError before writing anything when the frozen file exists with different content, EmptyEvalContext — naming the offending row ids — when any row’s rendered context has no substantive content, and SplitLeakError when a sibling train.parquet shares any row’s exact text with the eval (the E43 train/eval leak), so an invalid eval can never be frozen. Any dedup sidecar the eval builder wrote and the disjointness check’s counts merge into the manifest under <name>.meta. Returns the frozen file’s sha256.

retrain.evalset.freeze_steer_type()

Build then freeze the steer-type eval; returns the frozen file’s sha256.

Usage

Source

retrain.evalset.freeze_steer_type(
    *,
    dataset_dir=None,
    root=None,
    seed=1729,
    embed=None,
    semantic_threshold=SEMANTIC_THRESHOLD
)

retrain.evalset.freeze_pick()

Build then freeze the pick-prediction eval; returns the frozen file’s sha256.

Usage

Source

retrain.evalset.freeze_pick(
    *,
    decisions_path=None,
    dataset_dir=None,
    root=None,
    seed=1729,
    embed=None,
    semantic_threshold=SEMANTIC_THRESHOLD
)

retrain.evalset.EvalFrame

The frozen watcher eval as the arrays the promotion gate reads.

Usage

Source

retrain.evalset.EvalFrame(ids, labels, corrective, prose, tails, digest)

Attributes

ids: tuple[str, …]

The row ids, in file order (probability arrays align to this order).

labels: np.ndarray

True for true-steer rows (should fire).

corrective: np.ndarray

label & category != "direction" — a true corrective steer.

prose: np.ndarray

source_kind != "question_answer" — not an option-picking QA event.

tails: tuple[str, …]

The render-v2 flattened context tail per row (the watcher’s input).

digest: DatasetDigest

The eval’s order-invariant content digest, stamped into the probs store.

Methods

Name	Description
load()	Build the frame from the frozen watcher_eval.parquet under root.

load()

Build the frame from the frozen watcher_eval.parquet under root.

Usage

Source

load(*, root=None)

retrain.evalset.SteerTypeFrame

The frozen steer-type eval as the arrays a category classifier is scored on.

Usage

Source

retrain.evalset.SteerTypeFrame(ids, texts, categories, digest)

Attributes

ids: tuple[str, …]

The row ids, in file order.

texts: tuple[str, …]

The role-blocked classifier input per row.

categories: tuple[str, …]

The judge’s eleven-way category label per row (one of STEER_TYPE_CATEGORIES).

digest: DatasetDigest

The eval’s order-invariant content digest.

Methods

Name	Description
load()	Build the frame from the frozen steer_type_eval.parquet under root.

load()

Build the frame from the frozen steer_type_eval.parquet under root.

Usage

Source

load(*, root=None)

retrain.evalset.PickFrame

The frozen pick-prediction eval as the arrays an option classifier is scored on.

Usage

Source

retrain.evalset.PickFrame(ids, texts, chosen, n_options, digest)

Attributes

ids: tuple[str, …]

The row ids, in file order.

texts: tuple[str, …]

The rendered ask — question and options — per row.

chosen: np.ndarray

The user’s chosen option index per row.

n_options: np.ndarray

The number of options offered per row (the prediction’s valid range).

digest: DatasetDigest

The eval’s order-invariant content digest.

Methods

Name	Description
load()	Build the frame from the frozen pick_eval.parquet under root.

load()

Build the frame from the frozen pick_eval.parquet under root.

Usage

Source

load(*, root=None)

retrain.promotion.corrected_gate()

Evaluate the corrected paired gate over common rows at matched budget.

Usage

Source

retrain.promotion.corrected_gate(
    candidate_fire_scores,
    incumbent_fire_scores,
    *,
    candidate,
    incumbent,
    incumbent_fire_threshold,
    labels,
    warranted,
    harmful_favors_incumbent=None
)

Every score input has an explicit higher-is-fire contract. Callers starting from a no-fire probability must orient it before calling this function. The incumbent fires strictly above incumbent_fire_threshold; the candidate is then matched conservatively to that fire count. warranted selects the caller-defined stratum in which discordant coverage pairs count.

Parameters

candidate_fire_scores: np.ndarray

Candidate scores where larger values mean fire.

incumbent_fire_scores: np.ndarray

Incumbent scores where larger values mean fire.

candidate: str

Candidate name recorded in the result.

incumbent: str

Incumbent name recorded in the result.

incumbent_fire_threshold: float

Strict lower bound for incumbent fires.

labels: np.ndarray

Binary labels used for both sentinel AUC calculations.

warranted: np.ndarray

Boolean mask selecting rows where coverage wins and losses count.

harmful_favors_incumbent: bool | None = None

Deferred harmful-fire judgment, or None while pending.

Returns

GateResult

Every gate component and the promotion verdict when harmful judging exists.

retrain.promotion.GateResult

The corrected paired gate over a candidate and incumbent at matched budget.

Usage

Source

retrain.promotion.GateResult(
    candidate,
    incumbent,
    coverage_wins,
    coverage_losses,
    coverage_sign_p,
    coverage_sig,
    budget_held,
    cell_auc,
    incumbent_auc,
    auc_not_regressed,
    harmful_favors_incumbent,
    promote
)

Attributes

candidate: str

The candidate’s name.

incumbent: str

The incumbent’s name.

coverage_wins: int

Warranted rows where only the candidate fires.

coverage_losses: int

Warranted rows where only the incumbent fires.

coverage_sign_p: float

Exact sign-test p-value over discordant coverage pairs.

coverage_sig: bool

Whether coverage significantly favors the candidate.

budget_held: bool

Whether candidate fires do not exceed incumbent fires.

cell_auc: float

The candidate’s sentinel AUC.

incumbent_auc: float

The incumbent’s sentinel AUC.

auc_not_regressed: bool

Whether candidate AUC is at least incumbent AUC.

harmful_favors_incumbent: bool | None

Whether harmful-fire judging favors the incumbent, or None while judging is pending.

promote: bool | None

The full verdict, or None while harmful-fire judging is pending.

retrain.promotion.Verdict

One promotion decision: whether to promote and the human-readable reason.

Usage

Source

retrain.promotion.Verdict(promote, reason)

Parameter Attributes

promote: bool

reason: str