Janady13/missionmatch / internal/modules/matching/aliasresolver.go

1package matching 2 3import ( 4 "context" 5 "strings" 6 "sync" 7 8 "github.com/shopspring/decimal" 9 10 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 11 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 12) 13 14// relEdge is one directed curated relationship from a source skill to a target skill. 15type relEdge struct { 16 toID string 17 relation string 18 strength decimal.Decimal 19} 20 21// DeterministicAliasResolver resolves a required skill against a candidate skill set using two curated 22// ontology tables: skill_aliases (exact equivalences) and skill_relationships (partial credit via 23// substitutes_for and broader_than). It runs BEFORE the semantic matcher so an ontology-backed curated 24// match takes precedence over a cosine similarity. Graceful degradation: a DB load error leaves all 25// maps empty and the resolver returns no matches, leaving exact and semantic matching unaffected. 26type DeterministicAliasResolver struct { 27 db *tenant.DB 28 29 mu sync.RWMutex 30 loaded bool 31 nameToID map[string]string // lower(skills.name) to skills.id 32 aliasToID map[string]string // lower(skill_aliases.alias_text) to skill_id 33 rels map[string][]relEdge // from_skill_id to outgoing curated edges 34} 35 36// NewDeterministicAliasResolver builds a resolver backed by the global skills ontology tables. The 37// maps are loaded lazily on first call to ResolveAlias, matching the StoredSkillMatcher pattern. 38func NewDeterministicAliasResolver(db *tenant.DB) *DeterministicAliasResolver { 39 return &DeterministicAliasResolver{db: db} 40} 41 42// newResolverFromMaps builds a resolver with maps injected directly, for deterministic unit tests 43// that need no DB. 44func newResolverFromMaps(nameToID, aliasToID map[string]string, rels map[string][]relEdge) *DeterministicAliasResolver { 45 if nameToID == nil { 46 nameToID = map[string]string{} 47 } 48 if aliasToID == nil { 49 aliasToID = map[string]string{} 50 } 51 if rels == nil { 52 rels = map[string][]relEdge{} 53 } 54 return &DeterministicAliasResolver{ 55 loaded: true, 56 nameToID: nameToID, 57 aliasToID: aliasToID, 58 rels: rels, 59 } 60} 61 62// ResolveAlias runs the deterministic alias and relationship resolution for one required skill 63// against all candidate skills. The engine has already handled true exact id and name matches before 64// calling the resolver, so any hit here is alias or relationship sourced. 65// 66// Steps: 67// 1. Canonicalize the required skill to its ontology id. 68// 2. Canonicalize each candidate skill to its ontology id. 69// 3. If any candidate canonical id equals the required canonical id, return an alias match (1.0, 70// Exact true, AliasMatched true). 71// 4. Otherwise check curated relationships for a substitutes_for or broader_than edge from any 72// candidate to the required skill at or above strength 0.62. 73// 5. On no match, return engine.SkillMatch{}, false. 74func (r *DeterministicAliasResolver) ResolveAlias( 75 ctx context.Context, 76 required engine.RequiredSkill, 77 candidateSkills []engine.CandidateSkill, 78) (engine.SkillMatch, bool) { 79 r.ensureLoaded(ctx) 80 81 reqCanonical := r.canonicalize(required.SkillID, required.Name) 82 if reqCanonical == "" { 83 return engine.SkillMatch{}, false 84 } 85 86 // First pass: alias match (canonical id equality). 87 for _, cs := range candidateSkills { 88 csCanonical := r.canonicalize(cs.SkillID, cs.Name) 89 if csCanonical == "" { 90 continue 91 } 92 if csCanonical == reqCanonical { 93 return engine.SkillMatch{ 94 CandidateSkillID: cs.SkillID, 95 CandidateName: cs.Name, 96 Similarity: decimal.NewFromInt(1), 97 Exact: true, 98 AliasMatched: true, 99 Matched: true, 100 }, true 101 } 102 } 103 104 // Second pass: relationship match at or above the 0.62 threshold. 105 threshold := decimal.RequireFromString("0.62") 106 bestStrength := decimal.Zero 107 var bestMatch engine.SkillMatch 108 found := false 109 110 for _, cs := range candidateSkills { 111 csCanonical := r.canonicalize(cs.SkillID, cs.Name) 112 if csCanonical == "" { 113 continue 114 } 115 r.mu.RLock() 116 edges := r.rels[csCanonical] 117 r.mu.RUnlock() 118 for _, e := range edges { 119 if e.toID != reqCanonical { 120 continue 121 } 122 if e.relation != "substitutes_for" && e.relation != "broader_than" { 123 continue 124 } 125 if e.strength.GreaterThan(bestStrength) { 126 bestStrength = e.strength 127 bestMatch = engine.SkillMatch{ 128 CandidateSkillID: cs.SkillID, 129 CandidateName: cs.Name, 130 Similarity: e.strength, 131 Exact: false, 132 AliasMatched: false, 133 Matched: true, 134 } 135 found = true 136 } 137 } 138 } 139 140 if found && bestStrength.GreaterThanOrEqual(threshold) { 141 return bestMatch, true 142 } 143 return engine.SkillMatch{}, false 144} 145 146// canonicalize resolves a skill to its canonical ontology id. Priority: explicit id, then 147// nameToID lookup, then aliasToID lookup. Returns "" when nothing matches. 148func (r *DeterministicAliasResolver) canonicalize(skillID, name string) string { 149 if skillID != "" { 150 return skillID 151 } 152 r.mu.RLock() 153 defer r.mu.RUnlock() 154 key := strings.ToLower(strings.TrimSpace(name)) 155 if id, ok := r.nameToID[key]; ok { 156 return id 157 } 158 if id, ok := r.aliasToID[key]; ok { 159 return id 160 } 161 return "" 162} 163 164// ensureLoaded reads nameToID, aliasToID, and rels from the DB once. skills and skill_aliases are 165// global tables (no RLS), so a plain pool query without a tenant transaction is correct. A load 166// failure leaves all maps empty for graceful degradation: exact matching and semantic matching are 167// unaffected. 168func (r *DeterministicAliasResolver) ensureLoaded(ctx context.Context) { 169 r.mu.RLock() 170 if r.loaded { 171 r.mu.RUnlock() 172 return 173 } 174 r.mu.RUnlock() 175 176 r.mu.Lock() 177 defer r.mu.Unlock() 178 if r.loaded { 179 return 180 } 181 r.loaded = true // mark loaded before any possible early return so a DB error does not loop 182 183 if r.db == nil || r.db.Pool == nil { 184 r.nameToID = map[string]string{} 185 r.aliasToID = map[string]string{} 186 r.rels = map[string][]relEdge{} 187 return 188 } 189 190 nameToID := map[string]string{} 191 rows, err := r.db.Pool.Query(ctx, "SELECT id, name FROM skills") 192 if err == nil { 193 defer rows.Close() 194 for rows.Next() { 195 var id, name string 196 if err := rows.Scan(&id, &name); err != nil { 197 continue 198 } 199 nameToID[strings.ToLower(strings.TrimSpace(name))] = id 200 } 201 } 202 r.nameToID = nameToID 203 204 aliasToID := map[string]string{} 205 arows, err := r.db.Pool.Query(ctx, 206 "SELECT skill_id, alias_text FROM skill_aliases WHERE verified_at IS NOT NULL") 207 if err == nil { 208 defer arows.Close() 209 for arows.Next() { 210 var skillID, aliasText string 211 if err := arows.Scan(&skillID, &aliasText); err != nil { 212 continue 213 } 214 aliasToID[strings.ToLower(strings.TrimSpace(aliasText))] = skillID 215 } 216 } 217 r.aliasToID = aliasToID 218 219 rels := map[string][]relEdge{} 220 rrows, err := r.db.Pool.Query(ctx, 221 `SELECT from_skill_id, to_skill_id, relation, strength 222 FROM skill_relationships 223 WHERE verified_at IS NOT NULL 224 AND relation IN ('substitutes_for','broader_than')`) 225 if err == nil { 226 defer rrows.Close() 227 for rrows.Next() { 228 var fromID, toID, relation string 229 var strength decimal.Decimal 230 // strength is numeric(3,2). shopspring decimal implements sql.Scanner, the same path the sqlc 231 // generated numeric columns use (the pool registers no decimal codec), so pgx scans the numeric 232 // directly into the decimal with full precision. 233 if err := rrows.Scan(&fromID, &toID, &relation, &strength); err != nil { 234 continue 235 } 236 rels[fromID] = append(rels[fromID], relEdge{toID: toID, relation: relation, strength: strength}) 237 } 238 } 239 r.rels = rels 240} 241