CompactGenderClassifier: Ultra-Efficient Gender Classifier Trained From Scratch

🤗 Hugging Face Model Hub | 🐙 GitHub Repository

CompactGenderClassifier is a state-of-the-art, ultra-lightweight neural text classifier trained from scratch on a curated, audited dataset of 976,267 labeled records (889,912 train + 86,355 val; 485k Female + 491k Male across global and Indian cultural origins).

Unlike generic large language models or pretrained BERT variants, CompactGenderClassifier has zero external pretrained dependencies, weighs just ~632 KB (INT8 ONNX), and delivers sub-millisecond CPU inference (< 0.48 ms per query).

---

⚡ Performance Highlights

---

🧠 Architectural Innovations

1. Strict First-Name Purity & Given-Name Parsing:

   • Isolates the core given/first name before running morphology classification, ensuring family surnames do not introduce gender confusion.
   • Surnames are never assigned artificial gender labels, preventing spurious correlations.

2. Custom Domain WordPiece Tokenizer (100% Uncased, 4,000 Vocab):

   • Configured with Sequence([NFKC(), Lowercase(), StripAccents()]) and Sequence([Whitespace(), Punctuation(), Digits(individual_digits=True)]).
   • Captures high-salience gender morphology subwords (-a, -i, -ya, -ini, -wati for female, and -an, -ar, -esh, -kumar for male) across languages.
   • 100% uncased normalization eliminates casing artifacts.

3. Factorized Embeddings:

   • Projects token vocabulary through Embedding(4000, 64) -> Linear(64, 128, bias=False).
   • Cuts embedding parameter footprint in half with zero loss in representational capacity.

4. Pre-LN Transformer Encoder:

   • 2-layer, 128-hidden, 4-attention heads with GELU activations and Pre-LayerNorm (norm_first=True) for fast, stable convergence.

5. Masked Dual Pooling (MeanPool + MaxPool):

   • Concatenates Masked Mean Pooling (128) + Masked Max Pooling (128) into a 256-dimensional representation.
   • Max Pooling acts as a sensitive detector for gender-bearing subword morphemes.

6. Dual Runtime (Node.js & Python):

   • Pure Node.js runtime using onnxruntime-node requiring zero Python installed in production.
   • Built-in given-name extraction: handles single names ("Supratim"), full names ("Supratim Mondal"), and honorifics ("Dr. Rahul Verma").

---

📦 Files in this Repository

---

🚀 Quickstart: Node.js (Zero-Python Production)

Step 1: Install onnxruntime-node

npm install onnxruntime-node

Step 2: Run Inference

import { CompactGenderClassifier } from './scripts/classifier.mjs';

const classifier = new CompactGenderClassifier();
await classifier.init();

// Single first name
console.log(await classifier.predict('Sayantika'));
// Output: { gender: 'FEMALE', confidence: 0.952, raw_probs: { male: 0.048, female: 0.952 } }

// Full name with surname
console.log(await classifier.predict('Supratim Mondal'));
// Output: { gender: 'MALE', confidence: 0.967, given_name: 'Supratim', surnames: ['Mondal'], raw_probs: { male: 0.967, female: 0.033 } }

// Full name with title
console.log(await classifier.predict('Dr. Alexander Hamilton'));
// Output: { gender: 'MALE', confidence: 0.972, given_name: 'Alexander', surnames: ['Hamilton'] }

---

🐍 Quickstart: Python

1. Download Model from Hugging Face Hub

from huggingface_hub import hf_hub_download

repo_id = "SupratimRK/compact-gender-classifier"

# Download ONNX INT8 model and tokenizer
onnx_path = hf_hub_download(repo_id=repo_id, filename="model_int8.onnx")
tok_path = hf_hub_download(repo_id=repo_id, filename="tokenizer.json")

2. Run via CLI

# Interactive mode
python predict.py -i

# Batch query (supports positional names or --text)
python predict.py "Supratim Mondal" "Sayantika Biswas" "Alexander Hamilton" "Priya Sharma"

3. Run in Code

from predict import GenderClassifier

clf = GenderClassifier(use_onnx=True)
results = clf.predict(["Supratim Mondal", "Sayantika Biswas"])

for r in results:
    print(f"{r['text']} -> {r['gender']} ({r['confidence']*100:.1f}%) [Given: {r['given_name']}]")

---

🧪 Run Benchmarks

npm test
# or
node scripts/test_benchmark.mjs