Janady13/missionmatch / internal/modules/opportunities/normalize.go

1package opportunities 2 3import ( 4 "crypto/sha256" 5 "encoding/hex" 6 "encoding/json" 7 "fmt" 8 "strings" 9 "unicode" 10) 11 12// Model normalization, directive Section 5.2. The model proposes scope items; this file decides which of 13// them are allowed to exist. It is a PURE function of the model payload and the source text, with no 14// database and no I/O, so the grounding rules can be exhaustively tested without a model or a tenant. 15// 16// The rule that matters most is the third one below. A model that omits a citation is merely unhelpful; a 17// model that INVENTS a citation is dangerous, because fabricated support reads exactly like real support to 18// every reader downstream. So a quote is checked for actual presence in the source text, and an item whose 19// quote cannot be found is rejected as fabricated rather than accepted with a warning. 20 21// scopeTypes is the closed vocabulary from migration 0076. A model that invents a category is refused 22// rather than being folded into "other", because silently recategorizing model output loses the fact that 23// the model did not understand the ask. 24var scopeTypes = map[string]bool{ 25 "objective": true, "task": true, "deliverable": true, "labor_category": true, 26 "staffing_quantity": true, "skill": true, "certification": true, "clearance": true, 27 "customer_experience": true, "location": true, "travel": true, "schedule": true, 28 "security_control": true, "reporting": true, "transition": true, "key_personnel": true, 29 "pricing_instruction": true, "evaluation_factor": true, "compliance_clause": true, 30 "assumption": true, "dependency": true, "risk": true, "other": true, 31} 32 33const ( 34 maxScopeTitleLen = 300 35 maxScopeDescLen = 4000 36 minQuoteLen = 12 // a quote shorter than this cannot ground anything; it matches by accident 37) 38 39// ScopeCandidate is one item as the MODEL proposed it, before any validation. 40type ScopeCandidate struct { 41 ScopeType string `json:"scope_type"` 42 Title string `json:"title"` 43 Description string `json:"description"` 44 Quote string `json:"quote"` 45 SectionLabel string `json:"section_label"` 46 Confidence float64 `json:"confidence"` 47} 48 49// ValidatedScope is a candidate that survived every grounding rule, carrying the hash of the exact quote 50// that grounds it. That hash is what the scope item stores as its citation. 51type ValidatedScope struct { 52 ScopeType string 53 Title string 54 Description string 55 Quote string 56 QuoteHash string 57 SectionLabel string 58 Confidence float64 59} 60 61// RejectedScope records what was refused and why, so a normalization run can report its own precision 62// instead of silently dropping most of what the model said. 63type RejectedScope struct { 64 Title string 65 Reason string 66} 67 68// ValidateScopeCandidates parses a model response and returns only the items that are grounded in the 69// source text. It fails closed: an unparseable payload is an error and yields nothing, and every individual 70// rule rejects the item rather than repairing it. 71func ValidateScopeCandidates(raw []byte, sourceText string) ([]ValidatedScope, []RejectedScope, error) { 72 var payload struct { 73 Items []ScopeCandidate `json:"items"` 74 } 75 trimmed := extractJSONObject(raw) 76 if trimmed == nil { 77 return nil, nil, fmt.Errorf("%w: model response is not a JSON object", ErrInvalidInput) 78 } 79 if err := json.Unmarshal(trimmed, &payload); err != nil { 80 return nil, nil, fmt.Errorf("%w: model response did not match the declared schema: %v", ErrInvalidInput, err) 81 } 82 83 // Normalizing whitespace on both sides makes containment robust to the line wrapping a model reproduces 84 // differently from the source, without loosening the check into a fuzzy match. 85 haystack := normalizeWS(sourceText) 86 87 accepted := make([]ValidatedScope, 0, len(payload.Items)) 88 rejected := make([]RejectedScope, 0) 89 for _, c := range payload.Items { 90 title := strings.TrimSpace(c.Title) 91 quote := strings.TrimSpace(c.Quote) 92 switch { 93 case !scopeTypes[c.ScopeType]: 94 rejected = append(rejected, RejectedScope{title, fmt.Sprintf("scope_type %q is not in the closed vocabulary", clipStr(c.ScopeType, 40))}) 95 case title == "": 96 rejected = append(rejected, RejectedScope{title, "title is empty"}) 97 case len(title) > maxScopeTitleLen: 98 rejected = append(rejected, RejectedScope{title, "title exceeds the length cap"}) 99 case len(c.Description) > maxScopeDescLen: 100 rejected = append(rejected, RejectedScope{title, "description exceeds the length cap"}) 101 case len(quote) < minQuoteLen: 102 rejected = append(rejected, RejectedScope{title, "uncited, the item carries no usable source quote"}) 103 case haystack == "" || !strings.Contains(haystack, normalizeWS(quote)): 104 // A fabricated citation. This is the load bearing check. 105 rejected = append(rejected, RejectedScope{title, "the cited quote was not found in the source text, treating it as a fabricated citation"}) 106 case c.Confidence < 0 || c.Confidence > 1: 107 rejected = append(rejected, RejectedScope{title, "confidence is outside 0 to 1"}) 108 default: 109 sum := sha256.Sum256([]byte(normalizeWS(quote))) 110 accepted = append(accepted, ValidatedScope{ 111 ScopeType: c.ScopeType, 112 Title: title, 113 Description: strings.TrimSpace(c.Description), 114 Quote: quote, 115 QuoteHash: hex.EncodeToString(sum[:]), 116 SectionLabel: clipStr(strings.TrimSpace(c.SectionLabel), 120), 117 Confidence: c.Confidence, 118 }) 119 } 120 } 121 return accepted, rejected, nil 122} 123 124// extractJSONObject finds the outermost JSON object in a model response. Instruct models routinely wrap 125// JSON in prose or a fenced code block, and refusing those outright would reject correct output for a 126// formatting habit; anything that is not a locatable object still fails closed. 127func extractJSONObject(raw []byte) []byte { 128 s := strings.TrimSpace(string(raw)) 129 start := strings.Index(s, "{") 130 end := strings.LastIndex(s, "}") 131 if start < 0 || end <= start { 132 return nil 133 } 134 return []byte(s[start : end+1]) 135} 136 137// normalizeWS collapses every run of whitespace to one space and lowercases, so a quote matches the source 138// despite reflowed lines or a changed case, while still requiring the actual words in the actual order. 139func normalizeWS(s string) string { 140 var b strings.Builder 141 b.Grow(len(s)) 142 space := false 143 for _, r := range strings.ToLower(s) { 144 if unicode.IsSpace(r) { 145 space = true 146 continue 147 } 148 if space && b.Len() > 0 { 149 b.WriteByte(' ') 150 } 151 space = false 152 b.WriteRune(r) 153 } 154 return b.String() 155} 156 157func clipStr(s string, n int) string { 158 if len(s) > n { 159 return s[:n] 160 } 161 return s 162} 163