genderfluid-tiny

Offline Python classifier that predicts gender associations from names. 49KB model, CPU only, no API needed.

$ pip install genderfluid-tiny

0 KBModel

0 msPrediction

0KNames trained

0API calls

Installation

$ pip install genderfluid-tiny

From source:

$ git clone https://github.com/MaxEdgar/genderfluid-tiny.git
$ cd genderfluid-tiny
$ pip install -e .

Requirements: Python 3.10+, scikit-learn, numpy. No GPU or internet required.

What it does

Given a name, genderfluid-tiny estimates whether it is statistically associated with feminine or masculine naming conventions. It outputs girl-associated, boy-associated, or uncertain.

102,927 names trained from U.S. Social Security Administration (1880-2020) and Census 2020 records.

Quick start

from genderfluid import classify_name, is_girl_name, name_probability

classify_name("Emma")      # "girl-associated"
classify_name("James")     # "boy-associated"
classify_name("Alex")      # "uncertain"

is_girl_name("Emma")       # True
name_probability("Emma")   # 0.9731

Or from the command line:

$ genderfluid predict Emma

Name: Emma

Girl-associated: 97.3%
Boy-associated:  0.5%
Uncertain:       2.2%

Classification: girl-associated
Confidence:     high

Python API

Simple functions

from genderfluid import classify_name, is_girl_name, is_boy_name, name_probability

classify_name("Emma")       # "girl-associated"
is_girl_name("Emma")        # True
is_boy_name("James")        # True
name_probability("Emma")    # 0.9731

Full result dict

from genderfluid import predict_name, predict_names

result = predict_name("Isabella")
# {
#   "name": "Isabella",
#   "girl_associated_probability": 0.8929,
#   "boy_associated_probability": 0.0486,
#   "uncertain_probability": 0.0585,
#   "classification": "girl-associated",
#   "confidence": "medium"
# }

Model instance (for repeated use)

from genderfluid import GenderfluidModel

model = GenderfluidModel()  # loads once, cached
model.predict("Olivia")
model.predict_batch(["Emma", "James", "Alex"])

Batch prediction

from genderfluid import predict_names

results = predict_names(["Emma", "James", "Alex", "Max"])
for r in results:
    print(f"{r['name']}: {r['classification']}")

Command line

$ genderfluid predict Olivia

Name: Olivia

Girl-associated: 97.5%
Boy-associated:  1.2%
Uncertain:       1.2%

Classification: girl-associated
Confidence:     high

Multi-word names work without quotes:

$ genderfluid predict Isabella

Compare names

$ genderfluid predict --compare Emma James Alex Max Taylor

Name                      Classification         Girl    Boy Confidence
----------------------------------------------------------------------
Emma                      girl-associated         97%     0% high
James                     boy-associated           8%    79% medium
Alex                      uncertain               27%    59% low
Max                       boy-associated           7%    77% medium
Taylor                    uncertain               42%    17% low

5 names in 30.5 ms

Batch processing

Create a text file with one name per line:

# names.txt
Emma
James
Alex
Isabella

Then run:

$ genderfluid predict --file names.txt

Output is JSONL (one JSON object per line), with timing info at the end.

JSON output

$ genderfluid predict --json Alex

{
  "name": "Alex",
  "girl_associated_probability": 0.2692,
  "boy_associated_probability": 0.5914,
  "uncertain_probability": 0.1395,
  "classification": "uncertain",
  "confidence": "low"
}

Architecture

Input name
  |
Unicode normalization + lowercase
  |
Character n-gram extraction (2-5 grams)
  |
Hashing trick (4096-dim feature vector)
  |
Logistic regression (3 classes)
  |
Sigmoid calibration
  |
Output: girl-associated / boy-associated / uncertain

The classifier extracts character-level patterns. Names ending in -a, -ia, -ine tend to be feminine. Names ending in -o, -us, -er tend to be masculine. The model learns these patterns from data rather than hard-coding rules.

Features

Fully offlineNo internet. No API. No data leaves your machine.

49 KB modelSmaller than most profile pictures.

Sub-millisecond0.93ms per prediction. 5,500 names/sec.

CPU onlyNo GPU. No CUDA. Works on old hardware.

Uncertain categoryDoes not force binary. Ambiguous names get flagged.

Real data102,927 names from SSA and Census 2020.

Unicode supportHandles accented characters, hyphens, apostrophes.

Simple APIOne function call. No complex setup.

Benchmark

Measured on Intel Celeron N4000 @ 1.10GHz:

Metric	Value
Model size	49 KB
Loading time	0.3 ms
Single prediction	0.93 ms
Batch (100 names)	18.7 ms
Batch (1000 names)	180 ms
Throughput	5,551 names/sec
Peak RSS	198 MB

$ genderfluid benchmark

Accuracy

Tested on held-out test data (10,294 names):

Metric	Value
Accuracy	68.9%
Macro F1	0.629
Girl-associated F1	0.844
Boy-associated F1	0.664
Uncertain F1	0.380
Calibration error	0.031

The model is trained on U.S./English naming conventions. Accuracy varies by cultural context.

CLI reference

Command	Description
`genderfluid predict <name>`	Predict gender association
`genderfluid predict --json <name>`	JSON output
`genderfluid predict --compare <names>`	Compare multiple names
`genderfluid predict --file <file>`	Batch from file (JSONL output)
`genderfluid predict --info`	Show model metadata
`genderfluid interactive`	Interactive prediction mode
`genderfluid stats`	Model statistics
`genderfluid benchmark`	Run inference benchmark
`genderfluid --version`	Show version
`genderfluid --help`	Show help

Training from source

$ python process_real_data.py   # download and process SSA + Census data
$ python prepare_data.py        # validate and split data
$ python train.py               # train model
$ python evaluate.py            # evaluate on test set

The training script:

Loads and validates the dataset
Trains logistic regression with 3 classes
Calibrates probabilities with sigmoid scaling
Evaluates on the test set
Saves the model to models/genderfluid-tiny.bin

Dataset

JSONL format, one entry per line:

{"name": "Emma", "label": "girl-associated"}
{"name": "James", "label": "boy-associated"}
{"name": "Alex", "label": "uncertain"}

Optional fields: weight, country, language, year.

Training data sources:

U.S. Social Security Administration baby names (1880-2020): 100,364 unique names
U.S. Census Bureau 2020 Census first names: 53,616 unique names

Names with 85%+ statistical association are labeled girl-associated or boy-associated. Below that threshold: uncertain.

Limitations

Works with full names: first, middle, and last
U.S./English-centric training data
Name associations vary by culture, language, and generation
The uncertain category exists for genuinely ambiguous names
Not suitable for high-stakes decisions
The classifier can be wrong

License

Polyform Noncommercial License 1.0.0. Free for personal, educational, and noncommercial use. Commercial use requires a license.

Commercial licensing · GitHub · PyPI