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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/ai/graph_loop.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	720d47fae476b0d38477ae4401697d372b1ea2bc
Branch	feature/opportunity-to-outcome
Path or archive member	internal/modules/ai/graph_loop.go
Original SHA-256	cf7ca4e8427956ea333ea630f977e398b46956057b6751ecc50ba07be7b7f8f7
Git blob SHA	4250b5c344861faeed45812cef380056ca8b3a78
Reading-copy SHA-256	cf7ca4e8427956ea333ea630f977e398b46956057b6751ecc50ba07be7b7f8f7
Original source ↗
Every recorded occurrence

These 2 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/graph_loop.go	feature/opportunity-to-outcome	720d47fae476b0d38477ae4401697d372b1ea2bc	Open original
Janady13/missionmatch / internal/modules/ai/graph_loop.go	feature/aioe-upgrade	2178e7298d0e5d9af83afa12402fd587f0ba6ed8	Open original
Recovered source transcript

Download complete source text ↓353 lines · 18.6 KB
package ai

// G6 the loop. This file closes the keystone of the GraphRAG program: a single integrated capture answer
// for one requirement that REASONS ACROSS the planes rather than within one. It is an ORCHESTRATOR
// COMPOSITION, NOT a new SQL intent: it reuses the already validated planes so each keeps its guarantees,
// the SUPPRESSING bench executors (G4 BenchGapForRequirement, G5 BenchClearanceCoverage) for the person
// touching legs and the PUBLIC market reads (G9 RecompeteClock, G1 SegmentCompetitorField) for the market
// leg, resolving the requirement's market segment from requirements.customer_agency and, when present, the
// linked opportunity's naics.
//
// G6 is a PERSON TOUCHING bench intent: it reads the bench, so it is registered in benchIntents, requires an
// authenticated tenant context (it refuses without one), surfaces every bench count only through RenderCount
// (the sentinel for a suppressed cell, never a raw sub k number), and emits a counts only audit, exactly
// like the G4 intents. The market leg is PUBLIC (no suppression) and rendered verbatim. The composed answer
// NEVER computes a match score, a band, or any employment decision number: the per candidate score and the
// ranking stay the frozen engine in internal/modules/matching/engine, which is untouched. G6 reports the
// STRUCTURAL bench coverage (suppressed counts) plus the public market structure and narrates the gap.
//
// The honesty floor is explicit. When a requirement has no resolvable market segment (no customer_agency and
// no linked opportunity), the market leg states that plainly rather than guessing. The price to win leg (M5)
// carries a REAL advisory BLS OEWS wage band for the requirement's occupation and place of performance when
// the requirement's role resolves to a SOC and its work_location resolves to a known OEWS area AND a wage row
// exists; otherwise it keeps the honest floor (labor rate data not yet ingested) and fabricates no rate.

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"strings"

	"github.com/jackc/pgx/v5"

	"github.com/missionworkforce/missionmatch/internal/platform/tenant"
)

// IntentCapturePictureForRequirement is the FIXED registered name of the G6 composition. It is a closed
// Registry entry (so ValidateRegistry asserts it at boot) and a benchIntent (so the raw ExecuteIntent path
// hard rejects it and the AnswerGraph bench fork routes it to answerCapturePicture). It does NOT run through
// ExecuteIntent: the registered SQL is the segment resolver read, a valid allowlisted single SELECT that
// passes the guard, but it is reached only by the composition, never the raw intent path.
const IntentCapturePictureForRequirement = "capture_picture_for_requirement"

// capturePriceToWinFloor is the honest floor for the price to win leg, the fallback the composition states
// plainly whenever a real OEWS wage band does not resolve for the requirement (its role does not map to a
// SOC, its work_location does not map to a known OEWS area, or no wage row exists for that occupation and
// area). No rate is fabricated for the floor. It is a surfaced string with no dashes.
const capturePriceToWinFloor = "labor rate data not yet ingested"

// requirementSegmentSQL resolves the market segment for one requirement under RLS. It reads requirements
// (the caller's own, RLS scoped) and LEFT JOINs the linked tenant opportunity (the composite FK
// (organization_id, opportunity_id)) and, through the opportunity's federal_ref cross source link, the
// global opportunity_records row that carries the naics. The agency is the requirement's customer_agency
// when non empty; the naics is the linked opportunity_records naics when the opportunity links one, else the
// empty string. Every joined table is in the read allowlist (requirements, opportunities,
// opportunity_records), and the joins are plain equi joins to allowlisted tables with scalar predicates, NO
// set returning function in a FROM or JOIN position, so the guard accepts it. coalesce and nullif keep the
// scan free of a mutating keyword (no set keyword appears), and the single row filter is the requirement id.
const requirementSegmentSQL = `
SELECT
    coalesce(nullif(btrim(r.customer_agency), ''), '') AS agency,
    coalesce(orec.naics, '')                           AS naics,
    r.required_level                                   AS required_level,
    coalesce(r.title, '')                              AS title,
    coalesce(r.work_location, '')                      AS work_location
FROM requirements r
LEFT JOIN opportunities o
       ON o.organization_id = r.organization_id
      AND o.id = r.opportunity_id
LEFT JOIN opportunity_records orec
       ON o.federal_ref IS NOT NULL
      AND o.federal_ref <> ''
      AND orec.source_record_id = o.federal_ref
WHERE r.id = $1
  AND r.deleted_at IS NULL
ORDER BY orec.naics ASC NULLS LAST
LIMIT 1`

// RequirementSegment is the resolved market segment of a requirement: the customer agency (the empty string
// when the requirement names none), the naics (the empty string when no linked opportunity carries one), the
// required clearance level, and whether the requirement was found under RLS. It carries no person data and no
// score.
type RequirementSegment struct {
	Agency        string `json:"agency"`
	NAICS         string `json:"naics"`
	RequiredLevel string `json:"required_level"`
	Title         string `json:"title"`
	WorkLocation  string `json:"work_location"`
	Found         bool   `json:"found"`
}

// AgencyBound reports whether the segment resolved a non empty agency (the agency keyed market reads can
// run). NAICSBound reports whether the segment resolved a non empty naics (the (agency, naics) keyed reads
// can run). SegmentBound reports whether either market arm can run at all (a non empty agency is the floor;
// without it the market leg states the honest floor and calls no market executor with empty args).
func (s RequirementSegment) AgencyBound() bool  { return s.Agency != "" }
func (s RequirementSegment) NAICSBound() bool   { return s.NAICS != "" }
func (s RequirementSegment) SegmentBound() bool { return s.AgencyBound() }

// resolveRequirementSegment resolves the market segment for one requirement under RLS (the app role sees only
// the caller's requirement through app.current_org_id). It runs the guarded resolver read inside
// RunInTenantTx and returns Found false when no row matches (a foreign or missing requirement), so the
// composition can state the honest floor rather than guessing a segment.
func resolveRequirementSegment(ctx context.Context, db *tenant.DB, requirementID string) (RequirementSegment, error) {
	if db == nil {
		return RequirementSegment{}, errors.New("ai: no database")
	}
	var seg RequirementSegment
	err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error {
		if err := GuardReadOnlyQuery(requirementSegmentSQL, ReadAllowlist); err != nil {
			return err
		}
		row := tx.QueryRow(ctx, requirementSegmentSQL, requirementID)
		var agency, naics, level, title, workLocation string
		if err := row.Scan(&agency, &naics, &level, &title, &workLocation); err != nil {
			if errors.Is(err, pgx.ErrNoRows) {
				return nil // not found under RLS: Found stays false, the honest floor
			}
			return err
		}
		seg = RequirementSegment{Agency: agency, NAICS: naics, RequiredLevel: level, Title: title, WorkLocation: workLocation, Found: true}
		return nil
	})
	return seg, err
}

// answerCapturePicture is the G6 composition: one integrated capture answer for a requirement, who on the
// caller's bench can structurally staff it (the SUPPRESSED bench legs), the public market context (the
// recompete clock and, when the segment binds a naics, the incumbent or competitor field), the gap, and the
// price to win honest floor. It mirrors answerBench: it requires an authenticated tenant context (refuses
// without one), surfaces every bench count only through RenderCount, narrates through o.generate and
// o.finalize, and emits a counts only audit. It computes NO match score: the bench legs report structural
// coverage counts, the market legs report public market structure, and the frozen engine stays the only
// scorer. The EEO and protected attribute guards run upstream in AnswerGraph, so this path can never group,
// filter, or rank by a protected attribute.
func (o *Orchestrator) answerCapturePicture(ctx context.Context, requirementID string) (*Response, error) {
	if _, ok := tenant.OrgFromContext(ctx); !ok {
		return o.refuse(ctx, RouteGraph, "a capture question requires an authenticated tenant context")
	}
	k := ConfiguredSuppressionThreshold()

	// Resolve the market segment (agency, naics, required level) under RLS.
	seg, err := resolveRequirementSegment(ctx, o.db, requirementID)
	if err != nil {
		return nil, err
	}

	// SUPPRESSED bench legs (person touching, RLS scoped, piped through Suppress by the executors). Every cell
	// renders through RenderCount, so a suppressed cell is the sentinel and never a raw sub k number.
	gapRows, err := BenchGapForRequirement(ctx, o.db, requirementID, k)
	if err != nil {
		return nil, err
	}
	covRows, err := BenchClearanceCoverage(ctx, o.db, k)
	if err != nil {
		return nil, err
	}
	benchCells := 0
	suppressed := 0

	benchFit := make([]string, 0, len(gapRows))
	for _, r := range gapRows {
		benchCells++
		if r.Cell.Suppressed {
			suppressed++
		}
		benchFit = append(benchFit, r.Bucket+"="+RenderCount(r.Cell))
	}
	clearanceFit := make([]string, 0, len(covRows))
	for _, r := range covRows {
		benchCells++
		if r.Cell.Suppressed {
			suppressed++
		}
		clearanceFit = append(clearanceFit, r.LevelCode+"="+RenderCount(r.Cell))
	}

	// PUBLIC market legs, run only when the segment binds. The agency keyed recompete clock runs whenever the
	// agency is non empty; the (agency, naics) keyed competitor field runs only when the naics also binds. When
	// the segment does not bind, the market leg states the honest floor and calls no executor with empty args.
	marketLines := make([]string, 0, 4)
	var clockRows []RecompeteClockRow
	var fieldRows []CompetitorRow
	if seg.SegmentBound() {
		clockRows, err = RecompeteClock(ctx, o.db, seg.Agency, DefaultRecompeteWindowMonths)
		if err != nil {
			return nil, err
		}
		marketLines = append(marketLines, captureRecompeteLine(seg.Agency, clockRows))
		if seg.NAICSBound() {
			fieldRows, err = SegmentCompetitorField(ctx, o.db, seg.Agency, seg.NAICS, DefaultCompetitorLookbackYears)
			if err != nil {
				return nil, err
			}
			marketLines = append(marketLines, captureIncumbentLine(seg.Agency, seg.NAICS, fieldRows))
		} else {
			marketLines = append(marketLines, "the competitor and incumbent field could not be bound: this requirement has no linked opportunity naics.")
		}
	} else {
		marketLines = append(marketLines, "the market segment could not be bound: this requirement names no customer agency and links no opportunity.")
	}

	// PRICE TO WIN leg (M5). Resolve the requirement's SOC from its title (the curated Galapagos crosswalk
	// first, then the broadened national OEWS occupation set so any ingested occupation can bind) and its
	// OEWS area from its work_location. When the SOC resolves, the leg prefers the specific STATE band (HI or
	// NM) when the requirement names that state AND a state wage row exists for the SOC; otherwise it FALLS
	// BACK to the US national band. So a requirement in a state with no state level data (for example Texas)
	// still gets the national band, labeled United States. Otherwise the leg keeps the honest floor exactly as
	// before; no rate is fabricated for an unresolved role or a missing wage row. The line is ADVISORY market
	// context, never a match score. priceResolved is a boolean only; NO dollar value goes into the audit.
	priceToWin := capturePriceToWinFloor
	priceResolved := false
	if soc, socOK := resolvePriceToWinSOC(ctx, o.db, seg.Title); socOK {
		band, bandOK, bandErr := resolveWageBandWithNationalFallback(ctx, o.db, soc, seg.WorkLocation)
		if bandErr != nil {
			return nil, bandErr
		}
		if bandOK {
			priceToWin = capturePriceToWinLine(band)
			priceResolved = true
		}
	}

	// Build the deterministic capture narrative and a small evidence object for the faithfulness gate. The
	// evidence carries the SUPPRESSED bench rendering (RenderCount only), the public market lines verbatim, and
	// the price to win leg (the real OEWS band when it resolved, else the honest floor); no raw sub k count is
	// present anywhere in it.
	deterministic := captureNarrative(seg, benchFit, clearanceFit, marketLines, priceToWin)
	evidenceObj := map[string]any{
		"bench_fit":      benchFit,
		"clearance_fit":  clearanceFit,
		"market_context": marketLines,
		"price_to_win":   priceToWin,
		"segment_bound":  seg.SegmentBound(),
	}
	rendered, _ := json.Marshal(evidenceObj)
	evidence := []string{string(rendered)}

	model, genErr := o.generate(ctx,
		"State the capture picture plainly from the evidence: the bench fit and clearance coverage, the market context, and the price to win leg. Report each bench headcount exactly as the rows give it. A headcount shown as "+SuppressionSentinel+" was withheld to protect individuals: say it was withheld and NEVER guess or state a number for it. Report the market lines and the price to win leg exactly as given and never invent an incumbent, an agency, a wage, a dollar figure, or a recompete the evidence does not contain. The price to win leg is an advisory OEWS labor rate or the honest floor; report it verbatim and never fabricate a rate. Never compute a match score and never assign a band.",
		"INTENT: capture picture for one requirement\n\nEVIDENCE:\n"+string(rendered))
	resp, aerr := o.finalize(ctx, RouteGraph, model, genErr, deterministic, evidence)
	if aerr != nil {
		return nil, aerr
	}

	// Counts only audit: the route, the intent, the bench cell count, the suppressed count, whether the segment
	// bound, whether the price to win leg resolved to a real OEWS band (a boolean only, NEVER the dollar
	// value), and k. It carries NO candidate id, NO raw sub k count, NO requirement id, NO dollar figure, and
	// NO answer text.
	if err := o.audit(ctx, "aedt.ai.capture_answered", map[string]any{
		"route":          RouteGraph,
		"intent":         IntentCapturePictureForRequirement,
		"bench_cells":    benchCells,
		"suppressed":     suppressed,
		"segment_bound":  seg.SegmentBound(),
		"price_resolved": priceResolved,
		"k":              k,
	}); err != nil {
		return nil, err
	}
	return resp, nil
}

// captureRecompeteLine renders the public recompete clock leg for the bound agency verbatim: the count of
// recompetes the capture team watches in the window and the nearest one by period of performance end, naming
// the agency. It is public market structure (no suppression) and carries no score. An empty clock states
// plainly that nothing falls in the window.
func captureRecompeteLine(agency string, rows []RecompeteClockRow) string {
	if len(rows) == 0 {
		return fmt.Sprintf("recompete clock for %s: no recompetes fall inside the %d month window.", agency, DefaultRecompeteWindowMonths)
	}
	first := rows[0]
	title := strings.TrimSpace(first.Title)
	if title == "" {
		title = first.RecordID
	}
	return fmt.Sprintf("recompete clock for %s: %d in the %d month window, nearest is %q (%s) ending %s.",
		agency, len(rows), DefaultRecompeteWindowMonths, title, first.SourceTable, first.PopEndDate)
}

// captureIncumbentLine renders the public competitor and incumbent field leg for the bound (agency, naics)
// segment verbatim: the recipient that leads the recency weighted dollar share (the incumbent of record by
// public award data) and how many recipients hold the segment. It is public market structure (no
// suppression) and carries no score; the dollar share is the executor's exact decimal, never recomputed. An
// empty field states plainly that no award structure exists in the segment.
func captureIncumbentLine(agency, naics string, rows []CompetitorRow) string {
	if len(rows) == 0 {
		return fmt.Sprintf("incumbent and competitor field for %s in naics %s: no award structure on record.", agency, naics)
	}
	lead := rows[0]
	name := strings.TrimSpace(lead.RecipientName)
	if name == "" {
		name = lead.RecipientUEI
	}
	return fmt.Sprintf("incumbent and competitor field for %s in naics %s: %d recipients on record, the leading share is held by %s at %s.",
		agency, naics, len(rows), name, lead.DollarShare.String())
}

// capturePriceToWinLine renders the M5 price to win leg from a resolved OEWS wage band verbatim: the
// advisory annual mean and annual median labor rate for the requirement's occupation in its place of
// performance (the STATE name for a state band, United States for the national band), labeled BLS OEWS and
// advisory. It is public market structure (advisory labor rate context), NOT a match score and NOT an
// employment decision number; the two dollar figures are the band's exact decimals rendered to cents, never
// recomputed and never float. It carries no dash in surfaced prose. The occupation label is the Galapagos
// role when the band carries one (the HI and NM state rows), else the OEWS occupation title (the national
// rows carry an empty role), so a national band still names its occupation honestly.
func capturePriceToWinLine(band WageBand) string {
	label := strings.TrimSpace(band.Role)
	if label == "" {
		label = strings.TrimSpace(band.OccupationTitle)
	}
	return fmt.Sprintf("OEWS labor rate for %s in %s: annual mean $%s, annual median $%s (BLS OEWS, advisory).",
		label, band.AreaName, band.AnnualMean.StringFixed(2), band.AnnualMedian.StringFixed(2))
}

// captureNarrative composes the deterministic capture picture from the suppressed bench legs, the public
// market lines, and the price to win leg (a resolved OEWS wage band or the honest floor), in a byte stable
// order. It is the faithful answer the composition ships when the model prose is withheld; every bench count
// it contains already came through RenderCount, so the deterministic fallback is itself suppression safe. It
// names no candidate and computes no score.
func captureNarrative(seg RequirementSegment, benchFit, clearanceFit, marketLines []string, priceToWin string) string {
	var b strings.Builder
	b.WriteString("Capture picture for the requirement. ")

	b.WriteString("Bench fit (structural coverage, not a match score): ")
	if len(benchFit) > 0 {
		b.WriteString(strings.Join(benchFit, " "))
	} else {
		b.WriteString("no bench partition.")
	}
	b.WriteString(". ")

	b.WriteString("Clearance coverage of the bench: ")
	if len(clearanceFit) > 0 {
		b.WriteString(strings.Join(clearanceFit, " "))
	} else {
		b.WriteString("no clearance partition.")
	}
	b.WriteString(". ")

	b.WriteString("Market context: ")
	if len(marketLines) > 0 {
		b.WriteString(strings.Join(marketLines, " "))
	} else {
		b.WriteString("none.")
	}
	b.WriteString(" ")

	b.WriteString("Price to win: " + priceToWin + ".")
	return b.String()
}