lettucedect-v2-taxonomy-head: span typing head for the encoder cascade

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+lettuce_code.png filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,75 @@
+---
+license: apache-2.0
+language:
+- en
+- de
+- fr
+- es
+- it
+- pl
+- zh
+tags:
+- hallucination-detection
+- span-classification
+- taxonomy
+- rag
+- code
+base_model: jhu-clsp/mmBERT-base
+datasets:
+- KRLabsOrg/lettucedetect-code-hallucination
+- KRLabsOrg/lettucedetect-prose-hallucination
+---
+
+![LettuceCode mascot](lettuce_code.png)
+
+# lettucedect-v2-taxonomy-head: Span Typing Head (encoder cascade)
+
+## Overview
+
+`lettucedect-v2-taxonomy-head` **types** a hallucinated span — it does not find spans. It is a
+label-conditioned **mmBERT-base bi-encoder** that, given a span a binary detector already
+located, assigns a hallucination **category** and **subcategory** by embedding the span and
+taking the nearest taxonomy-label *description* (cosine). Paired with the binary encoder
+`lettucedect-v2-mmbert-base`, it forms a **fully-encoder typed detector** — detection + typing
+at encoder cost, no generative model.
+
+- **Taxonomy:** 3 categories (contradiction, fabricated_reference, unsupported_addition) × 13 subcategories.
+- **Stage-B only:** run a binary detector (e.g. `lettucedect-v2-mmbert-base`) first, then this head types each span.
+- For detection **and** typing in a single pass, see the generative `lettucedect-v2-qwen-2b`.
+
+## Usage (cascade, via lettucedetect)
+
+```python
+from lettucedetect.models.inference import HallucinationDetector
+
+det = HallucinationDetector(
+    method="transformer",
+    model_path="KRLabsOrg/lettucedect-v2-mmbert-base",      # binary detector (finds spans)
+    taxonomy_head="KRLabsOrg/lettucedect-v2-taxonomy-head",  # this head (types them)
+)
+spans = det.predict(context=[context], question=question, answer=answer, output_format="spans")
+# [{"start": ..., "end": ..., "text": "...", "category": "contradiction", "subcategory": "numerical"}]
+```
+
+## Performance
+
+- **Typing accuracy (given gold spans):** category 0.82 / subcategory 0.64 (validation).
+- **End-to-end cascade** (binary detector → this head), char-overlap typed-F1 on the unified
+  test set: **0.461** (subcategory-gated 0.315). The generative `lettucedect-v2-qwen-2b` is
+  higher (typed-F1 0.585 / 0.468) and types in one pass; this cascade is the option when you
+  want typed spans from a small, fast encoder stack.
+
+**Scope note.** Typing is *supervised* over the taxonomy labels seen in training; the head does
+**not** transfer zero-shot to a held-out subcategory from its description alone (binary-detection
+AUC ≈ chance for an unseen label). Train it on every subcategory you intend to emit.
+
+## Citing
+
+```bibtex
+@article{Kovacs2025LettuceDetect,
+  title={LettuceDetect: A Hallucination Detection Framework for RAG Applications},
+  author={Kovács, Ádám and Recski, Gábor},
+  journal={arXiv preprint arXiv:2502.17125},
+  year={2025}
+}
+```

config.json

@@ -0,0 +1,78 @@
+{
+  "architectures": [
+    "ModernBertModel"
+  ],
+  "attention_bias": false,
+  "attention_dropout": 0.0,
+  "bos_token_id": 2,
+  "classifier_activation": "gelu",
+  "classifier_bias": false,
+  "classifier_dropout": 0.0,
+  "classifier_pooling": "mean",
+  "cls_token_id": 1,
+  "decoder_bias": true,
+  "deterministic_flash_attn": false,
+  "dtype": "bfloat16",
+  "embedding_dropout": 0.0,
+  "eos_token_id": 1,
+  "global_attn_every_n_layers": 3,
+  "gradient_checkpointing": false,
+  "hidden_activation": "gelu",
+  "hidden_size": 768,
+  "initializer_cutoff_factor": 2.0,
+  "initializer_range": 0.02,
+  "intermediate_size": 1152,
+  "layer_norm_eps": 1e-05,
+  "layer_types": [
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention"
+  ],
+  "local_attention": 128,
+  "mask_token_id": 4,
+  "max_position_embeddings": 8192,
+  "mlp_bias": false,
+  "mlp_dropout": 0.0,
+  "model_type": "modernbert",
+  "norm_bias": false,
+  "norm_eps": 1e-05,
+  "num_attention_heads": 12,
+  "num_hidden_layers": 22,
+  "pad_token_id": 0,
+  "position_embedding_type": "sans_pos",
+  "rope_parameters": {
+    "full_attention": {
+      "rope_theta": 160000,
+      "rope_type": "default"
+    },
+    "sliding_attention": {
+      "rope_theta": 160000,
+      "rope_type": "default"
+    }
+  },
+  "sep_token_id": 1,
+  "sparse_pred_ignore_index": -100,
+  "sparse_prediction": false,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.12.0",
+  "vocab_size": 256000
+}

labels.json

@@ -0,0 +1,22 @@
+{
+  "category": {
+    "contradiction": "conflicts with the context (a wrong value, number, date, name, or relationship)",
+    "fabricated_reference": "an entity, name, identifier, or section that is absent from the context",
+    "unsupported_addition": "a claim, detail, or behavior the context never states"
+  },
+  "subcategory": {
+    "entity": "a wrong or invented name, entity, or object",
+    "temporal": "an incorrect date, time, duration, or ordering",
+    "numerical": "an incorrect number, quantity, or amount",
+    "value": "a wrong value, setting, or attribute value",
+    "relational": "an incorrect relationship or association between things",
+    "identifier": "an invented identifier or name not found in the context",
+    "section": "a reference to a section, part, or location that does not exist",
+    "attribute": "an invented or incorrect attribute or property",
+    "claim": "an added factual claim the context does not support",
+    "behavior": "an added or changed action or behavior the context never states",
+    "elaboration": "extra detail or elaboration beyond what the context supports",
+    "subjective": "an unsupported subjective or evaluative statement",
+    "unspecified": "unsupported, with no more specific subtype"
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a700e36913f07495ce43b3d8c7c3c1a2f5e239ba9c78f7b35d9239e1f8b9e1fd
+size 613892480

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:becd1e4f4de2611317d0a5d5366a7cf8b5e56560ebe43ccab753198318927bcf
+size 34363442

tokenizer_config.json

@@ -0,0 +1,25 @@
+{
+  "backend": "tokenizers",
+  "bos_token": "<bos>",
+  "clean_up_tokenization_spaces": false,
+  "cls_token": "<bos>",
+  "eos_token": "<eos>",
+  "extra_special_tokens": [
+    "<start_of_turn>",
+    "<end_of_turn>"
+  ],
+  "is_local": false,
+  "local_files_only": false,
+  "mask_token": "<mask>",
+  "model_input_names": [
+    "input_ids",
+    "attention_mask"
+  ],
+  "model_max_length": 8192,
+  "pad_token": "<pad>",
+  "padding_side": "right",
+  "sep_token": "<eos>",
+  "spaces_between_special_tokens": false,
+  "tokenizer_class": "TokenizersBackend",
+  "unk_token": "<unk>"
+}