Janady13/missionmatch / internal/modules/ai/graph_loop.go

1package ai 2 3// G6 the loop. This file closes the keystone of the GraphRAG program: a single integrated capture answer 4// for one requirement that REASONS ACROSS the planes rather than within one. It is an ORCHESTRATOR 5// COMPOSITION, NOT a new SQL intent: it reuses the already validated planes so each keeps its guarantees, 6// the SUPPRESSING bench executors (G4 BenchGapForRequirement, G5 BenchClearanceCoverage) for the person 7// touching legs and the PUBLIC market reads (G9 RecompeteClock, G1 SegmentCompetitorField) for the market 8// leg, resolving the requirement's market segment from requirements.customer_agency and, when present, the 9// linked opportunity's naics. 10// 11// G6 is a PERSON TOUCHING bench intent: it reads the bench, so it is registered in benchIntents, requires an 12// authenticated tenant context (it refuses without one), surfaces every bench count only through RenderCount 13// (the sentinel for a suppressed cell, never a raw sub k number), and emits a counts only audit, exactly 14// like the G4 intents. The market leg is PUBLIC (no suppression) and rendered verbatim. The composed answer 15// NEVER computes a match score, a band, or any employment decision number: the per candidate score and the 16// ranking stay the frozen engine in internal/modules/matching/engine, which is untouched. G6 reports the 17// STRUCTURAL bench coverage (suppressed counts) plus the public market structure and narrates the gap. 18// 19// The honesty floor is explicit. When a requirement has no resolvable market segment (no customer_agency and 20// no linked opportunity), the market leg states that plainly rather than guessing. The price to win leg (M5) 21// carries a REAL advisory BLS OEWS wage band for the requirement's occupation and place of performance when 22// the requirement's role resolves to a SOC and its work_location resolves to a known OEWS area AND a wage row 23// exists; otherwise it keeps the honest floor (labor rate data not yet ingested) and fabricates no rate. 24 25import ( 26 "context" 27 "encoding/json" 28 "errors" 29 "fmt" 30 "strings" 31 32 "github.com/jackc/pgx/v5" 33 34 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 35) 36 37// IntentCapturePictureForRequirement is the FIXED registered name of the G6 composition. It is a closed 38// Registry entry (so ValidateRegistry asserts it at boot) and a benchIntent (so the raw ExecuteIntent path 39// hard rejects it and the AnswerGraph bench fork routes it to answerCapturePicture). It does NOT run through 40// ExecuteIntent: the registered SQL is the segment resolver read, a valid allowlisted single SELECT that 41// passes the guard, but it is reached only by the composition, never the raw intent path. 42const IntentCapturePictureForRequirement = "capture_picture_for_requirement" 43 44// capturePriceToWinFloor is the honest floor for the price to win leg, the fallback the composition states 45// plainly whenever a real OEWS wage band does not resolve for the requirement (its role does not map to a 46// SOC, its work_location does not map to a known OEWS area, or no wage row exists for that occupation and 47// area). No rate is fabricated for the floor. It is a surfaced string with no dashes. 48const capturePriceToWinFloor = "labor rate data not yet ingested" 49 50// requirementSegmentSQL resolves the market segment for one requirement under RLS. It reads requirements 51// (the caller's own, RLS scoped) and LEFT JOINs the linked tenant opportunity (the composite FK 52// (organization_id, opportunity_id)) and, through the opportunity's federal_ref cross source link, the 53// global opportunity_records row that carries the naics. The agency is the requirement's customer_agency 54// when non empty; the naics is the linked opportunity_records naics when the opportunity links one, else the 55// empty string. Every joined table is in the read allowlist (requirements, opportunities, 56// opportunity_records), and the joins are plain equi joins to allowlisted tables with scalar predicates, NO 57// set returning function in a FROM or JOIN position, so the guard accepts it. coalesce and nullif keep the 58// scan free of a mutating keyword (no set keyword appears), and the single row filter is the requirement id. 59const requirementSegmentSQL = ` 60SELECT 61 coalesce(nullif(btrim(r.customer_agency), ''), '') AS agency, 62 coalesce(orec.naics, '') AS naics, 63 r.required_level AS required_level, 64 coalesce(r.title, '') AS title, 65 coalesce(r.work_location, '') AS work_location 66FROM requirements r 67LEFT JOIN opportunities o 68 ON o.organization_id = r.organization_id 69 AND o.id = r.opportunity_id 70LEFT JOIN opportunity_records orec 71 ON o.federal_ref IS NOT NULL 72 AND o.federal_ref <> '' 73 AND orec.source_record_id = o.federal_ref 74WHERE r.id = $1 75 AND r.deleted_at IS NULL 76ORDER BY orec.naics ASC NULLS LAST 77LIMIT 1` 78 79// RequirementSegment is the resolved market segment of a requirement: the customer agency (the empty string 80// when the requirement names none), the naics (the empty string when no linked opportunity carries one), the 81// required clearance level, and whether the requirement was found under RLS. It carries no person data and no 82// score. 83type RequirementSegment struct { 84 Agency string `json:"agency"` 85 NAICS string `json:"naics"` 86 RequiredLevel string `json:"required_level"` 87 Title string `json:"title"` 88 WorkLocation string `json:"work_location"` 89 Found bool `json:"found"` 90} 91 92// AgencyBound reports whether the segment resolved a non empty agency (the agency keyed market reads can 93// run). NAICSBound reports whether the segment resolved a non empty naics (the (agency, naics) keyed reads 94// can run). SegmentBound reports whether either market arm can run at all (a non empty agency is the floor; 95// without it the market leg states the honest floor and calls no market executor with empty args). 96func (s RequirementSegment) AgencyBound() bool { return s.Agency != "" } 97func (s RequirementSegment) NAICSBound() bool { return s.NAICS != "" } 98func (s RequirementSegment) SegmentBound() bool { return s.AgencyBound() } 99 100// resolveRequirementSegment resolves the market segment for one requirement under RLS (the app role sees only 101// the caller's requirement through app.current_org_id). It runs the guarded resolver read inside 102// RunInTenantTx and returns Found false when no row matches (a foreign or missing requirement), so the 103// composition can state the honest floor rather than guessing a segment. 104func resolveRequirementSegment(ctx context.Context, db *tenant.DB, requirementID string) (RequirementSegment, error) { 105 if db == nil { 106 return RequirementSegment{}, errors.New("ai: no database") 107 } 108 var seg RequirementSegment 109 err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 110 if err := GuardReadOnlyQuery(requirementSegmentSQL, ReadAllowlist); err != nil { 111 return err 112 } 113 row := tx.QueryRow(ctx, requirementSegmentSQL, requirementID) 114 var agency, naics, level, title, workLocation string 115 if err := row.Scan(&agency, &naics, &level, &title, &workLocation); err != nil { 116 if errors.Is(err, pgx.ErrNoRows) { 117 return nil // not found under RLS: Found stays false, the honest floor 118 } 119 return err 120 } 121 seg = RequirementSegment{Agency: agency, NAICS: naics, RequiredLevel: level, Title: title, WorkLocation: workLocation, Found: true} 122 return nil 123 }) 124 return seg, err 125} 126 127// answerCapturePicture is the G6 composition: one integrated capture answer for a requirement, who on the 128// caller's bench can structurally staff it (the SUPPRESSED bench legs), the public market context (the 129// recompete clock and, when the segment binds a naics, the incumbent or competitor field), the gap, and the 130// price to win honest floor. It mirrors answerBench: it requires an authenticated tenant context (refuses 131// without one), surfaces every bench count only through RenderCount, narrates through o.generate and 132// o.finalize, and emits a counts only audit. It computes NO match score: the bench legs report structural 133// coverage counts, the market legs report public market structure, and the frozen engine stays the only 134// scorer. The EEO and protected attribute guards run upstream in AnswerGraph, so this path can never group, 135// filter, or rank by a protected attribute. 136func (o *Orchestrator) answerCapturePicture(ctx context.Context, requirementID string) (*Response, error) { 137 if _, ok := tenant.OrgFromContext(ctx); !ok { 138 return o.refuse(ctx, RouteGraph, "a capture question requires an authenticated tenant context"), nil 139 } 140 k := ConfiguredSuppressionThreshold() 141 142 // Resolve the market segment (agency, naics, required level) under RLS. 143 seg, err := resolveRequirementSegment(ctx, o.db, requirementID) 144 if err != nil { 145 return nil, err 146 } 147 148 // SUPPRESSED bench legs (person touching, RLS scoped, piped through Suppress by the executors). Every cell 149 // renders through RenderCount, so a suppressed cell is the sentinel and never a raw sub k number. 150 gapRows, err := BenchGapForRequirement(ctx, o.db, requirementID, k) 151 if err != nil { 152 return nil, err 153 } 154 covRows, err := BenchClearanceCoverage(ctx, o.db, k) 155 if err != nil { 156 return nil, err 157 } 158 benchCells := 0 159 suppressed := 0 160 161 benchFit := make([]string, 0, len(gapRows)) 162 for _, r := range gapRows { 163 benchCells++ 164 if r.Cell.Suppressed { 165 suppressed++ 166 } 167 benchFit = append(benchFit, r.Bucket+"="+RenderCount(r.Cell)) 168 } 169 clearanceFit := make([]string, 0, len(covRows)) 170 for _, r := range covRows { 171 benchCells++ 172 if r.Cell.Suppressed { 173 suppressed++ 174 } 175 clearanceFit = append(clearanceFit, r.LevelCode+"="+RenderCount(r.Cell)) 176 } 177 178 // PUBLIC market legs, run only when the segment binds. The agency keyed recompete clock runs whenever the 179 // agency is non empty; the (agency, naics) keyed competitor field runs only when the naics also binds. When 180 // the segment does not bind, the market leg states the honest floor and calls no executor with empty args. 181 marketLines := make([]string, 0, 4) 182 var clockRows []RecompeteClockRow 183 var fieldRows []CompetitorRow 184 if seg.SegmentBound() { 185 clockRows, err = RecompeteClock(ctx, o.db, seg.Agency, DefaultRecompeteWindowMonths) 186 if err != nil { 187 return nil, err 188 } 189 marketLines = append(marketLines, captureRecompeteLine(seg.Agency, clockRows)) 190 if seg.NAICSBound() { 191 fieldRows, err = SegmentCompetitorField(ctx, o.db, seg.Agency, seg.NAICS, DefaultCompetitorLookbackYears) 192 if err != nil { 193 return nil, err 194 } 195 marketLines = append(marketLines, captureIncumbentLine(seg.Agency, seg.NAICS, fieldRows)) 196 } else { 197 marketLines = append(marketLines, "the competitor and incumbent field could not be bound: this requirement has no linked opportunity naics.") 198 } 199 } else { 200 marketLines = append(marketLines, "the market segment could not be bound: this requirement names no customer agency and links no opportunity.") 201 } 202 203 // PRICE TO WIN leg (M5). Resolve the requirement's SOC from its title (the curated Galapagos crosswalk 204 // first, then the broadened national OEWS occupation set so any ingested occupation can bind) and its 205 // OEWS area from its work_location. When the SOC resolves, the leg prefers the specific STATE band (HI or 206 // NM) when the requirement names that state AND a state wage row exists for the SOC; otherwise it FALLS 207 // BACK to the US national band. So a requirement in a state with no state level data (for example Texas) 208 // still gets the national band, labeled United States. Otherwise the leg keeps the honest floor exactly as 209 // before; no rate is fabricated for an unresolved role or a missing wage row. The line is ADVISORY market 210 // context, never a match score. priceResolved is a boolean only; NO dollar value goes into the audit. 211 priceToWin := capturePriceToWinFloor 212 priceResolved := false 213 if soc, socOK := resolvePriceToWinSOC(ctx, o.db, seg.Title); socOK { 214 band, bandOK, bandErr := resolveWageBandWithNationalFallback(ctx, o.db, soc, seg.WorkLocation) 215 if bandErr != nil { 216 return nil, bandErr 217 } 218 if bandOK { 219 priceToWin = capturePriceToWinLine(band) 220 priceResolved = true 221 } 222 } 223 224 // Build the deterministic capture narrative and a small evidence object for the faithfulness gate. The 225 // evidence carries the SUPPRESSED bench rendering (RenderCount only), the public market lines verbatim, and 226 // the price to win leg (the real OEWS band when it resolved, else the honest floor); no raw sub k count is 227 // present anywhere in it. 228 deterministic := captureNarrative(seg, benchFit, clearanceFit, marketLines, priceToWin) 229 evidenceObj := map[string]any{ 230 "bench_fit": benchFit, 231 "clearance_fit": clearanceFit, 232 "market_context": marketLines, 233 "price_to_win": priceToWin, 234 "segment_bound": seg.SegmentBound(), 235 } 236 rendered, _ := json.Marshal(evidenceObj) 237 evidence := []string{string(rendered)} 238 239 model, genErr := o.generate(ctx, 240 "State the capture picture plainly from the evidence: the bench fit and clearance coverage, the market context, and the price to win leg. Report each bench headcount exactly as the rows give it. A headcount shown as "+SuppressionSentinel+" was withheld to protect individuals: say it was withheld and NEVER guess or state a number for it. Report the market lines and the price to win leg exactly as given and never invent an incumbent, an agency, a wage, a dollar figure, or a recompete the evidence does not contain. The price to win leg is an advisory OEWS labor rate or the honest floor; report it verbatim and never fabricate a rate. Never compute a match score and never assign a band.", 241 "INTENT: capture picture for one requirement\n\nEVIDENCE:\n"+string(rendered)) 242 resp := o.finalize(ctx, RouteGraph, model, genErr, deterministic, evidence) 243 244 // Counts only audit: the route, the intent, the bench cell count, the suppressed count, whether the segment 245 // bound, whether the price to win leg resolved to a real OEWS band (a boolean only, NEVER the dollar 246 // value), and k. It carries NO candidate id, NO raw sub k count, NO requirement id, NO dollar figure, and 247 // NO answer text. 248 o.audit(ctx, "aedt.ai.capture_answered", map[string]any{ 249 "route": RouteGraph, 250 "intent": IntentCapturePictureForRequirement, 251 "bench_cells": benchCells, 252 "suppressed": suppressed, 253 "segment_bound": seg.SegmentBound(), 254 "price_resolved": priceResolved, 255 "k": k, 256 }) 257 return resp, nil 258} 259 260// captureRecompeteLine renders the public recompete clock leg for the bound agency verbatim: the count of 261// recompetes the capture team watches in the window and the nearest one by period of performance end, naming 262// the agency. It is public market structure (no suppression) and carries no score. An empty clock states 263// plainly that nothing falls in the window. 264func captureRecompeteLine(agency string, rows []RecompeteClockRow) string { 265 if len(rows) == 0 { 266 return fmt.Sprintf("recompete clock for %s: no recompetes fall inside the %d month window.", agency, DefaultRecompeteWindowMonths) 267 } 268 first := rows[0] 269 title := strings.TrimSpace(first.Title) 270 if title == "" { 271 title = first.RecordID 272 } 273 return fmt.Sprintf("recompete clock for %s: %d in the %d month window, nearest is %q (%s) ending %s.", 274 agency, len(rows), DefaultRecompeteWindowMonths, title, first.SourceTable, first.PopEndDate) 275} 276 277// captureIncumbentLine renders the public competitor and incumbent field leg for the bound (agency, naics) 278// segment verbatim: the recipient that leads the recency weighted dollar share (the incumbent of record by 279// public award data) and how many recipients hold the segment. It is public market structure (no 280// suppression) and carries no score; the dollar share is the executor's exact decimal, never recomputed. An 281// empty field states plainly that no award structure exists in the segment. 282func captureIncumbentLine(agency, naics string, rows []CompetitorRow) string { 283 if len(rows) == 0 { 284 return fmt.Sprintf("incumbent and competitor field for %s in naics %s: no award structure on record.", agency, naics) 285 } 286 lead := rows[0] 287 name := strings.TrimSpace(lead.RecipientName) 288 if name == "" { 289 name = lead.RecipientUEI 290 } 291 return fmt.Sprintf("incumbent and competitor field for %s in naics %s: %d recipients on record, the leading share is held by %s at %s.", 292 agency, naics, len(rows), name, lead.DollarShare.String()) 293} 294 295// capturePriceToWinLine renders the M5 price to win leg from a resolved OEWS wage band verbatim: the 296// advisory annual mean and annual median labor rate for the requirement's occupation in its place of 297// performance (the STATE name for a state band, United States for the national band), labeled BLS OEWS and 298// advisory. It is public market structure (advisory labor rate context), NOT a match score and NOT an 299// employment decision number; the two dollar figures are the band's exact decimals rendered to cents, never 300// recomputed and never float. It carries no dash in surfaced prose. The occupation label is the Galapagos 301// role when the band carries one (the HI and NM state rows), else the OEWS occupation title (the national 302// rows carry an empty role), so a national band still names its occupation honestly. 303func capturePriceToWinLine(band WageBand) string { 304 label := strings.TrimSpace(band.Role) 305 if label == "" { 306 label = strings.TrimSpace(band.OccupationTitle) 307 } 308 return fmt.Sprintf("OEWS labor rate for %s in %s: annual mean $%s, annual median $%s (BLS OEWS, advisory).", 309 label, band.AreaName, band.AnnualMean.StringFixed(2), band.AnnualMedian.StringFixed(2)) 310} 311 312// captureNarrative composes the deterministic capture picture from the suppressed bench legs, the public 313// market lines, and the price to win leg (a resolved OEWS wage band or the honest floor), in a byte stable 314// order. It is the faithful answer the composition ships when the model prose is withheld; every bench count 315// it contains already came through RenderCount, so the deterministic fallback is itself suppression safe. It 316// names no candidate and computes no score. 317func captureNarrative(seg RequirementSegment, benchFit, clearanceFit, marketLines []string, priceToWin string) string { 318 var b strings.Builder 319 b.WriteString("Capture picture for the requirement. ") 320 321 b.WriteString("Bench fit (structural coverage, not a match score): ") 322 if len(benchFit) > 0 { 323 b.WriteString(strings.Join(benchFit, " ")) 324 } else { 325 b.WriteString("no bench partition.") 326 } 327 b.WriteString(". ") 328 329 b.WriteString("Clearance coverage of the bench: ") 330 if len(clearanceFit) > 0 { 331 b.WriteString(strings.Join(clearanceFit, " ")) 332 } else { 333 b.WriteString("no clearance partition.") 334 } 335 b.WriteString(". ") 336 337 b.WriteString("Market context: ") 338 if len(marketLines) > 0 { 339 b.WriteString(strings.Join(marketLines, " ")) 340 } else { 341 b.WriteString("none.") 342 } 343 b.WriteString(" ") 344 345 b.WriteString("Price to win: " + priceToWin + ".") 346 return b.String() 347} 348