I Built a Bayesian Email Classifier Without a Single ML Library

90% classification accuracy. ~200 lines of TypeScript. Zero ML libraries. No model weights. No training infrastructure. Just math that's been proven for 270 years.

P(Category | Words) = P(Words | Category) × P(Category) / P(Words)

Since P(Words) is constant across all categories (we're comparing, not calculating absolute probabilities):
P(Category | Words) ∝ P(Words | Category) × P(Category)

The "Naive" assumption: words are conditionally independent given the category.
So: P(Words | Category) = P(word1 | Category) × P(word2 | Category) × ...

In log space (to avoid float underflow with many words):
log P(Category | Words) ∝ log P(Category) + Σ log P(wordᵢ | Category)

/**
 * Extract n-grams from a token array.
 * Returns unigrams + bigrams by default (n=1 and n=2).
 */
export function extractNgrams(tokens: string[], maxN: number = 2): string[] {
  const ngrams: string[] = [];

  for (let n = 1; n <= maxN; n++) {
    for (let i = 0; i <= tokens.length - n; i++) {
      ngrams.push(tokens.slice(i, i + n).join(" "));
    }
  }

  return ngrams;
}

/**
 * Tokenize email text: lowercase, strip HTML, remove stopwords,
 * remove numbers, collapse whitespace.
 */
const STOPWORDS = new Set([
  "the", "a", "an", "and", "or", "but", "in", "on", "at", "to",
  "for", "of", "with", "by", "from", "is", "was", "are", "were",
  "be", "been", "being", "have", "has", "had", "do", "does", "did",
  "will", "would", "could", "should", "may", "might", "this", "that",
  "these", "those", "i", "you", "he", "she", "we", "they", "it",
  "not", "no", "nor", "so", "yet", "both", "either", "neither",
  "as", "if", "when", "than", "because", "while", "although",
]);

export function tokenize(text: string): string[] {
  return text
    .toLowerCase()
    .replace(/<[^>]+>/g, " ")           // strip HTML
    .replace(/https?://S+/g, " ")    // strip URLs
    .replace(/[^a-zs]/g, " ")          // keep only letters
    .split(/s+/)
    .filter((t) => t.length > 2 && !STOPWORDS.has(t));
}

interface CategoryStats {
  docCount: number;
  ngramCounts: Map<string, number>;
  totalNgrams: number;
}

export class NaiveBayesClassifier {
  private categories = new Map<string, CategoryStats>();
  private totalDocs = 0;
  private vocabulary = new Set<string>();
  private alpha: number;  // Laplace smoothing parameter

  constructor(alpha = 1.0) {
    this.alpha = alpha;
  }

  /**
   * Add a training document.
   * Call this for each labeled email in the training set.
   */
  fit(text: string, category: string): void {
    const tokens = tokenize(text);
    const ngrams = extractNgrams(tokens, 2);

    if (!this.categories.has(category)) {
      this.categories.set(category, {
        docCount: 0,
        ngramCounts: new Map(),
        totalNgrams: 0,
      });
    }

    const stats = this.categories.get(category)!;
    stats.docCount++;
    this.totalDocs++;

    for (const ngram of ngrams) {
      this.vocabulary.add(ngram);
      stats.ngramCounts.set(ngram, (stats.ngramCounts.get(ngram) ?? 0) + 1);
      stats.totalNgrams++;
    }
  }

  /**
   * Classify a new document.
   * Returns the most likely category and confidence scores for all categories.
   */
  predict(text: string): { category: string; scores: Record<string, number> } {
    const tokens = tokenize(text);
    const ngrams = extractNgrams(tokens, 2);
    const vocabSize = this.vocabulary.size;

    let bestCategory = "";
    let bestScore = -Infinity;
    const scores: Record<string, number> = {};

    for (const [category, stats] of this.categories) {
      // Prior: log P(category)
      const logPrior = Math.log(stats.docCount / this.totalDocs);

      // Likelihood: Σ log P(ngram | category) with Laplace smoothing
      let logLikelihood = 0;
      for (const ngram of ngrams) {
        const count = stats.ngramCounts.get(ngram) ?? 0;
        // Laplace smoothing: add alpha to numerator, alpha * V to denominator
        const logP = Math.log(
          (count + this.alpha) / (stats.totalNgrams + this.alpha * vocabSize)
        );
        logLikelihood += logP;
      }

      const score = logPrior + logLikelihood;
      scores[category] = score;

      if (score > bestScore) {
        bestScore = score;
        bestCategory = category;
      }
    }

    return { category: bestCategory, scores };
  }

  /**
   * Serialize the classifier to JSON for persistence.
   * Store in DB or Redis — no need to retrain on each startup.
   */
  serialize(): string {
    const data = {
      totalDocs: this.totalDocs,
      alpha: this.alpha,
      vocabulary: Array.from(this.vocabulary),
      categories: Object.fromEntries(
        Array.from(this.categories.entries()).map(([cat, stats]) => [
          cat,
          {
            docCount: stats.docCount,
            totalNgrams: stats.totalNgrams,
            ngramCounts: Object.fromEntries(stats.ngramCounts),
          },
        ])
      ),
    };
    return JSON.stringify(data);
  }

  static deserialize(json: string): NaiveBayesClassifier {
    const data = JSON.parse(json);
    const classifier = new NaiveBayesClassifier(data.alpha);
    classifier.totalDocs = data.totalDocs;
    classifier.vocabulary = new Set(data.vocabulary);

    for (const [cat, stats] of Object.entries(data.categories as Record<string, {
      docCount: number;
      totalNgrams: number;
      ngramCounts: Record<string, number>;
    }>)) {
      classifier.categories.set(cat, {
        docCount: stats.docCount,
        totalNgrams: stats.totalNgrams,
        ngramCounts: new Map(Object.entries(stats.ngramCounts)),
      });
    }

    return classifier;
  }
}

Alpha = 1.0 works well for newsletters. If your classifier is overconfident on short texts, try alpha = 0.1. If it's underconfident on long texts with many rare words, try alpha = 2.0. We tested 0.1, 0.5, 1.0, 2.0 and 1.0 gave the best F1 score on our validation set.

/**
 * Two-stage classification:
 * 1. Check domain map (O(1), 100% accurate for known domains)
 * 2. Per-user classifier (personalized)
 * 3. Global classifier (fallback)
 */
export async function classifyNewsletter(
  email: Email,
  userId: string,
  db: Database,
): Promise<string> {
  // Stage 1: Domain heuristic
  const senderDomain = email.from.split("@")[1];
  const domainCategory = DOMAIN_CATEGORY_MAP.get(senderDomain);
  if (domainCategory) return domainCategory;

  // Stage 2: Per-user classifier
  const userModelJson = await db.getUserClassifierModel(userId);
  if (userModelJson) {
    const userClassifier = NaiveBayesClassifier.deserialize(userModelJson);
    const text = `${email.subject} ${email.preview} ${email.sender_name}`;
    const result = userClassifier.predict(text);
    // Only trust user model if it's confident
    const topScore = Math.max(...Object.values(result.scores));
    const secondScore = Object.values(result.scores)
      .sort((a, b) => b - a)[1] ?? -Infinity;
    if (topScore - secondScore > 2.0) {
      return result.category;
    }
  }

  // Stage 3: Global classifier
  const globalClassifier = await getGlobalClassifier(db);
  const text = `${email.subject} ${email.preview} ${email.sender_name}`;
  return globalClassifier.predict(text).category;
}

Naive Bayes isn't the most accurate classifier in the world. It's the most accurate classifier you can build in a weekend, run in 2ms, deploy with no infrastructure, and explain to a non-ML engineer in 10 minutes. In production, those constraints matter more than academic benchmarks.