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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/ai/scaffolds.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	720d47fae476b0d38477ae4401697d372b1ea2bc
Branch	feature/opportunity-to-outcome
Path or archive member	internal/modules/ai/scaffolds.go
Original SHA-256	0c6130532945eedd0fbb5d8dda2a215b354f4f4f59560f4535e53f5876fad092
Git blob SHA	e87eb5274afa9e41fc4289696053fbd16d754985
Reading-copy SHA-256	0c6130532945eedd0fbb5d8dda2a215b354f4f4f59560f4535e53f5876fad092

Original source ↗

Every recorded occurrence

These 23 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/scaffolds.go	feature/opportunity-to-outcome	720d47fae476b0d38477ae4401697d372b1ea2bc	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	per-tenant-routing	9bde0f9a74b89d01980fa658e5253acda7528d0c	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	collision-deconfliction	4ee5a09972608ed89f8377c6665542d5f450f0a6	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws6-retrieval	6c56e29231ec05735927fa265c97d517499dfeaf	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	m5-price-to-win	41000ad30fff4129fdaf5ec84e15ba14c27d4890	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws1-ontology-sync	b596f449a32a1016fbd403c36505cc00a1ac9ee6	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	master	1e9249840a4302ec82e123b9c9cb6f75badea3e4	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws8-teaching-loop	c823f0fb6bb2aba0f39001eb6de96f4000d9321f	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	mag-substrate	b82c7100a492dec67dfd1eda6b3f53def859be35	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws3-clearance	4b8e7ce594c068621867f9c9deed0ec64ae6c553	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	phase2-eval-fairness	d361af254701975fe239927656ababb56374655e	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	time-to-fill-survival	b66e1e505863d4f17741a4b9ede73509e45bd6c6	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	graphrag-foundation	b0ddeb9f633fd138d09309d1a17b7d13bc3a67f7	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	deploy-and-ops	bdacd9d0b4d5998d25fc74bf4007f4c3ec538c7a	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws9-bench-ingestion	f585a9ef32fa554663ce1fba9a414a54b6e49cf0	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws2-alias-relationship	e4dada4601c6eb101830f9d223a9655dfa120616	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	presentation-readiness	eb574acaa29d71ce4d0f852572e87c275c79fdb7	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	vendor-intelligence	fe9796a19c261951d3f2565206c0c1b5ac294465	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ws7-federal-signal	6a9f6ce9cfb13345ffb47770d4960e7c2d9c17c2	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	ai-brain-live	aac32fc49c878cc5bca099459307611562d0bac1	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	phase2-connectors	e038d4c687aec16f8bd9bc4d907eea14d91f8704	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	feature/aioe-upgrade	2178e7298d0e5d9af83afa12402fd587f0ba6ed8	Open original
Janady13/missionmatch / internal/modules/ai/scaffolds.go	capture-readiness	bae6af7cb2997e819174a9e9cfff5e16067a1975	Open original

Recovered source transcript

Download complete source text ↓156 lines · 7.6 KB

package ai

import (
	"context"
	"errors"
	"fmt"

	"github.com/jackc/pgx/v5"

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

// This file holds the augmented generation layers whose data structures are partly or fully scaffolded.
// What is REAL today: KAG skill adjacency (the now live skills.embedding HNSW) and CAG public rules.
// What is SCAFFOLDED (interface present, fuller build sequenced for more data or more clients): the
// GraphRAG teaming graph, the capture and foresight models, and the federated learning loop, which is
// designed in but DISABLED.

// ---------- KAG: clearance and skills knowledge (skill adjacency is REAL) ----------

// AdjacentSkill is one semantically adjacent skill and its cosine distance.
type AdjacentSkill struct {
	Name     string  `json:"name"`
	Distance float64 `json:"distance"`
}

// SkillAdjacency returns the k skills nearest to a named skill by embedding cosine, the curated skill
// graph the audit found missing. It is LIVE: it uses the skills.embedding HNSW index populated by
// cmd/embed-backfill. This is the substitution reasoner the engine's semantic skill match leans on (a
// candidate who lacks the exact skill but holds an adjacent one). It reads only the global skills table,
// never eeo.
func SkillAdjacency(ctx context.Context, db *tenant.DB, skillName string, k int) ([]AdjacentSkill, error) {
	if db == nil {
		return nil, errors.New("ai: no database")
	}
	var out []AdjacentSkill
	err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error {
		var e error
		out, e = SkillAdjacencyOnTx(ctx, tx, skillName, k)
		return e
	})
	return out, err
}

// SkillAdjacencyOnTx is SkillAdjacency on a caller supplied transaction, so a module that is already
// inside a tenant transaction (the W3 staffing recommendations module) reuses the exact same curated
// skill graph without opening a nested transaction. It still refuses any eeo reference and reads only the
// global skills table.
func SkillAdjacencyOnTx(ctx context.Context, tx pgx.Tx, skillName string, k int) ([]AdjacentSkill, error) {
	if err := ForbidEEO(skillName); err != nil {
		return nil, err
	}
	if k <= 0 || k > 25 {
		k = 8
	}
	rows, err := tx.Query(ctx, `
		SELECT s.name, (s.embedding <=> seed.embedding)::float8 AS dist
		FROM skills s, (SELECT embedding FROM skills WHERE name = $1 AND embedding IS NOT NULL LIMIT 1) seed
		WHERE s.embedding IS NOT NULL AND s.name <> $1
		ORDER BY s.embedding <=> seed.embedding, s.name
		LIMIT $2`, skillName, k)
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	var out []AdjacentSkill
	for rows.Next() {
		var a AdjacentSkill
		if err := rows.Scan(&a.Name, &a.Distance); err != nil {
			return nil, err
		}
		out = append(out, a)
	}
	return out, rows.Err()
}

// ---------- CAG: stable public rules preloaded into model context (REAL) ----------

// PublicRules returns the stable, public, contents free rules and definitions the platform always knows:
// the fixed scoring weights and bands, the clearance hierarchy and reciprocity, and the standing
// disclaimers. Cache augmented generation preloads this once into model context (it fits easily), so the
// model never has to retrieve it and never invents it. It contains NO client data and NO demographic
// field, so it is safe to hold in any tenant's context.
func PublicRules() string {
	return fmt.Sprintf(`MODEL (deterministic engine, %s; the floor, never overridden by the AI layer):
Match Score = Clearance*0.25 + Skills*0.25 + Certifications*0.15 + CustomerExperience*0.15 + Experience*0.10 + LocationAvailability*0.10.
Bands: Green (Proposal Ready) >= 90; Yellow (Potential) 75 to 89.99; Red (Recruiting Required) < 75.
Clearance: 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.
Clearance is a self reported intelligence indicator, NEVER verified by the platform; the real check is the hiring client FSO through DISS at onboarding.
Demographic and EEO data is NEVER an input to scoring or to any AI answer.`, engine.ModelVersion)
}

// ---------- GraphRAG: teaming and incumbent graph (SCAFFOLD) ----------

// TeamingGraph is the relationship graph over awards and opportunity_records (incumbents, agencies,
// NAICS, set asides). SCAFFOLD: the node and edge model and the community summarization pass are
// designed but not built; the awards and opportunity_records tables hold the raw relationships today.
// Building it is sequenced after the entity extraction pass. It will attach per tenant with its own
// embeddings and will read only public market data, never eeo.
type TeamingGraph struct {
	db *tenant.DB
}

// NewTeamingGraph returns the scaffold. BuildErr documents that the full graph is not yet constructed.
func NewTeamingGraph(db *tenant.DB) *TeamingGraph { return &TeamingGraph{db: db} }

// ErrScaffold marks a capability whose interface is present but whose full implementation is sequenced.
var ErrScaffold = errors.New("ai: scaffolded capability, fuller build sequenced (see BUILD_REPORT.md)")

// ---------- Capture and foresight (SCAFFOLD, needs more data) ----------

// Foresight groups the capture and foresight estimators: win probability, bid or no bid, price to win
// from BLS and USASpending, clearance timing survival analysis, and demand forecasting. SCAFFOLD: these
// need a labeled history (won and lost bids, time to clearance) the platform does not have enough of yet;
// the interfaces are fixed so they can be filled as the data accrues. Marked needs more data.
type Foresight struct{}

// PriceToWinInputs are the public market signals a price to win estimate would draw on (BLS OEWS wages,
// USASpending award amounts). The estimator is a scaffold.
type PriceToWinInputs struct {
	NAICS       string
	LaborCatSOC string
	AreaCode    string
}

// EstimatePriceToWin is a SCAFFOLD: it returns ErrScaffold until a labeled bid history exists.
func (Foresight) EstimatePriceToWin(_ context.Context, _ PriceToWinInputs) (float64, error) {
	return 0, ErrScaffold
}

// ---------- Federated learning with differential privacy (DESIGNED, DISABLED) ----------

// FederatedLearningEnabled is the master switch for cross tenant model improvement. It is DISABLED and
// must stay disabled until multiple live clients exist. While disabled, no craft signal is transmitted
// off a tenant (the scrub boundary already withholds transmission when teaching is off), and no cross
// tenant aggregation runs.
const FederatedLearningEnabled = false

// FederatedConfig is the design surface for the disabled loop: the differential privacy budget and the
// minimum number of distinct tenants required before any aggregate is computed (k anonymity over
// tenants). These are recorded so the privacy accounting is fixed before the loop is ever activated.
type FederatedConfig struct {
	Enabled        bool    // mirrors FederatedLearningEnabled; activation is a deliberate, reviewed change
	EpsilonPerWeek float64 // differential privacy budget per aggregation window
	Delta          float64 // differential privacy delta
	MinTenants     int     // do not aggregate below this many distinct contributing tenants
}

// DefaultFederatedConfig is the disabled, conservative default. Activation requires multiple live
// clients, a signed off privacy budget, and only contents scrubbed craft signals through the scrub
// boundary, never raw data.
func DefaultFederatedConfig() FederatedConfig {
	return FederatedConfig{Enabled: FederatedLearningEnabled, EpsilonPerWeek: 1.0, Delta: 1e-6, MinTenants: 5}
}