Documentation

NAME

Mail::MIMEDefang::ML::GLiClass - GLiClass zero-shot backend for Mail::MIMEDefang::ML.

SYNOPSIS

use Mail::MIMEDefang::ML;

$Mail::MIMEDefang::ML::Config{backend}              = 'gliclass';
$Mail::MIMEDefang::ML::Config{gliclass}{server_url} = 'http://127.0.0.1:8688';

my $verdict = ml_classify(ml_build_state(...));

DESCRIPTION

GLiClass (https://github.com/Knowledgator/GLiClass) is a zero-shot sequence classifier built on a bidirectional encoder (ModernBERT for the gliclass-modern-* checkpoints). The default checkpoint is English; for other languages start the server with a multilingual one, for example knowledgator/gliclass-multilang-mini, see script/ml-servers/README.md. It scores the text against every label in a single forward pass, so, like Laya, it avoids the latency and output parsing of an autoregressive LLM, and it needs no fine-tuning: the labels are plain text.

Because GLiClass is a Python library, this backend talks to a small resident Python inference server (see mimedefang-gliclass-server). The state is rendered as text (auth results, subject, then body) and scored in multi-label mode against the labels of each question, plus fixed labels describing legitimate mail (correspondence between people who know each other, receipts, notices and newsletters from companies the recipient is a customer of). Each question's probability is p = s / (s + h), where s is its best label's score and h the best ham label's score: on its own a label scores high on legitimate marketing mail too. The raw s and h of every question and its p are returned in the verdict's scores (is_spam, ham, p_is_spam, ...).

p is mapped to a yes answer when p >= 0.5, with confidence p for a yes and 1 - p for a no, so the usual min_confidence gate applies.

This module is not used directly: select it with $Mail::MIMEDefang::ML::Config{backend} = 'gliclass'.

CONFIGURATION

$Mail::MIMEDefang::ML::Config{gliclass}:

  • server_url

    Default http://127.0.0.1:8688.

  • predict_path

    Default /predict.

  • labels, ham_labels

    Override the labels scored, %Mail::MIMEDefang::ML::GLiClass::LABELS and @Mail::MIMEDefang::ML::GLiClass::HAM_LABELS. labels is a hash keyed by question (is_spam, is_phishing), each value one label or a list of labels; a question not in it keeps its default. ham_labels is a list. With several labels the best scoring one counts, so a question can cover different kinds of mail:

    $Mail::MIMEDefang::ML::Config{gliclass}{labels}{is_spam} = [
        'scam email: fake invoice, fake order, fake prize, advance-fee or investment fraud',
        'unsolicited bulk advertising for pills, replica watches, loans, dating or stock tips',
    ];
    

    Zero-shot scores depend on the wording of every label sent with the text.

    A model fine-tuned with contrib/ml-benchmark/gliclass-train must be served with the labels it was trained on.

  • body_head_chars, body_tail_chars

    Body kept for this backend, default 6000 and 1500 characters, about 2500 tokens with the headers. The gliclass-modern-* checkpoints read up to 8192 tokens; the --max-length of mimedefang-gliclass-server (default 4096 tokens, labels included) cuts anything longer. The time per message grows faster than the length: on CPU, 2000 tokens take several seconds, so lower these (or raise timeout) on slow hardware.

SEE ALSO

Mail::MIMEDefang::ML, mimedefang-gliclass-server.