Janady13/missionmatch / internal/modules/staffing/narrate.go

Source identity

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

Original source ↗

Every recorded occurrence

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

Recovered source transcript

Download complete source text ↓116 lines · 4.8 KB

package staffing

import (
	"context"
	"errors"
	"fmt"
	"strings"

	"github.com/missionworkforce/missionmatch/internal/modules/ai"
	"github.com/missionworkforce/missionmatch/internal/platform/inference"
)

// narrate produces the natural language rationale for one recommendation and records its source. It is
// the ONLY place a model is used, and the recommendation never depends on it: the model writes prose
// grounded strictly in the deterministic evidence, the faithfulness gate confirms the prose asserts
// nothing the evidence does not support, and any failure (no plane, circuit open, timeout, or an
// unconfirmed answer) falls back to a deterministic template assembled from the same facts. The fallback
// reason is recorded in the evidence (never in an audit payload) for later narration tuning.
//
// No candidate name, email, or any demographic field is ever sent to the plane; the facts are the action,
// the engine score and band, skill names, requirement ids, and the computed counterfactual numbers. Every
// string is passed through ai.ForbidEEO before it leaves the process.
func (s *Service) narrate(ctx context.Context, action Action, ev Evidence) (rationale string, source RationaleSource, fallbackReason string) {
	facts := evidenceStatements(action, ev)
	deterministic := strings.Join(facts, " ")
	if deterministic == "" {
		deterministic = "Recommended by the deterministic engine."
	}

	if s.infer == nil {
		return deterministic, RationaleDeterministic, "generation_disabled"
	}

	system := "You write a one or two sentence staffing rationale for a government contractor. Use ONLY the facts provided, assert nothing not present in them, never mention demographics, and never invent a number."
	prompt := "Facts:\n" + strings.Join(facts, "\n") + "\nWrite the rationale for the " + string(action) + " recommendation."
	for _, str := range append([]string{system, prompt}, facts...) {
		if err := ai.ForbidEEO(str); err != nil {
			return deterministic, RationaleDeterministic, "eeo_guard"
		}
	}

	gen, err := s.infer.Generate(ctx, inference.GenerateRequest{System: system, Prompt: prompt, MaxTokens: 120, Temperature: 0})
	if err != nil {
		return deterministic, RationaleDeterministic, fallbackReason2(err)
	}
	answer := strings.TrimSpace(gen.Text)
	if answer == "" {
		return deterministic, RationaleDeterministic, "empty_generation"
	}
	// Defense in depth: if the model echoed an eeo reference, refuse the prose.
	if ai.ForbidEEO(answer) != nil {
		return deterministic, RationaleDeterministic, "eeo_guard"
	}
	fr, err := s.infer.CheckFaithfulness(ctx, answer, facts)
	if err != nil {
		return deterministic, RationaleDeterministic, fallbackReason2(err)
	}
	if !fr.Supported {
		return deterministic, RationaleDeterministic, "could_not_confirm"
	}
	return answer, RationaleAIFaithful, ""
}

// evidenceStatements renders the deterministic facts a rationale may assert, from the structured evidence.
// These are also the evidence array the faithfulness gate checks the generated prose against.
func evidenceStatements(action Action, ev Evidence) []string {
	var out []string
	if ev.EngineTotal != "" {
		band := ev.Band
		if band == "" {
			band = "n/a"
		}
		out = append(out, "Engine total score is "+ev.EngineTotal+" out of 100, band "+band+".")
	}
	switch action {
	case ActionAssign:
		out = append(out, "The candidate is available and clears the staffing floor.")
	case ActionReassign:
		if ev.Reassign != nil {
			out = append(out, "The candidate is committed to requirement "+ev.Reassign.FromRequirementID+"; the target gap is higher priority by "+ev.Reassign.PriorityDelta.String()+".")
		}
	case ActionReskill:
		if ev.Reskill != nil {
			out = append(out, "The candidate holds "+ev.Reskill.HeldSkill+", adjacent to the missing required skill "+ev.Reskill.MissingSkill+" at cosine distance "+ev.Reskill.Distance.String()+".")
		}
	case ActionSource:
		if ev.OpenSlots != nil {
			out = append(out, fmt.Sprintf("No qualified, available bench candidate exists for %d open slot(s); external sourcing is required.", *ev.OpenSlots))
		}
	}
	if cf := ev.Counterfactual; cf != nil {
		out = append(out, "The assigned candidate's engine total for this requirement is "+cf.AssignedTotal+".")
		if cf.CandidateNextRequirement != "" {
			out = append(out, "Their next best alternative is requirement "+cf.CandidateNextRequirement+".")
		}
		if cf.RequirementNextCandidate != "" {
			out = append(out, "If reassigned, this requirement's next best candidate is "+cf.RequirementNextCandidate+".")
		}
	}
	if ev.Trigger != nil {
		out = append(out, "This alert was raised by a "+ev.Trigger.Kind+" change.")
	}
	return out
}

func fallbackReason2(err error) string {
	switch {
	case errors.Is(err, inference.ErrCircuitOpen):
		return "circuit_open"
	case errors.Is(err, context.DeadlineExceeded):
		return "plane_timeout"
	default:
		return "plane_error"
	}
}