feat(ai-sdk): Advisor Reasoning Stack — Clarity+G1+Concept-Injector+Context-Scope+Term-Resolution+E4-Curation+Intent-Signal

ai-compliance-sdk/internal/api/handlers/rag_handlers.go

@@ -1,6 +1,9 @@
 package handlers
 
 import (
+	"encoding/json"
+	"fmt"
+	"log"
 	"net/http"
 	"strconv"
 
@@ -87,6 +90,7 @@ func (h *RAGHandlers) Search(c *gin.Context) {
 type RetrieveRequest struct {
 	Query string `json:"query" binding:"required"`
 	TopK  int    `json:"top_k,omitempty"`
+	Context string `json:"context,omitempty"`
 }
 
 // Retrieve is the Authority Router endpoint. The Advisor calls this with ONLY a query and stays
@@ -105,6 +109,13 @@ func (h *RAGHandlers) Retrieve(c *gin.Context) {
 		req.TopK = 8
 	}
 
+	// E2 Term Resolution: expand unambiguous abbreviations (TOM/VVT/AVV/DSB/DSFA) into the
+	// query so retrieval finds them; ambiguous ones (DSE/DPA) are surfaced to the FE — NOT
+	// auto-mapped (chat context E1 wins, else the FE asks).
+	intent := ucca.DetectIntent(req.Query)
+	termRes := ucca.ResolveAbbreviations(req.Query)
+	req.Query = termRes.Expanded
+
 	results, err := h.ragClient.Retrieve(c.Request.Context(), req.Query, req.TopK)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "RAG retrieve failed: " + err.Error()})
@@ -114,7 +125,42 @@ func (h *RAGHandlers) Retrieve(c *gin.Context) {
 	// Evidence-Type-Schicht: die autoritative typisierte Evidence (Fußnoten/Tabellen/Figuren) aus
 	// dem KB-Wissensraum SEPARAT surfacen, statt sie im Breit-Basis-Text-Merge zu verlieren.
 	// results[] bleibt der Text-Kontext fürs LLM + die Quellen-Liste.
+	// Context scoping (E5): the user explicitly chose a knowledge space (chip), so scope
+	// the evidence HARD to it (wider re-retrieve + domain filter) — no off-domain regelwerke
+	// (MDR/UStG/eIDAS) after a context decision.
+	if req.Context != "" {
+		if wide, werr := h.ragClient.Retrieve(c.Request.Context(), req.Query, 30); werr == nil && len(wide) > 0 {
+			results = ucca.FilterByKnowledgeSpace(wide, req.Context, req.TopK)
+		} else {
+			results = ucca.FilterByKnowledgeSpace(results, req.Context, req.TopK)
+		}
+	}
+
+	// G1 scope-gating: a named regulation scopes the evidence to its knowledge space.
+	// Re-retrieve wider and lead with the named regulation's domain so the L2 answer +
+	// [n] citations are built on scoped evidence, not the embedding-majority domain.
+	if scope := ucca.QueryKnowledgeSpace(req.Query); scope != "" {
+		if wide, werr := h.ragClient.Retrieve(c.Request.Context(), req.Query, 30); werr == nil && len(wide) > 0 {
+			results = ucca.ScopeResults(wide, scope, req.TopK)
+		} else {
+			results = ucca.ScopeResults(results, scope, req.TopK)
+		}
+	}
+
 	ev := h.ragClient.RetrieveEvidence(c.Request.Context(), req.Query)
+	// Concept->Norm recall injector: if the query names a legal concept, fetch its
+	// load-bearing norms (Datenschutzerklärung -> Art. 12/13/14 DSGVO, ...) and inject
+	// them into the evidence set so they surface (embedding similarity misses them).
+	if norms := ucca.ConceptNorms(req.Query); len(norms) > 0 {
+		top := 0.9
+		if len(results) > 0 {
+			top = results[0].Score
+		}
+		injected := h.ragClient.FetchByNormIDs(c.Request.Context(), norms, top-0.001)
+		results = ucca.InjectConceptNorms(results, injected, req.TopK)
+	}
+	clarity := ucca.ClassifyClarity(req.Query, results)
+	traceClarity(req.Query, clarity, results)
 
 	c.JSON(http.StatusOK, gin.H{
 		"query":      req.Query,
@@ -123,7 +169,11 @@ func (h *RAGHandlers) Retrieve(c *gin.Context) {
 		"assessment": ucca.Assess(results),
 		"footnotes":  footnotesFromEvidence(ev[ucca.EvidenceFootnote]),
 		"tables":     tablesFromEvidence(ev[ucca.EvidenceTable]),
-		"figures":    figuresFromEvidence(ev[ucca.EvidenceFigure]),
+		"evidence":        evidenceFromResults(results),
+		"visual_evidence": visualEvidenceFromEvidence(ev[ucca.EvidenceFigure]),
+		"clarity":   clarity,
+		"term_resolution": termRes.Ambiguous,
+		"interaction_intent": intent,
 	})
 }
 
@@ -163,23 +213,67 @@ func tablesFromEvidence(rs []ucca.LegalSearchResult) []gin.H {
 	return out
 }
 
-// figuresFromEvidence maps FIGURE evidence (C8). Empty until C8 populates figure units; image_url/
-// caption/vision_summary get added here when C8 lands — same path, no router change.
-func figuresFromEvidence(rs []ucca.LegalSearchResult) []gin.H {
+// visualEvidenceFromEvidence maps FIGURE evidence to the Visual Evidence contract shape
+// (C8). visual_type/image_ref/vision_summary populate once C8 lands; the shape is stable now.
+func visualEvidenceFromEvidence(rs []ucca.LegalSearchResult) []gin.H {
 	out := make([]gin.H, 0, len(rs))
 	for _, r := range rs {
 		out = append(out, gin.H{
-			"figure_id":        r.CitationUnit,
-			"caption":          r.ArticleLabel,
-			"regulation_code":  r.RegulationCode,
-			"regulation_short": r.RegulationShort,
-			"regulation_name":  r.RegulationName,
-			"section":          r.RefCitationUnit,
+			"visual_id":       r.CitationUnit,
+			"visual_type":     "figure",
+			"caption":         r.ArticleLabel,
+			"document":        evidenceDocName(r),
+			"context":         ucca.KnowledgeSpaceOf(r.RegulationCode),
+			"regulation_code": r.RegulationCode,
+			"section":         r.RefCitationUnit,
+			"image_ref":       "",
+			"vision_summary":  "",
 		})
 	}
 	return out
 }
 
+// evidenceFromResults maps retrieval hits to the Evidence contract shape the Advisor
+// Evidence Workspace renders (citations[] reference evidence_id). Populated at retrieve
+// time; citations[] (the [n]<->evidence coupling) come from the answer-generation step.
+func evidenceFromResults(rs []ucca.LegalSearchResult) []gin.H {
+	out := make([]gin.H, 0, len(rs))
+	for _, r := range rs {
+		id := r.CitationUnit
+		if id == "" {
+			id = r.ArticleLabel
+		}
+		out = append(out, gin.H{
+			"evidence_id":     id,
+			"document":        evidenceDocName(r),
+			"section":         r.ArticleLabel,
+			"paragraph":       r.Paragraph,
+			"snippet":         evidenceSnippet(r.Text, 280),
+			"url":             r.SourceURL,
+			"regulation_code": r.RegulationCode,
+			"context":         ucca.KnowledgeSpaceOf(r.RegulationCode),
+		})
+	}
+	return out
+}
+
+// evidenceDocName is the human-facing source name (short code, else full name).
+func evidenceDocName(r ucca.LegalSearchResult) string {
+	if r.RegulationShort != "" {
+		return r.RegulationShort
+	}
+	return r.RegulationName
+}
+
+// evidenceSnippet returns a trimmed excerpt of at most n runes.
+func evidenceSnippet(s string, n int) string {
+	rs := []rune(s)
+	if len(rs) <= n {
+		return s
+	}
+	return string(rs[:n]) + "…"
+}
+
 // ListRegulations returns the list of available regulations in the corpus.
 // GET /sdk/v1/rag/regulations
 func (h *RAGHandlers) ListRegulations(c *gin.Context) {
@@ -334,3 +428,29 @@ func (h *RAGHandlers) LegalCorpusStructure(c *gin.Context) {
 		},
 	})
 }
+
+// traceClarity emits a structured CLARITY_TRACE log line per retrieve for the macmini
+// test session, so qualitative user ratings can be correlated with the gate decision.
+func traceClarity(query string, cl ucca.Clarity, results []ucca.LegalSearchResult) {
+	top := make([]string, 0, 3)
+	for i, r := range results {
+		if i >= 3 {
+			break
+		}
+		top = append(top, r.RegulationShort)
+	}
+	chips := make([]string, 0, len(cl.CandidateContexts))
+	for _, c := range cl.CandidateContexts {
+		chips = append(chips, fmt.Sprintf("%s:%d", c.ID, c.Hits))
+	}
+	b, _ := json.Marshal(map[string]interface{}{
+		"query":         query,
+		"mode":          cl.Mode,
+		"reason":        cl.Reason,
+		"concentration": cl.Concentration,
+		"dominant":      cl.DominantContext,
+		"chips":         chips,
+		"top_evidence":  top,
+	})
+	log.Printf("CLARITY_TRACE %s", string(b))
+}