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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/matching/skillmatcher.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	1e9249840a4302ec82e123b9c9cb6f75badea3e4
Branch	master
Path or archive member	internal/modules/matching/skillmatcher.go
Original SHA-256	e91912adb3c650321579a9d27842e4cfa818b369819244cb75e871a0c032c123
Git blob SHA	6e39a65c673e3d1dc4bd64a3d372b3c3d0c5a69d
Reading-copy SHA-256	e91912adb3c650321579a9d27842e4cfa818b369819244cb75e871a0c032c123

Original source ↗

Every recorded occurrence

These 37 records contain identical original source bytes. Their paths and revisions remain part of the archive.

Original record	Branch or archive	Revision / identifier	Original location
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	master	1e9249840a4302ec82e123b9c9cb6f75badea3e4	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	m5-price-to-win	41000ad30fff4129fdaf5ec84e15ba14c27d4890	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws3-clearance	4b8e7ce594c068621867f9c9deed0ec64ae6c553	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	collision-deconfliction	4ee5a09972608ed89f8377c6665542d5f450f0a6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws7-federal-signal	6a9f6ce9cfb13345ffb47770d4960e7c2d9c17c2	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws6-retrieval	6c56e29231ec05735927fa265c97d517499dfeaf	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ai-brain-live	aac32fc49c878cc5bca099459307611562d0bac1	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	graphrag-foundation	b0ddeb9f633fd138d09309d1a17b7d13bc3a67f7	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws1-ontology-sync	b596f449a32a1016fbd403c36505cc00a1ac9ee6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	time-to-fill-survival	b66e1e505863d4f17741a4b9ede73509e45bd6c6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	mag-substrate	b82c7100a492dec67dfd1eda6b3f53def859be35	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	capture-readiness	bae6af7cb2997e819174a9e9cfff5e16067a1975	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws8-teaching-loop	c823f0fb6bb2aba0f39001eb6de96f4000d9321f	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	phase2-eval-fairness	d361af254701975fe239927656ababb56374655e	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	phase2-connectors	e038d4c687aec16f8bd9bc4d907eea14d91f8704	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws2-alias-relationship	e4dada4601c6eb101830f9d223a9655dfa120616	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	presentation-readiness	eb574acaa29d71ce4d0f852572e87c275c79fdb7	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws9-bench-ingestion	f585a9ef32fa554663ce1fba9a414a54b6e49cf0	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	vendor-intelligence	fe9796a19c261951d3f2565206c0c1b5ac294465	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	collision-deconfliction	4ee5a09972608ed89f8377c6665542d5f450f0a6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws6-retrieval	6c56e29231ec05735927fa265c97d517499dfeaf	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	m5-price-to-win	41000ad30fff4129fdaf5ec84e15ba14c27d4890	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws1-ontology-sync	b596f449a32a1016fbd403c36505cc00a1ac9ee6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	master	1e9249840a4302ec82e123b9c9cb6f75badea3e4	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws8-teaching-loop	c823f0fb6bb2aba0f39001eb6de96f4000d9321f	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	mag-substrate	b82c7100a492dec67dfd1eda6b3f53def859be35	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws3-clearance	4b8e7ce594c068621867f9c9deed0ec64ae6c553	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	phase2-eval-fairness	d361af254701975fe239927656ababb56374655e	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	time-to-fill-survival	b66e1e505863d4f17741a4b9ede73509e45bd6c6	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	graphrag-foundation	b0ddeb9f633fd138d09309d1a17b7d13bc3a67f7	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws9-bench-ingestion	f585a9ef32fa554663ce1fba9a414a54b6e49cf0	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws2-alias-relationship	e4dada4601c6eb101830f9d223a9655dfa120616	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	presentation-readiness	eb574acaa29d71ce4d0f852572e87c275c79fdb7	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ws7-federal-signal	6a9f6ce9cfb13345ffb47770d4960e7c2d9c17c2	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	ai-brain-live	aac32fc49c878cc5bca099459307611562d0bac1	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	phase2-connectors	e038d4c687aec16f8bd9bc4d907eea14d91f8704	Open original
Janady13/missionmatch / internal/modules/matching/skillmatcher.go	capture-readiness	bae6af7cb2997e819174a9e9cfff5e16067a1975	Open original

Recovered source transcript

Download complete source text ↓179 lines · 6.8 KB

package matching

import (
	"context"
	"sync"

	"github.com/google/uuid"
	"github.com/pgvector/pgvector-go"
	"github.com/shopspring/decimal"

	"github.com/missionworkforce/missionmatch/internal/modules/matching/engine"
	"github.com/missionworkforce/missionmatch/internal/platform/embeddings"
	"github.com/missionworkforce/missionmatch/internal/platform/tenant"
)

// EmbeddingSkillMatcher implements engine.SkillMatcher using the embedding provider: it embeds the
// required skill name and each candidate skill name and picks the best cosine match at/above the
// engine's threshold. Vectors from the provider are L2-normalized, so cosine == dot product.
//
// This is the semantic ("synonyms / adjacent skills") layer the engine defers to AFTER exact match.
// With the deterministic offline embedder, unrelated skills score near zero, so it never invents a
// false semantic match, exact matching still dominates. Determinism follows from the embedder's.
type EmbeddingSkillMatcher struct {
	embedder embeddings.Embedder
}

// NewEmbeddingSkillMatcher wraps an embedder as an engine.SkillMatcher.
func NewEmbeddingSkillMatcher(e embeddings.Embedder) *EmbeddingSkillMatcher {
	return &EmbeddingSkillMatcher{embedder: e}
}

// Match satisfies engine.SkillMatcher. It returns the candidate skill side and the similarity; the
// engine owns the required-side identity and the match flags. ctx is the request context, so an
// embedding provider call respects the request deadline and cancellation (it is never stored).
//
// The float dot product picks the single best candidate (ordering ties are astronomically unlikely
// and never change the met/unmet outcome), but the at or above threshold DECISION is made in decimal
// on the similarity rounded to a fixed scale, so the boundary outcome is reproducible across
// architectures, on the engine's determinism path.
func (m *EmbeddingSkillMatcher) Match(ctx context.Context, required engine.RequiredSkill, cands []engine.CandidateSkill, threshold decimal.Decimal) (engine.SkillMatch, bool) {
	if m == nil || m.embedder == nil || len(cands) == 0 {
		return engine.SkillMatch{}, false
	}
	rv, err := m.embedder.Embed(ctx, required.Name)
	if err != nil {
		return engine.SkillMatch{}, false
	}

	bestSim := -2.0
	var best engine.CandidateSkill
	found := false
	for _, cs := range cands {
		cv, err := m.embedder.Embed(ctx, cs.Name)
		if err != nil || len(cv) != len(rv) {
			continue
		}
		if sim := dot(rv, cv); sim > bestSim {
			bestSim, best, found = sim, cs, true
		}
	}
	if !found {
		return engine.SkillMatch{}, false
	}
	sim := decimal.NewFromFloat(bestSim).Round(4)
	if sim.LessThan(threshold) {
		return engine.SkillMatch{}, false
	}
	return engine.SkillMatch{
		CandidateSkillID: best.SkillID,
		CandidateName:    best.Name,
		Similarity:       sim,
		Matched:          true,
	}, true
}

func dot(a, b []float32) float64 {
	var s float64
	for i := range a {
		s += float64(a[i]) * float64(b[i])
	}
	return s
}

// StoredSkillMatcher is the LIVE semantic skill matcher. It satisfies engine.SkillMatcher using the
// BACKFILLED skill embeddings in the global skills table (the same vector(384) column the HNSW index
// covers), instead of embedding skill name strings at request time. Embedding name strings at request time
// was the dead live path: with the fake default embedder it produced fake similarities, and it ignored the
// populated column entirely. This matcher reads the stored vectors once into an in memory cache (the skills
// ontology is a small, global, bounded table) and resolves a required skill against a candidate's skills by
// cosine over the stored vectors.
//
// The matcher's job is known skill to known skill (the required skill and the candidate's skills are both
// ontology entries with ids), which is a direct cosine over two stored vectors, not a nearest neighbor
// search; the HNSW index powers the UNBOUNDED adjacency search (ai.SkillAdjacency / KAG), which is already
// live. Both read the same populated column, so the vector layer is now live across the board.
//
// The engine still does exact match first; this is only consulted for a required skill the candidate does
// not hold exactly. A required or candidate skill with no stored embedding simply yields no semantic match
// (exact matching is unaffected), so a partial backfill degrades gracefully rather than inventing matches.
type StoredSkillMatcher struct {
	db    *tenant.DB
	mu    sync.RWMutex
	cache map[string][]float32 // skill id -> stored, L2 normalized embedding
}

// NewStoredSkillMatcher builds the matcher over the database that holds the global skills table. The
// pgvector codec is registered on the pool, so the embedding column scans into a pgvector.Vector.
func NewStoredSkillMatcher(db *tenant.DB) *StoredSkillMatcher {
	return &StoredSkillMatcher{db: db}
}

// Match resolves the required skill against the candidate's skills by cosine over the stored embeddings.
func (m *StoredSkillMatcher) Match(ctx context.Context, required engine.RequiredSkill, cands []engine.CandidateSkill, threshold decimal.Decimal) (engine.SkillMatch, bool) {
	if m == nil || m.db == nil || m.db.Pool == nil || len(cands) == 0 {
		return engine.SkillMatch{}, false
	}
	cache := m.ensureLoaded(ctx)
	rv, ok := cache[required.SkillID]
	if !ok {
		return engine.SkillMatch{}, false // the required skill has no stored embedding; exact match still applies
	}
	bestSim := -2.0
	var best engine.CandidateSkill
	found := false
	for _, cs := range cands {
		cv, ok := cache[cs.SkillID]
		if !ok || len(cv) != len(rv) {
			continue
		}
		if sim := dot(rv, cv); sim > bestSim {
			bestSim, best, found = sim, cs, true
		}
	}
	if !found {
		return engine.SkillMatch{}, false
	}
	sim := decimal.NewFromFloat(bestSim).Round(4)
	if sim.LessThan(threshold) {
		return engine.SkillMatch{}, false
	}
	return engine.SkillMatch{CandidateSkillID: best.SkillID, CandidateName: best.Name, Similarity: sim, Matched: true}, true
}

// ensureLoaded reads every embedded skill into the cache once. skills is a global, no RLS table, so a plain
// pool read is correct and needs no tenant scope. A read failure or a missing embedding degrades to no
// semantic match, never a fake one. Reload picks up a fresh backfill on a server restart.
func (m *StoredSkillMatcher) ensureLoaded(ctx context.Context) map[string][]float32 {
	m.mu.RLock()
	if m.cache != nil {
		c := m.cache
		m.mu.RUnlock()
		return c
	}
	m.mu.RUnlock()

	m.mu.Lock()
	defer m.mu.Unlock()
	if m.cache != nil {
		return m.cache
	}
	cache := map[string][]float32{}
	rows, err := m.db.Pool.Query(ctx, "SELECT id, embedding FROM skills WHERE embedding IS NOT NULL")
	if err != nil {
		m.cache = cache // mark loaded; exact matching still works
		return cache
	}
	defer rows.Close()
	for rows.Next() {
		var id uuid.UUID
		var vec pgvector.Vector
		if err := rows.Scan(&id, &vec); err != nil {
			continue
		}
		cache[id.String()] = vec.Slice()
	}
	m.cache = cache
	return cache
}