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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/ai/retrieval.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	1e9249840a4302ec82e123b9c9cb6f75badea3e4
Branch	master
Path or archive member	internal/modules/ai/retrieval.go
Original SHA-256	34f1b87e1d5fd6611845822d99700b5d0c67e4e7d05c4bafc45787e322fbba60
Git blob SHA	eaa9a8d689f8b797b2bbc6ac87a03be86e1d598d
Reading-copy SHA-256	34f1b87e1d5fd6611845822d99700b5d0c67e4e7d05c4bafc45787e322fbba60

Original source ↗

Every recorded occurrence

These 21 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/ai/retrieval.go	master	1e9249840a4302ec82e123b9c9cb6f75badea3e4	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	feature/aioe-upgrade	2178e7298d0e5d9af83afa12402fd587f0ba6ed8	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	m5-price-to-win	41000ad30fff4129fdaf5ec84e15ba14c27d4890	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	collision-deconfliction	4ee5a09972608ed89f8377c6665542d5f450f0a6	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	graphrag-foundation	b0ddeb9f633fd138d09309d1a17b7d13bc3a67f7	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	time-to-fill-survival	b66e1e505863d4f17741a4b9ede73509e45bd6c6	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	mag-substrate	b82c7100a492dec67dfd1eda6b3f53def859be35	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	capture-readiness	bae6af7cb2997e819174a9e9cfff5e16067a1975	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	phase2-connectors	e038d4c687aec16f8bd9bc4d907eea14d91f8704	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	presentation-readiness	eb574acaa29d71ce4d0f852572e87c275c79fdb7	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	vendor-intelligence	fe9796a19c261951d3f2565206c0c1b5ac294465	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	collision-deconfliction	4ee5a09972608ed89f8377c6665542d5f450f0a6	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	m5-price-to-win	41000ad30fff4129fdaf5ec84e15ba14c27d4890	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	master	1e9249840a4302ec82e123b9c9cb6f75badea3e4	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	mag-substrate	b82c7100a492dec67dfd1eda6b3f53def859be35	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	time-to-fill-survival	b66e1e505863d4f17741a4b9ede73509e45bd6c6	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	graphrag-foundation	b0ddeb9f633fd138d09309d1a17b7d13bc3a67f7	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	presentation-readiness	eb574acaa29d71ce4d0f852572e87c275c79fdb7	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	phase2-connectors	e038d4c687aec16f8bd9bc4d907eea14d91f8704	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	feature/aioe-upgrade	2178e7298d0e5d9af83afa12402fd587f0ba6ed8	Open original
Janady13/missionmatch / internal/modules/ai/retrieval.go	capture-readiness	bae6af7cb2997e819174a9e9cfff5e16067a1975	Open original

Recovered source transcript

Download complete source text ↓135 lines · 6.0 KB

package ai

import (
	"context"
	"errors"

	"github.com/jackc/pgx/v5"
	pgvector "github.com/pgvector/pgvector-go"

	"github.com/missionworkforce/missionmatch/internal/platform/database/dbgen"
	"github.com/missionworkforce/missionmatch/internal/platform/inference"
	"github.com/missionworkforce/missionmatch/internal/platform/tenant"
)

// Hit is one retrieved candidate with its fused relevance score and the matched text span.
//
// Snippet is the matched text span (a Postgres ts_headline over the SAME text the candidate's search_tsv
// is built from, with the SAME tsquery the full text leg already binds), so the faithfulness gate and the
// narration can cite WHY a candidate matched, the matched TEXT, not only the name. An empty Snippet is a
// valid no highlight result (a pure semantic or empty query, or a hit reached only through the vector arm),
// never an error.
type Hit struct {
	CandidateID string  `json:"candidate_id"`
	FullName    string  `json:"full_name"`
	Score       float64 `json:"rrf_score"`
	Snippet     string  `json:"snippet"`
}

// HybridSearch is the RAG retrieval leg: it embeds the query through the MEGAMIND plane and runs the
// existing hybrid query that fuses pgvector cosine kNN with full text rank via Reciprocal Rank Fusion
// (docs/AI_RESEARCH.md, pgvector + RRF). It runs RLS scoped as the tenant, so it returns only the
// caller's candidates, and it tunes the HNSW scan per the pgvector 0.8 guidance before the search.
//
// When mission is a non empty mission keyword (from MissionFromQuestion, drawn only from the fixed
// mission_spine vocabulary), retrieval is additionally constrained to that mission. An empty mission runs the
// unscoped query byte for byte as before, so the default path is unchanged.
//
// WS6 to WS7 upgrade (the mission gate is now structured, additively, with the WS6 text filter kept as a
// fallback): when the tenant has been backfilled by the mission tagging pass (candidate_mission_tags has at
// least one row, probed RLS scoped in the same transaction) AND the keyword maps to a known mission code, the
// scoped query is SearchCandidatesHybridMissionTagged, which gates both arms on a STRUCTURED EXISTS predicate
// over candidate_mission_tags rather than the WS6 search_tsv text match. That is the candidate's real
// classified mission, so it reaches a candidate whose mission lives in the resume body, not only one whose
// full_name, headline, or location text happens to contain the mission keyword (the WS6 limit, lifted once
// tags exist). When the tenant is NOT yet tagged, or the keyword has no code, retrieval falls back to the WS6
// SearchCandidatesHybridMission text query, so an un backfilled tenant keeps exact WS6 behavior. Either scoped
// path keeps the RLS scoping, the ForbidEEO guard, and the HNSW SET LOCAL tuning of the unscoped path.
//
// It never touches the eeo schema (the query reads only candidates and their own mission tags, never the eeo
// schema, and mission tags are never a scoring input), and the query string is guarded so a demographic
// reference cannot enter the retrieval path.
func HybridSearch(ctx context.Context, db *tenant.DB, client *inference.Client, query, mission string, limit int) ([]Hit, error) {
	if db == nil || client == nil {
		return nil, errors.New("ai: retrieval needs a database and an inference client")
	}
	if err := ForbidEEO(query); err != nil {
		return nil, err
	}
	if limit <= 0 || limit > 100 {
		limit = 20
	}
	emb, err := client.Embed(ctx, []string{query})
	if err != nil {
		return nil, err
	}
	if len(emb.Embeddings) != 1 {
		return nil, errors.New("ai: query embedding failed")
	}
	qv := pgvector.NewVector(emb.Embeddings[0])

	var hits []Hit
	err = db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error {
		// pgvector 0.8 tuning: a wider ef_search lifts recall on the filtered (RLS) scan, and relaxed
		// iterative scan avoids overfiltering under the tenant predicate (docs/AI_RESEARCH.md, pgvector).
		if _, err := tx.Exec(ctx, "SET LOCAL hnsw.ef_search = 100"); err != nil {
			return err
		}
		if _, err := tx.Exec(ctx, "SET LOCAL hnsw.iterative_scan = 'relaxed_order'"); err != nil {
			return err
		}
		q := dbgen.New(tx)
		if mission != "" {
			// WS7 structured mission gate, preferred when the tenant has been tagged and the keyword maps to a
			// known mission code. The probe is RLS scoped, so it counts only this tenant's tags. When either
			// condition is unmet the WS6 text query runs instead, so an un backfilled tenant is byte identical
			// to WS6.
			code := MissionCodeForTerm(mission)
			if code != "" {
				tagCount, err := q.CountCandidateMissionTags(ctx)
				if err != nil {
					return err
				}
				if tagCount > 0 {
					rows, err := q.SearchCandidatesHybridMissionTagged(ctx, dbgen.SearchCandidatesHybridMissionTaggedParams{
						QueryVector: qv, RowLimit: int32(limit), TextQuery: query, MissionCode: code,
					})
					if err != nil {
						return err
					}
					hits = make([]Hit, len(rows))
					for i, r := range rows {
						hits[i] = Hit{CandidateID: r.ID.String(), FullName: r.FullName, Score: r.RrfScore, Snippet: r.Snippet}
					}
					return nil
				}
			}
			// WS6 fallback: the tenant has no mission tags yet, or the keyword has no structured code, so the
			// documented WS6 search_tsv text filter scopes the mission (byte for byte the WS6 behavior).
			rows, err := q.SearchCandidatesHybridMission(ctx, dbgen.SearchCandidatesHybridMissionParams{
				QueryVector: qv, RowLimit: int32(limit), TextQuery: query, MissionQuery: mission,
			})
			if err != nil {
				return err
			}
			hits = make([]Hit, len(rows))
			for i, r := range rows {
				hits[i] = Hit{CandidateID: r.ID.String(), FullName: r.FullName, Score: r.RrfScore, Snippet: r.Snippet}
			}
			return nil
		}
		rows, err := q.SearchCandidatesHybrid(ctx, dbgen.SearchCandidatesHybridParams{
			Column1: qv, Limit: int32(limit), WebsearchToTsquery: query,
		})
		if err != nil {
			return err
		}
		hits = make([]Hit, len(rows))
		for i, r := range rows {
			hits[i] = Hit{CandidateID: r.ID.String(), FullName: r.FullName, Score: r.RrfScore, Snippet: r.Snippet}
		}
		return nil
	})
	return hits, err
}