QuantaSparkLabs commited on
Commit
128b910
Β·
verified Β·
1 Parent(s): 0010d29

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +137 -3
README.md CHANGED
@@ -1,9 +1,143 @@
1
  ---
 
2
  license: apache-2.0
 
 
 
 
 
 
 
 
3
  datasets:
4
  - SpiceeChat/Genre-Classifier
5
- language:
6
- - en
7
  base_model:
8
  - SpiceeChat/Genre-Classifier-1-20M-BASE-BF16
9
- ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ language: en
3
  license: apache-2.0
4
+ library_name: transformers
5
+ tags:
6
+ - gender-classification
7
+ - first-name
8
+ - tiny-models
9
+ - spiceechat
10
+ - causal-lm
11
+ pipeline_tag: text-classification
12
  datasets:
13
  - SpiceeChat/Genre-Classifier
 
 
14
  base_model:
15
  - SpiceeChat/Genre-Classifier-1-20M-BASE-BF16
16
+ ---
17
+
18
+ <p align="center">
19
+ <img src="https://huggingface.co/spaces/SpiceeChat/README/resolve/main/SpiceeChat_org_logo.png"
20
+ alt="SpiceeChat"
21
+ width="120">
22
+ </p>
23
+
24
+ <h1 align="center">FirstName Gender Classifier β€” 30M</h1>
25
+
26
+ <p align="center">
27
+ <em>Lightweight, fast, and accurate β€” because guessing isn't a strategy.</em>
28
+ </p>
29
+
30
+ <p align="center">
31
+ <a href="https://huggingface.co/SpiceeChat"><img src="https://img.shields.io/badge/SpiceeChat-πŸ”₯-orange" alt="SpiceeChat"></a>
32
+ <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-yellow" alt="License"></a>
33
+ <img src="https://img.shields.io/badge/Params-~20M-blue" alt="Params">
34
+ <img src="https://img.shields.io/badge/Accuracy-84.7%25-green" alt="Accuracy">
35
+ </p>
36
+
37
+ ---
38
+
39
+ ## Overview
40
+
41
+ This model is a fine-tuned version of a custom 20M-parameter CausalLM architecture, originally built by **PhysiQuanty**. It was trained on a combination of:
42
+
43
+ - **150,000** samples from the `SpiceeChat/Genre-Classifier` dataset
44
+ - **922** hand-curated examples to improve coverage and diversity
45
+
46
+ The result is a compact, production-ready classifier that predicts gender from a first name with **~85% accuracy** and no unnecessary overhead.
47
+
48
+ ---
49
+
50
+ ## Quick Start
51
+
52
+ ```python
53
+ from transformers import AutoModel, AutoTokenizer
54
+
55
+ model = AutoModel.from_pretrained(
56
+ "SpiceeChat/FirstName-Genre-Classifier-30M-SFT",
57
+ trust_remote_code=True # custom architecture, audited and safe
58
+ )
59
+ tokenizer = AutoTokenizer.from_pretrained(
60
+ "SpiceeChat/FirstName-Genre-Classifier-30M-SFT",
61
+ trust_remote_code=True
62
+ )
63
+
64
+ name = "Arjun"
65
+ inputs = tokenizer(name, return_tensors="pt")
66
+ pred, probs = model.predict_gender(inputs.input_ids)
67
+ gender = "M" if pred.item() == 1 else "F"
68
+ print(f"{name} β†’ {gender} (confidence: {probs.max().item():.2f})")
69
+ ```
70
+
71
+ **Expected output:**
72
+ ```
73
+ Arjun β†’ M (confidence: 0.98)
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Performance
79
+
80
+ | Metric | Value |
81
+ |---|---|
82
+ | Validation Accuracy | 84.74% |
83
+ | Macro F1 | 81.06% |
84
+ | Parameters | ~20M |
85
+ | Model Size | 129 MB |
86
+
87
+ Trained for 3 epochs with class weighting (F : M = 3:1) to handle the natural imbalance in the training data. Loss dropped cleanly from 0.41 to 0.34 across training β€” stable convergence, no overfitting.
88
+
89
+ ---
90
+
91
+ ## What Makes This Model Different
92
+
93
+ - **Handles global names** β€” from Wei (Chinese) to Haruto (Japanese) to Ama (Ghanaian)
94
+ - **Generalizes beyond dictionaries** β€” learns naming patterns rather than relying on lookup tables
95
+ - **Custom lightweight architecture** β€” small enough to run comfortably on CPU
96
+ - **Fully compatible** with Hugging Face Transformers β€” loads like any standard model
97
+
98
+ ---
99
+
100
+ ## Training Details
101
+
102
+ | Detail | Value |
103
+ |---|---|
104
+ | Base model | `SpiceeChat/Genre-Classifier-1-20M-BASE-BF16` |
105
+ | Training data | 150,000 + 922 custom examples |
106
+ | Optimizer | AdamW (LR = 2e-5) |
107
+ | Batch size | 64 (train) / 256 (eval) |
108
+ | Hardware | Tesla T4 (FP16) |
109
+
110
+ ---
111
+
112
+ ## Notes
113
+
114
+ - The model uses weight tying between `head.weight` and `tok_emb.weight`. A harmless `head.weight | MISSING` warning may appear on load β€” this is expected behavior.
115
+ - `trust_remote_code=True` is required because the architecture is custom. The modeling code is included in this repository and fully auditable.
116
+
117
+ ---
118
+
119
+ ## Try It Yourself
120
+
121
+ ```bash
122
+ python -c "
123
+ from transformers import AutoModel, AutoTokenizer
124
+ model = AutoModel.from_pretrained('SpiceeChat/FirstName-Genre-Classifier-30M-SFT', trust_remote_code=True)
125
+ tokenizer = AutoTokenizer.from_pretrained('SpiceeChat/FirstName-Genre-Classifier-30M-SFT', trust_remote_code=True)
126
+ name = input('Enter a first name: ')
127
+ inputs = tokenizer(name, return_tensors='pt')
128
+ pred, _ = model.predict_gender(inputs.input_ids)
129
+ print('M' if pred.item() == 1 else 'F')
130
+ "
131
+ ```
132
+
133
+ ---
134
+
135
+ ## License
136
+
137
+ Released under the Apache 2.0 license. Use it, modify it, ship it β€” no strings attached.
138
+
139
+ ---
140
+
141
+ <p align="center">
142
+ <sub>Built with a lot of caffeine β˜• by SpiceeChat</sub>
143
+ </p>