TealClassifier

TealClassifier performs local content classification using ONNX models — no external API calls, no data exfiltration risk. It supports multiple ensemble modes that combine regex pattern matching with ML inference for high-accuracy, low-latency classification.

TealClassifier mitigates data exfiltration risk (OWASP ASI-04). By running classification locally via ONNX Runtime, sensitive content never leaves your infrastructure for classification purposes. The governance path remains deterministic — ML confidence scores are thresholded into binary allow/deny decisions.

Why This Matters

Risk	Without Local Classification	With TealClassifier
Data exfiltration	Content sent to external classification APIs	All inference runs locally — zero network calls
Latency	External API round-trips add 100-500ms	Local ONNX inference in < 5ms
Availability	Classification depends on third-party uptime	No external dependencies
Privacy	Sensitive content visible to third parties	Content never leaves your infrastructure
Determinism	API responses may vary	Same model + same input = same output

Compliance alignment: NIST AI RMF (MAP 2.3 — data minimization), ISO 42001 (A.8.2 — data management), GDPR Article 25 (data protection by design).

Ensemble Modes

TealClassifier supports four ensemble modes that combine regex and ML classification:

Mode	Behavior	Use Case
`regex_only`	Only regex patterns — no ML inference	Maximum speed, known patterns only
`ml_only`	Only ONNX model inference — no regex	Novel content, semantic understanding
`ensemble_union`	Flag if either regex OR ML detects	Maximum recall — catch everything
`ensemble_intersection`	Flag only if both regex AND ML detect	Maximum precision — minimize false positives

import { TealClassifier } from 'tealtiger/classifier';

const classifier = new TealClassifier({
  mode: 'ensemble_union',
  model: {
    path: './models/content-classifier-v2.onnx',
    tokenizer: './models/tokenizer.json'
  },
  confidence_threshold: 0.7,
  categories: ['pii', 'secrets', 'harmful', 'off-topic']
});

Class

class TealClassifier {
  constructor(options: ClassifierOptions);

  /** Classify content */
  classify(content: string, ctx?: ClassificationContext): Promise<ClassificationResult>;

  /** Batch classification */
  classifyBatch(contents: string[]): Promise<ClassificationResult[]>;

  /** Get model metadata */
  getModelInfo(): ModelInfo;

  /** Warm up the model (pre-load into memory) */
  warmup(): Promise<void>;
}

ClassifierOptions

interface ClassifierOptions {
  /** Ensemble mode */
  mode: 'regex_only' | 'ml_only' | 'ensemble_union' | 'ensemble_intersection';

  /** ONNX model configuration (required for ml_only, ensemble modes) */
  model?: {
    /** Path to ONNX model file */
    path: string;
    /** Path to tokenizer configuration */
    tokenizer: string;
    /** Maximum sequence length (default: 512) */
    maxLength?: number;
    /** Execution provider (default: 'cpu') */
    provider?: 'cpu' | 'cuda' | 'tensorrt';
  };

  /** Confidence threshold for ML predictions (default: 0.7) */
  confidence_threshold: number;

  /** Categories to classify */
  categories: string[];

  /** Custom regex patterns (extends built-in patterns) */
  customPatterns?: Record<string, RegExp[]>;

  /** Fallback behavior when ML model fails */
  fallback?: {
    /** Fall back to regex_only on ML failure */
    mode: 'regex_only' | 'deny' | 'allow';
    /** Log fallback events */
    logFallback: boolean;
  };
}

classify()

Classify a single content string.

const result = await classifier.classify(
  'Please send the payment to [email protected], account 4111-1111-1111-1111',
  { agentId: 'support-bot-001' }
);

console.log(result.categories);
// [
//   { name: 'pii', confidence: 0.94, source: 'ensemble', details: ['email', 'credit_card'] },
//   { name: 'secrets', confidence: 0.12, source: 'ml', details: [] }
// ]

console.log(result.flagged);        // true (at least one category above threshold)
console.log(result.highestRisk);    // 'pii'
console.log(result.duration_ms);    // 3
console.log(result.mode);           // 'ensemble_union'

ClassificationResult

interface ClassificationResult {
  /** Detected categories with confidence scores */
  categories: CategoryDetection[];

  /** Whether any category exceeded the threshold */
  flagged: boolean;

  /** Highest-risk category detected */
  highestRisk: string | null;

  /** Classification duration */
  duration_ms: number;

  /** Mode used for this classification */
  mode: string;

  /** Which sources contributed (regex, ml, or both) */
  sources: ('regex' | 'ml')[];

  /** Raw ML confidence scores (for debugging) */
  rawScores?: Record<string, number>;
}

interface CategoryDetection {
  /** Category name */
  name: string;

  /** Confidence score (0.0 - 1.0) */
  confidence: number;

  /** Which source detected this */
  source: 'regex' | 'ml' | 'ensemble';

  /** Specific sub-patterns detected */
  details: string[];
}

Ensemble Behavior Examples

ensemble_union (Maximum Recall)

Flags content if either regex or ML detects it. Catches more, but may have higher false positive rate.

const classifier = new TealClassifier({
  mode: 'ensemble_union',
  confidence_threshold: 0.7,
  // ...
});

// Regex detects email pattern, ML confidence is 0.5 (below threshold)
// Result: FLAGGED (regex alone is sufficient in union mode)

// Regex misses novel PII format, ML confidence is 0.85
// Result: FLAGGED (ML alone is sufficient in union mode)

ensemble_intersection (Maximum Precision)

Flags content only if both regex and ML agree. Fewer false positives, but may miss novel patterns.

const classifier = new TealClassifier({
  mode: 'ensemble_intersection',
  confidence_threshold: 0.7,
  // ...
});

// Regex detects email pattern, ML confidence is 0.5 (below threshold)
// Result: NOT FLAGGED (both must agree)

// Regex detects email pattern, ML confidence is 0.85
// Result: FLAGGED (both agree)

ONNX Model Loading

TealClassifier uses ONNX Runtime for inference. Models are loaded once and kept in memory.

// Model warmup (optional — first classify() call will also load)
await classifier.warmup();

// Get model info
const info = classifier.getModelInfo();
console.log(info.name);          // 'content-classifier-v2'
console.log(info.version);       // '2.1.0'
console.log(info.inputShape);    // [1, 512]
console.log(info.outputShape);   // [1, 4] (4 categories)
console.log(info.provider);      // 'cpu'
console.log(info.loaded);        // true
console.log(info.memoryMB);      // 45

Supported Model Formats

Format	Extension	Notes
ONNX	`.onnx`	Primary format — recommended
Quantized ONNX	`.onnx` (INT8)	4x smaller, ~2% accuracy loss

Custom Patterns

Extend built-in regex patterns with domain-specific patterns:

const classifier = new TealClassifier({
  mode: 'ensemble_union',
  customPatterns: {
    'internal-ids': [
      /ACME-\d{6}/,           // Internal ticket IDs
      /EMP-[A-Z]{2}\d{4}/,   // Employee IDs
    ],
    'medical': [
      /\b\d{3}-\d{2}-\d{4}\b/,  // SSN format
      /MRN:\s*\d{8}/,            // Medical record numbers
    ]
  },
  categories: ['pii', 'secrets', 'internal-ids', 'medical'],
  confidence_threshold: 0.7
});

Fallback Behavior

When the ML model fails (corrupted file, OOM, unsupported operation), TealClassifier falls back gracefully:

const classifier = new TealClassifier({
  mode: 'ensemble_union',
  fallback: {
    mode: 'regex_only',    // Fall back to regex patterns
    logFallback: true      // Emit warning event
  },
  // ...
});

// If ONNX model fails to load or inference throws:
// → Automatically switches to regex_only mode
// → Logs: { event: 'classifier.fallback', reason: 'onnx_inference_error' }
// → Classification continues with regex patterns only

Performance

Operation	Latency (p99)	Notes
`regex_only`	< 1ms	Pattern matching only
`ml_only`	< 5ms	ONNX inference (CPU, 512 tokens)
`ensemble_union`	< 5ms	Parallel regex + ML
`ensemble_intersection`	< 5ms	Parallel regex + ML
Model warmup	~200ms	One-time cost
Batch (10 items)	< 15ms	Batched inference

Integration with TealEngine

import { TealEngine, TealClassifier } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    classifier: {
      mode: 'ensemble_union',
      confidence_threshold: 0.7,
      categories: ['pii', 'secrets', 'harmful'],
      actions: {
        pii: 'auto_sanitize',
        secrets: 'auto_deny',
        harmful: 'auto_deny'
      }
    }
  },
  modules: [
    new TealClassifier({
      mode: 'ensemble_union',
      model: { path: './models/classifier.onnx', tokenizer: './models/tokenizer.json' },
      confidence_threshold: 0.7,
      categories: ['pii', 'secrets', 'harmful']
    })
  ]
});

TealEngine v1.3 API — Engine integration
TealFlow — Workflow orchestration with classifier jobs
TealDrift — Drift detection uses classifier outputs
OWASP Policy Pack — Pre-built classification policies
SOC/IR Pipeline — Classification events in SIEM

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Why This Matters

Ensemble Modes

Class

ClassifierOptions

classify()

ClassificationResult

Ensemble Behavior Examples

ensemble_union (Maximum Recall)

ensemble_intersection (Maximum Precision)

ONNX Model Loading

Supported Model Formats

Custom Patterns

Fallback Behavior

Performance

Integration with TealEngine

​Why This Matters

​Ensemble Modes

​Class

​ClassifierOptions

​classify()

​ClassificationResult

​Ensemble Behavior Examples

​ensemble_union (Maximum Recall)

​ensemble_intersection (Maximum Precision)

​ONNX Model Loading

​Supported Model Formats

​Custom Patterns

​Fallback Behavior

​Performance

​Integration with TealEngine

​Related Documentation

Why This Matters

Ensemble Modes

Class

ClassifierOptions

classify()

ClassificationResult

Ensemble Behavior Examples

ensemble_union (Maximum Recall)

ensemble_intersection (Maximum Precision)

ONNX Model Loading

Supported Model Formats

Custom Patterns

Fallback Behavior

Performance

Integration with TealEngine

Related Documentation