feat(pii): observability for NER detections — backend trace, confidence, debug logs

There was no way to see what the NER detector actually produced, so a
false-positive block (e.g. a phone number scored as SSN) was opaque. Add three
views, all from data the TokenClassify gRPC already returns (no backend rebuild):

  - Backend trace: ModelTokenClassify now records a BackendTraceTokenClassify
    row (gated on tracing) with the input preview, threshold, and every entity's
    group, byte range, confidence and matched text. Wires up the long-standing
    TODO; shows in the Traces UI alongside the request it gated.
  - Confidence in the audit log: carry the detector score through
    rawHit -> Span -> PIIEvent, exposed as `score` on /api/pii/events. Metadata
    only — the event still stores a hash, never the value.
  - Per-detection DEBUG logs in the redactor: one line per raw hit with group,
    range, score, matched text and the policy decision (accepted / dropped
    below min_score / no action for group), so the masking/blocking rationale is
    visible in the backend logs.

Also drop a redundant same-type assertion in ModelTokenClassify (Load already
returns grpc.Backend) and give TokenEntity json tags for clean trace rendering.

Assisted-by: claude-code:claude-opus-4-8 [Claude Code]

Author: richiejp

core/backend/token_classify.go

@@ -2,10 +2,10 @@ package backend
 
 import (
 	"context"
-	"fmt"
+	"time"
 
 	"github.com/mudler/LocalAI/core/config"
-	"github.com/mudler/LocalAI/pkg/grpc"
+	"github.com/mudler/LocalAI/core/trace"
 	pb "github.com/mudler/LocalAI/pkg/grpc/proto"
 	model "github.com/mudler/LocalAI/pkg/model"
 )
@@ -16,11 +16,11 @@ import (
 // half-open (addressing text[Start:End]) — the proto contract. Group is
 // the model's entity label (e.g. "private_person", "EMAIL").
 type TokenEntity struct {
-	Group string
-	Start int
-	End   int
-	Score float32
-	Text  string
+	Group string  `json:"group"`
+	Start int     `json:"start"`
+	End   int     `json:"end"`
+	Score float32 `json:"score"`
+	Text  string  `json:"text"`
 }
 
 // TokenClassifyOptions controls a single TokenClassify request.
@@ -68,32 +68,64 @@ func (m *modelTokenClassifier) TokenClassify(ctx context.Context, text string) (
 // bound to the loaded model so a caller can reuse it within a request
 // without re-resolving the backend.
 //
-// NOTE: unlike ModelScore this does not yet emit a Traces UI row — wire
-// a trace.BackendTrace (new trace type) here if/when NER calls should
-// show up alongside the requests they gate.
+// When tracing is enabled it records a BackendTraceTokenClassify row so the
+// detector's output — every entity's group, byte range, confidence and the
+// matched substring — shows in the Traces UI alongside the request it gated.
+// This is the technical view for debugging false positives (e.g. a phone
+// number scored as SSN); the persisted PIIEvent keeps only a hash.
 func ModelTokenClassify(text string, opts TokenClassifyOptions, loader *model.ModelLoader, modelConfig config.ModelConfig, appConfig *config.ApplicationConfig) (func(ctx context.Context) ([]TokenEntity, error), error) {
 	modelOpts := ModelOptions(modelConfig, appConfig)
 	inferenceModel, err := loader.Load(modelOpts...)
 	if err != nil {
 		recordModelLoadFailure(appConfig, modelConfig.Name, modelConfig.Backend, err, nil)
 		return nil, err
 	}
-	b, ok := inferenceModel.(grpc.Backend)
-	if !ok {
-		return nil, fmt.Errorf("token classification not supported by backend %q", modelConfig.Backend)
-	}
 	return func(ctx context.Context) ([]TokenEntity, error) {
-		resp, err := b.TokenClassify(ctx, &pb.TokenClassifyRequest{
+		var startTime time.Time
+		if appConfig.EnableTracing {
+			trace.InitBackendTracingIfEnabled(appConfig.TracingMaxItems, appConfig.TracingMaxBodyBytes)
+			startTime = time.Now()
+		}
+		resp, err := inferenceModel.TokenClassify(ctx, &pb.TokenClassifyRequest{
 			Text:      text,
 			Threshold: opts.Threshold,
 		})
+		entities := tokenClassifyResponseToEntities(resp)
+		if appConfig.EnableTracing {
+			trace.RecordBackendTrace(tokenClassifyTrace(modelConfig, text, opts.Threshold, entities, startTime, err))
+		}
 		if err != nil {
 			return nil, err
 		}
-		return tokenClassifyResponseToEntities(resp), nil
+		return entities, nil
 	}, nil
 }
 
+// tokenClassifyTrace assembles the Traces-UI row for one NER call: the input
+// preview, the threshold, and every detected entity (group, byte range,
+// confidence, matched text). Split out from the closure so the Data assembly
+// is unit-testable without a live backend.
+func tokenClassifyTrace(modelConfig config.ModelConfig, text string, threshold float32, entities []TokenEntity, start time.Time, callErr error) trace.BackendTrace {
+	errStr := ""
+	if callErr != nil {
+		errStr = callErr.Error()
+	}
+	return trace.BackendTrace{
+		Timestamp: start,
+		Duration:  time.Since(start),
+		Type:      trace.BackendTraceTokenClassify,
+		ModelName: modelConfig.Name,
+		Backend:   modelConfig.Backend,
+		Summary:   trace.TruncateString(text, 200),
+		Error:     errStr,
+		Data: map[string]any{
+			"input_chars": len(text),
+			"threshold":   threshold,
+			"entities":    entities,
+		},
+	}
+}
+
 // tokenClassifyResponseToEntities converts the wire-format response into
 // the value type consumed by callers. Extracted so the conversion can be
 // unit-tested without a real backend (see token_classify_test.go).

core/backend/token_classify_test.go

@@ -1,6 +1,11 @@
 package backend
 
 import (
+	"errors"
+	"time"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/trace"
 	pb "github.com/mudler/LocalAI/pkg/grpc/proto"
 
 	. "github.com/onsi/ginkgo/v2"
@@ -32,3 +37,25 @@ var _ = Describe("tokenClassifyResponseToEntities", func() {
 		Expect(out).To(BeEmpty())
 	})
 })
+
+var _ = Describe("tokenClassifyTrace", func() {
+	cfg := config.ModelConfig{Name: "privacy-filter", Backend: "llama-cpp"}
+	ents := []TokenEntity{{Group: "SSN", Start: 5, End: 16, Score: 0.62, Text: "123-45-6789"}}
+
+	It("captures model, input preview, threshold and per-entity detail", func() {
+		tr := tokenClassifyTrace(cfg, "ssn is 123-45-6789", 0.5, ents, time.Now(), nil)
+		Expect(tr.Type).To(Equal(trace.BackendTraceTokenClassify))
+		Expect(tr.ModelName).To(Equal("privacy-filter"))
+		Expect(tr.Backend).To(Equal("llama-cpp"))
+		Expect(tr.Summary).To(ContainSubstring("ssn is"))
+		Expect(tr.Error).To(BeEmpty())
+		Expect(tr.Data["input_chars"]).To(Equal(len("ssn is 123-45-6789")))
+		Expect(tr.Data["threshold"]).To(BeEquivalentTo(float32(0.5)))
+		Expect(tr.Data["entities"]).To(Equal(ents))
+	})
+
+	It("records the backend error string when the call failed", func() {
+		tr := tokenClassifyTrace(cfg, "x", 0, nil, time.Now(), errors.New("boom"))
+		Expect(tr.Error).To(Equal("boom"))
+	})
+})

core/services/routing/pii/middleware.go

@@ -229,6 +229,7 @@ func RequestMiddleware(redactor *Redactor, store EventStore, adapter Adapter, fa
 						Length:        span.End - span.Start,
 						HashPrefix:    span.HashPrefix,
 						Action:        span.Action,
+						Score:         span.Score,
 						CreatedAt:     time.Now().UTC(),
 					}
 					if firstEventID == "" {

core/services/routing/pii/ner.go

@@ -28,6 +28,10 @@ type NEREntity struct {
 	Start int
 	End   int
 	Score float32
+	// Text is the matched substring as the detector saw it. Carried for
+	// debug logging only (the persisted PIIEvent never stores the raw
+	// value); the redactor re-slices the original text for masking.
+	Text string
 }
 
 // NERConfig configures the encoder tier for one redactor invocation.

core/services/routing/pii/redactor.go

@@ -6,6 +6,8 @@ import (
 	"encoding/hex"
 	"sort"
 	"strings"
+
+	"github.com/mudler/xlog"
 )
 
 // rawHit is one detection before overlap-merging. Lifted to file scope so
@@ -15,6 +17,7 @@ type rawHit struct {
 	action    Action
 	start     int
 	end       int
+	score     float32
 }
 
 // Redactor is a stateless handle for the PII subsystem. The regex tier
@@ -77,24 +80,42 @@ func collectNERHits(ctx context.Context, text string, cfg NERConfig) ([]rawHit,
 	}
 	var hits []rawHit
 	for _, e := range entities {
+		// One DEBUG line per raw detection with the model's confidence, the
+		// byte range, the matched substring, and the policy decision. This is
+		// the lowest-level view of why a request was masked/blocked — e.g. a
+		// phone number scored as SSN — and answers "what was in that range and
+		// how sure was the model" without re-running the detector. DEBUG-gated
+		// because the matched value is sensitive.
 		if e.Score < cfg.MinScore {
+			xlog.Debug("pii/ner: detection dropped (below min score)",
+				"group", e.Group, "score", e.Score, "min_score", cfg.MinScore,
+				"start", e.Start, "end", e.End, "text", e.Text)
 			continue
 		}
 		action, ok := cfg.ResolveAction(e.Group)
 		if !ok {
+			xlog.Debug("pii/ner: detection ignored (no action for group)",
+				"group", e.Group, "score", e.Score,
+				"start", e.Start, "end", e.End, "text", e.Text)
 			continue
 		}
 		if e.Start < 0 || e.End <= e.Start || e.End > len(text) {
 			// Defensive: the backend should return byte offsets into the
 			// original text, but a misconfigured model could produce
 			// garbage. Skip rather than panic on slice OOB.
+			xlog.Warn("pii/ner: detection has out-of-range offsets; skipping",
+				"group", e.Group, "start", e.Start, "end", e.End, "text_len", len(text))
 			continue
 		}
+		xlog.Debug("pii/ner: detection accepted",
+			"group", e.Group, "score", e.Score, "action", action,
+			"start", e.Start, "end", e.End, "text", e.Text)
 		hits = append(hits, rawHit{
 			patternID: nerPatternID(e.Group),
 			action:    action,
 			start:     e.Start,
 			end:       e.End,
+			score:     e.Score,
 		})
 	}
 	return hits, nil
@@ -125,6 +146,7 @@ func mergeAndEmit(text string, hits []rawHit) Result {
 				if actionRank(h.action) > actionRank(last.action) {
 					last.action = h.action
 					last.patternID = h.patternID
+					last.score = h.score
 				}
 				if h.end > last.end {
 					last.end = h.end
@@ -147,6 +169,7 @@ func mergeAndEmit(text string, hits []rawHit) Result {
 			Pattern:    h.patternID,
 			HashPrefix: hashPrefix(matched),
 			Action:     h.action,
+			Score:      h.score,
 		}
 		res.Spans = append(res.Spans, span)
 

core/services/routing/pii/types.go

@@ -64,9 +64,10 @@ const (
 type Span struct {
 	Start      int
 	End        int
-	Pattern    string // synthetic detector id, "ner:<GROUP>"
-	HashPrefix string // first 8 chars of sha256(matched value); audit-safe
-	Action     Action // the action that fired for this span (after merge)
+	Pattern    string  // synthetic detector id, "ner:<GROUP>"
+	HashPrefix string  // first 8 chars of sha256(matched value); audit-safe
+	Action     Action  // the action that fired for this span (after merge)
+	Score      float32 // detector confidence for the (winning) hit, 0..1
 }
 
 // Result is what Redact returns. Redacted is the input string after
@@ -131,7 +132,11 @@ type PIIEvent struct {
 	Length        int       `json:"length,omitempty"`
 	HashPrefix    string    `json:"hash_prefix,omitempty"`
 	Action        Action    `json:"action,omitempty"`
-	CreatedAt     time.Time `json:"created_at"`
+	// Score is the detector confidence (0..1) for an NER PII hit. Metadata
+	// only — never the matched value. Lets admins see how sure the model was
+	// about a (possibly false-positive) detection without re-running it.
+	Score     float32   `json:"score,omitempty"`
+	CreatedAt time.Time `json:"created_at"`
 
 	Host          string `json:"host,omitempty"`
 	Intercepted   *bool  `json:"intercepted,omitempty"`

core/services/routing/piidetector/detector.go

@@ -79,6 +79,7 @@ func (d *nerDetector) Detect(ctx context.Context, text string) ([]pii.NEREntity,
 			Start: e.Start,
 			End:   e.End,
 			Score: e.Score,
+			Text:  e.Text,
 		})
 	}
 	return out, nil

core/trace/backend_trace.go

@@ -33,6 +33,7 @@ const (
 	BackendTraceAudioTransform  BackendTraceType = "audio_transform"
 	BackendTraceModelLoad       BackendTraceType = "model_load"
 	BackendTraceScore           BackendTraceType = "score"
+	BackendTraceTokenClassify   BackendTraceType = "token_classify"
 	BackendTraceVectorStore     BackendTraceType = "vector_store"
 )
 
@@ -58,10 +59,12 @@ type BackendTrace struct {
 // runaway buffer when a caller streams MB-scale payloads.
 const MaxTraceBodyBytes = 1 << 20
 
-var backendTraceBuffer *circularbuffer.Queue[*BackendTrace]
-var backendMu sync.Mutex
-var backendLogChan = make(chan *BackendTrace, 100)
-var backendInitOnce sync.Once
+var (
+	backendTraceBuffer *circularbuffer.Queue[*BackendTrace]
+	backendMu          sync.Mutex
+	backendLogChan     = make(chan *BackendTrace, 100)
+	backendInitOnce    sync.Once
+)
 
 // backendMaxBodyBytes caps each captured string value in a BackendTrace.Data
 // field to keep the /api/backend-traces JSON small enough for the admin UI to