haspi

haspi extracts explainable classification rewards from text — reward scores for hate speech and moderation-removal, each decomposed into the words that drove it — built on the One Million Posts Corpus (DerStandard, OFAI). Rooted in inverse soft-Q learning (IQ-Learn); JAX / flax-nnx, with an optional PyTorch encoder path.

This package is aimed at forum moderators who want to test our method as well as researchers who want to reproduce or enhance our results.

The best method

The best method is the sequence-χ² reward: a linear χ² reward head on a frozen German decoder LM’s mean-pooled features, folded into a single vector so scoring is one forward pass and the reward decomposes exactly into per-word contributions. It also supports context-aware moderation — scoring a comment with its thread/article context, evaluated on article-disjoint splits so the gains are honest — and ships an interactive demo (haspi-demo) that highlights the risky words and shows a risk meter.

	held-out AUROC
hate-vs-neutral (10-fold CV)	0.76
OMP online/offline moderation	0.75 frozen → 0.77 LoRA fine-tuned
external cross-check — RP-Mod moderation (a different corpus, same splits as Assenmacher et al.)	0.796 (their fine-tuned BERT: 0.791)
external cross-check — HateXplain (English; hate+offensive vs normal)	0.857

The first two rows are reproducible from this package. The last two are additional experiments on other corpora — haspi targets the One Million Posts Corpus, so neither their data nor their scripts ship here. What they measure, including how the per-word attributions compare to HateXplain’s human rationales, is written up in External benchmarks.

$ haspi-explain
> Du bist ein widerlicher Idiot und gehörst abgeschoben.
  → HATE   (score +1.06, threshold -0.02)
     toward HATE:     'bist'+0.39  'widerlicher'+0.22  'gehörst'+0.22  'Du'+0.17
     toward non-hate: 'abgeschoben.'-0.10

Method evolution

The package retains the earlier methods for reproducibility and the research story; only one is current (the one described above as best method). haspi.CURRENT_METHOD and haspi.METHODS are the machine-readable source of truth.

method	status	where
continuous IQ-Learn	superseded	haspi.architecture.agent_continuous
two-distribution discrete IQ-Learn	superseded (~0.55; post-length artifact)	haspi.architecture.agent
sequence-χ² reward	current	haspi.sequence
gBERT unfrozen under the same χ² reward	ablation (0.69 hate; χ² ≈ CE)	haspi.training.finetune_gbert
sequence-χ² with LoRA fine-tuning	enhancement (best on moderation)	haspi.sequence.finetune

The superseded two-distribution IQ-Learn core is still documented under Architecture; its per-token reward \(r(s,a) = Q(s,a) - \gamma\cdot V(s')\) also decomposes into a per-token explanation.

Getting started

• Installation
  • Dependency pins worth knowing
  • GPU memory notes
• Quickstart
  • Explain a comment
  • Fit the reward yourself
  • Library use
  • Superseded: the two-distribution IQ-Learn trainer

Guide

• Sequence-χ² reward
  • How the method works
  • Pipeline and CLIs
  • Context-aware moderation
  • Interactive demo
• Fine-tuning
  • What fine-tuning buys (and what it doesn’t)
  • LoRA fine-tuning — haspi-finetune-reward
  • gBERT fine-tuning — haspi-finetune-gbert
• External benchmarks
  • Summary
  • RP-Mod — against a published fine-tuned baseline
  • HateXplain — cross-lingual transfer and human rationales
  • Future directions
  • Reproducing
• Architecture
  • The two-buffer IQ-Learn objective
  • The agent
  • The design pattern
  • Encoders
  • LoRA
  • The experimental continuous agent
• Training
  • Data preparation
  • Expert vs anchor: avenues
  • haspi-train: two modes
  • Tuning notes
  • Architecture knobs
  • Inspecting the policy during training
• Inference and explainability
  • Loading a model
  • Per-token rewards: the explainability primitive
  • Calibration
  • Evaluation
• RL environment & corpus buffers
  • The token MDP
  • Filling a filterable buffer
  • CLI

Reference

• API reference
  • Core modules
  • haspi.sequence
  • haspi.architecture
  • haspi.training
  • haspi.inference