Janady13/missionmatch / internal/modules/matching/engine/types.go

1// Package engine is the PURE, deterministic missionMATCH scoring core. 2// 3// It is the product's core IP and a compliance asset (an Automated Employment Decision Tool), 4// so it is held to three hard rules from CLAUDE.md: 5// 6// 1. PURE: no database, no I/O, no clock, no randomness. The skill matcher is INJECTED. 7// 2. DETERMINISTIC: all scoring math is decimal (never float64) and every input order is 8// normalized, so the same inputs always yield byte-identical scores and explanations. 9// 3. FAIR + EXPLAINABLE: it never reads a demographic/EEO attribute or a proxy for one, and 10// every score carries a per-component breakdown, a human-readable rationale, a gap summary, 11// and the matched required→candidate skill pairs with their similarity (the decision trace). 12// 13// Fixed weights (CLAUDE.md, do NOT change without explicit instruction): 14// 15// Clearance .25 Skills .25 Certifications .15 CustomerExperience .15 Experience .10 Location .10 16package engine 17 18import ( 19 "context" 20 21 "github.com/shopspring/decimal" 22) 23 24// ---------- Clearance model ---------- 25 26// ClearanceLevel is the ordered US personnel-security hierarchy. Higher ordinal satisfies lower 27// (TS/SCI satisfies Secret; Secret does NOT satisfy TS/SCI). Unknown is the safe default zero. 28type ClearanceLevel int 29 30const ( 31 ClearanceUnknown ClearanceLevel = iota // missing/unparseable, scores 0 32 ClearanceNone // no clearance / public trust 33 ClearanceConfidential 34 ClearanceSecret 35 ClearanceTopSecret 36 ClearanceTSSCI // Top Secret with SCI access 37) 38 39func (c ClearanceLevel) String() string { 40 switch c { 41 case ClearanceNone: 42 return "None" 43 case ClearanceConfidential: 44 return "Confidential" 45 case ClearanceSecret: 46 return "Secret" 47 case ClearanceTopSecret: 48 return "Top Secret" 49 case ClearanceTSSCI: 50 return "TS/SCI" 51 default: 52 return "Unknown" 53 } 54} 55 56// Polygraph is an additional access gate layered on a clearance. Full-scope satisfies CI. 57type Polygraph int 58 59const ( 60 PolyNone Polygraph = iota 61 PolyCI // counterintelligence 62 PolyFullScope // full-scope / lifestyle (satisfies CI) 63) 64 65func (p Polygraph) String() string { 66 switch p { 67 case PolyCI: 68 return "CI Poly" 69 case PolyFullScope: 70 return "Full Scope Poly" 71 default: 72 return "No Poly" 73 } 74} 75 76// ClearanceStatus gates the clearance: only an Active clearance can score. Expired/Unknown = 0. 77type ClearanceStatus int 78 79const ( 80 StatusUnknown ClearanceStatus = iota 81 StatusActive 82 StatusExpired 83 StatusInactive 84) 85 86// Clearance is a candidate's held clearance (or a requirement's required clearance via RequiredLevel/RequiredPoly). 87type Clearance struct { 88 Level ClearanceLevel 89 Poly Polygraph 90 Status ClearanceStatus 91 Compartments []string // SCI control systems or SAP markers the candidate holds; nil and empty are both "none" 92} 93 94// ---------- Candidate & Requirement (pure value inputs, NOT the DB models) ---------- 95 96// CandidateSkill is a single skill on a candidate, already normalized to the ontology upstream. 97// SkillID is the ontology id (stable); Name is the display label. The engine compares by SkillID 98// for exact matches and defers to the injected SkillMatcher for semantic matches. 99type CandidateSkill struct { 100 SkillID string 101 Name string 102} 103 104// Candidate is the pure scoring input for one person. It deliberately contains NO demographic field. 105type Candidate struct { 106 ID string 107 Clearance Clearance 108 Skills []CandidateSkill 109 Certifications []string // normalized cert names 110 CustomerExperience []string // government customers/agencies the candidate has supported 111 YearsExperience int 112 Location string 113 Remote bool // candidate can/will work remotely 114 Relocatable bool 115 Available bool // available to staff now 116} 117 118// RequiredSkill is a skill a requirement demands. Mandatory drives the gap summary (an unmet 119// mandatory skill is a hard gap); a non-mandatory required skill still counts toward the skill score. 120type RequiredSkill struct { 121 SkillID string 122 Name string 123 Mandatory bool 124} 125 126// Requirement is the pure scoring input for one role/labor-category. 127type Requirement struct { 128 ID string 129 RequiredLevel ClearanceLevel 130 RequiredPoly Polygraph 131 RequiredSkills []RequiredSkill 132 RequiredCerts []string 133 CustomerAgency string // "" means no specific customer required 134 RequiredYears int 135 WorkLocation string 136 RemoteAllowed bool 137 KeyPersonnel bool // a Key Personnel slot (surfaced; does not alter the score) 138 RequiredCompartments []string // compartments the candidate must hold; nil and empty mean no compartment requirement 139} 140 141// ---------- Skill matching (INJECTED, keeps the engine pure & testable) ---------- 142 143// SkillMatch records that a required skill was satisfied by a candidate skill, and how. 144type SkillMatch struct { 145 RequiredSkillID string 146 RequiredSkillName string 147 CandidateSkillID string // "" when unmatched 148 CandidateName string 149 Similarity decimal.Decimal // 1.0 for an exact match; the cosine similarity for a semantic match 150 Exact bool 151 AliasMatched bool // flags a match that came from a curated alias rather than an exact name or id match, for audit 152 Matched bool 153} 154 155// SkillMatcher resolves a required skill against a candidate's skills: exact first, then semantic. 156// It is injected so the engine has no embedding/DB dependency and tests are fully deterministic. 157// Implementations MUST be deterministic for a given input. Threshold is the engine's semantic cutoff. 158type SkillMatcher interface { 159 // Match returns the best candidate skill satisfying the required skill at or above threshold. 160 // On an exact id/name match it returns Exact=true, Similarity=1.0. ok is false when nothing 161 // meets the threshold. ctx carries the request deadline and cancellation to any provider call. 162 Match(ctx context.Context, required RequiredSkill, candidateSkills []CandidateSkill, threshold decimal.Decimal) (m SkillMatch, ok bool) 163} 164 165// ---------- Result ---------- 166 167// Band is the proposal-readiness classification of a total score. 168type Band int 169 170const ( 171 BandRed Band = iota // Recruiting Required (< 75) 172 BandYellow // Potential (75–89.99) 173 BandGreen // Proposal Ready (>= 90) 174) 175 176func (b Band) String() string { 177 switch b { 178 case BandGreen: 179 return "Green" 180 case BandYellow: 181 return "Yellow" 182 default: 183 return "Red" 184 } 185} 186 187// Label is the human-facing band name used in slates and explanations. 188func (b Band) Label() string { 189 switch b { 190 case BandGreen: 191 return "Proposal Ready" 192 case BandYellow: 193 return "Potential" 194 default: 195 return "Recruiting Required" 196 } 197} 198 199// ComponentScore is one weighted row of the decision trace (the AEDT/explainability artifact). 200type ComponentScore struct { 201 Component string // "Clearance", "Skills", ... 202 Weight decimal.Decimal // 0.25, 0.15, ... 203 Raw decimal.Decimal // the 0–100 sub-score 204 Weighted decimal.Decimal // Raw * Weight (contribution to the total) 205 Rationale string // human-readable reason for the sub-score 206} 207 208// MatchResult is the full, explainable, reproducible outcome of scoring one candidate vs one requirement. 209type MatchResult struct { 210 CandidateID string 211 RequirementID string 212 213 Clearance decimal.Decimal 214 Skills decimal.Decimal 215 Certifications decimal.Decimal 216 CustomerExperience decimal.Decimal 217 Experience decimal.Decimal 218 Location decimal.Decimal 219 220 Total decimal.Decimal // 0–100, rounded to 2 dp 221 Band Band 222 223 Explanation string // a human-readable summary 224 GapSummary []string // unmet MANDATORY items (clearance, mandatory skills, required certs, ...) 225 MatchedSkills []SkillMatch // required→candidate pairs with similarity (and the unmatched ones) 226 Trace []ComponentScore // per-component weighted breakdown, the decision trace 227 228 // WeightProfileVersion names the weight set that produced this result, stamped by the caller 229 // (the matching service): the tenant AIOE profile version when one is active, otherwise 230 // GlobalDefaultProfileVersion. The engine itself never reads it. 231 WeightProfileVersion string 232} 233