fix(classifiers): add PII NER allowlist and document metal feature for macOS (#2541)

Add configurable pii_ner_allowlist to ClassifiersConfig that prevents
tokens matching an allowlist entry (case-insensitive) from being redacted
by the piiranha NER model. Suppresses common false positives such as
"Zeph" being misclassified as [PII:CITY] by piiranha-v1.

Default allowlist entries: ["Zeph", "Rust", "OpenAI", "Ollama", "Claude"].
Configurable via [classifiers] pii_ner_allowlist in config.toml.
Set to [] to disable the allowlist entirely.

Also document that on macOS Apple Silicon, --features full,metal is
required for piiranha NER GPU acceleration. Without metal, the 1.1 GB
model times out after 30s on CPU and falls back to regex-only detection.

Closes #2537, closes #2538

Author: bug-ops

CHANGELOG.md

@@ -17,6 +17,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- fix(classifiers): add configurable `pii_ner_allowlist` to `ClassifiersConfig` — tokens matching an allowlist entry (case-insensitive) are never redacted by the piiranha NER model, suppressing false positives such as "Zeph" → `[PII:CITY]`; default entries: `["Zeph", "Rust", "OpenAI", "Ollama", "Claude"]`; list is empty-able via config to disable the feature (closes #2537)
+- fix(classifiers): document that macOS Apple Silicon requires `--features full,metal` for piiranha NER GPU acceleration; without `metal`, the 1.1 GB model exceeds the 30s timeout on CPU and falls back to regex-only PII detection (closes #2538)
+
 - fix(tools): propagate `claim_source` from `ToolOutput` into the post-execution audit entry in `AdversarialPolicyGateExecutor`; `write_audit` now accepts an explicit `claim_source` parameter so the field is no longer hardcoded to `None` for successful executions (closes #2535)
 - fix(tools): `extract_paths` now detects relative path tokens that contain `/` but do not start with `/` or `./` (e.g. `src/main.rs`, `.local/foo/bar`); URL schemes (`://`) and shell variable assignments (`KEY=value`) are excluded from matching (closes #2536)
 

crates/zeph-config/src/classifiers.rs

@@ -35,6 +35,16 @@ fn default_pii_ner_max_chars() -> usize {
     8192
 }
 
+fn default_pii_ner_allowlist() -> Vec<String> {
+    vec![
+        "Zeph".into(),
+        "Rust".into(),
+        "OpenAI".into(),
+        "Ollama".into(),
+        "Claude".into(),
+    ]
+}
+
 fn default_three_class_threshold() -> f32 {
     0.7
 }
@@ -203,6 +213,18 @@ pub struct ClassifiersConfig {
     /// timeout on large tool outputs (e.g. `search_code`). Default `8192`.
     #[serde(default = "default_pii_ner_max_chars")]
     pub pii_ner_max_chars: usize,
+
+    /// Allowlist of tokens that are never redacted by the NER PII classifier, regardless
+    /// of model confidence.
+    ///
+    /// Matching is case-insensitive and exact (whole span text must equal an allowlist entry).
+    /// This suppresses common false positives from the piiranha model — for example,
+    /// "Zeph" is misclassified as a city (PII:CITY) by the base model.
+    ///
+    /// Default entries: `["Zeph", "Rust", "OpenAI", "Ollama", "Claude"]`.
+    /// Set to `[]` to disable the allowlist entirely.
+    #[serde(default = "default_pii_ner_allowlist")]
+    pub pii_ner_allowlist: Vec<String>,
 }
 
 impl Default for ClassifiersConfig {
@@ -225,6 +247,7 @@ impl Default for ClassifiersConfig {
             pii_threshold: default_pii_threshold(),
             pii_model_sha256: None,
             pii_ner_max_chars: default_pii_ner_max_chars(),
+            pii_ner_allowlist: default_pii_ner_allowlist(),
         }
     }
 }
@@ -258,6 +281,10 @@ mod tests {
         );
         assert!((cfg.pii_threshold - 0.75).abs() < 1e-6);
         assert!(cfg.pii_model_sha256.is_none());
+        assert_eq!(
+            cfg.pii_ner_allowlist,
+            vec!["Zeph", "Rust", "OpenAI", "Ollama", "Claude"]
+        );
     }
 
     #[test]
@@ -337,6 +364,7 @@ mod tests {
             pii_threshold: 0.80,
             pii_model_sha256: None,
             pii_ner_max_chars: 4096,
+            pii_ner_allowlist: vec!["MyProject".into(), "Rust".into()],
         };
         let serialized = toml::to_string(&original).unwrap();
         let deserialized: ClassifiersConfig = toml::from_str(&serialized).unwrap();
@@ -429,6 +457,30 @@ mod tests {
         assert_eq!(cfg.three_class_model_sha256.as_deref(), Some("aabbcc"));
     }
 
+    #[test]
+    fn pii_ner_allowlist_default_entries() {
+        let cfg = ClassifiersConfig::default();
+        assert!(cfg.pii_ner_allowlist.contains(&"Zeph".to_owned()));
+        assert!(cfg.pii_ner_allowlist.contains(&"Rust".to_owned()));
+        assert!(cfg.pii_ner_allowlist.contains(&"OpenAI".to_owned()));
+        assert!(cfg.pii_ner_allowlist.contains(&"Ollama".to_owned()));
+        assert!(cfg.pii_ner_allowlist.contains(&"Claude".to_owned()));
+    }
+
+    #[test]
+    fn pii_ner_allowlist_configurable() {
+        let toml = r#"pii_ner_allowlist = ["MyProject", "AcmeCorp"]"#;
+        let cfg: ClassifiersConfig = toml::from_str(toml).unwrap();
+        assert_eq!(cfg.pii_ner_allowlist, vec!["MyProject", "AcmeCorp"]);
+    }
+
+    #[test]
+    fn pii_ner_allowlist_empty_disables() {
+        let toml = "pii_ner_allowlist = []";
+        let cfg: ClassifiersConfig = toml::from_str(toml).unwrap();
+        assert!(cfg.pii_ner_allowlist.is_empty());
+    }
+
     #[test]
     fn three_class_threshold_validation_rejects_zero() {
         let result: Result<ClassifiersConfig, _> = toml::from_str("three_class_threshold = 0.0");

crates/zeph-core/src/agent/builder.rs

@@ -850,6 +850,23 @@ impl<C: Channel> Agent<C> {
         self
     }
 
+    /// Set the NER PII allowlist on the sanitizer.
+    ///
+    /// Span texts matching any allowlist entry (case-insensitive, exact) are suppressed
+    /// from `detect_pii()` results. Must be called after `with_pii_detector`.
+    #[cfg(feature = "classifiers")]
+    #[must_use]
+    pub fn with_pii_ner_allowlist(mut self, entries: Vec<String>) -> Self {
+        let old = std::mem::replace(
+            &mut self.security.sanitizer,
+            zeph_sanitizer::ContentSanitizer::new(
+                &zeph_sanitizer::ContentIsolationConfig::default(),
+            ),
+        );
+        self.security.sanitizer = old.with_pii_ner_allowlist(entries);
+        self
+    }
+
     /// Attach a NER classifier backend for PII detection in the union merge pipeline.
     ///
     /// When attached, `sanitize_tool_output()` runs both regex and NER, merges spans, and

crates/zeph-sanitizer/src/lib.rs

@@ -328,6 +328,10 @@ pub struct ContentSanitizer {
     pii_detector: Option<std::sync::Arc<dyn zeph_llm::classifier::PiiDetector>>,
     #[cfg(feature = "classifiers")]
     pii_threshold: f32,
+    /// Case-folded allowlist — spans whose text (case-insensitive) matches an entry are
+    /// suppressed before the result is returned from `detect_pii()`.
+    #[cfg(feature = "classifiers")]
+    pii_ner_allowlist: Vec<String>,
     #[cfg(feature = "classifiers")]
     classifier_metrics: Option<std::sync::Arc<zeph_llm::ClassifierMetrics>>,
 }
@@ -364,6 +368,8 @@ impl ContentSanitizer {
             #[cfg(feature = "classifiers")]
             pii_threshold: 0.75,
             #[cfg(feature = "classifiers")]
+            pii_ner_allowlist: Vec::new(),
+            #[cfg(feature = "classifiers")]
             classifier_metrics: None,
         }
     }
@@ -468,6 +474,20 @@ impl ContentSanitizer {
         self
     }
 
+    /// Set the NER PII allowlist.
+    ///
+    /// Span texts that match any entry (case-insensitive, exact match) are suppressed
+    /// from the `detect_pii()` result. Use this to suppress known false positives such
+    /// as project names misclassified by the base NER model.
+    ///
+    /// Entries are stored case-folded at construction time for fast lookup.
+    #[cfg(feature = "classifiers")]
+    #[must_use]
+    pub fn with_pii_ner_allowlist(mut self, entries: Vec<String>) -> Self {
+        self.pii_ner_allowlist = entries.into_iter().map(|s| s.to_lowercase()).collect();
+        self
+    }
+
     /// Attach a [`ClassifierMetrics`] instance to record injection and PII latencies.
     #[cfg(feature = "classifiers")]
     #[must_use]
@@ -483,6 +503,10 @@ impl ContentSanitizer {
     ///
     /// Returns an empty result when no `pii_detector` is attached.
     ///
+    /// Spans whose extracted text matches an allowlist entry (case-insensitive, exact match)
+    /// are removed before returning. This suppresses common false positives from the
+    /// piiranha model (e.g. "Zeph" being misclassified as a city).
+    ///
     /// # Errors
     ///
     /// Returns `LlmError` if the underlying model fails.
@@ -494,10 +518,21 @@ impl ContentSanitizer {
         match &self.pii_detector {
             Some(detector) => {
                 let t0 = std::time::Instant::now();
-                let result = detector.detect_pii(text).await?;
+                let mut result = detector.detect_pii(text).await?;
                 if let Some(ref m) = self.classifier_metrics {
                     m.record(zeph_llm::classifier::ClassifierTask::Pii, t0.elapsed());
                 }
+                if !self.pii_ner_allowlist.is_empty() {
+                    result.spans.retain(|span| {
+                        let span_text = text
+                            .get(span.start..span.end)
+                            .unwrap_or("")
+                            .trim()
+                            .to_lowercase();
+                        !self.pii_ner_allowlist.contains(&span_text)
+                    });
+                    result.has_pii = !result.spans.is_empty();
+                }
                 Ok(result)
             }
             None => Ok(zeph_llm::classifier::PiiResult {
@@ -2215,4 +2250,142 @@ mod tests {
             );
         }
     }
+
+    // --- pii_ner_allowlist filtering ---
+
+    #[cfg(feature = "classifiers")]
+    mod pii_allowlist {
+        use super::*;
+        use std::future::Future;
+        use std::pin::Pin;
+        use std::sync::Arc;
+        use zeph_llm::classifier::{PiiDetector, PiiResult, PiiSpan};
+
+        struct MockPiiDetector {
+            result: PiiResult,
+        }
+
+        impl MockPiiDetector {
+            fn new(spans: Vec<PiiSpan>) -> Self {
+                let has_pii = !spans.is_empty();
+                Self {
+                    result: PiiResult { spans, has_pii },
+                }
+            }
+        }
+
+        impl PiiDetector for MockPiiDetector {
+            fn detect_pii<'a>(
+                &'a self,
+                _text: &'a str,
+            ) -> Pin<Box<dyn Future<Output = Result<PiiResult, zeph_llm::LlmError>> + Send + 'a>>
+            {
+                let result = self.result.clone();
+                Box::pin(async move { Ok(result) })
+            }
+
+            fn backend_name(&self) -> &'static str {
+                "mock"
+            }
+        }
+
+        fn span(start: usize, end: usize) -> PiiSpan {
+            PiiSpan {
+                entity_type: "CITY".to_owned(),
+                start,
+                end,
+                score: 0.99,
+            }
+        }
+
+        // T-A1: allowlist entry filtered from detect_pii result.
+        #[tokio::test]
+        async fn allowlist_entry_is_filtered() {
+            // "Zeph" occupies bytes 6..10 in "Hello Zeph"
+            let text = "Hello Zeph";
+            let mock = Arc::new(MockPiiDetector::new(vec![span(6, 10)]));
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default())
+                .with_pii_detector(mock, 0.5)
+                .with_pii_ner_allowlist(vec!["Zeph".to_owned()]);
+            let result = s.detect_pii(text).await.expect("detect_pii failed");
+            assert!(result.spans.is_empty());
+            assert!(!result.has_pii);
+        }
+
+        // T-A2: matching is case-insensitive ("zeph" in allowlist filters span "Zeph").
+        #[tokio::test]
+        async fn allowlist_is_case_insensitive() {
+            let text = "Hello Zeph";
+            let mock = Arc::new(MockPiiDetector::new(vec![span(6, 10)]));
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default())
+                .with_pii_detector(mock, 0.5)
+                .with_pii_ner_allowlist(vec!["zeph".to_owned()]);
+            let result = s.detect_pii(text).await.expect("detect_pii failed");
+            assert!(result.spans.is_empty());
+            assert!(!result.has_pii);
+        }
+
+        // T-A3: non-allowlist span preserved when another span is filtered.
+        #[tokio::test]
+        async fn non_allowlist_span_preserved() {
+            // text: "Zeph john.doe@example.com"
+            //        0123456789...
+            let text = "Zeph john.doe@example.com";
+            let city_span = span(0, 4);
+            let email_span = PiiSpan {
+                entity_type: "EMAIL".to_owned(),
+                start: 5,
+                end: 25,
+                score: 0.99,
+            };
+            let mock = Arc::new(MockPiiDetector::new(vec![city_span, email_span]));
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default())
+                .with_pii_detector(mock, 0.5)
+                .with_pii_ner_allowlist(vec!["Zeph".to_owned()]);
+            let result = s.detect_pii(text).await.expect("detect_pii failed");
+            assert_eq!(result.spans.len(), 1);
+            assert_eq!(result.spans[0].entity_type, "EMAIL");
+            assert!(result.has_pii);
+        }
+
+        // T-A4: empty allowlist passes all spans through (is_empty() guard is respected).
+        #[tokio::test]
+        async fn empty_allowlist_passes_all_spans() {
+            let text = "Hello Zeph";
+            let mock = Arc::new(MockPiiDetector::new(vec![span(6, 10)]));
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default())
+                .with_pii_detector(mock, 0.5)
+                .with_pii_ner_allowlist(vec![]);
+            let result = s.detect_pii(text).await.expect("detect_pii failed");
+            assert_eq!(result.spans.len(), 1);
+            assert!(result.has_pii);
+        }
+
+        // T-A5: no pii_detector attached returns empty PiiResult.
+        #[tokio::test]
+        async fn no_pii_detector_returns_empty() {
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default());
+            let result = s
+                .detect_pii("sensitive text")
+                .await
+                .expect("detect_pii failed");
+            assert!(result.spans.is_empty());
+            assert!(!result.has_pii);
+        }
+
+        // T-A6: has_pii recalculated to false when all spans are filtered.
+        #[tokio::test]
+        async fn has_pii_recalculated_after_all_spans_filtered() {
+            let text = "Zeph Rust";
+            // Two spans, both matching allowlist entries.
+            let spans = vec![span(0, 4), span(5, 9)];
+            let mock = Arc::new(MockPiiDetector::new(spans));
+            let s = ContentSanitizer::new(&ContentIsolationConfig::default())
+                .with_pii_detector(mock, 0.5)
+                .with_pii_ner_allowlist(vec!["Zeph".to_owned(), "Rust".to_owned()]);
+            let result = s.detect_pii(text).await.expect("detect_pii failed");
+            assert!(result.spans.is_empty());
+            assert!(!result.has_pii);
+        }
+    }
 }

src/agent_setup.rs

@@ -642,9 +642,15 @@ pub(crate) fn apply_pii_classifier_with_cfg<C: Channel>(
     tracing::info!(
         repo_id = %classifiers.pii_model,
         threshold = classifiers.pii_threshold,
+        allowlist_len = classifiers.pii_ner_allowlist.len(),
         "PII classifier attached (model loads lazily on first use)"
     );
-    agent.with_pii_detector(backend_arc, classifiers.pii_threshold)
+    let agent = agent.with_pii_detector(backend_arc, classifiers.pii_threshold);
+    if classifiers.pii_ner_allowlist.is_empty() {
+        agent
+    } else {
+        agent.with_pii_ner_allowlist(classifiers.pii_ner_allowlist.clone())
+    }
 }
 
 /// Wire the `CandleNerClassifier` into the PII union merge pipeline.