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} 92 93// ---------- Candidate & Requirement (pure value inputs, NOT the DB models) ---------- 94 95// CandidateSkill is a single skill on a candidate, already normalized to the ontology upstream. 96// SkillID is the ontology id (stable); Name is the display label. The engine compares by SkillID 97// for exact matches and defers to the injected SkillMatcher for semantic matches. 98type CandidateSkill struct { 99 SkillID string 100 Name string 101} 102 103// Candidate is the pure scoring input for one person. It deliberately contains NO demographic field. 104type Candidate struct { 105 ID string 106 Clearance Clearance 107 Skills []CandidateSkill 108 Certifications []string // normalized cert names 109 CustomerExperience []string // government customers/agencies the candidate has supported 110 YearsExperience int 111 Location string 112 Remote bool // candidate can/will work remotely 113 Relocatable bool 114 Available bool // available to staff now 115} 116 117// RequiredSkill is a skill a requirement demands. Mandatory drives the gap summary (an unmet 118// mandatory skill is a hard gap); a non-mandatory required skill still counts toward the skill score. 119type RequiredSkill struct { 120 SkillID string 121 Name string 122 Mandatory bool 123} 124 125// Requirement is the pure scoring input for one role/labor-category. 126type Requirement struct { 127 ID string 128 RequiredLevel ClearanceLevel 129 RequiredPoly Polygraph 130 RequiredSkills []RequiredSkill 131 RequiredCerts []string 132 CustomerAgency string // "" means no specific customer required 133 RequiredYears int 134 WorkLocation string 135 RemoteAllowed bool 136 KeyPersonnel bool // a Key Personnel slot (surfaced; does not alter the score) 137} 138 139// ---------- Skill matching (INJECTED, keeps the engine pure & testable) ---------- 140 141// SkillMatch records that a required skill was satisfied by a candidate skill, and how. 142type SkillMatch struct { 143 RequiredSkillID string 144 RequiredSkillName string 145 CandidateSkillID string // "" when unmatched 146 CandidateName string 147 Similarity decimal.Decimal // 1.0 for an exact match; the cosine similarity for a semantic match 148 Exact bool 149 AliasMatched bool // flags a match that came from a curated alias rather than an exact name or id match, for audit 150 Matched bool 151} 152 153// SkillMatcher resolves a required skill against a candidate's skills: exact first, then semantic. 154// It is injected so the engine has no embedding/DB dependency and tests are fully deterministic. 155// Implementations MUST be deterministic for a given input. Threshold is the engine's semantic cutoff. 156type SkillMatcher interface { 157 // Match returns the best candidate skill satisfying the required skill at or above threshold. 158 // On an exact id/name match it returns Exact=true, Similarity=1.0. ok is false when nothing 159 // meets the threshold. ctx carries the request deadline and cancellation to any provider call. 160 Match(ctx context.Context, required RequiredSkill, candidateSkills []CandidateSkill, threshold decimal.Decimal) (m SkillMatch, ok bool) 161} 162 163// ---------- Result ---------- 164 165// Band is the proposal-readiness classification of a total score. 166type Band int 167 168const ( 169 BandRed Band = iota // Recruiting Required (< 75) 170 BandYellow // Potential (75–89.99) 171 BandGreen // Proposal Ready (>= 90) 172) 173 174func (b Band) String() string { 175 switch b { 176 case BandGreen: 177 return "Green" 178 case BandYellow: 179 return "Yellow" 180 default: 181 return "Red" 182 } 183} 184 185// Label is the human-facing band name used in slates and explanations. 186func (b Band) Label() string { 187 switch b { 188 case BandGreen: 189 return "Proposal Ready" 190 case BandYellow: 191 return "Potential" 192 default: 193 return "Recruiting Required" 194 } 195} 196 197// ComponentScore is one weighted row of the decision trace (the AEDT/explainability artifact). 198type ComponentScore struct { 199 Component string // "Clearance", "Skills", ... 200 Weight decimal.Decimal // 0.25, 0.15, ... 201 Raw decimal.Decimal // the 0–100 sub-score 202 Weighted decimal.Decimal // Raw * Weight (contribution to the total) 203 Rationale string // human-readable reason for the sub-score 204} 205 206// MatchResult is the full, explainable, reproducible outcome of scoring one candidate vs one requirement. 207type MatchResult struct { 208 CandidateID string 209 RequirementID string 210 211 Clearance decimal.Decimal 212 Skills decimal.Decimal 213 Certifications decimal.Decimal 214 CustomerExperience decimal.Decimal 215 Experience decimal.Decimal 216 Location decimal.Decimal 217 218 Total decimal.Decimal // 0–100, rounded to 2 dp 219 Band Band 220 221 Explanation string // a human-readable summary 222 GapSummary []string // unmet MANDATORY items (clearance, mandatory skills, required certs, ...) 223 MatchedSkills []SkillMatch // required→candidate pairs with similarity (and the unmatched ones) 224 Trace []ComponentScore // per-component weighted breakdown, the decision trace 225} 226