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

1package ai 2 3import ( 4 "context" 5 "errors" 6 7 "github.com/jackc/pgx/v5" 8 9 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 10) 11 12// This file holds the augmented generation layers whose data structures are partly or fully scaffolded. 13// What is REAL today: KAG skill adjacency (the now live skills.embedding HNSW) and CAG public rules. 14// What is SCAFFOLDED (interface present, fuller build sequenced for more data or more clients): the 15// GraphRAG teaming graph, the capture and foresight models, and the federated learning loop, which is 16// designed in but DISABLED. 17 18// ---------- KAG: clearance and skills knowledge (skill adjacency is REAL) ---------- 19 20// AdjacentSkill is one semantically adjacent skill and its cosine distance. 21type AdjacentSkill struct { 22 Name string `json:"name"` 23 Distance float64 `json:"distance"` 24} 25 26// SkillAdjacency returns the k skills nearest to a named skill by embedding cosine, the curated skill 27// graph the audit found missing. It is LIVE: it uses the skills.embedding HNSW index populated by 28// cmd/embed-backfill. This is the substitution reasoner the engine's semantic skill match leans on (a 29// candidate who lacks the exact skill but holds an adjacent one). It reads only the global skills table, 30// never eeo. 31func SkillAdjacency(ctx context.Context, db *tenant.DB, skillName string, k int) ([]AdjacentSkill, error) { 32 if db == nil { 33 return nil, errors.New("ai: no database") 34 } 35 if err := ForbidEEO(skillName); err != nil { 36 return nil, err 37 } 38 if k <= 0 || k > 25 { 39 k = 8 40 } 41 var out []AdjacentSkill 42 err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 43 rows, err := tx.Query(ctx, ` 44 SELECT s.name, (s.embedding <=> seed.embedding)::float8 AS dist 45 FROM skills s, (SELECT embedding FROM skills WHERE name = $1 AND embedding IS NOT NULL LIMIT 1) seed 46 WHERE s.embedding IS NOT NULL AND s.name <> $1 47 ORDER BY s.embedding <=> seed.embedding, s.name 48 LIMIT $2`, skillName, k) 49 if err != nil { 50 return err 51 } 52 defer rows.Close() 53 for rows.Next() { 54 var a AdjacentSkill 55 if err := rows.Scan(&a.Name, &a.Distance); err != nil { 56 return err 57 } 58 out = append(out, a) 59 } 60 return rows.Err() 61 }) 62 return out, err 63} 64 65// ---------- CAG: stable public rules preloaded into model context (REAL) ---------- 66 67// PublicRules returns the stable, public, contents free rules and definitions the platform always knows: 68// the fixed scoring weights and bands, the clearance hierarchy and reciprocity, and the standing 69// disclaimers. Cache augmented generation preloads this once into model context (it fits easily), so the 70// model never has to retrieve it and never invents it. It contains NO client data and NO demographic 71// field, so it is safe to hold in any tenant's context. 72func PublicRules() string { 73 return `MODEL (deterministic engine, v1.0.0; the floor, never overridden by the AI layer): 74Match Score = Clearance*0.25 + Skills*0.25 + Certifications*0.15 + CustomerExperience*0.15 + Experience*0.10 + LocationAvailability*0.10. 75Bands: Green (Proposal Ready) >= 90; Yellow (Potential) 75 to 89.99; Red (Recruiting Required) < 75. 76Clearance: exact or higher and active scores 100, else 0. Hierarchy: None < Confidential < Secret < Top Secret < TS/SCI. TS/SCI satisfies Secret; Secret does NOT satisfy TS/SCI. Polygraph: None < CI < Full Scope; Full Scope satisfies CI. 77Clearance is a self reported intelligence indicator, NEVER verified by the platform; the real check is the hiring client FSO through DISS at onboarding. 78Demographic and EEO data is NEVER an input to scoring or to any AI answer.` 79} 80 81// ---------- GraphRAG: teaming and incumbent graph (SCAFFOLD) ---------- 82 83// TeamingGraph is the relationship graph over awards and opportunity_records (incumbents, agencies, 84// NAICS, set asides). SCAFFOLD: the node and edge model and the community summarization pass are 85// designed but not built; the awards and opportunity_records tables hold the raw relationships today. 86// Building it is sequenced after the entity extraction pass. It will attach per tenant with its own 87// embeddings and will read only public market data, never eeo. 88type TeamingGraph struct { 89 db *tenant.DB 90} 91 92// NewTeamingGraph returns the scaffold. BuildErr documents that the full graph is not yet constructed. 93func NewTeamingGraph(db *tenant.DB) *TeamingGraph { return &TeamingGraph{db: db} } 94 95// ErrScaffold marks a capability whose interface is present but whose full implementation is sequenced. 96var ErrScaffold = errors.New("ai: scaffolded capability, fuller build sequenced (see BUILD_REPORT.md)") 97 98// ---------- Capture and foresight (SCAFFOLD, needs more data) ---------- 99 100// Foresight groups the capture and foresight estimators: win probability, bid or no bid, price to win 101// from BLS and USASpending, clearance timing survival analysis, and demand forecasting. SCAFFOLD: these 102// need a labeled history (won and lost bids, time to clearance) the platform does not have enough of yet; 103// the interfaces are fixed so they can be filled as the data accrues. Marked needs more data. 104type Foresight struct{} 105 106// PriceToWinInputs are the public market signals a price to win estimate would draw on (BLS OEWS wages, 107// USASpending award amounts). The estimator is a scaffold. 108type PriceToWinInputs struct { 109 NAICS string 110 LaborCatSOC string 111 AreaCode string 112} 113 114// EstimatePriceToWin is a SCAFFOLD: it returns ErrScaffold until a labeled bid history exists. 115func (Foresight) EstimatePriceToWin(_ context.Context, _ PriceToWinInputs) (float64, error) { 116 return 0, ErrScaffold 117} 118 119// ---------- Federated learning with differential privacy (DESIGNED, DISABLED) ---------- 120 121// FederatedLearningEnabled is the master switch for cross tenant model improvement. It is DISABLED and 122// must stay disabled until multiple live clients exist. While disabled, no craft signal is transmitted 123// off a tenant (the scrub boundary already withholds transmission when teaching is off), and no cross 124// tenant aggregation runs. 125const FederatedLearningEnabled = false 126 127// FederatedConfig is the design surface for the disabled loop: the differential privacy budget and the 128// minimum number of distinct tenants required before any aggregate is computed (k anonymity over 129// tenants). These are recorded so the privacy accounting is fixed before the loop is ever activated. 130type FederatedConfig struct { 131 Enabled bool // mirrors FederatedLearningEnabled; activation is a deliberate, reviewed change 132 EpsilonPerWeek float64 // differential privacy budget per aggregation window 133 Delta float64 // differential privacy delta 134 MinTenants int // do not aggregate below this many distinct contributing tenants 135} 136 137// DefaultFederatedConfig is the disabled, conservative default. Activation requires multiple live 138// clients, a signed off privacy budget, and only contents scrubbed craft signals through the scrub 139// boundary, never raw data. 140func DefaultFederatedConfig() FederatedConfig { 141 return FederatedConfig{Enabled: FederatedLearningEnabled, EpsilonPerWeek: 1.0, Delta: 1e-6, MinTenants: 5} 142} 143