Sync model from GitHub repository

9b11d6f verified 29 days ago

7.78 kB

---
language:
- en
license: mit
library_name: onnx
pipeline_tag: text-classification
tags:
- gender-classification
- name-classification
- onnx
- quantized
- fast-inference
- text-classification
- scratch
- low-latency
metrics:
- accuracy
- f1
model-index:
- name: CompactGenderClassifier
  results:
  - task:
      type: text-classification
      name: Binary Gender Classification
    dataset:
      name: Curated Human First Names
      type: custom
    metrics:
    - name: F1 Score
      type: f1
      value: 0.8444
    - name: Accuracy
      type: accuracy
      value: 0.8444
widget:
- text: "Supratim Mondal"
  example_title: "Male Name"
- text: "Sayantika Biswas"
  example_title: "Female Name"
- text: "Alexander Hamilton"
  example_title: "Western Male Name"
- text: "Priya Sharma"
  example_title: "Female Name"
- text: "John Smith"
  example_title: "Western Male Name"
- text: "Emily Watson"
  example_title: "Western Female Name"
---
# CompactGenderClassifier: Ultra-Efficient Gender Classifier Trained From Scratch

<div align="center">

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model%20Hub-yellow.svg)](https://huggingface.co/SupratimRK/compact-gender-classifier)
[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/SupratimRK/.model.base.gc)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![ONNX Runtime](https://img.shields.io/badge/ONNX-INT8%20Quantized-blue)](https://onnxruntime.ai/)

**[🤗 Hugging Face Model Hub](https://huggingface.co/SupratimRK/compact-gender-classifier)** | **[🐙 GitHub Repository](https://github.com/SupratimRK/.model.base.gc)**

</div>

`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

| Metric | Previous Pretrained Model | **CompactGenderClassifier (Scratch)** | Improvement |
| :--- | :--- | :--- | :--- |
| **Model Size (INT8 ONNX)** | 4.30 MB (2.45 MB pruned) | **~632 KB** | **74%–85% smaller** |
| **Total Parameters** | 4,380,000 params | **532,482 params** | **88% parameter reduction** |
| **Vocabulary Size** | 30,522 tokens | **4,000 tokens** | **87% smaller vocabulary** |
| **Sequence Length** | 16 tokens | **20 tokens** | **No truncation blind spots** |
| **CPU Latency (Single Thread)** | ~1.20 ms | **0.475 ms** | **~2.5x faster inference** |
| **Throughput** | ~800 queries/sec | **2,105 queries/sec** | Single CPU core in Node.js |
| **Validation Accuracy** | 84.79% | **84.44%** | Evaluated on 86k held-out split |
| **Validation F1-Score** | — | **84.44%** | Macro F1 score across classes |
| **Test Suite Benchmark** | 55.6% (10/18 baseline) | **100.0% (18/18)** | **Flawless 18/18 accuracy across benchmark suite** |

---

## 🧠 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

| File | Size | Description |
| :--- | :--- | :--- |
| `models/model_int8.onnx` | ~632 KB | Quantized INT8 ONNX model (**recommended for production**) |
| `models/model.onnx` | ~2.1 MB | Full precision (FP32) ONNX model |
| `models/model_weights.pt` | ~2.1 MB | PyTorch model checkpoint |
| `models/tokenizer/vocab.txt` | ~26 KB | WordPiece vocabulary (4,000 tokens) |
| `models/tokenizer/tokenizer.json`| ~84 KB | Fast Rust-based Hugging Face tokenizer configuration |
| `config/model_config.json` | < 1 KB | Model architecture metadata & best validation scores |
| `scripts/classifier.mjs` | ~5.8 KB | Zero-Python Node.js inference engine |
| `scripts/predict.py` | ~5.2 KB | Python CLI & batch inference tool |
| `scripts/test_benchmark.mjs` | ~3.3 KB | Node.js accuracy & latency benchmark suite |
| `scripts/train.py` | ~9.8 KB | PyTorch GPU/CPU training pipeline |
| `scripts/export_onnx.py` | ~4.5 KB | FP32 export & INT8 dynamic quantization script |

---

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

### Step 1: Install `onnxruntime-node`
```bash
npm install onnxruntime-node
```

### Step 2: Run Inference
```javascript
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
```python
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
```bash
# 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
```python
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
```bash
npm test
# or
node scripts/test_benchmark.mjs
```

	---
	language:
	- en
	license: mit
	library_name: onnx
	pipeline_tag: text-classification
	tags:
	- gender-classification
	- name-classification
	- onnx
	- quantized
	- fast-inference
	- text-classification
	- scratch
	- low-latency
	metrics:
	- accuracy
	- f1
	model-index:
	- name: CompactGenderClassifier
	results:
	- task:
	type: text-classification
	name: Binary Gender Classification
	dataset:
	name: Curated Human First Names
	type: custom
	metrics:
	- name: F1 Score
	type: f1
	value: 0.8444
	- name: Accuracy
	type: accuracy
	value: 0.8444
	widget:
	- text: "Supratim Mondal"
	example_title: "Male Name"
	- text: "Sayantika Biswas"
	example_title: "Female Name"
	- text: "Alexander Hamilton"
	example_title: "Western Male Name"
	- text: "Priya Sharma"
	example_title: "Female Name"
	- text: "John Smith"
	example_title: "Western Male Name"
	- text: "Emily Watson"
	example_title: "Western Female Name"
	---

	# CompactGenderClassifier: Ultra-Efficient Gender Classifier Trained From Scratch

	<div align="center">

	[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model%20Hub-yellow.svg)](https://huggingface.co/SupratimRK/compact-gender-classifier)
	[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/SupratimRK/.model.base.gc)
	[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
	[![ONNX Runtime](https://img.shields.io/badge/ONNX-INT8%20Quantized-blue)](https://onnxruntime.ai/)

	[🤗 Hugging Face Model Hub](https://huggingface.co/SupratimRK/compact-gender-classifier) \| [🐙 GitHub Repository](https://github.com/SupratimRK/.model.base.gc)

	</div>

	`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

	\| Metric \| Previous Pretrained Model \| CompactGenderClassifier (Scratch) \| Improvement \|
	\| :--- \| :--- \| :--- \| :--- \|
	\| Model Size (INT8 ONNX) \| 4.30 MB (2.45 MB pruned) \| ~632 KB \| 74%–85% smaller \|
	\| Total Parameters \| 4,380,000 params \| 532,482 params \| 88% parameter reduction \|
	\| Vocabulary Size \| 30,522 tokens \| 4,000 tokens \| 87% smaller vocabulary \|
	\| Sequence Length \| 16 tokens \| 20 tokens \| No truncation blind spots \|
	\| CPU Latency (Single Thread) \| ~1.20 ms \| 0.475 ms \| ~2.5x faster inference \|
	\| Throughput \| ~800 queries/sec \| 2,105 queries/sec \| Single CPU core in Node.js \|
	\| Validation Accuracy \| 84.79% \| 84.44% \| Evaluated on 86k held-out split \|
	\| Validation F1-Score \| — \| 84.44% \| Macro F1 score across classes \|
	\| Test Suite Benchmark \| 55.6% (10/18 baseline) \| 100.0% (18/18) \| Flawless 18/18 accuracy across benchmark suite \|

	---

	## 🧠 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

	\| File \| Size \| Description \|
	\| :--- \| :--- \| :--- \|
	\| `models/model_int8.onnx` \| ~632 KB \| Quantized INT8 ONNX model (recommended for production) \|
	\| `models/model.onnx` \| ~2.1 MB \| Full precision (FP32) ONNX model \|
	\| `models/model_weights.pt` \| ~2.1 MB \| PyTorch model checkpoint \|
	\| `models/tokenizer/vocab.txt` \| ~26 KB \| WordPiece vocabulary (4,000 tokens) \|
	\| `models/tokenizer/tokenizer.json`\| ~84 KB \| Fast Rust-based Hugging Face tokenizer configuration \|
	\| `config/model_config.json` \| < 1 KB \| Model architecture metadata & best validation scores \|
	\| `scripts/classifier.mjs` \| ~5.8 KB \| Zero-Python Node.js inference engine \|
	\| `scripts/predict.py` \| ~5.2 KB \| Python CLI & batch inference tool \|
	\| `scripts/test_benchmark.mjs` \| ~3.3 KB \| Node.js accuracy & latency benchmark suite \|
	\| `scripts/train.py` \| ~9.8 KB \| PyTorch GPU/CPU training pipeline \|
	\| `scripts/export_onnx.py` \| ~4.5 KB \| FP32 export & INT8 dynamic quantization script \|

	---

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

	### Step 1: Install `onnxruntime-node`
	```bash
	npm install onnxruntime-node
	```

	### Step 2: Run Inference
	```javascript
	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
	```python
	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
	```bash
	# 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
	```python
	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
	```bash
	npm test
	# or
	node scripts/test_benchmark.mjs
	```