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

1package ai 2 3import ( 4 "encoding/json" 5 "errors" 6 "net/http" 7 "strings" 8 9 "github.com/go-chi/chi/v5" 10 11 "github.com/missionworkforce/missionmatch/internal/platform/inference" 12 "github.com/missionworkforce/missionmatch/internal/platform/security" 13 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 14) 15 16// Handler mounts the AI brain under the tenant scoped group, behind the session resolver, CSRF, RBAC, rate 17// limit, and audit (the same chain as every other module). It exposes one endpoint that routes a natural 18// language question across the augmented generation strategies and returns an explainable, faithfulness 19// gated, tenant isolated answer. The deterministic engine remains the floor; the brain narrates, it never 20// scores. 21type Handler struct { 22 orch *Orchestrator 23 gate *VectorGate // optional enforced re embed gate; nil means open (no vector store to verify) 24} 25 26// NewHandler builds the handler. orch may be nil (the brain is then reported unavailable rather than 27// panicking, the graceful posture when the inference plane is unconfigured). 28func NewHandler(orch *Orchestrator) *Handler { return &Handler{orch: orch} } 29 30// WithVectorGate attaches the enforced re embed gate. When set, /ai/query refuses to serve until the 31// gate confirms the stored vectors were produced by the configured embed model, so a half re embedded or 32// wrong model store cannot silently mis rank a retrieval. 33func (h *Handler) WithVectorGate(g *VectorGate) *Handler { h.gate = g; return h } 34 35// Routes mounts the brain endpoint gated on the brain.query capability (the same tier as search.run). 36func (h *Handler) Routes(r chi.Router) { 37 r.With(security.RequireCapability(security.CapBrainQuery)).Post("/ai/query", h.query) 38} 39 40// PublicRoutes mounts the unauthenticated federation read, GET or POST /mm-recall. It is deliberately NOT 41// behind the session resolver or CSRF: it takes no cookie, touches no database, no tenant, and no 42// orchestrator, and can only ever return the static, public, contents free knowledge base (the curated CAG 43// cards, each already cited and demographic free). There is nothing to protect and nothing to forge. It is 44// the World to missionMATCH federation edge: the world brain retrieves relevance ranked public knowledge, 45// and the caller's own relevance gate decides what to keep. A protected attribute query returns no cards. 46func (h *Handler) PublicRoutes(r chi.Router) { 47 r.Get("/mm-recall", h.mmRecall) 48 r.Post("/mm-recall", h.mmRecall) 49} 50 51// MMRecallResponse is the public federation read result: relevance ranked PUBLIC knowledge cards and 52// nothing else. No tenant data, no candidate data, no demographic field ever appears here. 53type MMRecallResponse struct { 54 Results []MMRecallItem `json:"results"` 55 Count int `json:"count"` 56} 57 58// MMRecallItem is one public knowledge card rendered for federation: the taught content with its cited 59// source. The text field name matches what a federated caller reads. 60type MMRecallItem struct { 61 Text string `json:"text"` 62 Topic string `json:"topic"` 63 Source string `json:"source"` 64} 65 66func (h *Handler) mmRecall(w http.ResponseWriter, r *http.Request) { 67 q := strings.TrimSpace(r.URL.Query().Get("q")) 68 k := 4 69 if r.Method == http.MethodPost { 70 var in struct { 71 Query string `json:"query"` 72 Q string `json:"q"` 73 Question string `json:"question"` 74 K int `json:"k"` 75 } 76 dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<16)) 77 if err := dec.Decode(&in); err == nil { 78 for _, s := range []string{in.Query, in.Q, in.Question} { 79 if t := strings.TrimSpace(s); t != "" { 80 q = t 81 break 82 } 83 } 84 if in.K > 0 { 85 k = in.K 86 } 87 } 88 } 89 if k < 1 || k > 8 { 90 k = 4 91 } 92 // Defense in depth: the knowledge base holds no demographic data, but a protected attribute or eeo 93 // question still returns nothing, so this edge can never be turned into a probe for one. The guard runs 94 // on the FULL query, before any truncation, so a protected word pushed past the length cap can never be 95 // scrubbed from the guard's view while still triggering a card. 96 lq := strings.ToLower(q) 97 if q == "" || MentionsProtectedAttribute(lq) || ForbidEEO(lq) != nil { 98 writeJSON(w, http.StatusOK, MMRecallResponse{Results: []MMRecallItem{}, Count: 0}) 99 return 100 } 101 sq := q 102 if len(sq) > 400 { 103 sq = sq[:400] 104 } 105 cards := SelectKnowledge(sq, k) 106 items := make([]MMRecallItem, 0, len(cards)) 107 for _, c := range cards { 108 items = append(items, MMRecallItem{Text: c.Content + " (source: " + c.Source + ")", Topic: c.Topic, Source: c.Source}) 109 } 110 writeJSON(w, http.StatusOK, MMRecallResponse{Results: items, Count: len(items)}) 111} 112 113// QueryRequest is the brain query. A free form question routes across CAG, RAG, and a refusal; an explicit 114// intent runs the curated, parameterized, read only TAG path over the database of record. The brain never 115// authors free form SQL. 116type QueryRequest struct { 117 Question string `json:"question"` 118 Intent string `json:"intent,omitempty"` 119 Args []any `json:"args,omitempty"` 120} 121 122// AnswerResponse is the brain's answer plus its provenance: which augmented path served it, whether the 123// prose was confirmed faithful or fell back to the deterministic rendering, and the evidence it was 124// grounded on. A faithfulness fallback is a normal 200 with rationale_source deterministic. 125type AnswerResponse struct { 126 Answer string `json:"answer"` 127 Path string `json:"path"` // cag | tag | rag | graph 128 RationaleSource string `json:"rationale_source"` 129 Citations []string `json:"citations"` 130 Faithful bool `json:"faithful"` 131 EvidenceCount int `json:"evidence_count"` 132 FallbackReason string `json:"fallback_reason,omitempty"` 133} 134 135func (h *Handler) query(w http.ResponseWriter, r *http.Request) { 136 if h.orch == nil { 137 writeErr(w, http.StatusServiceUnavailable, "brain_unavailable", "the brain is not configured") 138 return 139 } 140 // The enforced re embed gate: refuse to serve a query over a vector store that does not match the 141 // configured embed model, before any work, so a wrong model store never silently mis ranks. 142 if h.gate != nil { 143 if err := h.gate.Check(r.Context()); err != nil { 144 mapErr(w, err) 145 return 146 } 147 } 148 var in QueryRequest 149 dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) 150 dec.DisallowUnknownFields() 151 if err := dec.Decode(&in); err != nil { 152 writeErr(w, http.StatusBadRequest, "bad_request", "invalid request body") 153 return 154 } 155 if strings.TrimSpace(in.Question) == "" && strings.TrimSpace(in.Intent) == "" { 156 writeErr(w, http.StatusUnprocessableEntity, "validation", "a question or an intent is required") 157 return 158 } 159 160 resp, err := h.orch.Answer(r.Context(), in.Question, in.Intent, in.Args) 161 if err != nil { 162 mapErr(w, err) 163 return 164 } 165 if resp.Refused { 166 // An unanswerable, unsafe, or out of allowlist question is a typed 4xx, never a raw error. 167 writeErr(w, http.StatusUnprocessableEntity, "refused", resp.RefusalReason) 168 return 169 } 170 writeJSON(w, http.StatusOK, AnswerResponse{ 171 Answer: resp.Answer, 172 Path: pathOf(resp.Route), 173 RationaleSource: resp.RationaleSource, 174 Citations: resp.Citations, 175 Faithful: resp.Faithful, 176 EvidenceCount: resp.EvidenceCount, 177 FallbackReason: resp.FallbackReason, 178 }) 179} 180 181// pathOf maps the internal route to the augmented path name the caller sees. 182func pathOf(route Route) string { 183 switch route { 184 case RouteTAG: 185 return "tag" 186 case RouteRAG: 187 return "rag" 188 case RouteGraph: 189 return "graph" 190 default: 191 return "cag" 192 } 193} 194 195// mapErr maps a brain error to the typed envelope. It NEVER returns a raw SQL or database error string. 196func mapErr(w http.ResponseWriter, err error) { 197 switch { 198 case errors.Is(err, ErrNoModel): 199 writeErr(w, http.StatusServiceUnavailable, "brain_unavailable", "the inference plane is not configured") 200 case errors.Is(err, ErrVectorModelMismatch): 201 writeErr(w, http.StatusServiceUnavailable, "vector_model_mismatch", "the stored vectors do not match the configured embed model; the brain is disabled until the store is re embedded") 202 case errors.Is(err, inference.ErrCircuitOpen), errors.Is(err, inference.ErrPlaneUnavailable): 203 writeErr(w, http.StatusServiceUnavailable, "plane_unavailable", "the inference plane is temporarily unavailable") 204 case errors.Is(err, ErrAuditFailed): 205 // The brain could answer, but the AEDT record of that answer could not be written, so the answer is 206 // not served. It is a 503 and not a 4xx because the caller's request was fine: this is the platform 207 // declining to make an automated employment decision it cannot account for, and a retry once the 208 // audit path recovers is the correct client behaviour. 209 writeErr(w, http.StatusServiceUnavailable, "audit_unavailable", "the decision could not be recorded, so it was not served") 210 case errors.Is(err, ErrUnknownIntent): 211 writeErr(w, http.StatusUnprocessableEntity, "unknown_intent", "no such query intent") 212 case errors.Is(err, ErrEEOForbidden): 213 writeErr(w, http.StatusUnprocessableEntity, "refused", "the question references prohibited demographic data") 214 case errors.Is(err, tenant.ErrNoTenant): 215 writeErr(w, http.StatusForbidden, "no_tenant", "no validated tenant") 216 default: 217 // Any other failure (a bad intent argument, a database error) is reported generically so no raw SQL 218 // or internal detail leaks to the caller. 219 writeErr(w, http.StatusBadRequest, "brain_error", "the brain could not answer the question") 220 } 221} 222 223type errorBody struct { 224 Error errorEnvelope `json:"error"` 225} 226 227type errorEnvelope struct { 228 Code string `json:"code"` 229 Message string `json:"message"` 230} 231 232func writeErr(w http.ResponseWriter, status int, code, msg string) { 233 writeJSON(w, status, errorBody{errorEnvelope{Code: code, Message: msg}}) 234} 235 236func writeJSON(w http.ResponseWriter, status int, v any) { 237 w.Header().Set("Content-Type", "application/json") 238 w.WriteHeader(status) 239 _ = json.NewEncoder(w).Encode(v) 240} 241