Janady13/missionmatch / cmd/eval-model/main.go

1// Command eval-model is the offline EVALUATOR and the human promotion gate of the MAG learning loop. It replays 2// a challenger version of a MAG model against a held out split of the decided bid labels, compares its 3// calibration (ECE) and ranking (AUC) to the current champion, and runs the no adverse impact four fifths 4// fairness gate. Only when BOTH gates pass AND a human passes the promote flag does it flip the champion; by 5// default it is a pure report. It NEVER computes a per candidate score: the model is opportunity level and the 6// frozen decimal engine (internal/modules/matching, ModelVersion v1.4.0) stays the only per candidate scorer. 7// 8// Two gates guard a promotion. The QUALITY gate: on the held out split the challenger must rank at least as well 9// as the champion (AUC not materially lower) and calibrate at least as well (ECE not materially higher), so a 10// promotion never ships a worse model. The FAIRNESS gate: because the win probability model emits 11// opportunity_score and CANNOT drive candidate selection (the frozen engine does), promoting it cannot change 12// the four fifths selection ratios; the gate confirms that structural invariant AND reads the current adverse 13// impact state across every org (through the compliance pool, the only path to the eeo schema), refusing to 14// promote while any group's four fifths ratio is already below 0.80 unless an operator explicitly overrides, 15// on the governance principle that a model change does not ship into an unresolved disparate impact condition. 16// 17// Env (server side only): MM_MIGRATOR_DATABASE_URL (the BYPASSRLS migrator DSN, reads labels and models, flips 18// champion) and MM_COMPLIANCE_DATABASE_URL (the NOBYPASSRLS compliance DSN, the only path to the eeo schema). 19// Flags: -model, -challenger V (required), -holdout F (the held out fraction, default 0.30), -promote (default 20// false, a dry run report unless set), -allow-adverse-impact (override the fairness gate, logged loudly). 21// 22// Build and run FIPS validated: CGO_ENABLED=0 GOFIPS140=v1.0.0 go build, run with GODEBUG=fips140=on. 23package main 24 25import ( 26 "context" 27 "crypto/fips140" 28 "crypto/pbkdf2" 29 "crypto/sha256" 30 "flag" 31 "log" 32 "os" 33 "strings" 34 "time" 35 36 "github.com/google/uuid" 37 "github.com/jackc/pgx/v5/pgxpool" 38 39 "github.com/missionworkforce/missionmatch/internal/modules/eeo" 40 "github.com/missionworkforce/missionmatch/internal/platform/database" 41 "github.com/missionworkforce/missionmatch/internal/platform/magstore" 42 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 43) 44 45func main() { 46 kind := flag.String("kind", "win_probability", "which MAG model to evaluate: win_probability (opportunity_score) or reranker (display_order)") 47 modelKey := flag.String("model", "", "the MAG model_key to evaluate; defaults per kind") 48 challenger := flag.Int("challenger", 0, "the challenger version to evaluate (required)") 49 holdout := flag.Float64("holdout", 0.30, "the held out fraction of the decided labels or slates") 50 promote := flag.Bool("promote", false, "promote the challenger to champion when both gates pass") 51 allowAdverse := flag.Bool("allow-adverse-impact", false, "override the fairness gate (a deliberate governance decision, logged)") 52 flag.Parse() 53 54 if err := fipsSelfTest(); err != nil { 55 log.Fatalf("eval-model: FIPS self test (PBKDF2 HMAC SHA 256) failed: %v", err) 56 } 57 log.Printf("eval-model: fips_enabled=%v module=%s", fips140.Enabled(), fips140.Version()) 58 59 if *challenger <= 0 { 60 log.Fatal("eval-model: set -challenger V (the challenger version to evaluate)") 61 } 62 63 migDSN := firstNonEmpty(os.Getenv("MM_MIGRATOR_DATABASE_URL"), os.Getenv("MM_DATABASE_URL")) 64 if migDSN == "" { 65 log.Fatal("eval-model: set MM_MIGRATOR_DATABASE_URL (the BYPASSRLS migrator DSN)") 66 } 67 compDSN := strings.TrimSpace(os.Getenv("MM_COMPLIANCE_DATABASE_URL")) 68 if compDSN == "" { 69 log.Fatal("eval-model: set MM_COMPLIANCE_DATABASE_URL (the compliance role DSN, the only path to the eeo schema)") 70 } 71 72 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute) 73 defer cancel() 74 75 migPool, err := database.NewPool(ctx, migDSN) 76 if err != nil { 77 log.Fatalf("eval-model: connect migrator: %v", err) 78 } 79 defer migPool.Close() 80 if err := database.AssertMigratorRole(ctx, migPool); err != nil { 81 log.Fatalf("eval-model: migrator role check: %v", err) 82 } 83 84 compPool, err := database.NewPool(ctx, compDSN) 85 if err != nil { 86 log.Fatalf("eval-model: connect compliance: %v", err) 87 } 88 defer compPool.Close() 89 if err := database.AssertRole(ctx, compPool, "missionmatch_compliance"); err != nil { 90 log.Fatalf("eval-model: compliance pool role check: %v", err) 91 } 92 93 if *kind == "reranker" { 94 evalReranker(ctx, migPool, compPool, resolveModelKey(*modelKey, magstore.RerankModelKey), *challenger, *holdout, *promote, *allowAdverse) 95 return 96 } 97 if *kind == "timetofill" { 98 evalTimeToFill(ctx, migPool, compPool, resolveModelKey(*modelKey, magstore.TimeToFillModelKey), *challenger, *holdout, *promote, *allowAdverse) 99 return 100 } 101 winKey := resolveModelKey(*modelKey, "opportunity_win_probability") 102 103 // Load the champion and the challenger, and confirm both emit opportunity_score, so an evaluation can never 104 // compare or promote something that could surface a candidate score. 105 champVersion, err := magstore.ChampionVersion(ctx, migPool, winKey) 106 if err != nil { 107 log.Fatalf("eval-model: %v", err) 108 } 109 champ, err := magstore.LoadModel(ctx, migPool, winKey, champVersion) 110 if err != nil { 111 log.Fatalf("eval-model: load champion: %v", err) 112 } 113 chal, err := magstore.LoadModel(ctx, migPool, winKey, *challenger) 114 if err != nil { 115 log.Fatalf("eval-model: load challenger: %v", err) 116 } 117 if champ.OutputKind != "opportunity_score" || chal.OutputKind != "opportunity_score" { 118 log.Fatalf("eval-model: refusing to evaluate a non opportunity_score model (champion %q, challenger %q); this loop fits only opportunity level win probability", champ.OutputKind, chal.OutputKind) 119 } 120 log.Printf("eval-model: champion v%d vs challenger v%d for %q", champVersion, *challenger, winKey) 121 122 // The QUALITY gate: score the held out split under both models and compare calibration and ranking. 123 quality, err := magstore.EvaluateHeldOut(ctx, migPool, champ, chal, *holdout) 124 if err != nil { 125 log.Fatalf("eval-model: quality evaluation: %v", err) 126 } 127 logQuality(quality) 128 129 // The FAIRNESS gate: the current adverse impact state across every org, read through the compliance pool. 130 fairness, err := evaluateFairness(ctx, compPool) 131 if err != nil { 132 log.Fatalf("eval-model: fairness evaluation: %v", err) 133 } 134 logFairness(fairness) 135 136 // The gate decision. Fairness may be overridden by an explicit operator flag (logged loudly); quality may 137 // not, so a promotion never ships a measurably worse model. 138 fairnessPass := fairness.Clean || *allowAdverse 139 if fairness.Clean { 140 log.Print("eval-model: FAIRNESS gate PASS (no group below the 0.80 four fifths threshold; the opportunity level model cannot change candidate selection)") 141 } else if *allowAdverse { 142 log.Printf("eval-model: FAIRNESS gate OVERRIDDEN by -allow-adverse-impact despite %d flagged group(s); this is a recorded governance decision", fairness.FlaggedGroups) 143 } else { 144 log.Printf("eval-model: FAIRNESS gate FAIL (%d group(s) below the 0.80 four fifths threshold across %d org(s)); resolve the disparate impact or pass -allow-adverse-impact to override", fairness.FlaggedGroups, fairness.OrgsWithFlag) 145 } 146 log.Printf("eval-model: QUALITY gate %s", passFail(quality.Pass)) 147 148 if !*promote { 149 log.Print("eval-model: report only (no -promote); nothing changed") 150 return 151 } 152 if !quality.Pass || !fairnessPass { 153 log.Print("eval-model: NOT promoting; a gate did not pass") 154 return 155 } 156 from, err := magstore.PromoteChampion(ctx, migPool, winKey, *challenger) 157 if err != nil { 158 log.Fatalf("eval-model: promote: %v", err) 159 } 160 log.Printf("eval-model: PROMOTED %s v%d to champion (replacing v%d); the serve path now reflects the learned coefficients", winKey, *challenger, from) 161} 162 163func logQuality(q magstore.QualityResult) { 164 log.Printf("eval-model: held out %d bids", q.HeldOut) 165 log.Printf("eval-model: AUC champion %.4f vs challenger %.4f (higher is better ranking)", q.ChampAUC, q.ChalAUC) 166 log.Printf("eval-model: ECE champion %.4f vs challenger %.4f (lower is better calibration)", q.ChampECE, q.ChalECE) 167} 168 169// fourFifthsFloor is the EEOC four fifths threshold; a group impact ratio below it is adverse impact. 170// rankFairnessSlack absorbs small sample noise in the ratio estimate when comparing the challenger ranking to 171// the champion ranking (a regression must be real, not noise). 172const ( 173 fourFifthsFloor = 0.80 174 rankFairnessSlack = 0.05 175) 176 177// evalReranker evaluates a display order re ranker challenger: the held out RANKING quality (does it order 178// approved above rejected at least as well as the champion) AND the four fifths no adverse impact check 179// recomputed UNDER the challenger ranking per org (does its top of slate selection skew who surfaces first). 180// It promotes only when both gates pass and a human passes the flag. The re ranker emits an ordering, never a 181// per candidate score; a human still approves every member and the frozen v1.4.0 engine is untouched. 182func evalReranker(ctx context.Context, migPool, compPool *pgxpool.Pool, modelKey string, challenger int, holdout float64, promote, allowAdverse bool) { 183 champVersion, err := magstore.ChampionVersion(ctx, migPool, modelKey) 184 if err != nil { 185 log.Fatalf("eval-model: %v", err) 186 } 187 champ, err := magstore.LoadModel(ctx, migPool, modelKey, champVersion) 188 if err != nil { 189 log.Fatalf("eval-model: load champion: %v", err) 190 } 191 chal, err := magstore.LoadModel(ctx, migPool, modelKey, challenger) 192 if err != nil { 193 log.Fatalf("eval-model: load challenger: %v", err) 194 } 195 if champ.OutputKind != "display_order" || chal.OutputKind != "display_order" { 196 log.Fatalf("eval-model: refusing to evaluate a non display_order model as a re ranker (champion %q, challenger %q)", champ.OutputKind, chal.OutputKind) 197 } 198 champCoeffs := magstore.RerankCoeffs(champ) 199 chalCoeffs := magstore.RerankCoeffs(chal) 200 log.Printf("eval-model: re ranker champion v%d vs challenger v%d for %q", champVersion, challenger, modelKey) 201 202 // The QUALITY gate: held out pairwise ranking accuracy. 203 quality, err := magstore.EvaluateRerankerQuality(ctx, migPool, champCoeffs, chalCoeffs, holdout) 204 if err != nil { 205 log.Fatalf("eval-model: ranking evaluation: %v", err) 206 } 207 log.Printf("eval-model: held out %d slates, pairwise ranking accuracy champion %.4f vs challenger %.4f (higher orders approved above rejected better)", 208 quality.HeldOutGroups, quality.ChampAccuracy, quality.ChalAccuracy) 209 210 // The FAIRNESS gate: recompute the four fifths ratio UNDER the challenger ranking per org, comparing the 211 // challenger's top of slate selection to the champion's. A display order model influences selection, so this 212 // is a genuine per ranking recomputation, not a baseline check. 213 fair := evaluateRerankFairness(ctx, migPool, compPool, champCoeffs, chalCoeffs) 214 fairnessPass := fair.Clean || allowAdverse 215 if fair.Clean { 216 log.Printf("eval-model: FAIRNESS gate PASS (no org drops below the 0.80 four fifths floor or regresses from the engine order under the challenger ranking; %d org(s) checked)", fair.OrgsChecked) 217 } else if allowAdverse { 218 log.Printf("eval-model: FAIRNESS gate OVERRIDDEN by -allow-adverse-impact despite %d org(s) worsened under the challenger ranking; a recorded governance decision", fair.OrgsWorsened) 219 } else { 220 log.Printf("eval-model: FAIRNESS gate FAIL (%d org(s) drop below 0.80 or regress from the engine order under the challenger ranking, worst ratio %.4f); resolve or pass -allow-adverse-impact", fair.OrgsWorsened, fair.WorstRatio) 221 } 222 log.Printf("eval-model: QUALITY gate %s", passFail(quality.Pass)) 223 224 if !promote { 225 log.Print("eval-model: report only (no -promote); nothing changed") 226 return 227 } 228 if !quality.Pass || !fairnessPass { 229 log.Print("eval-model: NOT promoting; a gate did not pass") 230 return 231 } 232 from, err := magstore.PromoteChampion(ctx, migPool, modelKey, challenger) 233 if err != nil { 234 log.Fatalf("eval-model: promote: %v", err) 235 } 236 log.Printf("eval-model: PROMOTED re ranker %s v%d to champion (replacing v%d); the slate display order now reflects the learned weights, the engine score unchanged", modelKey, challenger, from) 237} 238 239// rerankFairness is the outcome of recomputing the four fifths ratio under a challenger ranking across orgs. 240type rerankFairness struct { 241 OrgsChecked int 242 OrgsWorsened int 243 WorstRatio float64 244 Clean bool 245} 246 247// evaluateRerankFairness reads the decided slates (migrator, no demographics), and for each org computes the 248// challenger's and the champion's top of slate selection, then recomputes the four fifths minimum impact ratio 249// under each through the compliance pool (the only demographic path; only candidate ids cross). An org fails 250// when the challenger drops below the 0.80 floor while the champion did not, or regresses from the champion 251// beyond the noise slack. Clean is true when no org fails. 252func evaluateRerankFairness(ctx context.Context, migPool, compPool *pgxpool.Pool, champCoeffs, chalCoeffs []float64) rerankFairness { 253 groups, err := magstore.ReadSlateGroups(ctx, migPool) 254 if err != nil { 255 log.Fatalf("eval-model: read slates for fairness: %v", err) 256 } 257 svc := eeo.NewService(tenant.New(compPool)) 258 res := rerankFairness{WorstRatio: 1.0} 259 for org, orgGroups := range magstore.GroupsByOrg(groups) { 260 champSel := magstore.CandidateSelection(champCoeffs, orgGroups) 261 chalSel := magstore.CandidateSelection(chalCoeffs, orgGroups) 262 champSection, cerr := svc.AdverseImpactForSelection(tenant.WithOrg(ctx, org), champSel) 263 if cerr != nil { 264 log.Printf("eval-model: fairness read for org %s failed: %v", org, cerr) 265 continue 266 } 267 chalSection, cerr := svc.AdverseImpactForSelection(tenant.WithOrg(ctx, org), chalSel) 268 if cerr != nil { 269 log.Printf("eval-model: fairness read for org %s failed: %v", org, cerr) 270 continue 271 } 272 res.OrgsChecked++ 273 champMin := champSection.MinImpactRatio() 274 chalMin := chalSection.MinImpactRatio() 275 if chalMin < res.WorstRatio { 276 res.WorstRatio = chalMin 277 } 278 // The org passes when the challenger stays above the floor OR is no worse than the champion (the engine 279 // order that ships today); it fails only when the challenger introduces or worsens adverse impact. 280 orgPass := chalMin >= fourFifthsFloor || chalMin >= champMin-rankFairnessSlack 281 if !orgPass { 282 res.OrgsWorsened++ 283 log.Printf("eval-model: org %s four fifths under challenger ranking %.4f vs champion %.4f (below floor or regressed)", org, chalMin, champMin) 284 } 285 } 286 res.Clean = res.OrgsWorsened == 0 287 return res 288} 289 290// evalTimeToFill evaluates a time to fill survival challenger: the held out CALIBRATION of its fill within 291// horizon probability against the observed fill rate, plus the baseline four fifths fairness check (the model is 292// requirement level and cannot drive candidate selection, exactly like win probability). It promotes only when 293// both gates pass and a human passes the flag. It NEVER computes a per candidate score. 294func evalTimeToFill(ctx context.Context, migPool, compPool *pgxpool.Pool, modelKey string, challenger int, holdout float64, promote, allowAdverse bool) { 295 champVersion, err := magstore.ChampionVersion(ctx, migPool, modelKey) 296 if err != nil { 297 log.Fatalf("eval-model: %v", err) 298 } 299 champ, err := magstore.LoadModel(ctx, migPool, modelKey, champVersion) 300 if err != nil { 301 log.Fatalf("eval-model: load champion: %v", err) 302 } 303 chal, err := magstore.LoadModel(ctx, migPool, modelKey, challenger) 304 if err != nil { 305 log.Fatalf("eval-model: load challenger: %v", err) 306 } 307 if champ.OutputKind != "opportunity_score" || chal.OutputKind != "opportunity_score" { 308 log.Fatalf("eval-model: refusing to evaluate a non opportunity_score time to fill model (champion %q, challenger %q)", champ.OutputKind, chal.OutputKind) 309 } 310 log.Printf("eval-model: time to fill champion v%d vs challenger v%d for %q", champVersion, challenger, modelKey) 311 312 const horizon = 3 // months; the fill within horizon calibration point 313 quality, err := magstore.EvaluateTimeToFill(ctx, migPool, champ, chal, horizon, holdout) 314 if err != nil { 315 log.Fatalf("eval-model: calibration evaluation: %v", err) 316 } 317 log.Printf("eval-model: horizon %d months, %d decidable requirements, observed fill rate %.4f", quality.Horizon, quality.Evaluated, quality.FillRate) 318 log.Printf("eval-model: P(fill within %d) champion %.4f vs challenger %.4f", horizon, quality.ChampPred, quality.ChalPred) 319 log.Printf("eval-model: calibration error (ECE) champion %.4f vs challenger %.4f (lower is better)", quality.ChampECE, quality.ChalECE) 320 321 // The FAIRNESS gate: the model is requirement level and cannot change candidate selection, so this is the 322 // same baseline check as win probability (refuse to ship a model change while a disparate impact is unresolved). 323 fairness, err := evaluateFairness(ctx, compPool) 324 if err != nil { 325 log.Fatalf("eval-model: fairness evaluation: %v", err) 326 } 327 logFairness(fairness) 328 fairnessPass := fairness.Clean || allowAdverse 329 if fairness.Clean { 330 log.Print("eval-model: FAIRNESS gate PASS (no group below the 0.80 four fifths threshold; a requirement level forecast cannot change candidate selection)") 331 } else if allowAdverse { 332 log.Printf("eval-model: FAIRNESS gate OVERRIDDEN by -allow-adverse-impact despite %d flagged group(s)", fairness.FlaggedGroups) 333 } else { 334 log.Printf("eval-model: FAIRNESS gate FAIL (%d flagged group(s)); resolve the disparate impact or pass -allow-adverse-impact", fairness.FlaggedGroups) 335 } 336 log.Printf("eval-model: CALIBRATION gate %s", passFail(quality.Pass)) 337 338 if !promote { 339 log.Print("eval-model: report only (no -promote); nothing changed") 340 return 341 } 342 if !quality.Pass || !fairnessPass { 343 log.Print("eval-model: NOT promoting; a gate did not pass") 344 return 345 } 346 from, err := magstore.PromoteChampion(ctx, migPool, modelKey, challenger) 347 if err != nil { 348 log.Fatalf("eval-model: promote: %v", err) 349 } 350 log.Printf("eval-model: PROMOTED time to fill %s v%d to champion (replacing v%d); the fill within horizon forecast now reflects the learned hazard", modelKey, challenger, from) 351} 352 353// resolveModelKey returns an explicit model_key flag when set, else the default for the kind. 354func resolveModelKey(flagKey, def string) string { 355 if s := strings.TrimSpace(flagKey); s != "" { 356 return s 357 } 358 return def 359} 360 361// fairnessResult is the current adverse impact state across every org with AEDT activity. 362type fairnessResult struct { 363 OrgsChecked int 364 OrgsWithFlag int 365 FlaggedGroups int 366 Clean bool 367} 368 369// evaluateFairness reads the current adverse impact report for every org with AEDT activity through the 370// compliance pool (the only path to the eeo schema), counting the groups whose four fifths ratio is already 371// below 0.80. It is Clean when no group is flagged in any org. The win probability model cannot itself change 372// these ratios (it emits opportunity_score, never a candidate selection), so this is a baseline safety check, 373// not a per model recomputation: a model governance action does not ship while a disparate impact is unresolved. 374func evaluateFairness(ctx context.Context, compPool *pgxpool.Pool) (fairnessResult, error) { 375 svc := eeo.NewService(tenant.New(compPool)) 376 orgs, err := orgsWithActivity(ctx, compPool) 377 if err != nil { 378 return fairnessResult{}, err 379 } 380 now := time.Now().UTC() 381 var res fairnessResult 382 for _, org := range orgs { 383 report, rerr := svc.AdverseImpact(tenant.WithOrg(ctx, org.String()), now) 384 if rerr != nil { 385 // One org failing must not abort the gate; log the org id (not PII) and continue conservatively. 386 log.Printf("eval-model: fairness read for org %s failed: %v", org, rerr) 387 continue 388 } 389 res.OrgsChecked++ 390 flagged := countFlagged(report) 391 if flagged > 0 { 392 res.OrgsWithFlag++ 393 res.FlaggedGroups += flagged 394 } 395 } 396 res.Clean = res.FlaggedGroups == 0 397 return res, nil 398} 399 400// countFlagged counts the demographic groups flagged below the 0.80 four fifths threshold across both analysis 401// stages (selection and screening) and all three cuts (gender, race, intersectional) of an adverse impact 402// report. 403func countFlagged(r eeo.Report) int { 404 n := 0 405 for _, section := range []eeo.AnalysisSection{r.Selection, r.Screening} { 406 for _, group := range [][]eeo.ImpactRow{section.ByGender, section.ByRace, section.Intersectional} { 407 for _, row := range group { 408 if row.Flagged { 409 n++ 410 } 411 } 412 } 413 } 414 return n 415} 416 417func logFairness(f fairnessResult) { 418 log.Printf("eval-model: fairness checked %d org(s), %d with a flagged group, %d flagged group(s) total", 419 f.OrgsChecked, f.OrgsWithFlag, f.FlaggedGroups) 420} 421 422// orgsWithActivity enumerates the orgs to check from the distinct organization_id values in audit_logs, which 423// is outside RLS and granted to the compliance role, so the gate needs no cross org read of tenant data. 424func orgsWithActivity(ctx context.Context, pool *pgxpool.Pool) ([]uuid.UUID, error) { 425 rows, err := pool.Query(ctx, 426 `SELECT DISTINCT organization_id FROM audit_logs WHERE organization_id IS NOT NULL ORDER BY organization_id`) 427 if err != nil { 428 return nil, err 429 } 430 defer rows.Close() 431 var out []uuid.UUID 432 for rows.Next() { 433 var id uuid.UUID 434 if err := rows.Scan(&id); err != nil { 435 return nil, err 436 } 437 out = append(out, id) 438 } 439 return out, rows.Err() 440} 441 442func passFail(ok bool) string { 443 if ok { 444 return "PASS" 445 } 446 return "FAIL" 447} 448 449// fipsSelfTest derives one PBKDF2 HMAC SHA 256 key under the active crypto module and fails closed if it errors. 450func fipsSelfTest() error { 451 _, err := pbkdf2.Key(sha256.New, "eval-model-self-test", []byte("eval-model-salt"), 600000, 32) 452 return err 453} 454 455func firstNonEmpty(vs ...string) string { 456 for _, v := range vs { 457 if s := strings.TrimSpace(v); s != "" { 458 return s 459 } 460 } 461 return "" 462} 463