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

1package ai 2 3// RouteGraph is the deterministic graph reasoning surface. It is the routing layer that crosses the brain 4// from a single table lookup (TAG) to walking a cited evidence path over the relational graph already in 5// Postgres: the G3 curated skill adjacency and the G1 market and relationship backbone. Like every other 6// route it runs the EEO and protected attribute guards FIRST, executes a FIXED, named, parameterized 7// QueryIntent from the closed Registry through ExecuteIntent (which re guards via GuardReadOnlyQuery), and 8// narrates the result behind the existing per claim faithfulness gate. It NEVER scores: the frozen engine in 9// internal/modules/matching/engine stays the only scorer. RouteGraph reads structure (the reachable skills, 10// the recency weighted dollar shares, the incumbent of record) and narrates it; a dollar share or a 11// competitor rank is a MARKET aggregate, never a match score or an employment decision number. The model 12// authors no SQL and binds no params it can invent: the intent is one of a fixed set and its arg slots are 13// curated, and a free form question whose required params cannot be extracted unambiguously falls back to the 14// existing RAG path rather than guessing. 15 16import ( 17 "context" 18 "encoding/json" 19 "fmt" 20 "regexp" 21 "strconv" 22 "strings" 23 24 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 25) 26 27// graphIntents is the closed set of Registry intents the dispatcher treats as GRAPH intents (the G3 skill 28// adjacency traversals and the G1 market and relationship traversals). It is how Answer tells a graph intent 29// from a TAG intent: a structured request naming one of these dispatches to AnswerGraph instead of 30// AnswerTAG, so the graph specific evidence rendering and the graph route audit apply. Every name here is a 31// FIXED entry in the closed Registry, asserted by ValidateRegistry at boot; IsGraphIntent over this set is 32// the single source of truth for the classification. 33var graphIntents = map[string]bool{ 34 // G3 skill and role adjacency graph (graph_skill.go). 35 IntentSkillSubstitutionClosure: true, 36 IntentSkillGapBridge: true, 37 // G1 market and relationship graph (graph_market.go). 38 IntentSegmentCompetitorField: true, 39 IntentIncumbentOfRecord: true, 40 IntentRecompetePipeline: true, 41 IntentAgencyBuyingPattern: true, 42 // G9 recompete lifecycle and foresight graph (graph_lifecycle.go). 43 IntentProcurementSuccession: true, 44 IntentRecompeteClock: true, 45 IntentForecastRunway: true, 46 // G7 agency buying pattern graph (graph_agency.go). 47 IntentAgencyBuyingPatternDetail: true, 48 IntentAgencyVendorConcentration: true, 49 IntentAgencySpendTrend: true, 50 // G2 public vendor co occurrence and teaming field graph (graph_teaming.go). 51 IntentVendorCooccurrenceField: true, 52 IntentPartnerOrCompetitorRatio: true, 53 IntentRecompeteTeamingField: true, 54 // G5 clearance lattice (graph_clearance.go). 55 IntentClearanceReachability: true, 56 IntentCompartmentRequirement: true, 57 IntentBenchClearanceCoverage: true, 58 // G4 bench graph (graph_bench.go). 59 IntentBenchSkillCoverage: true, 60 IntentBenchReadinessDistribution: true, 61 IntentBenchGapForRequirement: true, 62 // G6 the loop (graph_loop.go), the composed capture picture, a person touching bench intent. 63 IntentCapturePictureForRequirement: true, 64 // M5 price to win (graph_wage.go), the advisory OEWS wage band, PUBLIC reference data, never suppressed. 65 IntentLaborRateBand: true, 66 // MAG opportunity win probability (mag.go), a model backed intent. It is registered here so the planner 67 // and Answer route it through the graph surface, but the AnswerGraph model fork dispatches it to 68 // answerModelIntent (NOT the raw ExecuteIntent path, which hard rejects a model intent), where it gathers 69 // its features through the guarded feature source intents and scores a calibrated probability in decimal. 70 IntentOpportunityWinProbability: true, 71 // Capture Readiness (capture_readiness.go), the bid pursue decision composition. Registered here so Answer 72 // and the planner route it through the graph surface; AnswerGraph intercepts it by name and dispatches to 73 // answerCaptureReadiness (NOT the raw ExecuteIntent path, whose registered SQL only resolves the segment). 74 IntentOpportunityCaptureReadiness: true, 75 // Phase 2 Vendor Intelligence (vendor.go), the vendor quality distribution: a person derived headcount 76 // partition, so it is ALSO a benchIntent below. It is a graph intent so Answer routes it to AnswerGraph, 77 // whose bench fork dispatches it to the suppressing VendorQualityDistribution executor, never the raw 78 // ExecuteIntent path. (vendor_performance_scorecard is a plain TAG aggregate, so it is deliberately NOT 79 // here and runs the standard AnswerTAG path.) 80 IntentVendorQualityDistribution: true, 81} 82 83// IsGraphIntent reports whether a registered intent name is a GRAPH intent (one of the G3 or G1 traversals), 84// so the Answer dispatcher routes it to AnswerGraph rather than AnswerTAG. An unknown or empty name is not a 85// graph intent. 86func IsGraphIntent(name string) bool { return graphIntents[name] } 87 88// benchIntents is the closed set of PERSON TOUCHING bench intents (the G4 bench plane plus the G5 89// bench_clearance_coverage intersection): every one reads the RLS protected person tables and pipes its 90// partition through small cell suppression. It is the set the D1 route gate uses to REQUIRE a resolved 91// authenticated tenant context (an org_id and user_id from the session) before a person touching read runs; 92// the G5 reference reads (clearance_reachability, compartment_requirement_closure) carry no person data and 93// are NOT in this set. Building the gate itself is task D1; this set and IsBenchIntent are the registration 94// the orchestrator's gate keys on. 95var benchIntents = map[string]bool{ 96 // G4 bench graph (graph_bench.go), all person touching and suppressed. 97 IntentBenchSkillCoverage: true, 98 IntentBenchReadinessDistribution: true, 99 IntentBenchGapForRequirement: true, 100 // G5 bench clearance coverage (graph_clearance.go), the one person touching read on the clearance plane. 101 IntentBenchClearanceCoverage: true, 102 // G6 the loop (graph_loop.go), the composed capture picture: it reads the bench, so it is person touching, 103 // auth gated, and rejected on the raw ExecuteIntent path; the bench fork dispatches it to its composition. 104 IntentCapturePictureForRequirement: true, 105 // Phase 2 Vendor Intelligence (vendor.go), the vendor quality distribution: it joins the vendor's 106 // submissions to the frozen candidate_evaluations band, a person derived per vendor per band headcount, so 107 // it is person touching, auth gated, rejected on the raw ExecuteIntent path, and runs only through the 108 // suppressing VendorQualityDistribution executor. 109 IntentVendorQualityDistribution: true, 110} 111 112// IsBenchIntent reports whether a registered intent name is a PERSON TOUCHING bench intent, so the D1 route 113// gate requires an authenticated tenant context before it runs. An unknown or empty name is not a bench 114// intent, and the G5 reference reads are deliberately excluded (they carry no person data). 115func IsBenchIntent(name string) bool { return benchIntents[name] } 116 117// AnswerGraph runs a registered GRAPH traversal and narrates its cited evidence path behind the faithfulness 118// gate, the structured graph path. It mirrors AnswerTAG exactly: it runs ForbidEEO and 119// MentionsProtectedAttribute on the question FIRST and refuses on either (the orchestrator precedent, so the 120// graph path can never group, filter, or rank by a protected attribute), looks the intent up by name, runs 121// it through ExecuteIntent (which re guards via GuardReadOnlyQuery and runs RLS scoped as the tenant), builds 122// a DETERMINISTIC evidence rendering of the returned rows (the cited path), and narrates through o.generate 123// and o.finalize so the model prose ships ONLY when the faithfulness gate confirms it, else the deterministic 124// rendering (a 200, rationale_source deterministic). A plane outage degrades to the deterministic rendering, 125// never a hang, because the data is the database's and generate returns a typed error that finalize turns 126// into the deterministic fallback. The audit is aedt.ai.answered route graph, carrying route, rationale 127// source, and the evidence COUNT only, never a UEI, a candidate id, a score, or answer text. 128func (o *Orchestrator) AnswerGraph(ctx context.Context, question, intentName string, args []any) (*Response, error) { 129 if ForbidEEO(question) != nil || MentionsProtectedAttribute(question) { 130 return o.refuse(ctx, RouteGraph, "the question references prohibited demographic data"), nil 131 } 132 intent, ok := IntentByName(intentName) 133 if !ok { 134 return nil, fmt.Errorf("%w: %q", ErrUnknownIntent, intentName) 135 } 136 // A MAG (model backed) intent runs through answerModelIntent, NEVER the raw ExecuteIntent path (which hard 137 // rejects a model intent). It gathers its features through the existing guarded feature source intents, 138 // scores a calibrated probability in decimal, and narrates the contribution trace behind the faithfulness 139 // gate. It emits an opportunity level number, never a per candidate score. 140 if IsModelIntent(intentName) { 141 return o.answerModelIntent(ctx, question, intentName, args) 142 } 143 // Capture Readiness is a graph COMPOSITION intercepted by name: its registered SQL only resolves the 144 // opportunity's segment, and the composition (answerCaptureReadiness) gathers the factors and composes the 145 // decimal score. It never runs as the raw query and never computes a per candidate score. 146 if intentName == IntentOpportunityCaptureReadiness { 147 id, err := benchIDArg(args) 148 if err != nil { 149 return nil, err 150 } 151 return o.answerCaptureReadiness(ctx, id) 152 } 153 // A person touching bench intent runs through its suppressing executor, NEVER the raw ExecuteIntent path 154 // (which returns unsuppressed counts and which hard rejects bench intents). The bench path requires an 155 // authenticated tenant context, renders only suppressed safe counts, and emits a counts only audit. The G6 156 // capture picture is a person touching COMPOSITION over the bench and market planes, so the bench fork 157 // dispatches it to answerCapturePicture; the other four bench intents run their single suppressing executor 158 // through answerBench unchanged. 159 if IsBenchIntent(intentName) { 160 if intentName == IntentCapturePictureForRequirement { 161 id, err := benchIDArg(args) 162 if err != nil { 163 return nil, err 164 } 165 return o.answerCapturePicture(ctx, id) 166 } 167 return o.answerBench(ctx, intentName, args) 168 } 169 res, err := ExecuteIntent(ctx, o.db, intent, args) 170 if err != nil { 171 return nil, err 172 } 173 rendered, _ := json.Marshal(map[string]any{"columns": res.Columns, "rows": res.Rows}) 174 evidence := []string{string(rendered)} 175 deterministic := renderGraphEvidence(intent.Description, res.Columns, res.Rows) 176 model, genErr := o.generate(ctx, 177 "State the result plainly from the graph evidence path. Cite the reached skills, the recipients, the agencies, and the awards exactly as the rows give them. Do not invent a UEI, a dollar figure, a share, or a skill the rows do not contain, and never compute a match score.", 178 "INTENT: "+intent.Description+"\n\nEVIDENCE PATH:\n"+string(rendered)) 179 return o.finalize(ctx, RouteGraph, model, genErr, deterministic, evidence), nil 180} 181 182// renderGraphEvidence builds a deterministic, readable answer from a graph traversal result, the cited path 183// the question is answered from even when the model prose is withheld. It reuses the TAG table rendering: a 184// graph row is already the cited evidence (the reached skill and its evidence path for G3; the recipient UEI, 185// the dollar share, the matched award for G1), so rendering the columns and rows verbatim, in the byte stable 186// order the deterministic SQL returns, is the faithful deterministic answer. No number is recomputed and no 187// score is produced; the rows are reported exactly as the database returned them. 188func renderGraphEvidence(description string, columns []string, rows [][]any) string { 189 return renderTable(description, columns, rows) 190} 191 192// answerBench runs a person touching bench intent through its suppressing executor and narrates only the 193// suppressed safe counts. It is the ONLY answer path for a bench intent: the raw ExecuteIntent path hard 194// rejects bench intents, so an unsuppressed sub k headcount can never be served. The bench plane reads RLS 195// protected person data, so it REQUIRES a resolved authenticated tenant context and refuses without one 196// rather than relying only on the RLS empty result fail safe. Every count placed into the evidence, the 197// model prompt, and the audit comes from RenderCount, so a suppressed cell is the sentinel and never a 198// number. The frozen engine stays the only scorer; this path computes no match score. 199func (o *Orchestrator) answerBench(ctx context.Context, intentName string, args []any) (*Response, error) { 200 if _, ok := tenant.OrgFromContext(ctx); !ok { 201 return o.refuse(ctx, RouteGraph, "a bench question requires an authenticated tenant context"), nil 202 } 203 k := ConfiguredSuppressionThreshold() 204 labels, cells, err := o.runBenchIntent(ctx, intentName, args, k) 205 if err != nil { 206 return nil, err 207 } 208 // Build the suppressed safe rendering: each cell renders through RenderCount, so a suppressed cell is the 209 // sentinel and no sub k number reaches the evidence, the model prompt, or the audit. 210 columns := []string{"bucket", "headcount"} 211 rows := make([][]any, len(cells)) 212 suppressed := 0 213 for i, c := range cells { 214 if c.Suppressed { 215 suppressed++ 216 } 217 rows[i] = []any{labels[i], RenderCount(c)} 218 } 219 deterministic := renderBenchEvidence(intentName, columns, rows, suppressed, k) 220 rendered, _ := json.Marshal(map[string]any{"columns": columns, "rows": rows}) 221 evidence := []string{string(rendered)} 222 model, genErr := o.generate(ctx, 223 "State the bench counts plainly from the evidence. Report each bucket's 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. Never compute a match score.", 224 "INTENT: "+intentName+"\n\nEVIDENCE:\n"+string(rendered)) 225 resp := o.finalize(ctx, RouteGraph, model, genErr, deterministic, evidence) 226 // Counts only, suppression aware audit: the intent, the cell count, the suppressed count, and the 227 // configured k. It carries NO candidate id, NO raw sub k count, and NO answer text. 228 o.audit(ctx, "aedt.ai.bench_answered", map[string]any{"route": RouteGraph, "intent": intentName, "cells": len(cells), "suppressed": suppressed, "k": k}) 229 return resp, nil 230} 231 232// runBenchIntent dispatches a bench intent name to its suppressing Go executor and returns the partition as 233// parallel label and Cell slices (the Cells are already small cell suppressed by the executor). It is the 234// single place that runs a bench intent; the generic ExecuteIntent rejects them so an unsuppressed raw count 235// can never be served. 236func (o *Orchestrator) runBenchIntent(ctx context.Context, intentName string, args []any, k int) ([]string, []Cell, error) { 237 switch intentName { 238 case IntentBenchSkillCoverage: 239 id, err := benchIDArg(args) 240 if err != nil { 241 return nil, nil, err 242 } 243 out, err := BenchSkillCoverage(ctx, o.db, id, k) 244 if err != nil { 245 return nil, nil, err 246 } 247 labels := make([]string, len(out)) 248 cells := make([]Cell, len(out)) 249 for i, r := range out { 250 labels[i], cells[i] = r.Bucket, r.Cell 251 } 252 return labels, cells, nil 253 case IntentBenchReadinessDistribution: 254 id, err := benchIDArg(args) 255 if err != nil { 256 return nil, nil, err 257 } 258 out, err := BenchReadinessDistribution(ctx, o.db, id, k) 259 if err != nil { 260 return nil, nil, err 261 } 262 labels := make([]string, len(out)) 263 cells := make([]Cell, len(out)) 264 for i, r := range out { 265 labels[i], cells[i] = r.Band, r.Cell 266 } 267 return labels, cells, nil 268 case IntentBenchGapForRequirement: 269 id, err := benchIDArg(args) 270 if err != nil { 271 return nil, nil, err 272 } 273 out, err := BenchGapForRequirement(ctx, o.db, id, k) 274 if err != nil { 275 return nil, nil, err 276 } 277 labels := make([]string, len(out)) 278 cells := make([]Cell, len(out)) 279 for i, r := range out { 280 labels[i], cells[i] = r.Bucket, r.Cell 281 } 282 return labels, cells, nil 283 case IntentBenchClearanceCoverage: 284 out, err := BenchClearanceCoverage(ctx, o.db, k) 285 if err != nil { 286 return nil, nil, err 287 } 288 labels := make([]string, len(out)) 289 cells := make([]Cell, len(out)) 290 for i, r := range out { 291 labels[i], cells[i] = r.LevelCode, r.Cell 292 } 293 return labels, cells, nil 294 case IntentVendorQualityDistribution: 295 // The vendor quality distribution takes no id (it reports every vendor the caller's org has recorded), 296 // like the bench clearance coverage. Each row's label is the vendor name and the frozen band so the 297 // suppressed rendering names which vendor and band a cell belongs to; the Cell is already small cell 298 // suppressed per vendor by the executor. 299 out, err := VendorQualityDistribution(ctx, o.db, k) 300 if err != nil { 301 return nil, nil, err 302 } 303 labels := make([]string, len(out)) 304 cells := make([]Cell, len(out)) 305 for i, r := range out { 306 labels[i], cells[i] = r.VendorName+" / "+r.Band, r.Cell 307 } 308 return labels, cells, nil 309 default: 310 return nil, nil, fmt.Errorf("ai: %q is not a bench intent", intentName) 311 } 312} 313 314// benchIDArg extracts the single id argument a bench intent that keys on a UUID expects (a skill id or a 315// requirement id), accepting a string or any fmt.Stringer (so a uuid.UUID binds), and rejecting a missing, 316// empty, or wrong shaped argument. 317func benchIDArg(args []any) (string, error) { 318 if len(args) != 1 { 319 return "", fmt.Errorf("ai: a bench intent expects exactly one id argument, got %d", len(args)) 320 } 321 switch v := args[0].(type) { 322 case string: 323 if v == "" { 324 return "", fmt.Errorf("ai: a bench intent id argument must be a non empty string") 325 } 326 return v, nil 327 case fmt.Stringer: 328 s := v.String() 329 if s == "" { 330 return "", fmt.Errorf("ai: a bench intent id argument must be a non empty string") 331 } 332 return s, nil 333 default: 334 return "", fmt.Errorf("ai: a bench intent id argument must be a string, got %T", args[0]) 335 } 336} 337 338// renderBenchEvidence builds the deterministic, suppressed safe answer for a bench intent: each bucket with 339// its headcount (the sentinel for a suppressed cell), plus a fixed line naming how many of the buckets were 340// withheld to protect individuals. No raw sub k count appears, so the deterministic fallback is itself safe. 341func renderBenchEvidence(intentName string, columns []string, rows [][]any, suppressed, k int) string { 342 base := renderTable(intentName, columns, rows) 343 if suppressed > 0 { 344 base += fmt.Sprintf(" %d of %d buckets withheld to protect individuals (fewer than %d).", suppressed, len(rows), k) 345 } 346 return base 347} 348 349// graphRoute is the chosen graph intent plus the bound params the conservative NL classifier extracted. A nil 350// graphRoute means the question did not clearly name a graph traversal, or it named one but the required 351// params could not be extracted unambiguously, so the caller falls back to the existing RAG path. 352type graphRoute struct { 353 intent string 354 args []any 355} 356 357// naicsRe matches a bare six digit NAICS code as a standalone token, the only NAICS shape extracted 358// unambiguously from free text. Anything else (a partial code, a code embedded in a larger number) is not 359// extracted, so the classifier never guesses a segment key. 360var naicsRe = regexp.MustCompile(`\b(\d{6})\b`) 361 362// quotedAgencyRe matches a single or double quoted span, the only agency name extracted unambiguously from 363// free text. A bare agency phrase is NOT extracted (the buyer name is ambiguous without quotes), so the 364// classifier never guesses an agency and never authors a param the user did not delimit. 365var quotedAgencyRe = regexp.MustCompile(`["']([^"']{2,})["']`) 366 367// windowMonthsRe matches an explicit forward window phrased as a number of months, so a recompete question 368// that names its own window binds it; an unspecified window falls to the intent's own default clamp. 369var windowMonthsRe = regexp.MustCompile(`(\d{1,3})\s*month`) 370 371// graphClassify is the conservative natural language router for the graph surface. It maps a free form 372// question that CLEARLY names a capture or skill graph traversal (a curated keyword to intent table, never an 373// LLM, mirroring how Classify routes count and sum to TAG) to a graphRoute, and returns nil when the question 374// is not a graph question OR when it is but the required structured params cannot be extracted unambiguously. 375// Because the graph intents need structured params (an agency, a NAICS, an opportunity id, a skill id) that 376// are hard to extract deterministically from free text, extraction is deliberately MINIMAL: only a bare six 377// digit NAICS and a quoted agency name are read, and when a matched intent's required params are missing the 378// caller falls back to the existing RAG path rather than guessing. The model never authors the params; the 379// intent and its arg slots are fixed here. 380func graphClassify(question string) *graphRoute { 381 q := strings.ToLower(question) 382 383 // G6 the loop, the composed capture picture for a requirement. It reads the bench (person touching), so it 384 // keys on a requirement id (a UUID), which a user almost never types in free text; a capture picture 385 // question routes here only when it carries an explicit canonical UUID, the same conservative posture as 386 // the bench readiness and bench gap routes. It is checked FIRST so its distinct integrated phrasing wins 387 // over the narrower bench gap keywords. Absent an explicit requirement id it falls back to RAG rather than 388 // guessing a requirement. 389 captureKeywords := []string{"capture picture", "can we staff", "staffing and market", "staff it and the market", "bench and the market for the requirement"} 390 if containsAny(q, captureKeywords) { 391 if id, ok := quotedUUID(question); ok { 392 return &graphRoute{intent: IntentCapturePictureForRequirement, args: []any{id}} 393 } 394 return nil // a capture picture question with no explicit requirement id falls back to RAG 395 } 396 397 // MAG opportunity win probability (pwin) is the calibrated probability of winning an opportunity in a 398 // customer agency segment. It is a MODEL backed intent, an opportunity level number, NEVER a per candidate 399 // score. It is checked EARLY so its distinct win probability phrasing wins over the broader recompete and 400 // competitor keywords. It binds honestly only when the question carries a quoted agency (the only 401 // unambiguous segment key in free text); the naics is optional (the empty string means the overall segment, 402 // the model's own default). Absent a quoted agency it falls back to RAG rather than guessing a segment. 403 winProbabilityKeywords := []string{"win probability", "pwin", "p win", "probability of win", "probability of winning", "chance of winning"} 404 if containsAny(q, winProbabilityKeywords) { 405 agency, hasAgency := quotedAgency(question) 406 if hasAgency { 407 naics, _ := bareNAICS(question) // optional; the empty string is the model's overall segment default 408 return &graphRoute{intent: IntentOpportunityWinProbability, args: []any{agency, naics}} 409 } 410 return nil // a win probability question with no quoted agency falls back to RAG 411 } 412 413 // M5 labor rate band is the advisory OEWS prevailing wage for a role in a state, the price to win rate. It 414 // is PUBLIC reference data (bls_wages), never suppressed and never a candidate score. It binds honestly only 415 // when the question names BOTH a role we can resolve to a SOC through the curated crosswalk (from a quoted 416 // role span, the only unambiguous role shape in free text) AND a state we can resolve to a known OEWS area 417 // code (HI or NM), so an unresolvable role or a state with no wage data falls back to RAG rather than 418 // guessing a rate. It is checked here, before the market and skill routes, so its distinct wage phrasing 419 // wins over the broader keywords. 420 wageKeywords := []string{"labor rate", "prevailing wage", "oews wage", "price to win rate"} 421 if containsAny(q, wageKeywords) { 422 role, hasRole := quotedRole(question) 423 area, hasArea := quotedStateArea(question) 424 if hasRole && hasArea { 425 if occ, ok := resolveSOC(role); ok { 426 return &graphRoute{intent: IntentLaborRateBand, args: []any{occ.SOC, area}} 427 } 428 } 429 return nil // a wage question whose role or state we cannot resolve unambiguously falls back to RAG 430 } 431 432 // G5 bench clearance coverage is the suppressed structural headcount of the caller's bench per clearance 433 // level. It takes no SQL parameter (the suppression threshold is a Go argument, not a bound param), so a 434 // question that clearly asks for the clearance breakdown of the bench routes here directly. It is checked 435 // BEFORE the reachability route so the distinct bench coverage phrasing wins over a bare clearance keyword. 436 benchCoverageKeywords := []string{"clearance coverage", "clearance breakdown", "clearance distribution", "how many of our bench hold", "bench by clearance", "clearance mix of our bench"} 437 if containsAny(q, benchCoverageKeywords) { 438 return &graphRoute{intent: IntentBenchClearanceCoverage, args: nil} 439 } 440 441 // G4 bench skill coverage is the suppressed structural count of the caller's bench that holds a given 442 // skill versus does not. It keys on a skill id (a UUID), which a user almost never types in free text, so 443 // a bench skill coverage question routes only when it carries an explicit canonical UUID; absent one it 444 // falls back to RAG rather than guessing a skill. The same conservative UUID posture as the skill 445 // adjacency walks. 446 benchSkillKeywords := []string{"bench skill coverage", "how many of our bench hold the skill", "bench coverage for the skill", "who on the bench has the skill"} 447 if containsAny(q, benchSkillKeywords) { 448 if id, ok := quotedUUID(question); ok { 449 return &graphRoute{intent: IntentBenchSkillCoverage, args: []any{id}} 450 } 451 return nil // a bench skill coverage question with no explicit skill id falls back to RAG 452 } 453 454 // G4 bench readiness distribution is the suppressed distribution of bands the frozen engine already 455 // decided for one requirement, read from the audited candidate_evaluations. It keys on a requirement id 456 // (a UUID); absent an explicit canonical UUID it falls back to RAG rather than guessing a requirement. 457 benchReadinessKeywords := []string{"bench readiness", "readiness distribution", "band distribution", "how ready is our bench"} 458 if containsAny(q, benchReadinessKeywords) { 459 if id, ok := quotedUUID(question); ok { 460 return &graphRoute{intent: IntentBenchReadinessDistribution, args: []any{id}} 461 } 462 return nil // a bench readiness question with no explicit requirement id falls back to RAG 463 } 464 465 // G4 bench gap for a requirement is the suppressed structural count of the bench that meets a requirement 466 // versus does not, a count to size a gap, never a match score. It keys on a requirement id (a UUID); 467 // absent an explicit canonical UUID it falls back to RAG rather than guessing a requirement. 468 benchGapKeywords := []string{"bench gap", "structural gap", "how many of our bench meet", "who meets the requirement"} 469 if containsAny(q, benchGapKeywords) { 470 if id, ok := quotedUUID(question); ok { 471 return &graphRoute{intent: IntentBenchGapForRequirement, args: []any{id}} 472 } 473 return nil // a bench gap question with no explicit requirement id falls back to RAG 474 } 475 476 // G5 clearance reachability is the lattice fact: which required levels a held clearance satisfies. It binds 477 // the held clearance code from the six reference codes named in the question (the only unambiguous held key 478 // in free text); absent a named held clearance it falls back to RAG rather than guessing a level. 479 reachabilityKeywords := []string{"clearance satisfies", "what does a clearance satisfy", "which clearances satisfy", "clearance reachability", "satisfy the requirement", "clearance ladder"} 480 if containsAny(q, reachabilityKeywords) { 481 if code, ok := heldClearanceCode(q); ok { 482 return &graphRoute{intent: IntentClearanceReachability, args: []any{code}} 483 } 484 return nil // a reachability question with no named held clearance falls back to RAG 485 } 486 487 // G5 compartment requirement closure resolves a requirement's compartment codes to their kind. It binds the 488 // quoted comma separated compartment list (the only unambiguous compartment shape in free text); absent a 489 // quoted list it falls back to RAG rather than guessing the compartments. 490 compartmentKeywords := []string{"compartment required", "required compartments", "compartment closure", "which compartments", "sci compartment", "compartment gap"} 491 if containsAny(q, compartmentKeywords) { 492 if list, ok := quotedCompartmentList(question); ok { 493 return &graphRoute{intent: IntentCompartmentRequirement, args: []any{list}} 494 } 495 return nil // a compartment question with no quoted compartment list falls back to RAG 496 } 497 498 // G9 procurement succession is the lifecycle walk of one solicitation. It keys on an opportunity id (a 499 // UUID), which a user almost never types in free text, so a succession or lifecycle question routes only 500 // when it carries an explicit canonical UUID; absent one it falls back to RAG rather than guessing an 501 // opportunity. This is the same conservative posture as the skill adjacency UUID binding. 502 successionKeywords := []string{"succession", "lifecycle", "new or recompete", "is this a recompete", "predecessor award"} 503 if containsAny(q, successionKeywords) { 504 if id, ok := quotedUUID(question); ok { 505 return &graphRoute{intent: IntentProcurementSuccession, args: []any{id}} 506 } 507 return nil // a succession question with no explicit opportunity id falls back to RAG 508 } 509 510 // G9 recompete clock is the agency forward window read. The distinct phrase recompete clock routes here 511 // (checked BEFORE the existing recompete pipeline keyword so the more specific phrase wins) when a quoted 512 // agency is present, with the window defaulting to the intent clamp unless the question names a number of 513 // months. A bare recompete with no clock phrase still routes to the existing pipeline below, byte 514 // unchanged. 515 clockKeywords := []string{"recompete clock", "recompete window", "pop end window", "period of performance end"} 516 if containsAny(q, clockKeywords) { 517 agency, hasAgency := quotedAgency(question) 518 if hasAgency { 519 return &graphRoute{intent: IntentRecompeteClock, args: []any{agency, windowMonths(question)}} 520 } 521 return nil // a recompete clock question with no quoted agency falls back to RAG 522 } 523 524 // G9 forecast runway is the forward window read of agency forecasts by estimated award date. It routes 525 // only when the question names the forecast runway AND an explicit number of months (its only param), so 526 // the window is unambiguous; a forecast question with no stated window falls back to RAG rather than 527 // inventing a horizon. 528 runwayKeywords := []string{"forecast runway", "forecast pipeline", "upcoming forecasts", "forecast lead time"} 529 if containsAny(q, runwayKeywords) { 530 if months := windowMonths(question); months > 0 { 531 return &graphRoute{intent: IntentForecastRunway, args: []any{months}} 532 } 533 return nil // a forecast runway question with no explicit window falls back to RAG 534 } 535 536 // G7 agency vendor concentration is the recency weighted recipient dollar share for one (agency, naics) award 537 // segment. It needs BOTH a quoted agency and a bare six digit NAICS to bind honestly (the only keys 538 // usaspending_awards carries); it is checked BEFORE the competitor block so the distinct vendor concentration 539 // phrase wins over the broader competitor keywords. If either param is missing the question falls back to RAG. 540 vendorConcentrationKeywords := []string{"vendor concentration", "recipient concentration", "vendor share", "vendor concentration in", "concentration of vendors"} 541 if containsAny(q, vendorConcentrationKeywords) { 542 agency, hasAgency := quotedAgency(question) 543 naics, hasNAICS := bareNAICS(question) 544 if hasAgency && hasNAICS { 545 return &graphRoute{intent: IntentAgencyVendorConcentration, args: []any{agency, naics}} 546 } 547 return nil // a vendor concentration question whose segment we cannot bind unambiguously falls back to RAG 548 } 549 550 // G7 agency spend trend is the obligation trend by fiscal period for one (agency, naics) segment. It needs 551 // BOTH a quoted agency and a bare six digit NAICS to bind honestly; absent either it falls back to RAG. 552 spendTrendKeywords := []string{"spend trend", "obligation trend", "spending trend", "concentrating or fragmenting", "spend over time"} 553 if containsAny(q, spendTrendKeywords) { 554 agency, hasAgency := quotedAgency(question) 555 naics, hasNAICS := bareNAICS(question) 556 if hasAgency && hasNAICS { 557 return &graphRoute{intent: IntentAgencySpendTrend, args: []any{agency, naics}} 558 } 559 return nil // a spend trend question whose segment we cannot bind unambiguously falls back to RAG 560 } 561 562 // G7 agency buying pattern detail is the fuller where to position view (the vehicle mix, the set aside mix, the 563 // NAICS and PSC distribution, and the average and median value band). It routes on the distinct detail phrasing, 564 // checked BEFORE the existing G1 buying pattern keyword so the more specific phrase wins and the Phase 0 buying 565 // pattern route stays byte unchanged. It needs a quoted agency; the NAICS is optional (the empty string means 566 // every NAICS, the intent's own default). 567 buyingDetailKeywords := []string{"buying pattern detail", "vehicle mix", "value band", "average and median", "detailed buying pattern", "how does the agency buy"} 568 if containsAny(q, buyingDetailKeywords) { 569 agency, hasAgency := quotedAgency(question) 570 if hasAgency { 571 naics, _ := bareNAICS(question) // optional; the empty string is the intent's every NAICS default 572 return &graphRoute{intent: IntentAgencyBuyingPatternDetail, args: []any{agency, naics}} 573 } 574 return nil // a buying pattern detail question with no quoted agency falls back to RAG 575 } 576 577 // G2 partner or competitor ratio is the team versus compete read for one partner UEI in a core NAICS, from 578 // public co occurrence alone. It is checked FIRST among the G2 routes so the distinct partner versus 579 // competitor phrasing wins over the broader teaming keywords below. It needs BOTH a quoted UEI (a twelve 580 // character partner identifier the user delimits) and a bare six digit NAICS to bind honestly; absent 581 // either it falls back to RAG. It reads only the public is_galapagos self tag, never a tenant table. 582 partnerRatioKeywords := []string{"partner or competitor", "team or compete", "team versus compete", "do they team or compete", "partner versus competitor"} 583 if containsAny(q, partnerRatioKeywords) { 584 uei, hasUEI := quotedUEI(question) 585 naics, hasNAICS := bareNAICS(question) 586 if hasUEI && hasNAICS { 587 return &graphRoute{intent: IntentPartnerOrCompetitorRatio, args: []any{uei, naics}} 588 } 589 return nil // a partner or competitor question whose partner UEI and NAICS we cannot bind falls back to RAG 590 } 591 592 // G2 recompete teaming field is the forward window read of the incumbent's co occurring vendor 593 // neighborhood, the likely teaming field before the RFP drops. It is checked BEFORE the broader vendor co 594 // occurrence keywords so the distinct recompete teaming phrasing wins. It needs a quoted agency; the window 595 // defaults to the intent clamp unless the question names a number of months. 596 recompeteTeamingKeywords := []string{"recompete teaming", "teaming field before the rfp", "teaming field before the recompete", "who could team on the recompete"} 597 if containsAny(q, recompeteTeamingKeywords) { 598 agency, hasAgency := quotedAgency(question) 599 if hasAgency { 600 return &graphRoute{intent: IntentRecompeteTeamingField, args: []any{agency, windowMonths(question)}} 601 } 602 return nil // a recompete teaming question with no quoted agency falls back to RAG 603 } 604 605 // G2 vendor co occurrence field is the set of UEIs that co occur in one (agency, naics) segment, the likely 606 // teaming and competitor field. It is checked BEFORE the broader competitor block so the distinct co 607 // occurrence and teaming field phrasing wins. It needs BOTH a quoted agency and a bare six digit NAICS to 608 // bind honestly (the only keys usaspending_awards carries); absent either it falls back to RAG. 609 cooccurrenceKeywords := []string{"co occur", "cooccur", "co occurrence", "cooccurrence", "teaming field", "who teams up", "vendor field", "who appears together"} 610 if containsAny(q, cooccurrenceKeywords) { 611 agency, hasAgency := quotedAgency(question) 612 naics, hasNAICS := bareNAICS(question) 613 if hasAgency && hasNAICS { 614 return &graphRoute{intent: IntentVendorCooccurrenceField, args: []any{agency, naics}} 615 } 616 return nil // a co occurrence question whose segment we cannot bind unambiguously falls back to RAG 617 } 618 619 // The competitor field and the incumbent walk are agency plus NAICS segment questions. They need both a 620 // quoted agency and a bare six digit NAICS to bind honestly (the only keys usaspending_awards carries); if 621 // either is missing the question falls back to RAG. 622 competitorKeywords := []string{"competitor", "incumbent", "who teams", "teaming", "who else won", "market share", "dollar share", "who holds the work", "who has the work"} 623 if containsAny(q, competitorKeywords) { 624 agency, hasAgency := quotedAgency(question) 625 naics, hasNAICS := bareNAICS(question) 626 if hasAgency && hasNAICS { 627 // The recency lookback is left to the intent's own default clamp (a bound zero), so the NL path never 628 // invents a lookback the user did not state. 629 return &graphRoute{intent: IntentSegmentCompetitorField, args: []any{agency, naics, 0}} 630 } 631 return nil // a competitor or incumbent question whose segment we cannot bind unambiguously falls back to RAG 632 } 633 634 // The recompete pipeline is an agency plus a forward window question. It needs a quoted agency; the window 635 // is the intent's default clamp unless the question names an explicit number of months. 636 recompeteKeywords := []string{"recompete", "recompete pipeline", "expiring", "coming up for", "pipeline of", "what is coming up", "takeaway"} 637 if containsAny(q, recompeteKeywords) { 638 agency, hasAgency := quotedAgency(question) 639 if hasAgency { 640 return &graphRoute{intent: IntentRecompetePipeline, args: []any{agency, windowMonths(question)}} 641 } 642 return nil // a recompete question with no quoted agency falls back to RAG 643 } 644 645 // The agency buying pattern is a where to position question keyed on a quoted agency or department prefix, 646 // with an optional bare NAICS filter (the empty string means every NAICS, the intent's own default). 647 buyingKeywords := []string{"agency buys", "agency buying", "buying pattern", "what does the agency buy", "where to position", "where should we position", "set aside mix", "set-aside mix"} 648 if containsAny(q, buyingKeywords) { 649 agency, hasAgency := quotedAgency(question) 650 if hasAgency { 651 naics, _ := bareNAICS(question) // optional; the empty string is the intent's every NAICS default 652 return &graphRoute{intent: IntentAgencyBuyingPattern, args: []any{agency, naics}} 653 } 654 return nil // a buying pattern question with no quoted agency falls back to RAG 655 } 656 657 // The skill substitution and gap bridge walks key on a skill id (a UUID), which a user almost never types in 658 // free text. A skill adjacency question (what substitutes for, skill adjacency, what is close to) that names 659 // no skill id cannot be bound deterministically, so it falls back to RAG rather than guessing a skill. A 660 // quoted UUID is the only unambiguous skill key; absent one, RAG. 661 skillKeywords := []string{"what substitutes for", "substitutes for", "skill adjacency", "adjacent skill", "skill gap", "what is close to", "what bridges"} 662 if containsAny(q, skillKeywords) { 663 if id, ok := quotedUUID(question); ok { 664 return &graphRoute{intent: IntentSkillSubstitutionClosure, args: []any{id, 0}} 665 } 666 return nil // a skill question with no explicit skill id falls back to RAG 667 } 668 669 return nil // not a graph question 670} 671 672// containsAny reports whether the lowercased question contains any of the keywords. 673func containsAny(loweredQuestion string, keywords []string) bool { 674 for _, kw := range keywords { 675 if strings.Contains(loweredQuestion, kw) { 676 return true 677 } 678 } 679 return false 680} 681 682// quotedAgency extracts a quoted agency name from the question, the only unambiguous agency shape. The match 683// is from the ORIGINAL cased question (the agency name in the database is cased), so the bound param preserves 684// the user's casing. A missing or too short quoted span is not an agency. 685func quotedAgency(question string) (string, bool) { 686 m := quotedAgencyRe.FindStringSubmatch(question) 687 if len(m) < 2 { 688 return "", false 689 } 690 agency := strings.TrimSpace(m[1]) 691 if agency == "" { 692 return "", false 693 } 694 return agency, true 695} 696 697// quotedRole extracts a quoted role span from the question, the only unambiguous role shape in free text, so 698// the M5 wage route binds only an explicitly delimited role the caller means (for example "Program Manager"). 699// It reuses the quoted span matcher; a bare role phrase is NOT extracted (the role is ambiguous without 700// quotes), so the classifier never guesses a role. The match is from the ORIGINAL cased question so 701// resolveSOC sees the caller's casing. Absent a quoted role a wage question falls back to RAG. 702func quotedRole(question string) (string, bool) { 703 m := quotedAgencyRe.FindStringSubmatch(question) 704 if len(m) < 2 { 705 return "", false 706 } 707 role := strings.TrimSpace(m[1]) 708 if role == "" { 709 return "", false 710 } 711 return role, true 712} 713 714// quotedStateArea resolves a state named anywhere in the question to a known OEWS area code (HI or NM) through 715// the same conservative matcher the G6 composition uses, so the M5 wage route binds only a state the wage 716// baseline covers. A question naming no known state (or a state with no wage data) yields ok false and falls 717// back to RAG rather than guessing a state. 718func quotedStateArea(question string) (string, bool) { 719 return resolveArea(question) 720} 721 722// bareNAICS extracts a single bare six digit NAICS token from the question. Exactly one six digit token must 723// be present for an unambiguous segment key; zero matches is no NAICS, and the first match is taken when one 724// is present (a question rarely carries two distinct six digit codes, and the first is the segment of 725// interest). 726func bareNAICS(question string) (string, bool) { 727 m := naicsRe.FindStringSubmatch(question) 728 if len(m) < 2 { 729 return "", false 730 } 731 return m[1], true 732} 733 734// windowMonths extracts an explicit forward window in months when the question states one, else returns 0 so 735// the recompete intent applies its own default clamp. A stated window is clamped by the intent, so an 736// oversized number is bounded downstream. 737func windowMonths(question string) int { 738 m := windowMonthsRe.FindStringSubmatch(strings.ToLower(question)) 739 if len(m) < 2 { 740 return 0 741 } 742 n, err := strconv.Atoi(m[1]) 743 if err != nil { 744 return 0 745 } 746 return n 747} 748 749// ueiRe matches a quoted twelve character SAM UEI (the alphanumeric unique entity identifier), the only 750// unambiguous partner identifier a free form question can carry. The quotes delimit the partner the user 751// means, so the classifier never guesses a UEI from a bare token; the twelve character alphanumeric shape is 752// the SAM UEI format. A bare twelve character token in prose is NOT extracted (it is ambiguous), so the 753// partner ratio route binds only an explicitly delimited UEI. 754var ueiRe = regexp.MustCompile(`(?i)["']([0-9a-z]{12})["']`) 755 756// quotedUEI extracts a quoted twelve character UEI from the question, the only unambiguous partner id shape. 757// The match is from the ORIGINAL cased question so the bound param preserves the UEI's casing. Absent a quoted 758// UEI a partner or competitor question has no bindable partner and falls back to RAG. 759func quotedUEI(question string) (string, bool) { 760 m := ueiRe.FindStringSubmatch(question) 761 if len(m) < 2 { 762 return "", false 763 } 764 return m[1], true 765} 766 767// uuidRe matches a canonical UUID, the only unambiguous skill id a free form question can carry. 768var uuidRe = regexp.MustCompile(`(?i)\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b`) 769 770// quotedUUID extracts a canonical UUID from the question, the only unambiguous skill id shape. Absent one, a 771// skill adjacency question has no bindable start skill and falls back to RAG. 772func quotedUUID(question string) (string, bool) { 773 id := uuidRe.FindString(question) 774 if id == "" { 775 return "", false 776 } 777 return id, true 778} 779 780// heldClearanceCode extracts a held clearance code from a lowercased question by matching the natural 781// language phrase for each of the six reference codes, the only unambiguous held key in free text. The 782// longer phrases are checked first so ts sci wins over secret and top secret wins over secret. The matched 783// code is one of the six ParamEnum allowed values, so ExecuteIntent's enum guard accepts it; absent a named 784// held clearance the reachability question falls back to RAG rather than guessing a level. 785func heldClearanceCode(loweredQuestion string) (string, bool) { 786 // Ordered longest phrase first so a more specific clearance wins over a shorter substring. 787 phrases := []struct { 788 phrase string 789 code string 790 }{ 791 {"ts/sci", "ts_sci"}, 792 {"ts sci", "ts_sci"}, 793 {"ts_sci", "ts_sci"}, 794 {"top secret sci", "ts_sci"}, 795 {"sci", "ts_sci"}, 796 {"top secret", "top_secret"}, 797 {"top_secret", "top_secret"}, 798 {"secret", "secret"}, 799 {"confidential", "confidential"}, 800 {"public trust", "none"}, 801 {"unknown", "unknown"}, 802 } 803 for _, p := range phrases { 804 if strings.Contains(loweredQuestion, p.phrase) { 805 return p.code, true 806 } 807 } 808 return "", false 809} 810 811// compartmentListRe matches a quoted comma separated compartment list, the only unambiguous compartment 812// shape a free form question can carry. The quotes delimit the codes the user means, so the classifier never 813// guesses a compartment from a bare token; the match is from the ORIGINAL cased question because compartment 814// codes are upper cased in the reference table. 815var compartmentListRe = regexp.MustCompile(`["']([A-Za-z0-9, ]{1,})["']`) 816 817// quotedCompartmentList extracts a quoted comma separated compartment list from the question, the only 818// unambiguous compartment shape. Absent a quoted list a compartment question has no bindable compartments and 819// falls back to RAG. 820func quotedCompartmentList(question string) (string, bool) { 821 m := compartmentListRe.FindStringSubmatch(question) 822 if len(m) < 2 { 823 return "", false 824 } 825 list := strings.TrimSpace(m[1]) 826 if list == "" { 827 return "", false 828 } 829 return list, true 830} 831