## Gate ## train.gate.GateVerdict The gate's decision over a candidate's scores. Usage ``` python train.gate.GateVerdict( promote, reason, stats, ) ``` #### Attributes `promote: bool` Whether the candidate should replace the incumbent. `reason: str` Human-readable justification recorded alongside the decision. `stats: dict[str, float]` The named statistics the decision was derived from. ## train.gate.GateResult The corrected paired gate over a candidate and incumbent at matched budget. Usage ``` python train.gate.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. ## train.gate.corrected_gate() Evaluate the corrected paired gate over common rows at matched budget. Usage ``` python train.gate.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. ## train.gate.sentinel_auc() Return ROC-AUC for explicitly oriented higher-is-fire scores. Usage ``` python train.gate.sentinel_auc(labels, fire_scores) ``` #### Parameters `labels: np.ndarray` Binary labels where true or 1 identifies rows that should fire. `fire_scores: np.ndarray` Scores where larger values mean a row is more likely to fire. #### Returns `float` The ROC-AUC reported by scikit-learn. ## train.gate.sign_test_p() Return the exact two-sided sign-test p-value over discordant pairs. Usage ``` python train.gate.sign_test_p(wins, losses) ``` #### Parameters `wins: int` Discordant pairs favoring the candidate. `losses: int` Discordant pairs favoring the incumbent. #### Returns `float` The exact two-sided p-value, or 1.0 when there are no discordant pairs. #### Raises `ValueError` If either count is negative. ## train.gate.threshold_for_budget() Return a threshold whose exceedance count stays within an alert budget. Usage ``` python train.gate.threshold_for_budget(scores, *, fires_per_100, total_turns) ``` The threshold fires where `score >= threshold`. It is conservative around ties: a tied score is excluded when including the whole tie would exceed the budget. #### Parameters `scores: np.ndarray` Scores whose larger values are more eligible to fire. `fires_per_100: float` Maximum fires allowed per 100 total turns. `total_turns: int` Turn count used to convert the rate into an integer budget. #### Returns `float` The lowest threshold that admits as many scores as possible within budget. #### Raises `ValueError` If scores are empty, total_turns is not positive, or the rate is negative. ## train.gate.matched_fire_mask() Return a higher-is-fire mask matched conservatively to a fire budget. Usage ``` python train.gate.matched_fire_mask(fire_scores, *, budget_fires) ``` #### Parameters `fire_scores: np.ndarray` Explicitly oriented scores where larger values mean a row is more likely to fire. `budget_fires: int` Maximum number of rows that may fire. #### Returns `np.ndarray` A boolean mask firing on the highest scores without splitting ties. #### Raises `ValueError` If fire_scores is empty or budget_fires is negative.