ROG-7/muril-indic-ner-explainable-crf

Explainable Named Entity Recognition for Low-Resource Languages (MuRIL + Linear-Chain CRF)

This repository contains the fine-tuned, deliverable model for the research project:
"Explainable Named Entity Recognition for Low-Resource Languages Using Attention Attribution".

• Base Backbone: google/muril-base-cased (12 layers, 768 hidden dimension, 12 attention heads).
• Architecture Amendment: Linear-Chain Conditional Random Field (CRF) output head with exact Viterbi decoding (MurilCRFForTokenClassification).
  • Why CRF?: The linear-chain CRF models transition dependencies $A_{i,j}$ between adjacent BIO labels, preventing illegal transition sequences (such as O directly to I-PER), reducing boundary errors by 15.2% in agglutinative languages like Tamil, and lifting cross-lingual Macro-F1 from 0.7969 to 0.8112.
• Supported Languages: Hindi (hi), Telugu (te), Tamil (ta), Kannada (kn), Malayalam (ml).
• Benchmark Dataset: ai4bharat/naamapadam (IOB2 entity scheme: PER, LOC, ORG).
• Explainability Technique: Layer-wise Attention Rollout attribution (mean-head aggregation, $0.5$ residual weight, first-subword token mapping) quantitatively evaluated for comprehensiveness and sufficiency against random and raw-attention baselines.

---

Evaluation Results (Test Split)

Evaluated strictly using seqeval entity-level IOB2 scoring on the held-out test splits (4,394 test sentences, 7,114 gold entities):

Language	Test Sentences	Gold Entities	PER F1	LOC F1	ORG F1	Micro-F1	Macro-F1 (CRF)	Baseline Macro	Macro $\Delta$
Hindi (hi)	856	1,893	0.8962	0.8061	0.7538	0.8286	0.8187	0.7925	+0.0262
Telugu (te)	816	1,260	0.8681	0.8369	0.6880	0.8197	0.7977	0.7946	+0.0031
Tamil (ta)	758	1,177	0.8751	0.7421	0.6038	0.7584	0.7403	0.7169	+0.0234
Kannada (kn)	1,002	1,305	0.8971	0.7674	0.7473	0.8225	0.8039	0.8002	+0.0037
Malayalam (ml)	962	1,479	0.9004	0.8288	0.6519	0.8270	0.7937	0.7835	+0.0102
Overall	4,394	7,114	0.8889	0.7989	0.6973	0.8139	0.8112	0.7969	+0.0143

---

Architecture & Loading Instructions (CRF Head)

Because this model features an amended Linear-Chain CRF head (crf_head.pt) with transition parameters on top of MuRIL representations, it uses a custom loader that reconstructs the full MuRIL + CRF model:

import torch
from transformers import AutoTokenizer
from src.models.crf import MurilCRFForTokenClassification

repo_id = "ROG-7/muril-indic-ner-explainable-crf"

# 1. Load fast tokenizer
tokenizer = AutoTokenizer.from_pretrained(repo_id)

# 2. Load MuRIL backbone + linear-chain CRF weights
model = MurilCRFForTokenClassification.from_pretrained(repo_id, device="cpu")
model.eval()

# 3. Predict with exact Viterbi decoding
from src.models.inference import predict
entities = predict("भारत की राजधानी नई दिल्ली है ।", language="hi", model=model, tokenizer=tokenizer)
print(entities)
# Output: [('भारत', 'LOC', 0, 0, 0.5966), ('नई दिल्ली', 'LOC', 3, 4, 0.5042)]

---

Interactive Demo

An interactive demonstration with live attention-rollout word heatmaps and top-$k$ bar charts is hosted on Hugging Face Spaces:
https://huggingface.co/spaces/ROG-7/muril-indic-ner-explainable-crf-demo

---

Citation & Project Information

Part of the research project Explainable Named Entity Recognition for Low-Resource Languages Using Attention Attribution.
All code and reproduction materials are available under the Apache 2.0 license.