godsword/instagram-gender-detection

Instagram Username Gender Detection

This repository provides character-level neural network models. The models classify Instagram usernames into Male, Female, or UNK. The system runs fast inference on central processing units.

Key Features

• Champion Hybrid Architecture: Combines 1D CNN n-gram extraction with Bidirectional LSTM sequence modeling. Delivers 83.06% test accuracy and 0.8173 test Macro F1.
• Ultra-Low Latency CNN: An alternative Multi-Kernel CNN runs at 0.195 milliseconds per sample. It provides extreme inference throughput.
• Robust UNK Handling: Accurately routes business and brand accounts to the UNK class.
• Dynamic Hot-Reloading: Switches active models in memory via POST /model/switch with zero downtime.
• Interactive Web Demo: Serves a dark-theme web user interface at the root endpoint.
• FastAPI REST API: Validates input data with Pydantic and generates OpenAPI documentation at /docs.

Motivation and Project Origin

The author worked as a backend developer on an Instagram analytics platform. The platform required gender classification from usernames and public profile data. Initial experiments used large language model prompting pipelines. The team sent large JSON payloads containing usernames and biographies to external APIs. This design caused severe engineering trade-offs. Commercial API fees were expensive at scale. Network latency delayed real-time request pipelines. Smaller open-source generative models failed to deliver reliable classification accuracy.

The author started this project as an independent research investigation. The goal was to design lightweight character-level neural networks. The project covers end-to-end dataset curation, neural sequence modeling, and low-latency API deployment.

Technical Trade-Offs: Local Models versus LLMs

Generative language models carry massive parameter counts and high operational overhead. Our character-level neural networks execute on standard central processing units with sub-millisecond latency. The Multi-Kernel CNN processes a single username in 0.195 milliseconds. The Champion Hybrid model processes a sample in 1.49 milliseconds. Local execution requires zero external network calls. This architecture removes third-party API subscription costs.

Local sequence models also guarantee strict data privacy. Usernames remain entirely on local infrastructure. The neural network outputs deterministic Softmax probabilities without generative hallucinations. Character-level representations capture sub-word patterns, phonetic prefixes, and trailing digits efficiently.

Target Classes and UNK Rationale

The classifier predicts one of three mutually exclusive target classes.

Target Class	Description	Classification Rationale
Male	Personal accounts representing male individuals.	Identifies masculine forenames, diminutives, and typical username affix patterns.
Female	Personal accounts representing female individuals.	Identifies feminine forenames, diminutives, and typical username affix patterns.
UNK	Non-human entities, brands, and ambiguous usernames.	Prevents binary hallucination on business, corporate, meme, and organizational accounts.

Social media datasets contain millions of non-personal accounts. Binary models force business and meme handles into human gender categories. The UNK class absorbs non-human entities and preserves classification integrity.

Curated Datasets

The training engine aggregates five diverse public datasets.

Dataset Name	Source / Reference	Record Count	Purpose
SSA Baby Names	Social Security Administration (1880–2022)	2,085,158 records	Establishes historical name distributions and unisex probabilities.
Philippe Remy Name Dataset	Multi-national public repository across 106 countries	491,000,000 records	Provides multi-cultural first and last name pairs with gender labels.
Twitter User Gender Classification	CrowdFlower human-annotated screen name benchmark	20,050 records	Provides authentic social media handles with alphanumeric formatting.
Global Forename Usage	Cross-lingual international forename dictionary	142,000 records	Filters ambiguous cross-lingual overlaps and linguistic noise.
USA and UK Name Popularity	Ackerman demographic popularity corpus	108,000 records	Balances equi-biased unisex names and prevents common name overfitting.

The Social Security Administration dataset provides raw birth frequency statistics. These counts establish base prior probabilities for English first names. The Philippe Remy dataset expands coverage across international naming conventions. The Twitter Gender dataset provides authentic social media username structures. The Global Forename dictionary disambiguates names across distinct linguistic traditions. The Ackerman corpus balances unisex frequencies to prevent class prediction bias.

Preprocessing and Curation Pipeline

The data pipeline processes raw name entries through four sequential stages.

Stage 1: Character Normalization

The engine lowercases all input strings. A regex filter restricts characters to the 38 allowable Instagram characters. Allowable characters include English letters, digits, periods, and underscores. Diacritics and special symbols are removed or mapped to ASCII equivalents.

Stage 2: Username Synthesis

The synthesizer merges first and last name tokens. Tokens are joined via direct concatenation, single periods, or underscores. Trailing numbers simulate authentic user handle selection.

Stage 3: UNK Handle Aggregation

The pipeline ingests curated lists of business terms, corporate brands, and meme accounts. Random dictionary words and non-human patterns receive the UNK label.

Stage 4: Sequence Formatting

The pipeline truncates usernames longer than 30 characters. Instagram enforces a strict maximum length of 30 characters. Usernames shorter than 30 characters receive left zero-padding.

Dataset Distribution and Metrics

The curation pipeline creates 70,172 base curated samples. The dataset uses a stratified 70/20/10 split for training, validation, and testing. Training split augmentation expands the training set to 126,720 total samples.

Class Label	Curated Samples	Augmented Split Count	Proportion
Female	31,820	57,477	45.36%
Male	31,765	57,382	45.28%
UNK	6,587	11,861	9.36%
Total	70,172	126,720	100.00%

The evaluation split preserves identical class proportions across training, validation, and test subsets.

Model Architectures and Deep Learning Pipelines

The project evaluates three character-level sequence architectures.

1. Character Bidirectional LSTM (BiLSTM)

The BiLSTM captures forward and backward character sequence dependencies.

flowchart TD
    In["Input Tensor: (B, 30)"] --> Emb["Embedding Layer: (B, 30, 64)"]
    Emb --> LSTM["BiLSTM Layer: (B, 30, 256)"]
    LSTM --> MaxP["Global Max Pooling: (B, 256)"]
    LSTM --> AvgP["Global Average Pooling: (B, 256)"]
    MaxP --> Cat["Concatenation: (B, 512)"]
    AvgP --> Cat
    Cat --> Drop["Dropout Layer: p=0.3"]
    Drop --> Linear["Linear Projection: (B, 3)"]
    Linear --> Out["Softmax Probabilities: (B, 3)"]

2. Multi-Kernel 1D CNN

The CNN detects local character n-gram motifs using parallel convolution filters.

flowchart TD
    In["Input Tensor: (B, 30)"] --> Emb["Embedding Layer: (B, 30, 64)"]
    Emb --> Tr["Transpose: (B, 64, 30)"]
    Tr --> C2["Conv1D k=2: (B, 64, 29)"]
    Tr --> C3["Conv1D k=3: (B, 64, 28)"]
    Tr --> C4["Conv1D k=4: (B, 64, 27)"]
    Tr --> C5["Conv1D k=5: (B, 64, 26)"]
    C2 --> M2["Global Max Pool: (B, 64)"]
    C3 --> M3["Global Max Pool: (B, 64)"]
    C4 --> M4["Global Max Pool: (B, 64)"]
    C5 --> M5["Global Max Pool: (B, 64)"]
    M2 --> Cat["Concatenation: (B, 256)"]
    M3 --> Cat
    M4 --> Cat
    M5 --> Cat
    Cat --> Drop["Dropout Layer: p=0.3"]
    Drop --> Linear["Linear Projection: (B, 3)"]
    Linear --> Out["Softmax Probabilities: (B, 3)"]

3. Champion Hybrid Architecture (CNN + BiLSTM)

The Hybrid model combines n-gram feature extraction with recurrent sequence context.

flowchart TD
    In["Input Tensor: (B, 30)"] --> Emb["Embedding Layer: (B, 30, 64)"]
    Emb --> Tr["Transpose: (B, 64, 30)"]
    Tr --> Conv["Conv1D k=3: (B, 128, 30)"]
    Conv --> ReLU["ReLU Activation"]
    ReLU --> TrBack["Transpose: (B, 30, 128)"]
    TrBack --> LSTM["BiLSTM Layer: (B, 30, 256)"]
    LSTM --> MaxP["Global Max Pooling: (B, 256)"]
    LSTM --> AvgP["Global Average Pooling: (B, 256)"]
    MaxP --> Cat["Concatenation: (B, 512)"]
    AvgP --> Cat
    Cat --> Drop["Dropout Layer: p=0.25"]
    Drop --> Linear["Linear Projection: (B, 3)"]
    Linear --> Out["Softmax Probabilities: (B, 3)"]

Architecture Specifications and Hyperparameters

Parameter / Metric	Champion Hybrid	Multi-Kernel CNN	Character BiLSTM
Input Sequence Length	30 characters	30 characters	30 characters
Vocabulary Size	38 characters + Pad (39)	38 characters + Pad (39)	38 characters + Pad (39)
Embedding Dimension (d)	64	64	64
Convolutional Filters	128 filters (k=3)	64 filters each (k=2,3,4,5)	None
Recurrent Hidden Units	128 forward + 128 backward	None	128 forward + 128 backward
Pooling Mechanism	Global Max + Global Avg	Global Max per kernel	Global Max + Global Avg
Dropout Rate	0.25	0.30	0.30
Total Parameters	847,875	401,283	798,595
Test Accuracy	83.06%	81.59%	81.15%
Test Macro F1	0.8173	0.8021	0.7993
Male F1 Score	0.8311	0.8182	0.8146
Female F1 Score	0.8404	0.8260	0.8181
UNK F1 Score	0.7805	0.7621	0.7654
Inference Latency	1.49 ms/sample	0.195 ms/sample	0.79 ms/sample

API Documentation and Endpoints

Interactive Swagger documentation is available at /docs. ReDoc documentation is available at /redoc.

1. Interactive Demo UI

• Route: GET /
• Serves the standalone responsive single-page web demo.

2. Single Prediction

• Route: POST /predict
• Returns predicted gender, confidence score, class probabilities, and active architecture name.

3. Vectorized Batch Prediction

• Route: POST /predict/batch
• Accepts an array of usernames and returns batched predictions with latency metrics.

4. Health and Uptime Probe

• Route: GET /health
• Reports server health, loaded model architecture, and execution device.

5. Model Metadata

• Route: GET /info
• Returns test accuracy, Macro F1, parameter counts, and model hyperparameters.

6. Dynamic Model Hot-Reload

• Route: POST /model/switch
• Switches active in-memory model between hybrid and cnn presets without downtime.

Local Development and Execution

Run API Locally

python run_api.py --host 0.0.0.0 --port 7860 --model hybrid

Run Model Training Runners

Centralized runner scripts reside in the scripts/ directory.

python scripts/train_hybrid.py --epochs 200 --batch-size 128
python scripts/train_cnn.py --epochs 200 --batch-size 128
python scripts/train_bilstm.py --epochs 200 --batch-size 128

Run Cross-Validation and Evaluation

python scripts/run_cv.py --k-folds 5
python scripts/evaluate_all.py

Run Automated Tests

pytest tests/test_api.py -v

Run Live Smoke Test Script

python scripts/smoke_test_api.py --base-url http://localhost:7860

Docker Deployment

Build and run the container locally:

docker build -t instagram-gender-detection:latest .
docker run -p 7860:7860 instagram-gender-detection:latest

Hugging Face Dual Deployment

Publish model artifacts to Hugging Face Hub and deploy the container to Spaces:

python scripts/deploy_hf.py --dry-run
export HF_TOKEN="your_hf_token"
python scripts/deploy_hf.py   --model-repo "username/instagram-gender-detection"   --space-repo "username/instagram-gender-detector-space"