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

1package ai 2 3import "strings" 4 5// This file TEACHES the brain a curated body of stable, public, contents free knowledge: cleared workforce and 6// access facts, federal capture and staffing terminology, the compliance and AEDT framework, and the platform's 7// own methodology. It is the knowledge substrate behind the CAG (cache augmented generation) direct answer 8// path. Every card is PUBLIC domain knowledge or the platform's own published methodology, carries NO client 9// data and NO demographic field, and is safe to hold in any tenant's model context. A card is selected for a 10// question by a deterministic keyword match (never an LLM), so the brain answers a knowledge question ONLY from 11// the curated cards it was taught, cites the source of each, and refuses or falls back when it was taught 12// nothing relevant. The brain never invents a rule, a number, or a definition it was not given. 13 14// KnowledgeCard is one taught fact: a topic, the keywords that select it, the content the brain may answer from, 15// and the source it cites. Content is the ground truth the faithfulness gate holds the model prose to. 16type KnowledgeCard struct { 17 Topic string 18 Keywords []string 19 Content string 20 Source string 21} 22 23// KnowledgeBase is the closed, curated set of things the brain has been taught. Adding a card is a reviewed 24// decision, like adding a Registry intent. Every card must be public and contents free (a test walks the base 25// and refuses any eeo marker). 26var KnowledgeBase = []KnowledgeCard{ 27 // ---------- Clearance and access ---------- 28 { 29 Topic: "Clearance levels and hierarchy", 30 Keywords: []string{"clearance level", "clearance hierarchy", "confidential", "secret", "top secret", "ts/sci", "ts sci", "levels of clearance", "what clearance"}, 31 Content: "US security clearances rise through Confidential, Secret, and Top Secret, with TS/SCI adding Sensitive Compartmented Information access on top of Top Secret. A higher level satisfies a lower requirement (a Top Secret holder meets a Secret need), but a lower level never satisfies a higher one (Secret does not meet a TS/SCI need). Only an active clearance counts; an expired or unknown clearance scores zero on the platform.", 32 Source: "ODNI clearance framework", 33 }, 34 { 35 Topic: "Polygraph types", 36 Keywords: []string{"polygraph", "poly", "full scope", "lifestyle poly", "ci poly", "counterintelligence poly"}, 37 Content: "A polygraph is an additional access gate layered on a clearance. A Counterintelligence (CI) polygraph covers espionage and security matters; a Full Scope (also called lifestyle) polygraph adds personal conduct topics. Full Scope satisfies a CI requirement, but CI does not satisfy a Full Scope requirement.", 38 Source: "IC polygraph policy", 39 }, 40 { 41 Topic: "SCI and compartments", 42 Keywords: []string{"sci", "compartment", "compartmented", "control system", "sensitive compartmented"}, 43 Content: "Sensitive Compartmented Information is intelligence held in separate control systems (compartments) that each require specific read in, on top of a TS/SCI eligibility. Holding TS/SCI eligibility does not grant every compartment; a role can require a named compartment the candidate must already be read into.", 44 Source: "ICD 703", 45 }, 46 { 47 Topic: "Special Access Programs", 48 Keywords: []string{"sap", "special access", "special access program", "carve out", "waived"}, 49 Content: "A Special Access Program applies extra need to know and access controls beyond a normal clearance level, using formal nomination and read in. SAP access is program specific and is not implied by a clearance level alone.", 50 Source: "DoD SAP policy", 51 }, 52 { 53 Topic: "Background investigation tiers", 54 Keywords: []string{"investigation", "tier 3", "tier 5", "t3", "t5", "background check", "reinvestigation", "sf 86", "sf86", "eqip", "questionnaire"}, 55 Content: "Clearances are supported by a background investigation: Tier 3 supports Secret and Tier 5 supports Top Secret and TS/SCI. The subject completes the SF 86 questionnaire through the eQIP or eApp system. Investigations were historically reinvestigated on a fixed cycle and are now maintained by continuous vetting.", 56 Source: "SEAD 4 and Trusted Workforce 2.0", 57 }, 58 { 59 Topic: "Continuous vetting", 60 Keywords: []string{"continuous vetting", "continuous evaluation", "trusted workforce", "cv"}, 61 Content: "Continuous vetting replaces the old periodic reinvestigation with ongoing automated record checks, so a cleared person is monitored continuously rather than only at renewal. It is part of the Trusted Workforce 2.0 reform.", 62 Source: "Trusted Workforce 2.0", 63 }, 64 { 65 Topic: "DISS and clearance systems of record", 66 Keywords: []string{"diss", "jpas", "system of record", "clearance verification", "fso", "facility security officer", "adjudication"}, 67 Content: "The Defense Information System for Security (DISS) is the government system of record for clearance eligibility and access, managed by a company's Facility Security Officer. Adjudication against the SEAD 4 national security adjudicative guidelines determines eligibility. The authoritative clearance check is always the hiring customer FSO through the system of record at onboarding, never a self reported indicator.", 68 Source: "DCSA DISS and SEAD 4", 69 }, 70 { 71 Topic: "Clearance reciprocity", 72 Keywords: []string{"reciprocity", "transfer clearance", "reciprocal", "crossover"}, 73 Content: "Reciprocity is the requirement that a clearance eligibility granted by one agency be honored by another without a new investigation, so a cleared person can move between contracts and agencies. In practice a receiving program still verifies eligibility and grants access.", 74 Source: "SEAD 7", 75 }, 76 // ---------- Federal capture and staffing terminology ---------- 77 { 78 Topic: "Recompete versus new start", 79 Keywords: []string{"recompete", "new start", "follow on", "re compete", "period of performance end"}, 80 Content: "A recompete is a contract for work that already exists, coming up for award again as the current period of performance ends, usually with a known incumbent. A new start is work with no predecessor. A recompete favors staffing that can retain or match the incumbent workforce.", 81 Source: "Federal acquisition practice", 82 }, 83 { 84 Topic: "Incumbent and incumbency", 85 Keywords: []string{"incumbent", "incumbency", "incumbent capture", "badge and move"}, 86 Content: "The incumbent is the contractor currently performing the work and, on a recompete, the team to beat. Capturing incumbent staff (a badge and move) is a common win strategy because it lowers transition risk and signals continuity to the customer.", 87 Source: "Capture practice", 88 }, 89 { 90 Topic: "Small business set asides", 91 Keywords: []string{"set aside", "8(a)", "8a", "sdvosb", "hubzone", "wosb", "small business", "socioeconomic"}, 92 Content: "A set aside reserves a contract for a class of firm: 8(a) for socially and economically disadvantaged small businesses, SDVOSB for service disabled veteran owned, HUBZone for firms in historically underutilized business zones, and WOSB for women owned small businesses. Eligibility is verified through the Small Business Administration.", 93 Source: "13 CFR and SBA programs", 94 }, 95 { 96 Topic: "NAICS and PSC codes", 97 Keywords: []string{"naics", "psc", "product service code", "industry code", "classification code"}, 98 Content: "A NAICS code classifies the industry of a contract and drives the small business size standard; a Product Service Code (PSC) classifies what is being bought. Buyers and market analysis segment opportunities and awards by agency plus NAICS plus PSC.", 99 Source: "Census NAICS and GSA PSC", 100 }, 101 { 102 Topic: "Key personnel", 103 Keywords: []string{"key personnel", "key person", "named personnel", "kp"}, 104 Content: "Key personnel are the specific roles a solicitation names as critical, often requiring resumes and letters of commitment in the proposal. A gap or a weak key personnel slot can make a bid non compliant, so key personnel drive slate priority.", 105 Source: "Proposal compliance practice", 106 }, 107 { 108 Topic: "Labor category", 109 Keywords: []string{"labor category", "lcat", "labor cat", "labor rate"}, 110 Content: "A labor category (LCAT) is a priced role on a contract, such as Intelligence Analyst or Cyber Engineer, with a required skill and experience profile and an hourly rate. Staffing maps candidates to LCATs, and pricing uses the LCAT rate.", 111 Source: "Government contracting practice", 112 }, 113 { 114 Topic: "Prime, subcontractor, and teaming", 115 Keywords: []string{"prime", "subcontractor", "teaming", "teaming agreement", "sub", "prime contractor"}, 116 Content: "The prime holds the contract with the government; subcontractors perform portions under the prime. A teaming agreement sets out, before award, who bids as prime and who supports as a sub and on which scope. Public award data records the prime of record, not the subcontractor split.", 117 Source: "FAR teaming practice", 118 }, 119 { 120 Topic: "IDIQ and task orders", 121 Keywords: []string{"idiq", "task order", "delivery order", "period of performance", "pop", "ceiling", "vehicle"}, 122 Content: "An Indefinite Delivery Indefinite Quantity (IDIQ) vehicle is a master contract under which the government issues task orders for specific work, each with its own period of performance. Winning a vehicle gives the right to compete for its task orders.", 123 Source: "FAR 16.5", 124 }, 125 { 126 Topic: "Price to win and basis of estimate", 127 Keywords: []string{"price to win", "ptw", "basis of estimate", "boe", "pricing", "wage", "oews"}, 128 Content: "Price to Win is the estimated price a bid must reach to be competitive, informed by market labor rates such as the BLS OEWS wage survey and historical award amounts. A Basis of Estimate documents the labor mix and hours behind a priced volume. Both are advisory market context, never a candidate score.", 129 Source: "Capture and pricing practice", 130 }, 131 { 132 Topic: "Proposal color teams", 133 Keywords: []string{"color team", "pink team", "red team", "gold team", "proposal review", "black hat"}, 134 Content: "Proposal reviews run as color teams: a Pink Team reviews the early draft approach, a Red Team reviews the near final as an evaluator would, and a Gold Team is the final executive review. A Black Hat review models the competition.", 135 Source: "Shipley proposal practice", 136 }, 137 // ---------- Compliance and AEDT ---------- 138 { 139 Topic: "Four fifths adverse impact rule", 140 Keywords: []string{"four fifths", "80 percent rule", "adverse impact", "disparate impact", "selection rate"}, 141 Content: "The four fifths rule from the EEOC uniform guidelines flags potential adverse impact when a group's selection rate is less than 80 percent of the highest group's rate. The platform computes selection rates and four fifths ratios so a customer can run a bias audit; it provides the data, it is not itself the audit.", 142 Source: "EEOC Uniform Guidelines", 143 }, 144 { 145 Topic: "NYC Local Law 144 bias audit", 146 Keywords: []string{"local law 144", "ll144", "bias audit", "nyc law", "aedt law"}, 147 Content: "New York City Local Law 144 requires an independent annual bias audit of an automated employment decision tool used on candidates or employees who reside in the city, with the results published. The platform is built to produce the adverse impact reporting such an audit needs.", 148 Source: "NYC DCWP Local Law 144", 149 }, 150 { 151 Topic: "Automated employment decision tool obligations", 152 Keywords: []string{"aedt", "automated employment", "responsible ai", "explainable", "human in the loop", "ofccp"}, 153 Content: "As an automated employment decision tool the platform keeps every score explainable with a per component breakdown and a recordable trace, keeps a human in the loop who approves or rejects every slate member, and never automatically rejects a candidate. It aligns to the NIST AI Risk Management Framework and provides adverse impact reporting for OFCCP style reviews.", 154 Source: "NIST AI RMF and OFCCP practice", 155 }, 156 { 157 Topic: "Demographic firewall", 158 Keywords: []string{"demographic firewall", "demographic", "protected attribute", "firewall", "isolation of demographics"}, 159 Content: "Demographic data lives in a separate access controlled module reachable only by a dedicated compliance role, is never an input to scoring or to any AI answer, and the scoring code cannot reach it. The brain refuses any question that asks to rank or filter people by a protected attribute.", 160 Source: "missionMATCH responsible AI design", 161 }, 162 { 163 Topic: "Small cell suppression", 164 Keywords: []string{"small cell", "suppression", "k anonymity", "re identification", "reporting threshold"}, 165 Content: "Any count derived from people is suppressed below a threshold of ten so an answer can never re identify an individual, and complementary suppression hides a second cell so a suppressed value cannot be recovered by subtraction. A suppressed count is shown as a sentinel, never a number.", 166 Source: "NIST SP 800 188 de identification", 167 }, 168 // ---------- Platform methodology ---------- 169 { 170 Topic: "The three tools", 171 Keywords: []string{"three tools", "screenmatch", "slatematch", "missionmatch", "what tools", "products"}, 172 Content: "The platform is three tools over one engine and one data model: screenMATCH answers whether one candidate is qualified for one requirement, slateMATCH ranks a proposal ready candidate slate for a requirement, and missionMATCH is the workforce command center that names staffing gaps and fuses market signal. Each answers a distinct question in the capture lifecycle.", 173 Source: "missionMATCH methodology", 174 }, 175 { 176 Topic: "The intelligence loop", 177 Keywords: []string{"the loop", "intelligence loop", "how it works", "workflow", "requirement to slate"}, 178 Content: "The platform serves one loop: a requirement enters, candidate intelligence is gathered, the engine scores the match, a ranked slate is produced, and proposal readiness is recorded. The output of each stage is the input to the next, and every stage writes to one audited system of record.", 179 Source: "missionMATCH methodology", 180 }, 181 { 182 Topic: "The scoring engine", 183 Keywords: []string{"scoring engine", "match score", "how is the score", "weights", "deterministic", "frozen engine"}, 184 Content: "The match score is a fixed weighted model: Clearance 25, Skills 25, Certifications 15, Customer Experience 15, Experience 10, and Location and Availability 10, out of 100, with bands Green at 90 and above, Yellow from 75 to 89, and Red below 75. Version 1.4.0 then applies deterministic band caps that only lower the band and never change the total: if a required clearance is not met the band is capped to Red even at 90 or above, and if a mandatory required skill is unmet a Green is capped to Yellow, with the clearance cap taking precedence. It is pure deterministic decimal arithmetic, so the same inputs always produce the same score, and it is the only per candidate scorer.", 185 Source: "missionMATCH engine v1.4.0", 186 }, 187 { 188 Topic: "The AI brain augmentation classes", 189 Keywords: []string{"ai brain", "augmentation", "rag", "tag", "graphrag", "mag", "cag", "how does the brain", "how does the ai"}, 190 Content: "The brain answers over the deterministic engine, never around it, through a closed set of validated intents across four augmentation classes: retrieval over the tenant's own documents, table analytics over curated read only queries, graph reasoning over the market and skill graphs, and learned models that emit only an opportunity level number or an ordering. A faithfulness gate ships generated prose only when the evidence supports it.", 191 Source: "missionMATCH AI architecture", 192 }, 193 { 194 Topic: "Learned models and the frozen engine", 195 Keywords: []string{"learned model", "mag", "win probability", "re ranker", "time to fill", "does the ai score", "machine learning"}, 196 Content: "Learned models can emit only an opportunity level number, an ordering, or a confidence, never a per candidate match score, so the frozen deterministic engine stays the only per candidate scorer by construction. A learned model is promoted only after passing a held out quality gate and a four fifths fairness gate, and a human confirms the promotion.", 197 Source: "missionMATCH MAG design", 198 }, 199 { 200 Topic: "Security and portability posture", 201 Keywords: []string{"fips", "security", "govcloud", "azure government", "both cloud", "multi tenant", "portability", "rls"}, 202 Content: "The platform is built with validated FIPS cryptography from day one, isolates every tenant with Postgres row level security so no context yields zero rows, keeps an append only audit outside those policies, and runs on either AWS GovCloud or Azure Government with no single vendor lock in. Choosing a cloud is configuration, not a rewrite.", 203 Source: "missionMATCH stack decisions", 204 }, 205 { 206 Topic: "Clearance intelligence disclaimer", 207 Keywords: []string{"clearance intelligence", "verified clearance", "self reported", "is the clearance verified", "disclaimer"}, 208 Content: "Clearance values in the platform are self reported indicators shown as clearance intelligence, never a verification. The authoritative determination is made by the hiring customer Facility Security Officer through the government system of record at onboarding.", 209 Source: "missionMATCH disclosure policy", 210 }, 211} 212 213// SelectKnowledge returns the curated cards most relevant to a question by a deterministic keyword match, 214// capped at max cards so only the relevant knowledge enters the model context. A card scores by how many of 215// its keywords appear in the lowercased question; cards with no hit are dropped, and ties break by the card's 216// order in the base for a stable result. When nothing matches, the brain was taught nothing relevant and the 217// caller falls back to the standing rules rather than inventing an answer. 218func SelectKnowledge(question string, max int) []KnowledgeCard { 219 if max <= 0 { 220 max = 4 221 } 222 q := strings.ToLower(question) 223 type scored struct { 224 card KnowledgeCard 225 hits int 226 order int 227 } 228 var matched []scored 229 for i, c := range KnowledgeBase { 230 hits := 0 231 for _, kw := range c.Keywords { 232 if strings.Contains(q, kw) { 233 hits++ 234 } 235 } 236 if hits > 0 { 237 matched = append(matched, scored{card: c, hits: hits, order: i}) 238 } 239 } 240 // Sort by hit count descending, then by base order ascending, both deterministic. 241 for i := 1; i < len(matched); i++ { 242 for j := i; j > 0; j-- { 243 a, b := matched[j-1], matched[j] 244 if b.hits > a.hits || (b.hits == a.hits && b.order < a.order) { 245 matched[j-1], matched[j] = matched[j], matched[j-1] 246 } else { 247 break 248 } 249 } 250 } 251 out := make([]KnowledgeCard, 0, max) 252 for i := 0; i < len(matched) && i < max; i++ { 253 out = append(out, matched[i].card) 254 } 255 return out 256} 257 258// renderKnowledge builds the deterministic answer from the selected cards: the topic, the taught content, and 259// the cited source for each. It is the faithful fallback when the model prose is withheld or the plane is out, 260// so a CAG answer is always grounded in exactly what the brain was taught. 261func renderKnowledge(cards []KnowledgeCard) string { 262 if len(cards) == 0 { 263 return "" 264 } 265 var b strings.Builder 266 for i, c := range cards { 267 if i > 0 { 268 b.WriteString(" ") 269 } 270 b.WriteString(c.Content) 271 b.WriteString(" (source: ") 272 b.WriteString(c.Source) 273 b.WriteString(")") 274 } 275 return b.String() 276} 277