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

1package ai 2 3// THE PLANNER. This file generalizes the G6 loop (the one hardcoded fan out over four fixed intents in 4// graph_loop.go) into a data driven planner that answers a COMPOUND cross plane question by SELECTING and 5// running a set of EXISTING closed Registry intents and composing their evidence behind the faithfulness 6// gate. It is the biggest unlock on the ANI roadmap: it turns the single shot keyword router (which drops 7// every compound capture question to RAG narration) into a true multi step reasoner, while the model 8// authors ZERO SQL and ZERO param values. 9// 10// Why this is safe by construction. The model NEVER authors SQL and NEVER supplies a param value. It 11// selects from a CLOSED enum of intent names; the validator asserts every name is in Registry and drops 12// anything else. Every param value comes from the same deterministic extractors graphClassify already uses 13// (bareNAICS, quotedAgency, quotedUUID, heldClearanceCode, quotedUEI, windowMonths, quotedCompartmentList), 14// so the read only guard, the EEO and protected attribute guards, bench suppression, RLS RunInTenantTx, and 15// the frozen engine boundary all apply UNCHANGED on every node (each node runs its existing guarded path). 16// A bench node runs only through the suppressing executor (runBenchIntent), never the raw ExecuteIntent 17// path (which already hard rejects bench intents). The G6 capture composition runs through 18// answerCapturePicture. Every other graph or TAG intent runs through ExecuteIntent. The planner adds NO new 19// query and NO new SQL. Hard caps (maxPlanNodes, no recursion) bound the work; the surviving node set runs 20// in a deterministic order (Registry order, then name) so the composed answer is byte stable. Self 21// consistency samples the plan K times and runs only the stable intent set. The plan trace audit carries 22// only names, kinds, counts, and verdicts, never a value and never PII. 23// 24// Iteration 1 (this file) is planned SELECTION with deterministic binding. Data dependency edges (one 25// node's scalar output binding a downstream node's arg) are a documented iteration 2, explicitly out of 26// scope here so the first planner is maximally safe. 27 28import ( 29 "context" 30 "encoding/json" 31 "sort" 32 "strings" 33 34 "github.com/missionworkforce/missionmatch/internal/platform/inference" 35 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 36) 37 38// PlanNode is one selected intent in a plan: a name that MUST be in the closed Registry, plus the args the 39// validator bound for it from the available params. The model supplies only the Intent name; Args are bound 40// deterministically by the orchestrator, never by the model. 41type PlanNode struct { 42 Intent string 43 Args []any 44 // EdgeFrom, when non empty, marks that the arg at EdgeArgIdx is supplied at RUN time from the upstream 45 // EdgeFrom intent's EdgeColumn output (its first result row), not from the question and not from the model. 46 // The value is a PUBLIC identifier and the catalog is fixed; a placeholder empty string sits in 47 // Args[EdgeArgIdx] until the runner resolves it, and if the upstream yields no value the node is dropped. 48 EdgeFrom string 49 EdgeColumn string 50 EdgeArgIdx int 51} 52 53// Plan is the validated, bounded set of intents to run for one compound question. It carries no SQL and no 54// model authored value; every Intent is a Registry name and every Arg came from a deterministic extractor. 55type Plan struct { 56 Nodes []PlanNode 57} 58 59// planEdge is one allowed data dependency edge in the CLOSED catalog: an upstream intent's named output column 60// supplies a downstream intent's named param. This is what turns the planner from a set of independent lookups 61// into a chained reasoner ("recompetes for whoever holds the SIGINT work" becomes incumbent then that 62// incumbent's field). It is safe the same way the rest of the planner is: the model authors NO edge (the 63// catalog is fixed Go, not model output), every source column is a PUBLIC federal identifier (a prime UEI from 64// the public award tables), and a bench, person, or EEO intent is NEVER a source, so no candidate or 65// demographic value can ever flow through a chain. An edge wires only when BOTH endpoints are already in the 66// selected plan, and the value comes from the upstream RESULT (first row of the named column), never invented. 67type planEdge struct { 68 FromIntent string // upstream intent name, a Registry name 69 FromColumn string // the upstream result column that carries the value, a PUBLIC identifier only 70 ToIntent string // downstream intent name 71 ToParam string // the downstream Registry param the value binds 72} 73 74// edgeCatalog is the CLOSED, fixed set of legal dependency edges. Every source column is a public prime UEI 75// from the public market reads (incumbent_of_record and segment_competitor_field over usaspending_awards and 76// opportunity_records), never a bench or person or EEO output, so the PII firewall holds by construction. 77// Adding an edge is a code change reviewed like any other, never a runtime or model decision. A unit test 78// asserts every source is in the Registry and is not a bench intent. 79var edgeCatalog = []planEdge{ 80 {FromIntent: IntentIncumbentOfRecord, FromColumn: "incumbent_uei", ToIntent: IntentPartnerOrCompetitorRatio, ToParam: "partner_uei"}, 81 {FromIntent: IntentSegmentCompetitorField, FromColumn: "recipient_uei", ToIntent: IntentPartnerOrCompetitorRatio, ToParam: "partner_uei"}, 82} 83 84// edgeInto returns the catalog edge that can supply param toParam of intent toIntent from an upstream that is 85// in the selected set, or nil. The catalog is fixed, so this is a deterministic lookup, never a model choice. 86func edgeInto(toIntent, toParam string, selected map[string]bool) *planEdge { 87 for i := range edgeCatalog { 88 e := &edgeCatalog[i] 89 if e.ToIntent == toIntent && e.ToParam == toParam && selected[e.FromIntent] { 90 return e 91 } 92 } 93 return nil 94} 95 96// maxPlanNodes is the hard cap on how many intents one plan may run. It bounds the work the same way a 97// recursive CTE's depth cap bounds its walk; there is no recursion in the planner. Raised to 10 so a rich 98// cross plane capture question can compose more of the closed Registry in one integrated answer (the ANI 99// deepening); the closed enum, per node guards, RLS, and the frozen engine boundary bound every node the 100// same regardless of the count, so a deeper plan is exactly as safe as a shallow one, only more complete. 101const maxPlanNodes = 10 102 103// planSelfConsistencyK is the number of times the plan is sampled before only the stable (majority) intent 104// set runs. It mirrors the low temperature the faithfulness gate already uses, three samples. 105const planSelfConsistencyK = 3 106 107// availableParams is the typed bag of what the question unambiguously carries, extracted by the same 108// deterministic extractors graphClassify uses. The model supplies none of these; every value here came 109// from a regex over the original question. A node binds only from this bag, so the model can never inject a 110// param value. 111type availableParams struct { 112 Agency string 113 AgencyOK bool 114 NAICS string 115 NAICSOK bool 116 UUID string 117 UUIDOK bool 118 HeldClearance string 119 HeldOK bool 120 UEI string 121 UEIOK bool 122 WindowMonths int 123 Compartments string 124 CompartmentsOK bool 125 // M5 wage band params: the SOC occupation code resolved from a quoted role through the curated crosswalk, 126 // and the OEWS area code (HI or NM) resolved from a named state. Both come from deterministic resolvers over 127 // the question text, never the model. 128 OccupationCode string 129 OccupationOK bool 130 Area string 131 AreaOK bool 132} 133 134// extractAvailableParams runs the existing deterministic extractors and returns the typed bag of what the 135// question unambiguously carries. It is pure, deterministic, and touches no database. Every value comes from 136// a regex over the question text, never from the model. WindowMonths defaults to zero so an intent that 137// takes a window applies its own clamp when the question states no months. 138func extractAvailableParams(question string) availableParams { 139 lower := strings.ToLower(question) 140 var a availableParams 141 if agency, ok := quotedAgency(question); ok { 142 a.Agency, a.AgencyOK = agency, true 143 } 144 if naics, ok := bareNAICS(question); ok { 145 a.NAICS, a.NAICSOK = naics, true 146 } 147 if id, ok := quotedUUID(question); ok { 148 a.UUID, a.UUIDOK = id, true 149 } 150 if code, ok := heldClearanceCode(lower); ok { 151 a.HeldClearance, a.HeldOK = code, true 152 } 153 if uei, ok := quotedUEI(question); ok { 154 a.UEI, a.UEIOK = uei, true 155 } 156 a.WindowMonths = windowMonths(question) 157 if list, ok := quotedCompartmentList(question); ok { 158 a.Compartments, a.CompartmentsOK = list, true 159 } 160 // M5 wage band: a quoted role resolved to a SOC through the curated crosswalk, and a named state resolved to 161 // a known OEWS area code. Both are conservative: an unresolvable role or an unknown state leaves the slot 162 // unset so the wage intent simply drops rather than binding a wrong occupation or state. 163 if role, ok := quotedRole(question); ok { 164 if occ, resolved := resolveSOC(role); resolved { 165 a.OccupationCode, a.OccupationOK = occ.SOC, true 166 } 167 } 168 if area, ok := resolveArea(question); ok { 169 a.Area, a.AreaOK = area, true 170 } 171 return a 172} 173 174// paramSource names the available bag field a Registry param binds from. It is the FIXED lookup table keyed 175// on the EXACT param names the Registry uses (read from tag.go and graph_*.go), so a param binds by its 176// declared name, never by a guess. A param name not in this table never binds, which means its intent is 177// simply never selectable by the planner, the safe default. 178type paramSource string 179 180const ( 181 srcUUID paramSource = "uuid" // a ParamUUID id binds from avail.UUID 182 srcAgency paramSource = "agency" // an agency or agency_prefix ParamText binds from avail.Agency 183 srcNAICS paramSource = "naics" // a naics ParamText binds from avail.NAICS 184 srcHeldClearance paramSource = "held" // a clearance ParamEnum binds from avail.HeldClearance 185 srcUEI paramSource = "uei" // a partner_uei ParamText binds from avail.UEI 186 srcCompartments paramSource = "compartments" // a compartment list ParamText binds from avail.Compartments 187 srcWindowMonths paramSource = "window_months" // a window ParamInt binds from avail.WindowMonths 188 srcClampZero paramSource = "clamp_zero" // a bounded ParamInt the question never states binds zero, the intent's own clamp 189 srcOccupation paramSource = "occupation" // a SOC occupation_code ParamText binds from avail.OccupationCode 190 srcArea paramSource = "area" // an OEWS area ParamEnum binds from avail.Area 191) 192 193// paramBindings maps every Registry param NAME to the available bag field it binds from. The keys are the 194// EXACT names declared in the Registry. A required param whose name is absent here cannot bind, so its 195// intent drops, which is safe (the planner simply never selects an intent it cannot bind honestly). The 196// window and clamp sources differ: a window_months reads the stated window (zero applies the intent clamp), 197// while max_depth and lookback_years always bind zero so the intent applies its own clamp and the planner 198// never invents a recursion depth or a lookback the user did not state. 199var paramBindings = map[string]paramSource{ 200 // UUID id params across the planes. 201 "requirement_id": srcUUID, 202 "slate_id": srcUUID, 203 "start_skill_id": srcUUID, 204 "required_skill_id": srcUUID, 205 "opportunity_id": srcUUID, 206 "skill_id": srcUUID, 207 // Agency text params (the buyer key the market and TAG reads use). 208 "agency": srcAgency, 209 "agency_prefix": srcAgency, 210 "customer_agency": srcAgency, 211 // NAICS text param. 212 "naics": srcNAICS, 213 // Clearance enum params (both bind the held clearance code; the executor re checks each declared allowed 214 // set, so a value out of one intent's vocabulary is rejected at execution, not bound blindly). 215 "held_code": srcHeldClearance, 216 "clearance_level": srcHeldClearance, 217 // Partner UEI text param. 218 "partner_uei": srcUEI, 219 // Compartment list text param. 220 "required_compartments": srcCompartments, 221 // Window and clamp integer params. 222 "window_months": srcWindowMonths, 223 "max_depth": srcClampZero, 224 "lookback_years": srcClampZero, 225 // M5 wage band params: the SOC occupation code and the OEWS area code. 226 "occupation_code": srcOccupation, 227 "area": srcArea, 228} 229 230// bindOneParam binds a SINGLE Registry param from the available bag through the fixed paramBindings table, 231// returning (value, true) when the question supplies it, else (nil, false). It is the per param core of 232// bindIntentArgs, factored so the edge aware binder can ask "can the question supply THIS one param" without 233// the all or nothing whole intent bind. The model supplies no value: each value comes from a deterministic 234// extractor, or the intent's own clamp (zero) for a bounded integer the question never states. 235func bindOneParam(p Param, avail availableParams) (any, bool) { 236 src, known := paramBindings[p.Name] 237 if !known { 238 return nil, false // an unmapped param name can never bind, the safe default 239 } 240 switch src { 241 case srcUUID: 242 if !avail.UUIDOK { 243 return nil, false 244 } 245 return avail.UUID, true 246 case srcAgency: 247 if !avail.AgencyOK { 248 return nil, false 249 } 250 return avail.Agency, true 251 case srcNAICS: 252 if !avail.NAICSOK { 253 return nil, false 254 } 255 return avail.NAICS, true 256 case srcHeldClearance: 257 if !avail.HeldOK { 258 return nil, false 259 } 260 return avail.HeldClearance, true 261 case srcUEI: 262 if !avail.UEIOK { 263 return nil, false 264 } 265 return avail.UEI, true 266 case srcCompartments: 267 if !avail.CompartmentsOK { 268 return nil, false 269 } 270 return avail.Compartments, true 271 case srcWindowMonths: 272 // A stated window binds; an unstated window binds zero so the intent applies its own clamp. 273 return avail.WindowMonths, true 274 case srcClampZero: 275 // A bounded recursion depth or lookback the question never states binds zero, the intent's own clamp. 276 return 0, true 277 case srcOccupation: 278 if !avail.OccupationOK { 279 return nil, false 280 } 281 return avail.OccupationCode, true 282 case srcArea: 283 if !avail.AreaOK { 284 return nil, false 285 } 286 return avail.Area, true 287 default: 288 return nil, false 289 } 290} 291 292// bindIntentArgs supplies, for each of the intent's Params in order, the matching available value by the 293// param NAME. It returns (args, true) ONLY when every required param is available from the question, else 294// (nil, false) so the node is dropped. This is the NON edge bind used by the single shot paths. 295func bindIntentArgs(intent QueryIntent, avail availableParams) ([]any, bool) { 296 if len(intent.Params) == 0 { 297 return nil, true 298 } 299 args := make([]any, 0, len(intent.Params)) 300 for _, p := range intent.Params { 301 one, ok := bindOneParam(p, avail) 302 if !ok { 303 return nil, false 304 } 305 args = append(args, one) 306 } 307 return args, true 308} 309 310// bindIntentArgsWithEdges binds an intent's args from the available bag, allowing AT MOST ONE param to be 311// supplied later by a catalog edge from an upstream that is in the selected set. It returns the args (with an 312// empty placeholder at the edge bound position resolved at run time), the edge (nil when the node binds fully 313// from the question), the edge arg index, and ok. A node needing two edge bound params, or a param that 314// neither the question nor a catalog edge supplies, does not bind (ok false), so the planner chains only a 315// node it can honestly complete. The model supplies no value and no edge: the edge comes from the fixed 316// catalog and the value from the upstream RESULT. 317func bindIntentArgsWithEdges(intent QueryIntent, avail availableParams, selected map[string]bool) ([]any, *planEdge, int, bool) { 318 if len(intent.Params) == 0 { 319 return nil, nil, -1, true 320 } 321 args := make([]any, 0, len(intent.Params)) 322 var edge *planEdge 323 edgeIdx := -1 324 for i, p := range intent.Params { 325 one, ok := bindOneParam(p, avail) 326 if ok { 327 args = append(args, one) 328 continue 329 } 330 // The question does not supply this param: at most one param may be edge bound, from a catalog edge 331 // whose upstream is in the selected set. A second unbindable param drops the node, the safe default. 332 if edge == nil { 333 if e := edgeInto(intent.Name, p.Name, selected); e != nil { 334 edge = e 335 edgeIdx = i 336 args = append(args, "") // placeholder resolved at run time from the upstream result 337 continue 338 } 339 } 340 return nil, nil, -1, false 341 } 342 return args, edge, edgeIdx, true 343} 344 345// proposePlan asks the inference plane to SELECT the relevant intent names for a compound question. The 346// prompt lists every Registry intent NAME with its one line Description and required param names, states 347// which params are AVAILABLE for this question, and instructs the model to return ONLY a JSON array of 348// intent names from that list, at most maxPlanNodes, no prose, no SQL, no new names. It parses the JSON 349// array and DISCARDS any element that is not an exact IntentByName hit (the closed enum check). On any plane 350// error or unparseable output it returns an EMPTY selection (the caller falls back to RAG), never a guess. 351// With a nil client (the no plane posture) it returns empty so the planner degrades to RAG. 352func (o *Orchestrator) proposePlan(ctx context.Context, question string, avail availableParams) ([]string, error) { 353 if o.client == nil { 354 return nil, nil // no plane: the planner degrades to RAG, never a guess 355 } 356 system := "You are a query PLANNER for a cleared workforce intelligence platform. You select which of a " + 357 "FIXED set of named, read only intents to run to answer a compound question. You author NO SQL and " + 358 "supply NO parameter values: you return ONLY intent names from the list below, the ones that are both " + 359 "relevant to the question AND bindable from the AVAILABLE parameters. Return a JSON array of intent " + 360 "name strings, at most " + itoa(maxPlanNodes) + ", no prose, no SQL, no names that are not in the list. " + 361 "If no intent is relevant and bindable, return an empty array." 362 prompt := "AVAILABLE PARAMETERS: " + describeAvail(avail) + "\n\nINTENTS:\n" + registryCatalog() + 363 "\n\nQUESTION: " + question + "\n\nReturn ONLY the JSON array of intent names." 364 out, err := o.client.Generate(ctx, inference.GenerateRequest{System: system, Prompt: prompt, MaxTokens: 200, Temperature: 0.1}) 365 if err != nil { 366 return nil, nil // a plane error returns an empty selection so the caller falls back to RAG, never a guess 367 } 368 names := parseIntentNames(out.Text) 369 // The closed enum check: keep only names that are an exact registered intent, cap at maxPlanNodes. The 370 // model can never introduce an intent the platform did not author. 371 kept := make([]string, 0, len(names)) 372 seen := map[string]bool{} 373 for _, n := range names { 374 n = strings.TrimSpace(n) 375 if n == "" || seen[n] { 376 continue 377 } 378 if _, ok := IntentByName(n); !ok { 379 continue // not a Registry name: dropped (the closed enum check) 380 } 381 seen[n] = true 382 kept = append(kept, n) 383 if len(kept) >= maxPlanNodes { 384 break 385 } 386 } 387 return kept, nil 388} 389 390// validatePlan turns a proposed name list into a bounded, ordered, fully bound Plan. For each registered 391// name (in deterministic Registry order, then name) it looks up the intent, binds its args, and keeps the 392// node ONLY if it binds. A name not in the Registry, or one whose required params are not available, never 393// reaches the runner. The result is byte stable on a re run: the same proposed set yields the same ordered 394// Plan. 395func validatePlan(names []string, avail availableParams) Plan { 396 want := map[string]bool{} 397 for _, n := range names { 398 want[n] = true 399 } 400 var nodes []PlanNode 401 // Walk the Registry in its declared order so the surviving set is deterministic. Each node binds through 402 // the edge aware binder, so a node whose one missing param a catalog edge can supply from a selected 403 // upstream survives with that param marked edge bound (resolved at run time); a node the question and the 404 // catalog cannot complete drops. 405 for _, intent := range Registry { 406 if !want[intent.Name] { 407 continue 408 } 409 args, edge, edgeIdx, ok := bindIntentArgsWithEdges(intent, avail, want) 410 if !ok { 411 continue // unbindable: dropped, never reaches the runner 412 } 413 node := PlanNode{Intent: intent.Name, Args: args} 414 if edge != nil { 415 node.EdgeFrom, node.EdgeColumn, node.EdgeArgIdx = edge.FromIntent, edge.FromColumn, edgeIdx 416 } 417 nodes = append(nodes, node) 418 if len(nodes) >= maxPlanNodes { 419 break 420 } 421 } 422 // Deterministic topological order: an edge target runs AFTER its source. The order is byte stable so the 423 // composed answer is reproducible. 424 return Plan{Nodes: topoOrderEdges(nodes)} 425} 426 427// topoOrderEdges returns the nodes in a deterministic order that always runs an edge source before its target: 428// the edge free nodes first (name sorted), then the edge bound nodes (name sorted). The catalog is a single 429// level (a source binds from the question, a target binds from a source), so two tiers suffice and are acyclic 430// by construction. The order is byte stable so the composed answer is reproducible. 431func topoOrderEdges(nodes []PlanNode) []PlanNode { 432 var free, bound []PlanNode 433 for _, n := range nodes { 434 if n.EdgeFrom == "" { 435 free = append(free, n) 436 } else { 437 bound = append(bound, n) 438 } 439 } 440 sort.SliceStable(free, func(i, j int) bool { return free[i].Intent < free[j].Intent }) 441 sort.SliceStable(bound, func(i, j int) bool { return bound[i].Intent < bound[j].Intent }) 442 return append(free, bound...) 443} 444 445// proposeFn is the proposer signature, injected so the unit tests can drive self consistency with a stub and 446// no live plane. proposeStablePlan calls it k times. 447type proposeFn func(ctx context.Context, question string, avail availableParams) ([]string, error) 448 449// proposeStablePlan samples the plan k times and runs only the STABLE intent set: the nodes that appear in a 450// MAJORITY of the k validated plans, in the deterministic order. If the plans disagree entirely (no majority 451// node), it returns an empty plan so the caller falls back to the deterministic single intent or RAG path. 452// The proposer is injected so the tests drive it with a stub and no live plane. 453func proposeStablePlan(ctx context.Context, question string, avail availableParams, k int, propose proposeFn) Plan { 454 if k < 1 { 455 k = 1 456 } 457 counts := map[string]int{} 458 for i := 0; i < k; i++ { 459 names, err := propose(ctx, question, avail) 460 if err != nil { 461 continue 462 } 463 plan := validatePlan(names, avail) 464 // Count each node once per validated plan (the plan already deduplicates names). 465 for _, node := range plan.Nodes { 466 counts[node.Intent]++ 467 } 468 } 469 majority := (k / 2) + 1 470 stable := make([]string, 0, len(counts)) 471 for name, c := range counts { 472 if c >= majority { 473 stable = append(stable, name) 474 } 475 } 476 if len(stable) == 0 { 477 return Plan{} // no majority node: fall back to the deterministic single intent or RAG path 478 } 479 return validatePlan(stable, avail) 480} 481 482// describeAvail renders the available parameter KINDS (never the values) for the proposer prompt and is also 483// the shape the audit records. It tells the model which slots can bind without ever revealing a value (a 484// requirement id, an agency name, a UEI), so a value can never leak into the prompt or the audit. 485func describeAvail(avail availableParams) string { 486 kinds := availableKinds(avail) 487 if len(kinds) == 0 { 488 return "none" 489 } 490 return strings.Join(kinds, ", ") 491} 492 493// availableKinds returns the sorted list of param KIND names the question carries (never the values). It is 494// the proposer prompt's available list and the audit's available_kinds field; it holds no value and no PII. 495func availableKinds(avail availableParams) []string { 496 var kinds []string 497 if avail.UUIDOK { 498 kinds = append(kinds, "uuid") 499 } 500 if avail.AgencyOK { 501 kinds = append(kinds, "agency") 502 } 503 if avail.NAICSOK { 504 kinds = append(kinds, "naics") 505 } 506 if avail.HeldOK { 507 kinds = append(kinds, "held_clearance") 508 } 509 if avail.UEIOK { 510 kinds = append(kinds, "uei") 511 } 512 if avail.CompartmentsOK { 513 kinds = append(kinds, "compartments") 514 } 515 if avail.WindowMonths > 0 { 516 kinds = append(kinds, "window_months") 517 } 518 if avail.OccupationOK { 519 kinds = append(kinds, "occupation_code") 520 } 521 if avail.AreaOK { 522 kinds = append(kinds, "area") 523 } 524 sort.Strings(kinds) 525 return kinds 526} 527 528// registryCatalog lists every Registry intent NAME, its one line Description, and its required param names 529// for the proposer prompt, in Registry order. The model sees only names, descriptions, and param names, the 530// closed menu it selects from; it never sees SQL. 531func registryCatalog() string { 532 var b strings.Builder 533 for _, it := range Registry { 534 b.WriteString("- ") 535 b.WriteString(it.Name) 536 if len(it.Params) > 0 { 537 names := make([]string, len(it.Params)) 538 for i, p := range it.Params { 539 names[i] = p.Name 540 } 541 b.WriteString(" (params: ") 542 b.WriteString(strings.Join(names, ", ")) 543 b.WriteString(")") 544 } else { 545 b.WriteString(" (no params)") 546 } 547 b.WriteString(": ") 548 b.WriteString(it.Description) 549 b.WriteString("\n") 550 } 551 return b.String() 552} 553 554// parseIntentNames parses the model's output into a list of candidate intent names. It accepts a bare JSON 555// array of strings (the instructed shape) and tolerates surrounding prose by extracting the first bracketed 556// array. On any parse failure it returns nil, so proposePlan returns an empty selection and the caller falls 557// back to RAG. 558func parseIntentNames(text string) []string { 559 text = strings.TrimSpace(text) 560 start := strings.IndexByte(text, '[') 561 end := strings.LastIndexByte(text, ']') 562 if start < 0 || end < 0 || end <= start { 563 return nil 564 } 565 var names []string 566 if err := json.Unmarshal([]byte(text[start:end+1]), &names); err != nil { 567 return nil 568 } 569 return names 570} 571 572// itoa is a tiny no dependency integer to string for the prompt; strconv would do but this keeps the prompt 573// builder self contained and avoids an import for one cap value. 574func itoa(n int) string { 575 if n == 0 { 576 return "0" 577 } 578 neg := n < 0 579 if neg { 580 n = -n 581 } 582 var buf [20]byte 583 i := len(buf) 584 for n > 0 { 585 i-- 586 buf[i] = byte('0' + n%10) 587 n /= 10 588 } 589 if neg { 590 i-- 591 buf[i] = '-' 592 } 593 return string(buf[i:]) 594} 595 596// capturedResult holds a node's rendered result columns and rows so a DOWNSTREAM edge can read a value from 597// it. Only public identifier columns are ever read (the catalog guarantees this), so nothing PII is captured 598// for a use it is not allowed to have; the map lives for one plan and is discarded. 599type capturedResult struct { 600 Columns []string 601 Rows [][]any 602} 603 604// firstRowColumn returns the first row's value in the named column as a string, and ok. It reads ONLY a value 605// the edge catalog authorized (a public identifier). It requires a string cell (a text identifier like a UEI), 606// so a non text value never binds a text param; an empty result, a missing column, or a non string cell all 607// return ok false, so the dependent node drops rather than binding a wrong or empty value. 608func firstRowColumn(r capturedResult, col string) (string, bool) { 609 if len(r.Rows) == 0 { 610 return "", false 611 } 612 idx := -1 613 for i, c := range r.Columns { 614 if c == col { 615 idx = i 616 break 617 } 618 } 619 if idx < 0 || idx >= len(r.Rows[0]) { 620 return "", false 621 } 622 s, ok := r.Rows[0][idx].(string) 623 if !ok || s == "" { 624 return "", false 625 } 626 return s, true 627} 628 629// runPlan executes each surviving node through its CORRECT existing path, collects the union of rendered 630// evidence, and returns the union, the suppressed cell count across bench nodes, and the ordered names that 631// actually ran. A bench intent runs through the suppressing executor (runBenchIntent) rendered with 632// RenderCount, so a suppressed cell is the sentinel and never a raw sub k number; the G6 capture composition 633// runs through answerCapturePicture; every other graph or TAG intent runs through ExecuteIntent rendered 634// with renderTable. A node that errors is dropped from the union with a logged note (the plan degrades, 635// never hangs). The planner adds no new query: every node is an existing guarded path. 636func (o *Orchestrator) runPlan(ctx context.Context, plan Plan) (evidence []string, suppressed int, ran []string, edges []string, err error) { 637 k := ConfiguredSuppressionThreshold() 638 results := map[string]capturedResult{} // upstream outputs captured so a downstream edge can read a value 639 for _, node := range plan.Nodes { 640 // Resolve an incoming dependency edge: the value comes from the upstream RESULT's named public column 641 // (first row), never the model and never the question. An upstream that produced no such value drops the 642 // dependent node, so the plan degrades and never guesses. The nodes run in topological order, so the 643 // source has already run and its result is in the map before its target reaches this point. 644 if node.EdgeFrom != "" { 645 val, ok := firstRowColumn(results[node.EdgeFrom], node.EdgeColumn) 646 if !ok { 647 continue // upstream yielded no value: drop the dependent node 648 } 649 if node.EdgeArgIdx >= 0 && node.EdgeArgIdx < len(node.Args) { 650 node.Args[node.EdgeArgIdx] = val 651 } 652 edges = append(edges, node.EdgeFrom+"->"+node.Intent) 653 } 654 switch { 655 case node.Intent == IntentCapturePictureForRequirement: 656 // The G6 capture composition is itself a person touching bench intent and already composed. Run it 657 // through its existing path and fold its deterministic answer into the union as one evidence line. 658 id, idErr := benchIDArg(node.Args) 659 if idErr != nil { 660 continue // a malformed id drops the node, the plan degrades 661 } 662 resp, cErr := o.answerCapturePicture(ctx, id) 663 if cErr != nil || resp == nil || resp.Refused { 664 continue 665 } 666 evidence = append(evidence, "capture_picture_for_requirement: "+resp.Answer) 667 ran = append(ran, node.Intent) 668 case IsModelIntent(node.Intent): 669 // A MAG (model backed) intent runs through answerModelIntent (NOT the raw ExecuteIntent path, which 670 // hard rejects a model intent). It gathers its features through the guarded feature source intents and 671 // scores a calibrated probability in decimal; its deterministic answer folds into the union as one 672 // evidence line. It computes an opportunity level number, never a per candidate score. A node that 673 // errors or refuses drops from the union, the plan degrades. 674 resp, mErr := o.answerModelIntent(ctx, "", node.Intent, node.Args) 675 if mErr != nil || resp == nil || resp.Refused { 676 continue 677 } 678 evidence = append(evidence, node.Intent+": "+resp.Answer) 679 ran = append(ran, node.Intent) 680 case IsBenchIntent(node.Intent): 681 // A bench intent runs through the suppressing executor. The bench plane reads RLS protected person 682 // data, so it REQUIRES a resolved authenticated tenant context (the same gate answerBench enforces); 683 // without one the node drops rather than relying only on the RLS empty result fail safe. Every cell 684 // renders through RenderCount, so a suppressed cell is the sentinel and no sub k number reaches the 685 // union. 686 if !guardTenantForBench(ctx) { 687 continue 688 } 689 labels, cells, bErr := o.runBenchIntent(ctx, node.Intent, node.Args, k) 690 if bErr != nil { 691 continue // the node drops, the plan degrades, never hangs 692 } 693 columns := []string{"bucket", "headcount"} 694 rows := make([][]any, len(cells)) 695 for i, c := range cells { 696 if c.Suppressed { 697 suppressed++ 698 } 699 rows[i] = []any{labels[i], RenderCount(c)} 700 } 701 evidence = append(evidence, node.Intent+": "+renderTable(node.Intent, columns, rows)) 702 ran = append(ran, node.Intent) 703 default: 704 // Every other graph or TAG intent runs through ExecuteIntent (re guarded, RLS scoped) and renders 705 // with the existing deterministic table rendering. 706 intent, ok := IntentByName(node.Intent) 707 if !ok { 708 continue 709 } 710 res, eErr := ExecuteIntent(ctx, o.db, intent, node.Args) 711 if eErr != nil { 712 continue // the node drops, the plan degrades, never hangs 713 } 714 results[node.Intent] = capturedResult{Columns: res.Columns, Rows: res.Rows} // capture for a downstream edge 715 evidence = append(evidence, node.Intent+": "+renderTable(intent.Description, res.Columns, res.Rows)) 716 ran = append(ran, node.Intent) 717 } 718 } 719 return evidence, suppressed, ran, edges, nil 720} 721 722// AnswerPlan answers a COMPOUND cross plane question by planning over the closed Registry. It runs the EEO 723// and protected attribute guards FIRST (refuse on either), extracts the available params, gets the stable 724// plan (sampled planSelfConsistencyK times, only the majority intent set), and falls back to AnswerRAG 725// unchanged when the plan is empty (so a non compound or unbindable question is byte for byte unchanged). 726// Otherwise it runs the plan, narrates ONE answer over the union of node evidence through o.generate (state 727// only what the union supports, report a suppressed bench count as withheld and never guess a number for it, 728// never compute a match score), and o.finalize behind the faithfulness gate. It emits the counts only 729// aedt.ai.plan_answered audit: the ordered ran intent NAMES, the available param KINDS (never values), the 730// node count, the suppressed count, the faithfulness verdict, and the self consistency outcome. The audit 731// carries NO param value, NO candidate id, NO raw count, NO requirement id, NO answer text, and NO question. 732func (o *Orchestrator) AnswerPlan(ctx context.Context, question string) (*Response, error) { 733 if ForbidEEO(question) != nil || MentionsProtectedAttribute(question) { 734 return o.refuse(ctx, RoutePlan, "the question references prohibited demographic data") 735 } 736 avail := extractAvailableParams(question) 737 plan := proposeStablePlan(ctx, question, avail, planSelfConsistencyK, o.proposePlan) 738 consistency := "stable" 739 if len(plan.Nodes) == 0 { 740 // No stable plan: a non compound or unbindable question is unchanged, it falls back to RAG. 741 return o.AnswerRAG(ctx, question, 8) 742 } 743 evidence, suppressed, ran, edges, err := o.runPlan(ctx, plan) 744 if err != nil { 745 return nil, err 746 } 747 if len(evidence) == 0 { 748 // Every node dropped (errors or empty results): degrade to RAG rather than narrate over nothing. 749 return o.AnswerRAG(ctx, question, 8) 750 } 751 deterministic := renderPlanUnion(ran, evidence) 752 model, genErr := o.generate(ctx, 753 "State ONE integrated answer using ONLY the listed evidence lines as evidence, one line per intent that ran. "+ 754 "State only what the union of the evidence supports. A headcount shown as "+SuppressionSentinel+" was "+ 755 "withheld to protect individuals: say it was withheld and NEVER guess or state a number for it. Never "+ 756 "compute a match score and never assign a band. Do not invent an agency, a UEI, a dollar figure, a "+ 757 "recompete, or a count the evidence does not contain.", 758 "QUESTION: "+question+"\n\nEVIDENCE:\n"+strings.Join(evidence, "\n")) 759 resp, aerr := o.finalize(ctx, RoutePlan, model, genErr, deterministic, evidence) 760 if aerr != nil { 761 return nil, aerr 762 } 763 // Counts only plan trace audit: the ordered ran names (the closed set, not PII), the available param KINDS 764 // (not values), the node count, the suppressed cell count, the faithfulness verdict, and the self 765 // consistency outcome. NO param value, NO candidate id, NO raw count, NO requirement id, NO answer text, 766 // NO question. 767 if err := o.audit(ctx, "aedt.ai.plan_answered", map[string]any{ 768 "route": RoutePlan, 769 "intents": ran, 770 "available_kinds": availableKinds(avail), 771 "nodes": len(plan.Nodes), 772 "edges": edges, // upstream to downstream intent NAME pairs that fired, never a value 773 "suppressed": suppressed, 774 "faithful": resp.Faithful, 775 "rationale_source": resp.RationaleSource, 776 "self_consistency": consistency, 777 }); err != nil { 778 return nil, err 779 } 780 return resp, nil 781} 782 783// renderPlanUnion builds the deterministic union answer the planner ships when the model prose is withheld: 784// one line per intent that ran, in the deterministic plan order, each line already its node's suppressed 785// safe rendering. It names no candidate and computes no score; every bench count it contains already came 786// through RenderCount, so the deterministic fallback is itself suppression safe. 787func renderPlanUnion(ran []string, evidence []string) string { 788 var b strings.Builder 789 b.WriteString("Integrated plan answer across the planes. ") 790 b.WriteString(strings.Join(evidence, " ")) 791 return b.String() 792} 793 794// benchPlaneWords are the conservative bench plane signal: a question that names one of these is asking about 795// the caller's own bench (the suppressed person touching plane). Pairing a bench word with a market word is 796// the compound signal that routes to the planner. 797var benchPlaneWords = []string{"bench", "our staff", "our people", "who can staff", "clearance coverage", "structural gap"} 798 799// marketPlaneWords are the conservative market plane signal: a question that names one of these is asking 800// about the public market plane (agencies, awards, incumbents, recompetes, competitors, forecasts). 801var marketPlaneWords = []string{"market", "incumbent", "competitor", "recompete", "award", "agency", "forecast", "vendor", "teaming", "buying pattern", "spend"} 802 803// The additional planes so the planner (the multi step reasoner) engages ANY cross plane question, not only 804// bench and market. Each group is kept semantically disjoint from bench and market and from each other, so a 805// question that names several words WITHIN one plane still counts as one plane and is not compound. 806var clearancePlaneWords = []string{"ts/sci", "polygraph", "compartment", "reciprocity", "sci access", "clearance level"} 807var wagePlaneWords = []string{"wage", "salary", "labor rate", "bill rate", "oews", "pay band", "compensation", "prevailing wage"} 808var skillPlaneWords = []string{"adjacent skill", "skill adjacency", "related skill", "capability", "competenc"} 809var lifecyclePlaneWords = []string{"period of performance", "option year", "pop end", "renewal", "recompete timeline"} 810 811// planeGroups is the full set of plane signals the planner can span. A compound question names words from 812// TWO OR MORE distinct planes, so the single shot keyword router cannot bind it to one intent. 813var planeGroups = [][]string{benchPlaneWords, marketPlaneWords, clearancePlaneWords, wagePlaneWords, skillPlaneWords, lifecyclePlaneWords} 814 815// isCompoundQuestion reports whether a question spans TWO OR MORE distinct planes. Broadened from the original 816// bench AND market rule so the planner engages the full closed Registry for any cross plane capture question, 817// while a single plane question (however many words it names within that one plane) still falls through to the 818// existing single shot path so a working route is never regressed. It is still conservative: fewer than two 819// distinct planes returns false. It never refuses; the EEO guards run in AnswerPlan. 820func isCompoundQuestion(question string) bool { 821 q := strings.ToLower(question) 822 planes := 0 823 for _, g := range planeGroups { 824 if containsAny(q, g) { 825 planes++ 826 if planes >= 2 { 827 return true 828 } 829 } 830 } 831 return false 832} 833 834// guardTenantForBench reports whether the context carries a resolved authenticated tenant, the gate a bench 835// node needs before it runs a person touching read. The runner drops a bench node without one so the plan 836// path keeps the same auth posture answerBench enforces, rather than relying only on the RLS empty result 837// fail safe. The G6 capture composition checks the same gate inside answerCapturePicture. 838func guardTenantForBench(ctx context.Context) bool { 839 _, ok := tenant.OrgFromContext(ctx) 840 return ok 841} 842